MASTER ROADMAP - HIGH LEVEL (v7 ADDITIVE)

Status Key

complete
[.] in progress
planned

Rules

repo structure work is now constrained to exact move-map BUILDs only
remaining structure normalization should avoid broad folder churn until active shared extraction and promotion-gate work stabilize
shared math is now a real active layer and should continue by exact-cluster extraction only
avoid broad repo-wide cleanup passes until the active lanes above are materially further along

Conservative Rebaseline (2026-04-12)

status updates in this revision are conservative and execution-backed
recent tool-host, asset-pipeline, debug-inspector, and launch-smoke lanes are reflected without broad scope expansion
templates/ cleanup was completed by relocating active template surfaces to tools/templates/ and removing the empty root templates/ directory

Strategic Layer

Learning System

phases form a complete learning path
each phase introduces one new concept cleanly
each sample has a clear teaching purpose
samples build progressively from prior phases
no overlapping concept samples without clear justification
advanced phases depend on mastered earlier phases
samples remain understandable as standalone learning units
sample naming stays aligned to phase numbering

Architectural Separation

engine contains reusable runtime logic only
shared contains reusable cross-domain helpers only
games contain game-specific implementation only
samples contain learning/demo logic only
tools contain editor/pipeline/debug-authoring logic only
no sample logic promoted directly into engine without stabilization
no tool logic promoted directly into engine without stabilization
games do not become the default location for engine experiments
dependency direction stays enforced across all refactors

Promotion Pipeline

sample proves concept
shared extracts reusable logic
engine receives stable abstraction
promotion requires multi-use reuse evidence
promotion requires stable public contract
promotion requires removal of sample-specific assumptions
promotion requires validation after extraction
promotion does not happen as a blind dedupe exercise

Productization Rule

do not create standalone showcase tracks in future roadmaps
fold showcase importance into the main feature or sample title when needed

Tooling Strategy

tools are created when they unblock engine/content progress
tools do not define engine behavior
tools share common IO/state/util layers where appropriate
tools remain organized under tools/
active tools list remains explicit
legacy tools remain isolated and visibly non-current
3D tools arrive when 3D capability needs them, not before
content pipeline tools arrive when asset complexity justifies them
no standalone showcase-only tool tracks
tools header accordion added to reduce vertical real-estate usage
tool-shell UI compaction is useful but does not replace tool-boundary normalization work
any follow-up tool UI cleanup should remain subordinate to shared-boundary and data-contract work

End State Vision

clean engine core
clean shared layer
games follow a standard structure
samples form a complete curriculum
tools support authoring/debug/content workflows
debug platform supports games, tools, and samples
network concepts are deterministic and explainable
2D capabilities are complete and reusable
3D capabilities are complete and reusable
productization/distribution is documented and repeatable

0. Workflow + Delivery Foundation

1. Repo Structure Normalization

Structure Targets

Recent Checkpoint Notes

broad import-path correction from engine/ to src/engine/ applied across remaining games/samples
partial retro smoke pass completed after path correction
additional post-move validation complete

2. Engine Core

2D Engine Capability

3. Shared Foundation (`src/shared`)

Duplicate / Rename Focus

asFiniteNumber unified
asPositiveInteger unified
isPlainObject unified
getState variants bucketed by domain
getSimulationState naming established where needed
getReplayState naming established where needed
getEditorState naming established where needed
sample/tool/runtime duplicates classified before move

Recent Consolidation Checkpoint

vector-domain toFiniteNumber promoted into src/shared/math/numberNormalization.js
vector-domain roundNumber promoted into src/shared/math/numberNormalization.js
state/sample toFiniteNumber consumers migrated to shared math
duplicated asNumber consumers migrated to shared math
Asteroids numeric sanitizers promoted into shared math
duplicated asObject / asArray consumers moved to shared utils
remaining number/string/id helpers still need exact-cluster normalization

4. State, Replay, Timeline, Authoritative Flow

Subcomponents

5. Debug Platform & Ecosystem

Track A - Debug Foundation

Dev Console (input + command execution)
Debug Overlay (visual panels)
Console â†” Overlay Boundary
Panel Registry
Data Providers (read-only model)
Operator Commands (control surface)
Panel Persistence

Track B - Promotion To Engine Layer

