@reicek/neataptic-ts 0.1.21 → 0.1.23

package/plans/ES2023 migration

@@ -5,17 +5,26 @@ Objective
 ---------
 Aggressively modernize the codebase to idiomatic ES2023, leveraging the latest TypeScript and JavaScript features to improve code clarity, expressiveness, and maintainability. As an educational library, it should serve as an example of modern coding practices.
 
+Roadmap status
+--------------
+This plan is part of `plans/Roadmap.md` Phase 0, but it starts after the current demo-structure work is complete.
+
+Current prerequisite work before broad mechanical modernization:
+- refine the active demo surfaces, especially `test/examples/flappy_bird`,
+- finish the SOLID split of `test/examples/asciiMaze`,
+- keep touched orchestration in `src/` strict about responsibility boundaries, substitutability, and DRY reuse.
+
 Guiding Principles
 ------------------
 1.  **Modern First**: Always prefer the most modern and expressive ES2023+ features where they improve clarity.
 2.  **Test-Driven Refactoring**: All changes will be validated against the existing comprehensive test suite (909+ tests). No new features will be added, but refactoring will be done with confidence that the public API and behavior remain unchanged.
 3.  **API Stability**: Maintain the existing public API contract. Syntactic changes must be behavior-preserving, as confirmed by passing tests.
-4.  **Memory Diligence**: Proactively use memory-saving techniques like memory pools and object reuse where appropriate.
+4.  **Scope Discipline**: Keep this plan focused on syntax, modules, and enforcement. Memory-management features and performance architecture belong in `plans/Memory_Optimization.md`.
 
 Phase Roadmap
 -------------
 *   **Phase 0: Baseline & Tooling**
-    *   **Status**: Not Started
+    *   **Status**: Queued behind current demo refactor work
     *   **Description**: Set up and configure linting and code style validation tools to enforce modern syntax.
 
 *   **Phase 1: Mechanical Syntax Upgrades**
@@ -30,15 +39,11 @@ Phase Roadmap
     *   **Status**: Not Started
     *   **Description**: Convert CommonJS `require()` statements to ES modules (`import`/`export`) and audit for import cycles.
 
-*   **Phase 4: Advanced Memory Management**
-    *   **Status**: Not Started
-    *   **Description**: Implement an optional `WeakRef`-based tracking system for large network populations to reduce memory pressure.
-
-*   **Phase 5: Automation & CI**
+*   **Phase 4: Automation & CI**
     *   **Status**: Not Started
     *   **Description**: Implement CI checks to enforce ES2023 style and prevent regressions.
 
-*   **Phase 6: Documentation**
+*   **Phase 5: Documentation**
     *   **Status**: Not Started
     *   **Description**: Update all project documentation, including `README.md` and contributor guidelines, to reflect the modernized codebase.
 

package/plans/Evolution_Training_Interoperability_Contracts.md

@@ -187,4 +187,4 @@ Acceptance:
 
 - Hybrid workflows are well-defined and reproducible.
 - Training integration does not require ad-hoc per-project glue.
-- Parameter mapping becomes a building block for export/worker features.
+- Parameter mapping becomes a later unification seam for export- and worker-adjacent tooling once those Phase 4 foundations exist.

package/plans/Flappy_Bird_Folder_Documentation_Pass.md

@@ -0,0 +1,53 @@
+# Flappy Bird Folder Documentation Pass
+
+## Purpose
+
+Run a folder-focused documentation pass across every README-owning folder under
+`test/examples/flappy_bird` so the generated documentation reads like a guided
+tour of the example architecture rather than a sparse export inventory.
+
+## Root
+
+- Split root: `test/examples/flappy_bird`
+- README inventory: 24 README-owning folders under the root
+- Nearest README reviewed: `test/examples/flappy_bird/README.md`
+- Parent README reviewed: `test/examples/README.md` if needed per step
+- Relevant plan: `plans/Interactive_Examples_and_Learning_Path.md`
+
+## Durable Rules
+
+- Keep the README inventory explicit and visible in the todo list.
+- Keep exactly one active README or README-owning folder at a time.
+- Do not hand-edit generated subfolder README files; improve source JSDoc and
+  regenerate docs.
+- Keep compatibility facades documented as facades, not as implementation sinks.
+- Prefer educational JSDoc that explains what, why, invariants, defaults, and
+  performance tradeoffs when those details help a learner understand the example.
+
+## Target Shape
+
+- Each README-owning folder has source JSDoc rich enough to generate a useful
+  README without manual rescue edits.
+- Compatibility facades explain where deeper responsibilities live.
+- Browser, evaluation, simulation, worker, and trainer boundaries read like a
+  coherent architecture map when browsed top-down.
+
+## Steps
+
+- [x] Step 1: Tidy the root `test/examples/flappy_bird` surface and verify the
+  README inventory-driven workflow.
+- [x] Step 2: Tidy the worker and trainer-facing folders.
+- [ ] Step 3: Tidy shared simulation, environment, constants, and evaluation
+  folders.
+- [ ] Step 4: Tidy browser-entry and its nested README-owning folders one by one.
+- [ ] Step 5: Regenerate docs, run focused validation, and record any durable
+  boundary notes that changed during the pass.
+
+## Done Criteria
+
+- Every README-owning folder in the inventory has been handled explicitly.
+- Generated README content is educational and boundary-aware.
+- The todo list reflects completion folder by folder.
+- Docs regeneration succeeds after documentation-affecting changes.
+- A later session can resume from this plan and the todo list without prior chat
+  history.

