Capacitor 7 Native-to-Webview Zero-Copy TypedArray Bridge Invariant

--- description: Capacitor 7 Native-to-Webview Zero-Copy TypedArray Bridge Invariant - Mandates bounded zero-copy buffer transfers or SharedArrayBuffer ring-buffers via Web Workers for high-frequency native telemetry in Capacitor 7. Eliminates JSON bridge serialization overhead, GC thrashing, and UI main-thread frame drops during sensor, IMU, audio, and biometric data ingest. globs: src/**/*.{ts,tsx}, src/workers/**/*.{ts,js}, ios/App/App/**/*.swift, android/app/src/main/java/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor7-sharedarraybuffer-zero-copy-streaming" --- # Capacitor 7 Native-to-Webview Zero-Copy TypedArray Bridge Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Serializing Continuous High-Frequency Sensor Telemetry as JSON Across the Capacitor Bridge ## System Constraints You are a Principal Mobile Architect enforcing strict zero-copy streaming invariants between native runtimes (Android/iOS) and Capacitor 7 WebViews. You mandate that high-frequency biometric, IMU, or audio telemetry bypasses JSON-over-bridge serialization entirely. Require pre-allocated TypedArrays, SharedArrayBuffer ring buffers, or Transferable ArrayBuffers executed inside Web Workers with Atomics synchronization to preserve 60/120fps UI rendering. ## Strict Guidelines - Engineers MUST NEVER emit high-frequency (>30Hz) sensor or biometric samples through standard Capacitor `notifyListeners` using JSON objects. - Engineers MUST isolate high-frequency telemetry processing inside a dedicated Web Worker, completely off the UI main thread. - Streaming bridges MUST utilize pre-allocated `SharedArrayBuffer` structures with `Atomics` or binary chunks piped via `Transferable` ArrayBuffers to achieve zero-copy semantics. - Native plugins (Kotlin/Swift) MUST expose binary byte channels or native memory handles mapped directly into the WebView via custom asset loaders or direct buffer bridge calls. - UI components MUST NEVER directly subscribe to raw sensor streams; they MUST consume downsampled, RAF-throttled view models published by the worker. ## Bad vs Good Implementations ### High-Frequency Native Telemetry Ingest Bridge #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Routing 100Hz+ sensor payloads through standard Capacitor plugin events causes excessive bridge JSON serialization, bridge message queue saturation, heavy GC pressure, and UI main-thread jank. ```typescript import { Plugins } from '@capacitor/core'; const { BiometricSensorPlugin } = Plugins; // Anti-pattern: Direct main-thread listener with JSON deserialization at 100Hz export function setupSensorStream(onData: (val: number) => void) { BiometricSensorPlugin.addListener('onSample', (payload: { timestamp: number; ppgValue: number; ecgValue: number }) => { // Main thread JSON parse overhead + rapid GC allocation destroys 60/120fps UI render loop onData(payload.ppgValue); }); } ``` #### Production Standard (Correct) > **Standard**: Bypasses JSON serialization entirely using native binary transfers via Transferable ArrayBuffers into a Web Worker, updating a pre-allocated SharedArrayBuffer ring-buffer synchronized with Atomics, completely eliminating UI main-thread stutter. ```typescript // worker.ts: Dedicated Web Worker processing binary stream via SharedArrayBuffer const BUFFER_SIZE = 4096; const sharedBuffer = new SharedArrayBuffer(BUFFER_SIZE * Float32Array.BYTES_PER_ELEMENT); const ringBuffer = new Float32Array(sharedBuffer); const stateBuffer = new Int32Array(new SharedArrayBuffer(4)); // Write pointer self.onmessage = (event: MessageEvent<{ nativeStreamPort: MessagePort }>) => { const port = event.data.nativeStreamPort; port.onmessage = (msg: MessageEvent<ArrayBuffer>) => { // Zero-copy transfer: binary buffer transferred directly without serialization const incomingData = new Float32Array(msg.data); const currentHead = Atomics.load(stateBuffer, 0); for (let i = 0; i < incomingData.length; i++) { const targetIndex = (currentHead + i) % BUFFER_SIZE; ringBuffer[targetIndex] = incomingData[i]; } Atomics.store(stateBuffer, 0, (currentHead + incomingData.length) % BUFFER_SIZE); }; }; export { sharedBuffer, stateBuffer }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Native-to-Webview Zero-Copy TypedArray Bridge Invariant

Capacitor 7 Native-to-Webview Zero-Copy TypedArray Bridge Invariant defines an industrial-grade behavioral standard for mobile engineering. Mandates bounded zero-copy buffer transfers or SharedArrayBuffer ring-buffers via Web Workers for high-frequency native telemetry in Capacitor 7. Eliminates JSON bridge serialization overhead, GC thrashing, and UI main-thread frame drops during sensor, IMU, audio, and biometric data ingest. 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: Serializing Continuous High-Frequency Sensor Telemetry as JSON Across the Capacitor Bridge 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	Serializing Continuous High-Frequency Sensor Telemetry as JSON Across the Capacitor Bridge	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 emit high-frequency (>30Hz) sensor or biometric samples through standard Capacitor `notifyListeners` using JSON objects.

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.