PLAN_PR_DEBUG_SURFACES_PROMOTION
BUILD_PR_DEBUG_SURFACES_PROMOTION
APPLY_PR_DEBUG_SURFACES_PROMOTION

Track C - Standard Debug Library

PLAN_PR_DEBUG_SURFACES_STANDARD_LIBRARY
BUILD_PR_DEBUG_SURFACES_STANDARD_LIBRARY
APPLY_PR_DEBUG_SURFACES_STANDARD_LIBRARY

Track D - Debug Presets

PLAN_PR_DEBUG_SURFACES_PRESETS
BUILD_PR_DEBUG_SURFACES_PRESETS
APPLY_PR_DEBUG_SURFACES_PRESETS

Track E - Advanced Debug UX

PLAN_PR_DEBUG_SURFACES_ADVANCED_UX
BUILD_PR_DEBUG_SURFACES_ADVANCED_UX
APPLY_PR_DEBUG_SURFACES_ADVANCED_UX

Track F - Game Integration

PLAN_PR_DEBUG_SURFACES_GAME_INTEGRATION
BUILD_PR_DEBUG_SURFACES_GAME_INTEGRATION
APPLY_PR_DEBUG_SURFACES_GAME_INTEGRATION
Sample game uses full debug platform
Toggle debug in production-safe mode
Performance-safe overlays
Build-time debug flags

Track I - Inspectors & Tooling

Track J - Engine Maturity

6. Samples Program

sample numbering normalization completed
sample formatting alignment completed
phase grouping normalized
samples/shared boundaries defined and used
sample index normalized to phase structure
sample-to-engine dependency cleanup completed
sample duplicate helper usage reduced
sample curriculum progression validated

Sample Phase Tracks

foundational phases normalized
tilemap / camera / rendering phases normalized
tool-linked sample phases normalized
network concepts / latency / simulation phase normalized

Dependency-Driven Sample Builds

7. Phase 13 - Network Concepts, Latency & Simulation

Track N - Network Sample Foundation

Track O - Host / Client Sample

Sample B - Host / Client Diagnostics
Host status panel data
Client status panel data
Authority / ownership visibility
Replication snapshot visibility
Divergence warning surface

Track P - Divergence / Trace Sample

Track Q - Network Debug Panels

Track R - Network Debug Commands

Track S - Readiness To Promote

Sample-backed provider validation
Sample-backed panel validation
Operator command validation
Debug-only gating validation
Promotion recommendation

Track T - Server Dashboard

Track U - Server Containerization

Recommended Execution Order

8. Games Layer

9. Tools

Existing Tools

TileMapEditor normalized
ParallaxEditor normalized
VectorMapEditor normalized
VectorAssetStudio normalized
Tool sample packs + dropdown loading (3 samples per active tool)

New Required Tools (By Dependency)

Tooling Strategy By Need

2D tool stabilization before 3D tool expansion
content pipeline tools after asset complexity justifies them
debug tools align with engine/debug maturity

10. Assets & Data Policy

shared asset policy defined at planning level
game asset ownership normalized
sample asset ownership normalized
tool demo asset ownership normalized
promotion criteria for shared assets enforced
asset duplication reduced
top-level shared asset strategy finalized if needed

11. Productization & Distribution

Track P - Product Samples / Demonstrations

Asteroids Debug Showcase
Breakout Debug Showcase

Track Q - UX Polish

Debug toggle indicator
Default preset auto-load
Open Debug Panel button
Inline mini help

Track R - Distribution And Packaging

Showcase landing page
Build packaging strategy
Asset bundling rules

Track S - Documentation And Adoption

Debug tour
Getting started guide
Example-driven docs

12. 2D Capability Track

camera systems stabilized
tilemap/runtime integration stabilized
collision patterns stabilized
enemy/hero/gameplay conventions stabilized
replay/state integration for 2D games stabilized
polished 2D reference game path established
2D reference game built

13. 3D Capability Track (Phase 16)

Phase 16 Description Alignment

phase-16 description updated in repo docs/index
phase-16 description kept separate from networking language

14. Testing & Validation

tests/ structure normalized
unit coverage aligned to engine/shared/games
integration coverage aligned to state/replay/rendering/tools
smoke validation aligned to samples/tools/games
fixtures/helpers organization normalized
move/refactor validation strategy documented
post-PR acceptance criteria consistently enforced