package/plans/Flappy_Evolution_Worker_Documentation_Pass.md

@@ -0,0 +1,58 @@
+# Flappy Evolution Worker Documentation Pass
+
+## Purpose
+
+Deepen the source JSDoc for the `test/examples/flappy_bird/flappy-evolution-worker`
+boundary so the generated folder README explains not only what each exported
+surface is called, but why the worker exists, how the protocol fits browser
+rendering, which pieces own simulation versus transport versus warm-start
+behavior, and what invariants matter when extending the example.
+
+## Root
+
+- Split root: `test/examples/flappy_bird/flappy-evolution-worker`
+- Nearest README reviewed: `test/examples/flappy_bird/flappy-evolution-worker/README.md`
+- Parent README reviewed: `test/examples/flappy_bird/README.md`
+- Relevant plan: `plans/Interactive_Examples_and_Learning_Path.md`
+
+## Durable Rules
+
+- Keep exactly one active step at a time.
+- Update this plan immediately after each completed step.
+- Do not hand-edit generated README files; improve source JSDoc and run docs.
+- Keep `flappy-evolution-worker.ts` orchestration-first and document helper
+  ownership clearly.
+- Treat the demo worker as a learning surface: documentation should teach the
+  message flow, deterministic simulation model, and packed-snapshot transport.
+
+## Target Shape
+
+- `test/examples/flappy_bird/flappy-evolution-worker/flappy-evolution-worker.ts`
+  remains the orchestration-first worker entrypoint.
+- Supporting files explain their responsibility in the generated README:
+  runtime setup, protocol routing, evolution, playback, simulation,
+  snapshots, warm-start, and transport contracts.
+- Public and README-visible symbols include conceptual JSDoc, brief examples
+  where behavior is non-obvious, and notes about defaults, invariants, or
+  performance tradeoffs when that context improves learning value.
+
+## Steps
+
+- [x] Step 1: Review the nearest README files, current worker surface, and the
+  relevant examples plan.
+- [x] Step 2: Enrich foundational worker service docs (`constants`, `errors`,
+  `runtime`, `protocol`, `evolution`, `playback`).
+- [x] Step 3: Enrich simulation and transport docs (`simulation.*`,
+  `snapshot.*`, `types`, `warm-start`, entrypoint helpers, and narrow tests).
+- [x] Step 4: Run docs regeneration and focused validation, then record the
+  finished boundary note.
+
+## Done Criteria
+
+- The generated worker README reads like a guided tour of the subsystem rather
+  than a sparse symbol index.
+- Each worker file has enough source JSDoc to explain its role in the folder.
+- Non-obvious contracts mention the important defaults, invariants, or
+  performance semantics.
+- Docs regeneration completes after the source comments are updated.
+- The next session can resume from this plan alone if another pass is needed.

package/plans/Interactive_Examples_and_Learning_Path.md

@@ -6,12 +6,16 @@ Reduce time-to-first-success by shipping a small set of **runnable examples** th
 
 - building networks (preconfigured + primitives)
 - evolving with NEAT
-- exporting inference
 - running in browser
 
+Phase note:
+
+- Phase 3 covers the starter learning path only.
+- Standalone export and worker examples are follow-on additions after the corresponding Phase 4 capabilities exist.
+
 ## Goals
 
-- G1: Provide a clear learning path: “hello world” → “evolution” → “export” → “workers”.
+- G1: Provide a clear learning path: “hello world” → “evolution” → “browser quickstart”, then extend it with “export” and “workers” once those features are shipped.
 - G2: Examples are runnable with minimal setup and are kept in sync with the public API.
 - G3: Examples serve as regression checks (lightweight smoke checks).
 
@@ -32,6 +36,9 @@ Reduce time-to-first-success by shipping a small set of **runnable examples** th
    - Run a tiny NEAT evolution loop.
 4. **Sequence (NARX)**
    - Demonstrate state handling + reset.
+
+### Later extensions (after Phase 4 capabilities land)
+
 5. **Standalone export**
    - Export inference module and run it.
 6. **Worker evaluation**
@@ -82,6 +89,7 @@ Acceptance:
 ### Step 4 — Document the learning path
 
 - Add a top-level doc that lists examples in recommended order.
+- Clearly mark export/worker examples as later-phase extensions so starter examples stay aligned with the roadmap.
 
 Acceptance:
 

package/plans/Memory_Optimization.md

@@ -259,7 +259,7 @@ Test Coverage (single expectation style): capacity growth, versioning, flags par
 
 Deferred (post‑Phase 3): chunked copy yield refinements (browser large slabs), adjacency→phenotype direct mapping (moved to caching phase), forward variance reduction (targeted in later phases once churn reduced).
 
