# Systematic LT Protocol & Performance Suite Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Accelerate optical air-gapped data transfer speeds (targeting ~10–25 KB/sec) by implementing a Systematic LT Fountain protocol, offscreen canvas frame pre-rendering, and high-throughput speed presets.

**Architecture:** Update `lt_engine.js` with systematic single-block Phase 1 encoding ($s = 1 \dots K$) and rateless Phase 2 XOR drops ($s > K$). Upgrade `transmitter.html` with an offscreen image cache array to play QR frames at 15–30 FPS with zero DOM redraw latency, and add ⚡ Ultra Speed presets.

**Tech Stack:** Vanilla JavaScript (ES6+), HTML5 Canvas, `easy.qrcode.min.js`, `qr-scanner`, Node.js.

## Global Constraints
- Pure client-side JavaScript execution in browser.
- Backward-compatible binary packet layout and Base64 string encoding.
- Zero external runtime server dependencies.

---

### Task 1: Update LT Engine with Systematic Encoding & Unit Tests

**Files:**
- Modify: `lt_engine.js`
- Modify: `test_lt_engine.js`

**Interfaces:**
- Produces: `LTEngine.encodeFrameSystematic(sourceBlocks, seed, flags, filename)`

- [ ] **Step 1: Write failing unit test for Systematic LT Encoding**

In `test_lt_engine.js`, add Test 10:
```javascript
// Test 10: Systematic LT Encoding (Phase 1 vs Phase 2)
const sysBlocks = LTEngine.sliceSourceBlocks(new Uint8Array([10, 20, 30, 40, 50]), 1); // K = 5
const packet1 = LTEngine.encodeFrameSystematic(sysBlocks, 1, 0, null); // Phase 1 (Seed 1)
const drop1 = LTEngine.unpackPacket(packet1);
assert.strictEqual(drop1.payload[0], 10, "Seed 1 should encode block 0 directly");

const packet5 = LTEngine.encodeFrameSystematic(sysBlocks, 5, 0, null); // Phase 1 (Seed 5)
const drop5 = LTEngine.unpackPacket(packet5);
assert.strictEqual(drop5.payload[0], 50, "Seed 5 should encode block 4 directly");

const packet6 = LTEngine.encodeFrameSystematic(sysBlocks, 6, 0, null); // Phase 2 (Seed 6 > K)
const drop6 = LTEngine.unpackPacket(packet6);
assert.strictEqual(drop6.seed, 6, "Seed 6 should encode rateless drop");

console.log("SYSTEMATIC LT ENGINE TEST PASSED!");
```

- [ ] **Step 2: Run test to verify failure**

Run: `node test_lt_engine.js`
Expected: FAIL with "LTEngine.encodeFrameSystematic is not a function"

- [ ] **Step 3: Implement `encodeFrameSystematic` in `lt_engine.js`**

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

    let degree;
    let blockIndices;

    if (seed <= K) {
        degree = 1;
        blockIndices = [seed - 1];
    } else {
        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);
}
```
Export `encodeFrameSystematic` in `LTEngine` module return object.

- [ ] **Step 4: Run test to verify it passes**

Run: `node test_lt_engine.js`
Expected: PASS with "SYSTEMATIC LT ENGINE TEST PASSED!"

- [ ] **Step 5: Commit**

```bash
git add lt_engine.js test_lt_engine.js
git commit -m "feat: add Systematic LT encoding (Phase 1 single blocks & Phase 2 rateless drops)"
```

---

### Task 2: Implement Pre-rendered Frame Cache and Speed Presets in Transmitter

**Files:**
- Modify: `transmitter.html`

**Interfaces:**
- Consumes: `LTEngine.encodeFrameSystematic`, `LTEngine.uint8ArrayToBase64`

- [ ] **Step 1: Add Speed Presets UI & Pre-rendering Engine in `transmitter.html`**

In `transmitter.html`:
1. Add Preset buttons to UI: **Standard (5 FPS)**, **🚀 High Speed (10 FPS)**, **⚡ Ultra Speed (15 FPS)**.
2. Maintain `frameCache = []` (array of pre-rendered image Data URLs).
3. In `prepareMovie()`:
   - Slice payload into `sourceBlocks`.
   - Calculate total cache frames $N = \max(K \times 2, 60)$.
   - Display loading spinner while pre-rendering:
     ```javascript
     frameCache = [];
     for (let s = 1; s <= totalCacheFrames; s++) {
         const packet = LTEngine.encodeFrameSystematic(sourceBlocks, s, flags, filename);
         const b64 = LTEngine.uint8ArrayToBase64(packet);
         // Render offscreen via temporary QRCode instance and extract dataURL
         ...
         frameCache.push(dataUrl);
     }
     ```
4. In `playMovie()` / `renderSeed()`:
   - Swap `img.src = frameCache[seed - 1]` directly from memory without calling `new QRCode()` or DOM rebuilds.

- [ ] **Step 2: Test pre-rendered playback in browser**

Launch `python3 server.py 8443`, generate movie, and verify 15 FPS playback.

- [ ] **Step 3: Commit**

```bash
git add transmitter.html
git commit -m "feat: add offscreen frame pre-rendering and Ultra Speed presets to transmitter"
```

---

### Task 3: Optimize Receiver UI and Integration Verification

**Files:**
- Modify: `receiver.html`
- Modify: `test_receiver_integration.js`

- [ ] **Step 1: Optimize Receiver for Systematic Drops & High-FPS Scans**

In `receiver.html`:
1. Cache DOM cell elements (`chunkCells[i]`) during `initializeProgressGrid()` to eliminate high-frequency `document.getElementById()` DOM queries.
2. In `processScanResults()`, support `encodeFrameSystematic` packet processing.

- [ ] **Step 2: Update integration tests in `test_receiver_integration.js`**

Update `test_receiver_integration.js` to test systematic frame drops ($s = 1 \dots K$).

- [ ] **Step 3: Run integration test suite**

Run: `node test_receiver_integration.js`
Expected: PASS with "ALL RECEIVER INTEGRATION TESTS PASSED!"

- [ ] **Step 4: Commit**

```bash
git add receiver.html test_receiver_integration.js
git commit -m "perf: optimize receiver DOM cell caching and systematic drop handling"
```

---

### Task 4: Update Documentation and ADRs

**Files:**
- Modify: `README.md`
- Modify: `README.ko.md`
- Modify: `docs/adr/0001-animated-qr-code-frame-streaming.md`

- [ ] **Step 1: Update README and README.ko.md**

Update throughput benchmark tables (10–25 KB/sec), pre-rendering engine descriptions, and speed presets in English & Korean READMEs.

- [ ] **Step 2: Update ADR 0001**

Document the Systematic LT two-phase transmission strategy.

- [ ] **Step 3: Commit**

```bash
git add README.md README.ko.md docs/adr/
git commit -m "docs: update README and ADRs for Systematic LT performance suite"
```