15. Legacy Reduction

legacy inventory completed
keep vs migrate vs future-delete decisions recorded
legacy class-retention policy marker policy defined
SpriteEditor_old_keep policy defined
archived notes policy defined
imports pointing to legacy paths reduced
roadmap for eventual legacy retirement defined
templates/ folder evaluated, relocated to tools/templates/, and root templates/ removed after validation

16. Documentation + Planning System

PR docs structure established
reports structure established
templates structure established
roadmaps folder recognized as tracker space
master roadmap committed and maintained
per-component roadmap slices added only when truly needed
structure normalization roadmap linked to future BUILD lanes
phase descriptions normalized repo-wide
naming policy documented

Dependency-Ordered Future Build Sequence

Active Execution Lanes

Finish current promotion-gate lane (BUILD => APPLY)
Apply repo structure normalization implementation plan
Extract / normalize shared utilities
Normalize phase-13 network concepts samples

Next Planning / Normalization Lanes

Apply master roadmap baseline
Normalize samples phase structure
Establish games/_template and normalize games layer
Normalize tools/shared and tool boundaries
Normalize assets/data ownership
Expand testing/validation structure

Repo Operator + Asset Conversion Scripting Lanes

Existing games asset folders updated so existing images / vectors / related runtime assets can be transformed into tool-editable data/ objects, with corresponding project JSON updates
Add the ability for a PowerShell script to create a new game from template, including a project scaffold for the tools
Add scripts to prep / update / delete the repo so it can be placed on a website
Add scripts to switch between Pay-as-you-go and Codex plan modes, and scripts to input API key material and validate it

Full Real-Network Capability Lane (Required Before 3D Execution)

real transport/session layer
authoritative live server runtime
replication/client application
playable real multiplayer validation
server hosting + Docker containerization
promotion/readiness gate
include samples for phase 13

3D Execution Dependency Gate

begin active phase-16 / 3D execution only after the full real-network capability lane is complete

Later Capability Lanes

FEATURE: Fullscreen Bezel Overlay System - Render game in full screen with optional bezel artwork layer (static or animated) surrounding the active playfield, preserving aspect ratio and supporting per-game/theme bezel assets without modifying core engine rendering.

Later Capability Lanes

Execute 2D capability polish lanes

Final Cleanup Lane

Reduce legacy footprint after replacements are proven
Execute templates/ relocation and root removal cleanup PR

Recommended Final Status Summary

current active execution lanes are 3 / 6 / 8
next planning lanes are 2 / 5 / 7 / 9 / 10
later capability lanes are 11 / 12
final cleanup lane is 13

Immediate Next High-Level Actions

continue exact-cluster shared extraction until the current lane reaches a stable stop point
finish active promotion-gate lane enough to remove it from half-active status
convert repo structure normalization into exact move-map BUILDs with explicit validation
re-baseline this roadmap after active execution lanes stabilize
split future implementation into small dependency-ordered PRs
relocate active template surfaces to tools/templates/ and remove the empty root templates/ directory

Deferred Infrastructure

asset naming normalization (trigger condition: start only when a new non-3D asset lane requires cross-game naming standardization beyond current stable ownership/pipeline conventions)
manifest discovery (trigger condition: start only when a new non-3D runtime/tool lane requires automatic manifest discovery beyond current explicit manifest wiring)

Recovery / Preserved Content

MASTER ROADMAP HIGH LEVEL (status updates only)

[x] fullscreen bezel overlay system (low priority, before next game)

17. 3D Activation, Validation, and Execution (Phase 16)

Impact Validation (FIRST - REQUIRED)

Validate no render loop regressions
Validate no timing model regressions
Validate no input system regressions
Confirm networking/runtime remains stable during 3D activation
Confirm 2D samples still run correctly after 3D activation work

3D Engine Foundation

Track H - 3D Debug Support

Sample Phase Tracks

3D phase normalized

Dependency-Driven Sample Builds

3D scene boot sample
3D camera orbit sample
3D movement sample
3D collision sample

Tooling Strategy By Need

3D prerequisite samples before advanced 3D tools

Prerequisite Samples

3D Scene Boot Sample
Camera Orbit Sample
3D Movement Sample
Basic Collision Sample

Core Sample Track (1601 - 1608)