-### Phase 3 Results (Final Validation Before HyperEvoDevo MorphoNEAT)
+### Phase 3 Results (Final Validation Before Later Track 1 Phases)
 
 Source: `test/benchmarks/benchmark.results.json` (latest history entry vs earliest recorded baseline in same file).
 
@@ -285,11 +285,11 @@ Notes:
 - Bytes/connection held constant (no regression) despite added optional slabs; gain omission and plasticity pay‑for‑use prevented per-connection inflation. This confirms the pay-for-use principle is working but highlights that progress on the bytes/connection reduction metric is dependent on Phase 5 (Sparsity).
 - Field audit counts: Connection enumerable keys = 9 (stable), Node = 15 (stable) per benchmark `fieldAudit` confirmation.
 
-Results Notes & Next Step: For quantitative deltas see table above; variance & invariant consolidation detailed in Phase 3 Conclusion below. Proceed to HyperEvoDevo MorphoNEAT work with stable slab foundation.
+Results Notes & Next Step: For quantitative deltas see table above; variance & invariant consolidation detailed in Phase 3 Conclusion below. Proceed to Phase 4 centralized memory management and browser-validation work with a stable slab foundation. Track 2 Hyper work remains gated behind the Track 1 conditions defined earlier in this document.
 
 #### Phase 3 Conclusion (Extended Slab Packing & Validation)
 
-All planned Phase 3 memory layout features are implemented, documented, and validated by tests; the slab system now provides a pay‑for‑use foundation for forthcoming HyperEvoDevo MorphoNEAT caching & morphogenesis work.
+All planned Phase 3 memory layout features are implemented, documented, and validated by tests; the slab system now provides a pay-for-use foundation for later Track 1 caching work and eventual HyperEvoDevo MorphoNEAT phases once the Track 1 gate is satisfied.
 
 Delivered Enhancements (Recap):
 

package/plans/README.md

@@ -0,0 +1,63 @@
+# Plans Index
+
+This file is a lightweight index for the `plans/` folder.
+
+Purpose:
+
+- help agents and contributors choose the right plan document quickly,
+- keep architectural work aligned with roadmap intent,
+- avoid loading the entire `plans/` directory into context.
+
+Recommended reading order:
+
+1. Read `plans/README.md` for the map.
+2. Read `plans/Roadmap.md` when the task depends on sequencing, current phase status, or cross-plan priority.
+3. Read only the single most relevant detailed plan.
+4. Read one additional related plan only when the task clearly spans two initiatives.
+5. Read `plans/neat.plans.md` for the core NEAT direction and current engineering baseline when the task touches architecture or evolutionary correctness.
+
+Selection guide:
+
+- `plans/neat.plans.md`: core NEAT correctness, innovation tracking, crossover alignment, speciation invariants.
+- `plans/Roadmap.md`: dependency-aware execution order across all initiatives.
+- `plans/Architecture_Primitives_Node_Group_Layer.md`: first-class architecture-building primitives such as nodes, groups, and layers.
+- `plans/Browser_Build_and_CDN_Distribution.md`: browser packaging, CDN usage, and distribution ergonomics.
+- `plans/Construct_From_Parts_Graph_Assembly.md`: deterministic graph assembly and validated network construction from parts.
+- `plans/Evolution_Training_Interoperability_Contracts.md`: contracts between evolution workflows and gradient-based training.
+- `plans/HyperEvoDevoMorphoNEAT.md`: evo-devo and morphology-oriented research direction.
+- `plans/Interactive_Examples_and_Learning_Path.md`: runnable examples, onboarding flow, and learning-path improvements.
+- `plans/Memory_Optimization.md`: scaling, memory layout, and strategies for very large networks.
+- `plans/Network_Visualization_Export_Schema.md`: stable export schema for visualization and inspection tooling.
+- `plans/ONNX_EXPORT_PLAN.md`: ONNX export/import architecture and rollout phases.
+- `plans/Population_Save_Resume_and_Checkpointing.md`: checkpointing, persistence, save/resume workflows.
+- `plans/Preconfigured_Architectures_MLP_LSTM_GRU_NARX.md`: prebuilt architecture constructors and sequence-oriented builders.
+- `plans/Stable_Activation_Ordering_and_Explicit_IO_Roles.md`: deterministic execution ordering and explicit input/output roles.
+- `plans/Standalone_Inference_Export.md`: dependency-free exported inference runtime.
+- `plans/Turnkey_Multithread_Evaluation_API.md`: parallel evaluation API for Node and browser workers.
+- `plans/Worker_Friendly_Network_Serialization_Fastpath.md`: fast serialization path for worker-based evaluation.
+
+Task-to-plan trigger phrases:
+
+- NEAT correctness, innovation IDs, crossover, compatibility distance, speciation: `plans/neat.plans.md`
+- roadmap, sequence, dependency order, what comes first: `plans/Roadmap.md`
+- architecture builder, layer API, node/group primitives: `plans/Architecture_Primitives_Node_Group_Layer.md`
+- construct from parts, graph assembly, deterministic builder: `plans/Construct_From_Parts_Graph_Assembly.md`
+- browser bundle, CDN, browser-first usage: `plans/Browser_Build_and_CDN_Distribution.md`
+- ONNX, import/export interoperability: `plans/ONNX_EXPORT_PLAN.md`
+- visualization, schema, inspect network shape: `plans/Network_Visualization_Export_Schema.md`
+- checkpoint, resume, save population: `plans/Population_Save_Resume_and_Checkpointing.md`
+- workers, threads, parallel evaluation: `plans/Turnkey_Multithread_Evaluation_API.md`
+- worker serialization, transfer cost, fastpath: `plans/Worker_Friendly_Network_Serialization_Fastpath.md`
+- standalone runtime, exported inference file: `plans/Standalone_Inference_Export.md`
+- activation order, IO roles, deterministic execution: `plans/Stable_Activation_Ordering_and_Explicit_IO_Roles.md`
+- memory pressure, large networks, compact storage: `plans/Memory_Optimization.md`
+- hybrid evolution plus training, optimizer handoff: `plans/Evolution_Training_Interoperability_Contracts.md`
+- preconfigured models, MLP, LSTM, GRU, NARX builders: `plans/Preconfigured_Architectures_MLP_LSTM_GRU_NARX.md`
+- examples, tutorials, learning path, onboarding: `plans/Interactive_Examples_and_Learning_Path.md`
+- evo-devo, morphology, research-heavy extensions: `plans/HyperEvoDevoMorphoNEAT.md`
+
+Working rule:
+When a task changes code in a way that could conflict with one of these plans, mention the relevant plan in the working notes or final summary and call out any mismatch instead of silently diverging from the roadmap.
+
+Authority rule:
+For cross-plan sequencing and active priority, `plans/Roadmap.md` is authoritative. Detailed plans may contain future-state inventory, local sub-phases, or stale status notes; if a detailed plan appears to pull later-phase work earlier, follow `plans/Roadmap.md` unless both files are updated together.

