# Design Specification: Ultimate Optical Reliability & Throughput Bundle

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

---

## 1. Executive Summary

This design specification addresses camera optical scanning bottlenecks by upgrading `qrcode_transceiver` with camera-optimized module densities (Versions 10, 12, 15), Error Correction Level M (15% error tolerance), shutter-synchronized framerate presets (5, 7, 10 FPS), and expanded display sizing (up to 450px).

---

## 2. Technical Architecture & Parameter Calibration

### 2.1 Camera-Optimized QR Versions & Block Sizes
To prevent module pixel blur on mobile and webcam sensors, maximum QR matrix dimensions are capped at Version 15 ($77 \times 77$ modules).

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

```javascript
function getChunkSizeForVersion(version) {
    // Safe max raw binary packet size per QR version at Level M (15% Error Correction)
    // Base64 string length = Math.ceil(rawBytes / 3) * 4 must remain strictly within Level M byte limits
    const safeRawCapacityMap = {
        1:  12,   // Base64 = 16 chars (Max QR V1 Level M = 14 B)
        5:  60,   // Base64 = 80 chars (Max QR V5 Level M = 84 B)
        10: 158,  // Base64 = 212 chars (Max QR V10 Level M = 213 B)
        12: 204,  // Base64 = 272 chars (Max QR V12 Level M = 272 B)
        15: 272   // Base64 = 364 chars (Max QR V15 Level M = 367 B)
    };
    let rawCapacity = 158; // Default for Auto mode (Version 10)
    if (version && safeRawCapacityMap[version]) {
        rawCapacity = safeRawCapacityMap[version];
    } else if (version && version !== 'auto') {
        if (version < 5) rawCapacity = 12;
        else if (version < 10) rawCapacity = 60;
        else if (version < 12) rawCapacity = 158;
        else if (version < 15) rawCapacity = 204;
        else rawCapacity = 272;
    }
    const headerLen = 16;
    return Math.max(1, rawCapacity - headerLen);
}
```

### 2.2 Error Correction Level M Upgrade
- Sets `correctLevel: QRCode.CorrectLevel.M` across `transmitter.html`.
- Provides **15% Reed-Solomon error correction**, enabling camera decoders to scan frames damaged by glare, tilt, or motion blur.

### 2.3 Shutter-Synchronized Speed Presets & Sizing
- **Speed Presets**:
  - **Standard (5 FPS)**: 200ms per frame.
  - **🚀 High Speed (7 FPS)**: 142ms per frame (**Mobile Sweet Spot**).
  - **⚡ Ultra Speed (10 FPS)**: 100ms per frame.
- **Display Sizing Options**:
  - Small (128px), Medium (192px), Large (256px), Extra Large (300px), **Huge (400px)**, **Max (450px)**.

---

## 3. Verification & Test Plan

1. **Unit Test Calibration**: Verify block size $L$ calculations for Versions 1, 5, 10, 12, 15 at Error Correction Level M in `test_lt_engine.js`.
2. **Integration Verification**: Verify 100% frame decode rate across 200+ frames using Level M Base64 packets in `test_receiver_integration.js`.