Advanced 3D Samples (1609+ EXPANDED VALIDATION TRACK)

3D Capability Requirements

Later Capability Lanes

Execute phase-16 / 3D capability lanes (after full real-network capability lane completion)
Stabilize networking/runtime before 3D

18. Engine Finalization & Hardening (Deferred Execution)

Purpose: convert the built system into a clean, stable, production-grade engine after all major capability tracks are complete.
This is NOT a scaffolding phase � it is a consolidation + enforcement phase.

Scope Rules

additive only (no blind refactors)
no structural churn without move-map PRs
all changes must be validation-backed
no template-driven work

[x] Some games are actually samples/demos; identify and recommend a phase-xx move target.

[x] Lock APIs [x] Clean boundaries [x] Document contracts

Track A � Engine Usage Enforcement

verify all samples/ use engine systems (no local reimplementation)
verify all games/ use engine systems
migrate any local logic into engine/shared where appropriate
remove sample-specific logic from engine paths

Track B � Boundary Hardening

enforce engine vs shared vs game vs tool boundaries
eliminate cross-layer leakage
validate dependency direction rules across repo
remove accidental coupling

Track C � Contract Stabilization

finalize engine public APIs
finalize shared contracts
ensure selectors/providers are stable
remove unstable or experimental surfaces

Track D � Codebase Consistency

single class per file enforcement
eliminate import/export anti-patterns repo wide
remove duplicate helpers
normalize naming consistency

Track E � CSS & UI Normalization

flatten CSS layers
enforce shared UI classes
remove redundant styles

Track F � Docs System Cleanup

[x] Docs organization: classify all ./docs/ into buckets. [x] Arrange docs into classification buckets. [x] Any doc that is only move/rename/etc. should be deleted (verify content is in the correct doc before deleting).

classify all docs into buckets
consolidate duplicate docs - consolidate PRs for easier one-stop review, so one capability does not require reading many docs (for example, bezel/background); focus on what the capability does.
remove move-only historical docs (after validation)
align docs to feature-based structure

Track G � Repo Hygiene

[x] Remove imports to export (should not be import x, export x) [x] Other than templates (games/samples/tools), remove the .keep file, if the folder is empty, delete

remove unnecessary .keep files
remove empty folders
validate folder ownership rules
enforce clean repo structure

Track H � PR Consolidation Strategy

bundle related PRs into capability-level units
reduce multi-PR fragmentation
ensure each PR represents a complete capability

19. Architecture Maturity & Long-Term Stability (Deferred Execution)

Purpose: ensure the system is scalable, explainable, and extensible long-term.
This phase turns the engine into a platform, not just a project.

Scope Rules

no feature creation
no experimental work
only stabilization, validation, and extensibility

Track A � System Integration Validation

validate all major systems working together:
- rendering
- input
- physics
- state/replay
- networking
- debug platform
verify no hidden coupling
verify predictable system interaction

Track B � Runtime Lifecycle Validation

validate boot ? run ? shutdown lifecycle
validate hot reload / reset flows
validate error handling paths
validate long-running stability

Track C � Performance & Scaling

validate large scene performance
validate stress scenarios (1k+ entities)
validate memory stability
identify bottlenecks

Track D � Debug & Observability Maturity

ensure all systems expose debug data
ensure providers are complete and consistent
validate debug panels across systems
confirm production-safe debug toggling

Track E � Toolchain Validation

verify tools integrate cleanly with engine
validate asset pipelines end-to-end
validate editor ? runtime consistency
confirm no tool-specific logic leaks into engine

Track F � Sample & Game Validation

Organize/rebuild samples/ and games/ as if newly constructed, with proper classes/data in proper folders.
Simulated code (for example, some network samples) should be converted to real networks, with tests as needed.
verify all samples still function correctly
verify curriculum progression remains intact
validate games follow template strictly
confirm no regression across phases

Track G � Extensibility Readiness

validate plugin/extension patterns
validate adding new systems is clean
validate external integration points
ensure future phases can build cleanly

Track H � Final Stability Gate

full-repo validation sweep
zero regression requirement
contract freeze readiness
readiness for long-term maintenance mode

20. Production Readiness & System Stabilization

Track A ? Release Readiness

define release criteria
finalize build pipeline
validate deployment flow

Track B ? Stability & Monitoring