package/plans/Roadmap.md

@@ -13,12 +13,17 @@ Where it helps, this roadmap uses **lanes** (things that can proceed in parallel
 
 ## Phase 0 — Hygiene + Refactor Baseline
 
-**Outcome:** keep iteration speed high and reduce refactor risk.
+**Outcome:** keep iteration speed high, reduce refactor risk, and finish the structural cleanup needed before broad mechanical modernization.
 
-- ES2023 modernization (ongoing, mechanical refactors + CI enforcement)
+- Demo refinement and learnability hardening [DONE]
+- asciiMaze SOLID split before ES2023 modernization [DONE]
+- Phase 0 remaining focus: ES2023 modernization (after the completed demo-structure pass)
+   - The `flappy_bird` reference split plan and the `asciiMaze` SOLID split plan are now both complete, so the remaining Phase 0 work is the repository-wide modernization pass and its validation gate.
+- ES2023 modernization (after the demo-structure pass; mechanical refactors + CI enforcement)
   - Plan: [ES2023 migration](ES2023%20migration)
+  - Scope note: this phase is syntax/module modernization plus CI enforcement. Memory-management or performance-feature work remains owned by [Memory_Optimization.md](Memory_Optimization.md).
 
-**Gate to Phase 1:** `npx tsc --noEmit -p tsconfig.json` and `npm test` are green after the refactor split.
+**Gate to Phase 1:** `flappy_bird` refinement is stable, the `asciiMaze` SOLID split is complete, and `npx tsc --noEmit -p tsconfig.json` plus `npm test` are green after the refactor pass.
 
 ## Phase 1 — Core Correctness + Determinism Foundations (Critical Path)
 
@@ -62,6 +67,9 @@ Where it helps, this roadmap uses **lanes** (things that can proceed in parallel
 
 **Notes:**
 
+- Phase 3 examples are the starter set only: Node hello/evolve flows plus one minimal browser quickstart once the browser bundle exists.
+- Examples that depend on standalone export or worker execution are follow-on additions in Phase 4 after those capabilities land.
+- Before expanding the examples catalog, choose the canonical examples home and decide whether `bench-browser/` is the browser-example host so demo work does not fragment.
 - Visualization can be implemented slightly earlier, but it becomes much more valuable once primitives/builders provide stable labels/roles.
 
 ## Phase 4 — Deployment + Parallel Evaluation (Inference Artifacts, Workers, Checkpoints)
@@ -84,6 +92,7 @@ Where it helps, this roadmap uses **lanes** (things that can proceed in parallel
 - Standalone export and worker payloads share an “inference IR” concept; building that once reduces duplication.
 - Multithread evaluation becomes straightforward after payloads exist.
 - Checkpointing and hybrid evaluation benefit from deterministic scheduling and a clear parameter/vector mapping.
+- Evolution-training parameter vectors are a later unification seam, not a blocker for standalone export or worker payloads unless that contract is deliberately split into an earlier mini-phase.
 
 ## Phase 5 — Scale & Performance (Memory Optimization Track)
 
@@ -98,6 +107,7 @@ This plan is large and can run as a **parallel lane** after Phase 1, but it shou
 
 - Start / continue Track 1 after Phase 1 is stable.
 - Prioritize improvements that directly benefit the worker payload + inference export paths (typed arrays, slabs, reuse) so Phase 4 gets faster “for free”.
+- If a detailed memory-plan subsection implies Hyper work can begin immediately after an intermediate Track 1 checkpoint, treat that as stale wording; Hyper remains gated by the Track 1 conditions below.
 
 **Gate to Phase 7 (Hyper):** Track 1 gates in `Memory_Optimization.md` are met (especially Phase 4–7 stability + variance/hardening).
 
@@ -124,6 +134,8 @@ This plan is large and can run as a **parallel lane** after Phase 1, but it shou
 
 ## Summary: Critical Path vs Parallel Lanes
 
+Current status: the project is still in **Phase 0**, with the demo-structure baseline complete (`flappy_bird` refinement and `asciiMaze` SOLID split) and repository-wide ES2023 modernization now the remaining Phase 0 focus.
+
 - **Critical path:** Phase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4
 - **Parallel lane A (performance):** [Memory_Optimization.md](Memory_Optimization.md) Track 1 after Phase 1 stabilizes
 - **Parallel lane B (interop):** [ONNX_EXPORT_PLAN.md](ONNX_EXPORT_PLAN.md) after Phase 2 (or earlier if scoped tightly)

package/plans/asciiMaze_SOLID_split.done.md

@@ -0,0 +1,130 @@
+# asciiMaze SOLID Split
+
+Purpose
+
+- Keep `test/examples/asciiMaze` aligned with the stronger modular example direction established by `test/examples/flappy_bird`.
+- Track only the durable, high-level structural work still needed to reach a strict SOLID, DRY, maintainable end state.
+- Keep this document resumable across sessions.
+- Keep this document short; detailed split design belongs in the implementation step.
+
+Progress rules
+
+- Use `[]` for a step that is not yet completed.
+- Use `[DONE]` immediately after finishing a step.
+- Update this document whenever the step order changes, a step is added, a step is removed, or the overall plan shifts.
+- Keep completed steps in place so progress is visible when resuming later.
+- Do not expand this file with temporary implementation detail; only record durable high-level progress.
+
+Current read
+
+- `asciiMaze` is already meaningfully decomposed compared with an older flat layout.
+- The remaining work is concentrated in a small number of large coordination and policy-heavy modules.
+- Confirmed current runtime orchestration order: `browser-entry.ts` bootstraps host services and invokes `EvolutionEngine.runMazeEvolution()`, `evolutionEngine.ts` normalizes and prepares the run, `evolutionEngine/evolutionLoop.ts` owns generation orchestration, `mazeMovement.ts` executes per-agent simulation, and `dashboardManager.ts` emits telemetry back to browser listeners and host globals.
+- The existing Step 2-8 order still matches that flow: split simulation policy first, then presentation, then browser host glue, then shared contracts, and only then collapse the remaining engine-side reporting and runtime adapter seams.
+- Step 2 is now finalized around the dedicated `mazeMovement/` folder boundary: shared simulation types live in `mazeMovement.types.ts`, constants in `mazeMovement.constants.ts`, reusable helpers in `mazeMovement.utils.ts`, pooled mutable infrastructure in `mazeMovement.services.ts`, runtime primitives in `mazeMovement/runtime/mazeMovement.runtime.ts`, action policy in `mazeMovement/policy/mazeMovement.policy.ts`, reward shaping in `mazeMovement/shaping/mazeMovement.shaping.ts`, result assembly in `mazeMovement/finalization/mazeMovement.finalization.ts`, and the public class facade now lives in `mazeMovement/mazeMovement.ts` with the old top-level file reduced to a compatibility re-export.
+- Step 3 is now finalized around the dedicated `dashboardManager/` folder boundary: shared dashboard types live in `dashboardManager.types.ts`, constants in `dashboardManager.constants.ts`, reusable formatting and calculation helpers live in `dashboardManager.utils.ts`, rendering/archive/telemetry orchestration now lives in `dashboardManager.services.ts`, and the public class facade now lives in `dashboardManager/dashboardManager.ts` with the old top-level file reduced to a compatibility re-export.
+- Step 4 is now finalized around the dedicated `browser-entry/` folder boundary: shared browser host contracts live in `browser-entry.types.ts`, host and curriculum constants live in `browser-entry.constants.ts`, DOM resolution and curriculum helpers live in `browser-entry.utils.ts`, host bootstrap/resize wiring/abort composition/globals compatibility/runtime orchestration now live in `browser-entry.services.ts`, and the public browser facade now lives in `browser-entry/browser-entry.ts` with the old top-level file reduced to a compatibility re-export.
+- Step 5 is now finalized around focused contract owners instead of the old `interfaces.ts` dependency bucket: evolution run/configuration and engine-internal helper contracts now live in `evolutionEngine/evolutionEngine.types.ts`, fitness evaluation contracts now live in `fitness.types.ts`, existing browser-entry/dashboardManager/mazeMovement module-owned `*.types.ts` files remain the primary owners for their split boundaries, and the top-level `interfaces.ts` file is now reduced to a narrow shared/core compatibility layer that re-exports moved contracts while retaining only the genuinely cross-cutting network, dashboard-abstraction, maze-run-result, and terminal-result shapes.
+- Step 6 is now finalized around a narrow engine-owned host adapter boundary: `evolutionEngine/evolutionEngine.types.ts` owns the `EvolutionHostAdapter` and stop-event contracts, `evolutionEngine/setupHelpers.ts` now reads cooperative pause state through that adapter instead of polling browser globals directly, `evolutionEngine/evolutionLoop.ts` now reports solve and stop outcomes through the adapter instead of dispatching browser behavior itself, and `browser-entry/browser-entry.globals.services.ts` owns the browser implementation that maps those engine events back to browser globals and solved-event compatibility behavior.
+- Step 7 is now finalized around owner-defined runtime and presentation contracts instead of browser-entry-local runtime shims: `dashboardManager/dashboardManager.types.ts` now owns the shared browser/non-browser presentation seam through `DashboardPresentationAdapter`, `DashboardTelemetryPayload`, and `AsciiMazeTelemetrySnapshot`; `browser-entry/browser-entry.types.ts` now consumes those dashboard-owned contracts for the public run handle and host services instead of defining its own `RuntimeDashboard`/`RuntimeEvolutionResult` adapters; and `evolutionEngine/evolutionEngine.types.ts` now owns the shared run-result and loose runtime helper contracts (`MazeEvolutionRunResult`, tracked network/genome helpers, species-history host) consumed by the engine facade, telemetry helpers, and population-dynamics helpers. The remaining compatibility-only runtime shapes are the browser platform shims in `browser-entry/browser-entry.types.ts` (`RuntimeWindow` and abort-signal helpers), not duplicated presentation or engine result seams.
+- Step 8 is now finalized around an engine-owned curriculum/refinement boundary: `evolutionEngine/curriculumPhase.ts` now owns phase-outcome interpretation, curriculum solve-threshold evaluation, and refined winner carry-over resolution; `browser-entry/browser-entry.curriculum.services.ts` now focuses on browser-only dimension scheduling, animation-frame pacing, and lifecycle completion; and `asciiMaze.e2e.test.ts` now reuses the same engine-owned helper instead of re-implementing winner-refinement carry-over locally. The remaining compatibility surface is the underlying `networkRefinement.ts` implementation, which stays reusable behind the engine-owned curriculum helper rather than being called directly by browser-entry.
+- Step 9 is now finalized around final-shape validation rather than further splitting: the folder-owned boundaries remain `mazeMovement/`, `dashboardManager/`, `browser-entry/`, and `evolutionEngine/`; the top-level compatibility files remain intentionally narrow for stable imports; the engine facade now explicitly documents `resolveMazeEvolutionPhaseOutcome` as a compatibility export owned by `evolutionEngine/curriculumPhase.ts`; and the required final validations succeeded with `npx tsc --noEmit -p tsconfig.json` and `npm run docs`.
+
+Split standard
+
+- Large or multi-responsibility example files should not be split into a growing pile of sibling files at the same level.
+- When a main file becomes a real module boundary, split it into a dedicated folder that keeps orchestration, contracts, helpers, constants, errors, and services together.
+- The exported main surface should remain easy to find and should keep the module's public orchestration flow.
+
+Required naming pattern
+
+- For a main module named `module`, prefer:
+- `module/module.ts`
+- `module/module.utils.ts`
+- `module/module.types.ts`
+- `module/module.errors.ts`
+- `module/module.services.ts`
+- `module/module.constants.ts`
+
+- For a nested sub-module named `sub-module` inside `module`, prefer:
+- `module/sub-module/module.sub-module.ts`
+- `module/sub-module/module.sub-module.utils.ts`
+- `module/sub-module/module.sub-module.types.ts`
+- `module/sub-module/module.sub-module.errors.ts`
+- `module/sub-module/module.sub-module.services.ts`
+- `module/sub-module/module.sub-module.constants.ts`
+
+Naming intent
+
+- `*.ts`: main orchestration or primary public surface for that module boundary.
+- `*.utils.ts`: pure or mostly pure helpers that do not define the module's main orchestration.
+- `*.types.ts`: focused types, DTOs, interfaces, and narrow contracts.
+- `*.errors.ts`: named error classes and error helpers local to the module.
+- `*.services.ts`: side-effecting or stateful service helpers used by the orchestration layer.
+- `*.constants.ts`: named constants and lookup tables local to the module.
+
+Boundary rules
+
+- Do not create dedicated folders for trivial files that are already small and single-purpose.
+- Do create a dedicated folder once a file becomes a real subsystem with multiple helper categories.
+- Keep the top-level `module/module.ts` file orchestration-first rather than turning it into another utility bucket.
+- Prefer subfolders when a subsystem inside a module grows into its own concern, instead of continuing to append helper files to the parent module folder.
+- Keep runtime-host glue, domain policy, rendering, telemetry, and shared contracts in separate files once they stop being tiny.
+
+asciiMaze target shape
+
+- `evolutionEngine.ts` should continue toward a dedicated `evolutionEngine/` orchestration-first module, which is already the correct direction.
+- `mazeMovement.ts` should move toward a dedicated `mazeMovement/` folder rather than being split into multiple top-level siblings.
+- `dashboardManager.ts` should move toward a dedicated `dashboardManager/` folder with rendering, archive, telemetry, and formatting boundaries.
+- `browser-entry.ts` should move toward a dedicated `browser-entry/` folder that separates host bootstrap, runtime orchestration, globals compatibility, and resize behavior.
+- `interfaces.ts` should be replaced by narrower module-local `*.types.ts` files plus a smaller shared contract surface where truly needed.
+
+High-level gaps
+
+- `mazeMovement.ts` is still a god module.
+- It mixes simulation state, pooled buffers, action policy, exploration heuristics, reward shaping, saturation handling, and result finalization.
+- Shared static mutable state in `mazeMovement.ts` weakens substitutability, test isolation, and future worker-safe reuse.
+- When split, this should become a dedicated `mazeMovement/` folder instead of several new top-level files.
+
+- `browser-entry.ts` still combines host bootstrapping with runtime policy.
+- It currently handles DOM lookup, logger wiring, dashboard setup, resize behavior, abort composition, curriculum progression, best-network carry-over, compatibility globals, and auto-start behavior.
+- This should be split into smaller host/runtime/bootstrap services so the browser entry becomes thin orchestration only.
+- When split, prefer a dedicated `browser-entry/` folder with runtime, host, globals, and resize sub-areas.
+
+- Runtime shape adapters are now mostly centralized in owning module boundaries.
+- Engine-side loose runtime helper contracts now live in `evolutionEngine/evolutionEngine.types.ts`, and browser/non-browser presentation contracts now live in `dashboardManager/dashboardManager.types.ts`.
+- Remaining runtime-specific shapes are limited to browser platform compatibility helpers rather than duplicated presentation or evolution-result adapters.
+
+- Browser and non-browser presentation concerns are now more parallel.
+- Host-specific browser wiring now depends on the shared dashboard-owned presentation model instead of re-declaring telemetry and redraw seams locally.
+- Remaining follow-up work is concentrated in refinement, curriculum, and evolution orchestration boundaries rather than presentation-contract drift.
+
+- Refinement, curriculum progression, and evolution orchestration now have clearer owners.
+- The engine-owned curriculum helper interprets completed run results and refines carry-over winners, while browser-entry stays focused on host scheduling and maze-dimension progression.
+- Future changes to winner refinement or curriculum carry-over policy should now land in the engine boundary instead of cross-cutting browser-entry and curriculum-style callers.
+
+Execution steps
+
+- [DONE] Step 1: Audit the remaining `asciiMaze` coordination-heavy surfaces and confirm the execution order across `mazeMovement`, `dashboardManager`, `browser-entry`, shared contracts, and engine-side reporting seams.
+- [DONE] Step 2: Split `mazeMovement.ts` into a dedicated `mazeMovement/` module boundary so simulation state, pooled buffers, action policy, exploration heuristics, reward shaping, saturation handling, and result finalization stop accumulating in one file.
+- [DONE] Step 3: Split `dashboardManager.ts` into a dedicated `dashboardManager/` module boundary so live rendering, solved-archive rendering, telemetry aggregation, bounded history storage, event emission, and formatting evolve behind focused files.
+- [DONE] Step 4: Thin `browser-entry.ts` into a dedicated `browser-entry/` module boundary so host bootstrap, runtime orchestration, globals compatibility, and resize behavior evolve independently.
+- [DONE] Step 5: Decompose `interfaces.ts` into focused module-owned `*.types.ts` files and leave behind only the smallest shared contract surface that is still truly cross-cutting.
+- [DONE] Step 6: Remove browser-facing solve, stop, and pause side effects from engine internals so `evolutionEngine` reports through a narrower adapter or reporting boundary instead of touching host behavior directly.
+- [DONE] Step 7: Consolidate scattered runtime shape adapters and presentation seams so browser and non-browser paths depend on clearer shared contracts rather than ad hoc local `Runtime*` compensating interfaces.
+- [DONE] Step 8: Recheck refinement, curriculum, and evolution boundaries so follow-up changes do not reintroduce cross-cutting orchestration drift after the earlier splits.
+- [DONE] Step 9: Validate the final shape by checking naming consistency, folder ownership, generated-doc expectations, and TypeScript/build health.
+
+Execution expectation
+
+- Each major split should create a dedicated folder first, then move one helper category at a time.
+- Preserve the public entry surface in the main module file inside that folder.
+- Avoid introducing one-off naming styles for each refactor; use the module and sub-module naming pattern above.
+
+Done criteria
+
+- No single demo file remains the obvious coordination sink for multiple unrelated responsibilities.
+- Host glue, simulation policy, telemetry aggregation, and rendering each have clear module boundaries.
+- Shared contracts are focused enough that runtime-specific adapters stop proliferating.
+- The example remains educational, but the top-level flow becomes orchestration rather than implementation-heavy.
+- Dedicated folders, file names, and subfolder names follow one predictable pattern instead of ad hoc split layouts.

package/plans/flappy_bird_SOLID_split.done.md

@@ -0,0 +1,67 @@
+# flappy_bird SOLID Split
+
+Purpose
+
+- Keep `test/examples/flappy_bird` as the reference demo for SOLID, modular example work.
+- Keep this document resumable across sessions.
+- Keep this document high level only.
+- Keep implementation details, temporary file maps, and short-lived decisions in the chat session rather than in this file.
+
+Progress rules
+
+- Use `[]` for a step that is not yet completed.
+- Use `[DONE]` immediately after finishing a step.
+- Update this document whenever the step order changes, a step is added, a step is removed, or the overall plan shifts.
+- Keep completed steps in place so progress is visible when resuming later.
+- Do not expand this file with temporary implementation detail; only record durable high-level progress.
+
+Split standard
+
+- Large or multi-responsibility demo files should not grow into a wider pile of sibling files at the same folder level.
+- When an area becomes a real subsystem, move it into a dedicated folder that keeps orchestration, contracts, helpers, constants, errors, and services together.
+- Keep the main exported module file as the easiest entry point and keep it orchestration-first.
+- Prefer dedicated subfolders once a subsystem has clear internal categories.
+- Preserve domain-scoped constants instead of recentralizing them.
+
+Naming pattern
+
+- Main module pattern:
+- `module/module.ts`
+- `module/module.utils.ts`
+- `module/module.types.ts`
+- `module/module.errors.ts`
+- `module/module.services.ts`
+- `module/module.constants.ts`
+
+- Nested sub-module pattern:
+- `module/sub-module/module.sub-module.ts`
+- `module/sub-module/module.sub-module.utils.ts`
+- `module/sub-module/module.sub-module.types.ts`
+- `module/sub-module/module.sub-module.errors.ts`
+- `module/sub-module/module.sub-module.services.ts`
+- `module/sub-module/module.sub-module.constants.ts`
+
+Execution steps
+
+- [DONE] Step 1: Audit `browser-entry` utility surfaces and confirm which broad files still need dedicated subfolder splits.
+- [DONE] Step 2: Continue the `browser-entry/playback/` split so playback orchestration, rendering support, and snapshot interpretation stay in focused module-owned files.
+- [DONE] Step 3: Continue the `browser-entry/visualization/` split so visualization orchestration, layout, rendering, and interpretation responsibilities stay separate.
+- [DONE] Step 4: Continue the `browser-entry/network-view/` split so layout, color semantics, labeling, and draw-time interpretation do not collapse into one broad utility surface.
+- [DONE] Step 5: Continue the `browser-entry/host/` split so DOM assembly stays compositional and host setup does not keep accumulating in one utility file.
+- [DONE] Step 6: Keep `trainer/trainer.ts` orchestration-first by moving reporting, policy, planning, and stop-control details behind trainer-owned helpers and services.
+- [DONE] Step 7: Keep the worker entry surface thin by preserving `flappy-evolution-worker` as a protocol-first boundary with playback, simulation, evolution, and runtime details behind worker-owned modules.
+- [DONE] Step 8: Continue splitting `simulation-shared` observation assembly so shared observation logic does not reform into a broad policy hub.
+- [DONE] Step 9: Recheck the browser visualization and network-view path for responsibility drift after the earlier splits, and realign any overlap back into explicit module boundaries.
+- [DONE] Step 10: Validate the final shape by checking naming consistency, folder ownership, generated-doc expectations, and TypeScript/build health.
+- [DONE] Step 11: Extract playback background composition into a dedicated background submodule so sky, horizon, and future ground parallax can evolve independently.
+- [DONE] Step 12: Extract host resize orchestration, layout math, and DOM mutation helpers into a dedicated `host/resize/` submodule so responsive layout policies evolve without bloating the host root.
+- [DONE] Step 13: Extract playback starfield contracts and tile-render mechanics into dedicated starfield-owned files so cache orchestration stays thin and reusable.
+- [DONE] Step 14: Extract evaluation rollout orchestration into a dedicated `evaluation/rollout/` submodule so runtime state, policy, shaping helpers, and rollout-local contracts evolve behind one stable public entry.
+
+Done criteria
+
+- Browser runtime files read as orchestration over focused services rather than large utility buckets.
+- Trainer and worker entrypoints stay thin, with domain logic living behind explicit service boundaries.
+- Visualization, observation, playback, and host setup each evolve independently without overlapping responsibility.
+- Dedicated folders, file names, and subfolder names continue following one predictable pattern instead of drifting into ad hoc layouts.
+- The demo remains the stronger reference shape that other examples can copy and resume cleanly.