# Design Specification: Systematic LT Protocol & Performance Suite

* **Date**: 2026-08-07
* **Status**: Approved
* **Target Repository**: `qrcode_transceiver`

---

## 1. Executive Summary

This design specification upgrades `qrcode_transceiver` with a **Systematic LT Fountain Protocol**, **Offscreen Canvas Animation Pre-rendering**, and **High-Throughput Speed Presets** to maximize optical air-gapped data transfer rates (targeting ~10–25 KB/sec).

---

## 2. Systematic LT Protocol Engine

In systematic mode, transmission is divided into two phases:

### Phase 1: Systematic Single Blocks ($s = 1 \dots K$)
For seeds $s = 1 \dots K$:
- Degree $d = 1$.
- Target block index $b = s - 1$.
- Encodes exact single source block $b$ directly.
- **Benefit**: Zero-overhead reception ($1.00 \times K$) under clean camera conditions.

### Phase 2: Rateless Fountain Drops ($s > K$)
For seeds $s > K$:
- PRNG: `Mulberry32(s)`.
- Degree $d \sim \mu(d)$ sampled from Robust Soliton distribution.
- Encodes XOR combinations of $d$ blocks.
- **Benefit**: Provides rateless recovery if any Phase 1 frames are dropped.

```javascript
function encodeFrameSystematic(sourceBlocks, seed, flags, filename) {
    const K = sourceBlocks.length;
    const L = sourceBlocks[0].length;

    let degree;
    let blockIndices;

    if (seed <= K) {
        // Phase 1: Systematic single block (1-indexed seed)
        degree = 1;
        blockIndices = [seed - 1];
    } else {
        // Phase 2: Rateless Robust Soliton XOR drop
        const cdf = RobustSoliton(K);
        const prng = Mulberry32(seed);
        degree = sampleDegree(cdf, prng);
        blockIndices = sampleBlocks(K, degree, prng);
    }

    const xorPayload = new Uint8Array(L);
    for (const idx of blockIndices) {
        const b = sourceBlocks[idx];
        for (let i = 0; i < L; i++) {
            xorPayload[i] ^= b[i];
        }
    }

    return packPacket(seed, K, L, flags, filename, xorPayload);
}
```

---

## 3. Offscreen Canvas Animation Pre-rendering

To eliminate DOM redraw latency during high-FPS playback:

1. When **Generate Movie** is clicked:
   - Compute source blocks $K$ and total frame count $N = \max(K \times 2, 60)$.
   - Allocate `frameCache = []`.
   - Loop $s = 1 \dots N$, encode packet, convert to Base64, and render QR image using `easy.qrcode.min.js`.
   - Store rendered image data URLs in `frameCache[s - 1]`.
2. During playback (`playMovie()`):
   - Cycle through `frameCache[currentFrameIndex]` via `requestAnimationFrame` or `setInterval`.
   - Swap `<img>` tag `src` directly without triggering `new QRCode()` or DOM rebuilding.
   - Achieves 15–30 FPS animation with zero CPU stutter.

---

## 4. High-Throughput Presets

Presets added to `transmitter.html`:

| Preset | QR Version | Block Size $L$ | FPS | Speed |
| :--- | :--- | :--- | :--- | :--- |
| 🐢 Standard | Version 10 | 234 Bytes | 5 FPS | ~1.1 KB/s |
| 🚀 High Speed | Version 20 | 584 Bytes | 10 FPS | ~5.8 KB/s |
| ⚡ Ultra Speed | Version 30 | 1084 Bytes | 15 FPS | ~16.2 KB/s |

---

## 5. Verification & Test Plan

1. **Unit Test Systematic LT Engine**: Verify seeds $1 \dots K$ produce degree-1 drops and seeds $> K$ produce Soliton XOR drops in `test_lt_engine.js`.
2. **Pre-rendering Test**: Verify `frameCache` pre-renders correctly and plays smoothly at 15 FPS.
3. **Speed & Reception Verification**: Measure end-to-end transfer time for 50 KB file across optical link.