runtime error tracking
performance monitoring hooks
logging standardization

Track C ? Documentation Completeness

finalize developer docs
finalize tool documentation
validate onboarding flow

23. Engine Runtime Validation Sweep

validation sweep executed across samples, runtime, and engine boundaries (BUILD_PR_LEVEL_23_1)
integration fixes applied and validated for 23.1-reported runtime/guard gaps (BUILD_PR_LEVEL_23_2)
sample system validation and repair executed with post-fix clean sample launch/runtime checks (BUILD_PR_LEVEL_23_4)
sample index and routing normalization validated (BUILD_PR_LEVEL_23_5)

Level 8 — Schema-Driven First-Class Tool Normalization

Level 10 — Game Palette Completeness And Tool Input Alignment

Game palette completeness is normalized with manifest-owned palette data under game.manifest.json tool sections.
Tool input alignment contract is documented as toolInput = gameManifest.tools[toolId] (no game-owned file-path JSON input).
Palette standalone singleton correction is complete (game.manifest.json root palette, no tool-owned palettes).
Palette tool singleton + tool section metadata correction is complete (tools["palette-browser"].palette + metadata on all tool sections).
Games index Workspace Manager open-action browser test is complete (gameId + mount=game, legacy ?game= rejected, diagnostic check included).
tools/shared/asteroidsPlatformDemo.js shared-boundary audit is complete with move recommendation captured for follow-up.
Manifest payload expectation test + cleanup completed (no root legacy manifest blocks, no sourcePath, palette singleton enforced, Asteroids tool payloads pruned to active data domains).
Workspace Manager shared palette binding now hydrates from game.manifest.json tools["palette-browser"].palette (with root palette compatibility fallback only).

FilesExpand file tree

MASTER_ROADMAP_ENGINE.md

Latest commit

History

MASTER_ROADMAP_ENGINE.md

File metadata and controls

MASTER ROADMAP - HIGH LEVEL (v7 ADDITIVE)

Status Key

Rules

Conservative Rebaseline (2026-04-12)

Strategic Layer

Learning System

Architectural Separation

Promotion Pipeline

Productization Rule

Tooling Strategy

End State Vision

0. Workflow + Delivery Foundation

1. Repo Structure Normalization

Structure Targets

Recent Checkpoint Notes

2. Engine Core

2D Engine Capability

3. Shared Foundation (src/shared)

Duplicate / Rename Focus

Recent Consolidation Checkpoint

4. State, Replay, Timeline, Authoritative Flow

Subcomponents

5. Debug Platform & Ecosystem

Track A - Debug Foundation

Track B - Promotion To Engine Layer

Track C - Standard Debug Library

Track D - Debug Presets

Track E - Advanced Debug UX

Track F - Game Integration

Track G - Network / Multiplayer Debug

Track I - Inspectors & Tooling

Track J - Engine Maturity

6. Samples Program

Sample Phase Tracks

Dependency-Driven Sample Builds

7. Phase 13 - Network Concepts, Latency & Simulation

Track N - Network Sample Foundation

Track O - Host / Client Sample

Track P - Divergence / Trace Sample

Track Q - Network Debug Panels

Track R - Network Debug Commands

Track S - Readiness To Promote

Track T - Server Dashboard

Track U - Server Containerization

Recommended Execution Order

8. Games Layer

9. Tools

Existing Tools

New Required Tools (By Dependency)

Tooling Strategy By Need

10. Assets & Data Policy

11. Productization & Distribution

Track P - Product Samples / Demonstrations

Track Q - UX Polish

Track R - Distribution And Packaging

Track S - Documentation And Adoption

12. 2D Capability Track

13. 3D Capability Track (Phase 16)

Phase 16 Description Alignment

14. Testing & Validation

15. Legacy Reduction

16. Documentation + Planning System

Dependency-Ordered Future Build Sequence

Active Execution Lanes

Next Planning / Normalization Lanes

Repo Operator + Asset Conversion Scripting Lanes

Full Real-Network Capability Lane (Required Before 3D Execution)

3D Execution Dependency Gate

Later Capability Lanes

Later Capability Lanes

Final Cleanup Lane

Recommended Final Status Summary

Immediate Next High-Level Actions

Deferred Infrastructure

3. Shared Foundation (`src/shared`)