Runtime Modernization Roadmap (tracking)

[HsienW]

Why

This project should not become "another React Snake Game".

Its strongest portfolio position:

A framework-free browser game used to demonstrate game-loop design, deterministic state, rendering lifecycle, browser performance, Worker isolation, and OffscreenCanvas experiments.

Modernization path

Legacy Vanilla JS Game
        ↓
Baseline + regression protection
        ↓
Input / Simulation / State / Render separation
        ↓
Fixed-timestep runtime
        ↓
Deterministic state + seeded RNG + replay
        ↓
Renderer abstraction
        ↓
Canvas renderer + performance telemetry
        ↓
Stable public release
        ↓
Web Worker simulation experiment
        ↓
OffscreenCanvas experiment

Key rule: do not jump directly to Worker or OffscreenCanvas. Worker only becomes meaningful after simulation is independent from DOM. OffscreenCanvas only becomes meaningful after rendering is behind a Canvas-compatible renderer contract.

Target architecture

flowchart TD
    A["Keyboard / UI<br/>Input Adapter"] -->|Command| RT

    subgraph RT["Game Runtime"]
        direction TB
        C["Clock → Accumulator → Simulation Step"]
        C --> D["Rule / Collision"]
        C --> E["Event Log"]
        D --> F["Game State"]
        E --> G["Replay"]
    end

    RT -->|RenderSnapshot| H["Renderer Contract"]
    H --> I["DOM Renderer"]
    H --> J["Canvas Renderer"]
    J --> K["OffscreenCanvas Renderer<br/>[experimental]"]

Loading

Milestones & PR checklist

Tip: hover each line below and click Convert to issue to spin up the real issue — GitHub links it back to this tracking issue automatically. Then paste the matching body from the setup doc into the new issue, and assign its Milestone + Labels.

M0 — Legacy Baseline

• PR-00 chore(baseline): freeze legacy version and document current behavior #5
• PR-01 build(tooling): modernize development toolchain without runtime changes #6
• PR-02 test(baseline): add gameplay baseline and smoke test coverage #7

M1 — Runtime Core

• PR-03 refactor(input): convert keyboard events into buffered commands #11
• PR-04 refactor(state): define GameState / Simulation boundary #12
• PR-05 feat(runtime): add accumulator-based fixed-timestep GameLoop #13
• PR-06 refactor(runtime): explicit lifecycle state machine cleanup #14

M2 — Determinism

• PR-07 feat(random): add seeded RNG for deterministic food placement
• PR-08 feat(replay): record commands by simulation tick
• PR-09 feat(replay): deterministic replay runner
• PR-10 test(replay): add state-hash regression suite

M3 — Rendering

• PR-11 refactor(render): introduce renderer contract
• PR-12 refactor(render): wrap legacy implementation as DOMRenderer
• PR-13 feat(render): add DPR-aware Canvas renderer
• PR-14 fix(render): DPR / resize handling

M4 — Performance / Public Relaunch

• PR-15 feat(metrics): expose frame and simulation timing panel
• PR-16 test(perf): add deterministic benchmark scenario
• PR-17 docs: README refresh + live demo + CI → v2.0.0

M5 — Worker

• PR-18 feat(worker): define worker protocol
• PR-19 feat(worker): move authoritative simulation to worker runtime
• PR-20 test(worker): worker/main-thread parity tests
• PR-21 test(worker): worker benchmark and tradeoff report → v2.1.0

M6 — OffscreenCanvas

• PR-22 feat(render): OffscreenCanvas capability detection adapter
• PR-23 experiment(render): worker render mode (OffscreenCanvas)
• PR-24 feat(render): OffscreenCanvas fallback + diagnostics
• PR-25 docs(architecture): benchmark + architecture comparison notes → v2.2.0 (experimental)

Explicit non-goals

Do not let the project expand into:

• backend leaderboard
• login system
• WebSocket multiplayer
• NFT/game economy
• React rewrite
• full game engine
• ECS framework
• physics engine
• three separate workers
• complex asset pipeline
• unnecessary AI features

Agent / contributor handoff rules

1. Inspect current master before editing.
2. Preserve current gameplay before restructuring.
3. Do not introduce React or a game framework.
4. Do not introduce TypeScript unless explicitly approved later.
5. Do not merge build migration and runtime architecture rewrite in one change.
6. Every phase must have tests or a reproducible manual validation.
7. No benchmark claim without actual measured data.
8. No OffscreenCanvas work before Canvas renderer and Worker protocol exist.
9. Maintain fallback paths for all experimental runtime modes.
10. Keep diffs reviewable.