# ADR 0001: Animated QR Code Frame Streaming Protocol & LT Fountain Engine

* **Status**: Accepted (Updated)
* **Date**: 2026-08-07
* **Deciders**: Core Development Team

---

## Context

We require a reliable mechanism to transfer data between physically air-gapped devices (e.g. from a display monitor to a mobile camera) without establishing any wireless, cellular, wired, or network connection.

Static QR codes are constrained by maximum symbol capacity (e.g. QR Version 40 with Error Correction Level L can hold at most ~2,953 binary bytes). Files larger than a few kilobytes cannot fit inside a single QR code image.

Sequential chunking protocols suffer from severe optical stall vulnerabilities: if a single chunk frame is missed during camera scanning, the receiver must wait for the transmitter animation loop to cycle through all frames to capture the missing index.

---

## Decision

We decided to implement an **optical frame streaming protocol** powered by a **Systematic Luby Transform (LT) Fountain Code engine** ("QR Code Movie") and an **Offscreen Frame Pre-rendering Engine** where:
1. Payloads exceeding single-frame QR limits are sliced into $K$ equal source blocks of length $L$, calibrated for **Error Correction Level M** (15% Reed-Solomon fault tolerance) and camera-optimized module densities (Versions 10, 12, 15 capped at $77 \times 77$ modules).
2. The transmitter executes a **Two-Phase Transmission Strategy**:
   - **Phase 1 (Systematic Stream, seeds $1 \dots K$)**: Transmit direct degree-1 single blocks ($s=1..K$ maps directly to source block index $s-1$) with flag bit `0x04` (`isSystematic`). Receivers under clean optical conditions solve all $K$ blocks in exactly $K$ frames with zero BP decoding overhead.
   - **Phase 2 (Rateless Fountain Stream, seeds $> K$)**: Generates dynamic fountain droplets by sampling degree distributions via a **Robust Soliton distribution** and selecting source block indices using a deterministic **Mulberry32 PRNG**.
3. Each droplet's payload is packed into a raw 8-bit binary QR code frame (`MODE_8BIT_BYTE`).
4. An **Offscreen Canvas Pre-rendering Engine** pre-calculates $N = \max(K \times 2, 60)$ QR code frames into memory (`frameCache`), removing DOM/canvas generation bottlenecks and enabling smooth playback at shutter-synchronized speed presets:
   - **Standard (5 FPS)**: 200ms per frame.
   - **🚀 High Speed (7 FPS - Mobile Sweet Spot)**: 142ms per frame (optimal shutter-to-scan balance for mobile sensors).
   - **⚡ Ultra Speed (10 FPS)**: 100ms per frame.
   - Display sizing scaled up to **Huge (400px)** and **Max (450px)**.
5. The receiver runs a real-time **Belief Propagation (BP) decoder** with cached DOM progress grid elements that resolves degree-1 droplets immediately and propagates solved blocks across a bipartite graph. Once all $K$ source blocks are resolved, payload reconstruction completes immediately regardless of frame capture order or missed drops.

---

### Optical Density & Payload Calibration (Level M)

| Version | Matrix Size | Module Width (350px display) | Max Raw Packet | Block Size $L$ |
| :--- | :--- | :--- | :--- | :--- |
| **Version 1** | $21 \times 21$ | 16.6 px | 12 Bytes | 1 Byte |
| **Version 5** | $37 \times 37$ | 9.4 px | 60 Bytes | 44 Bytes |
| **Version 10** | $57 \times 57$ | 6.1 px | 158 Bytes | 142 Bytes |
| **Version 12** | $65 \times 65$ | 5.3 px | 204 Bytes | 188 Bytes |
| **Version 15** | $77 \times 77$ | 4.5 px | 272 Bytes | 256 Bytes |

---

## Consequences

### Positive
* **0% Reception Overhead in Clean Channels**: Systematic Phase 1 allows clean transmissions to complete in exactly $K$ frames without requiring degree $> 1$ linear combinations or matrix inversions.
* **Immunity to Missed Frames & Optical Blur**: Phase 2 rateless fountain droplets combined with Level M 15% error correction seamlessly cover lost frames, optical glare, motion blur, and tilt distortion.
* **Camera-Optimized Density & Reliable Throughput**: Capping symbol size at Version 15 ($77 \times 77$) maintains module pixel legibility on mobile cameras while achieving **1.1 – 2.7 KB/sec** throughput.
* **Scalable Data Size**: Transmits text and multi-megabyte binary files over a purely visual optical channel.
* **Zero Infrastructure & Air-Gap Security**: Operates entirely in modern web browsers with 100% optical air-gap isolation.

### Negative
* **Memory Overhead for Pre-rendering**: Caching $N = \max(K \times 2, 60)$ Data URLs in memory consumes transient browser RAM prior to playback.
* **Computational Overhead during Scanning**: BP decoding graph solving and bitwise XOR operations run in JavaScript during real-time video frame scanning.