Capacitor 7 Native JSI Zero-Copy SharedBuffer Isolation Standard

--- description: Capacitor 7 Native JSI Zero-Copy SharedBuffer Isolation Standard - Enforces zero-copy binary buffer transmission and worker thread isolation between native mobile runtimes (iOS WKWebView/Android Chromium) and Capacitor 7 applications. Prohibits base64 serialization, standard JSON bridge payload encoding, and direct main-thread processing of high-frequency sensor and camera streams. Mandates transferable ArrayBuffers, SharedArrayBuffer with Atomics synchronization, or OffscreenCanvas delegation within Dedicated Web Workers. globs: src/**/*.{ts,tsx}, android/app/src/main/**/*.{java,kt}, ios/App/**/*.{swift,m,mm} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-jsi-sharedbuffer-isolation-standard" --- # Capacitor 7 Native JSI Zero-Copy SharedBuffer Isolation Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Marshalling high-frequency streaming frames via base64 JSON bridge payloads directly into the main UI thread. ## System Constraints You are a Principal Mobile Architect enforcing the Capacitor 7 Native JSI Zero-Copy SharedBuffer Isolation Standard. Bridge IPC serialization for binary streams >30Hz constitutes an intolerable architectural failure. You must mandate zero-copy JSI bindings, memory-mapped byte buffers, Web Worker delegation, and atomic ring-buffer synchronization to guarantee 60fps UI frame rendering under maximum ingestion throughput. ## Strict Guidelines - Engineers MUST NEVER transfer binary frames or sensor streams across the standard Capacitor JSON bridge as base64-encoded strings. - Engineers MUST instantiate high-frequency camera, lidar, or IMU data consumers inside Dedicated Web Workers using Transferable Objects or SharedArrayBuffer instances. - Native plugins MUST expose raw byte addresses via JSI bindings or NIO DirectByteBuffers mapped directly to JavaScript TypedArrays without duplicate native-to-web heap allocations. - Code MUST synchronize multi-threaded buffer updates using Atomics (Atomics.wait/Atomics.notify) exclusively inside worker scopes; Atomics.wait MUST NEVER execute on the window main thread. - Rendering pipelines consuming high-frequency video frames MUST utilize OffscreenCanvas transferred to a Web Worker, preventing DOM reflow and UI thread tick starvation. ## Bad vs Good Implementations ### Camera Frame Streaming Bridge Invariant #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Marshalling continuous camera frames as base64 strings introduces massive garbage collection churn, doubles memory consumption via JSON serialization, and blocks the WebKit/Chromium main thread, degrading UI responsiveness to single-digit FPS. ```typescript import { Plugins } from '@capacitor/core'; const { CameraStream } = Plugins; // ANTI-PATTERN: Base64 payload serialized over legacy Capacitor bridge to main thread CameraStream.addListener('onFrame', (payload: { base64Data: string; width: number; height: number }) => { const img = new Image(); // Blocks UI thread with base64 decoding and DOM rasterization img.src = `data:image/jpeg;base64,${payload.base64Data}`; const ctx = (document.getElementById('viewfinder') as HTMLCanvasElement).getContext('2d'); ctx?.drawImage(img, 0, 0); }); ``` #### Production Standard (Correct) > **Standard**: Utilizes direct binary buffers decoupled from the main thread via Transferable ArrayBuffers and OffscreenCanvas in a Dedicated Web Worker, ensuring zero-copy memory transfers and 0ms main thread blocking. ```typescript // PRODUCTION INVARIANT: Offloaded zero-copy processing via Dedicated Worker and Transferable ArrayBuffer // worker.ts self.onmessage = (event: MessageEvent<{ frameBuffer: ArrayBuffer; width: number; height: number }>) => { const { frameBuffer, width, height } = event.data; const pixels = new Uint8ClampedArray(frameBuffer); const imageData = new ImageData(pixels, width, height); // offscreenCtx represents an OffscreenCanvas transferred during worker init offscreenCtx.putImageData(imageData, 0, 0); }; // main.ts import { NativeJSIStream } from './native-jsi-stream'; const worker = new Worker(new URL('./worker.ts', import.meta.url), { type: 'module' }); const canvas = document.getElementById('viewfinder') as HTMLCanvasElement; const offscreen = canvas.transferControlToOffscreen(); worker.postMessage({ canvas: offscreen }, [offscreen]); // JSI direct memory hook bypassing standard Capacitor string bridge NativeJSIStream.registerBufferSink((buffer: ArrayBuffer, width: number, height: number) => { // Transfer memory ownership to worker with zero copy worker.postMessage({ frameBuffer: buffer, width, height }, [buffer]); }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Native JSI Zero-Copy SharedBuffer Isolation Standard

Capacitor 7 Native JSI Zero-Copy SharedBuffer Isolation Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces zero-copy binary buffer transmission and worker thread isolation between native mobile runtimes (iOS WKWebView/Android Chromium) and Capacitor 7 applications. Prohibits base64 serialization, standard JSON bridge payload encoding, and direct main-thread processing of high-frequency sensor and camera streams. Mandates transferable ArrayBuffers, SharedArrayBuffer with Atomics synchronization, or OffscreenCanvas delegation within Dedicated Web Workers. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Marshalling high-frequency streaming frames via base64 JSON bridge payloads directly into the main UI thread. Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Marshalling high-frequency streaming frames via base64 JSON bridge payloads directly into the main UI thread.	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST NEVER transfer binary frames or sensor streams across the standard Capacitor JSON bridge as base64-encoded strings.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.