Web → ESP32 Migration

The process freezes a contract first and replaces the runtime second. Every stage has host or device evidence, so drift is found before the full firmware is complete.

M0 / Hardware lock and recoverable environment

1. Confirm exact SKU, resolution, panel, touch, IMU, Flash/PSRAM and official demos.
2. Read all 16 MiB of device Flash and store a SHA-256 rollback point.
3. Install ESP-IDF in isolation and build/flash the vendor BSP example first.
4. Leave irreversible security features disabled.

The original-image backup lives at pocket-star/firmware/backups/pre-migration-full-flash.bin, SHA-256 e24913…a065651, and is intentionally not tracked by Git.

M1 / Display, touch and performance baseline

• Initialize CO5300 at fixed 466×466 RGB565.
• Read CST9217 checkcode, ProjectID and coordinate range.
• Record full-refresh FPS, render/present time, heap and PSRAM.
• Draw a test pattern before game assets so driver faults are not misdiagnosed as renderer faults.

M2 / Pure C++ game core

Port state/economy/progression/engine into host-testable C++ without LVGL. Eleven browser golden snapshots align to 1e-10 before UI work begins.

M3 / Static SEED vertical slice

Pack PNG and fonts, render one fixed SEED, and compare browser and C++ RGB565 output. This freezes byte order, font baseline, alpha composition and 1:1 pixels.

M4 / Three pages and gesture transactions

Port navigation, tap/hold, edge detents, SHOP cards and orbit preview/commit. Host tests cover center crossing, annulus re-entry, cancellation latch and multiple detents.

M5 / Full assets, effects and incremental rendering

Integrate 111 frames, particles, callouts and three FX families. Start with a correct full frame, then add pixel diff, semantic dirty regions and clipped rendering one layer at a time. Every optimization remains pixel-identical to the full reference.

M6 / Device services and product behavior

Integrate QMI8658, PCF85063, NVS, AXP2101, battery, settings, ambient, audio and PWR. Explicitly exclude or map web-only virtual controls instead of leaving fake device UI.

v7 increment

v7 extends the signed-off v6 base with three-stage hold/burst, integer-band tilt, the black settings instrument, scoped battery, ambient-display toggle, strict first-input wake, SHOP preview/commit, edge rebase, audio and safe PWR sequences.

Definition of Done

• Economy, gesture thresholds and save migration pass host tests.
• Fixed three-page states achieve palette-pixel parity.
• Incremental multi-frame output equals full reference through effects.
• Device boot identifies chip, memory, display, touch, IMU, RTC, audio and NVS.
• Long runs show no WDT, assert, brownout, coredump or declining memory.
• Glass appearance, finger feel and speaker pressure remain explicit human acceptance items.