@reicek/neataptic-ts 0.1.26 → 0.1.27

package/test/examples/asciiMaze/evolutionEngine/docs.order.json

@@ -0,0 +1,10 @@
+{
+  "introFile": "evolutionEngine.types.ts",
+  "fileOrder": [
+    "evolutionEngine.types.ts",
+    "engineState.types.ts",
+    "evolutionLoop.ts",
+    "evolutionEngine.services.ts",
+    "sampling.ts"
+  ]
+}

package/test/examples/asciiMaze/evolutionEngine/evolutionEngine.types.ts

@@ -1,3 +1,90 @@
+/**
+ * Population-level runtime contracts for the ASCII Maze evolution engine.
+ *
+ * This folder is where one maze, one fitness story, and one NEAT controller
+ * turn into a repeatable training program. The public `EvolutionEngine` facade
+ * uses these contracts to normalize options, coordinate host callbacks, keep
+ * deterministic state reproducible, and decide when a curriculum phase has
+ * produced a winner worth carrying forward.
+ *
+ * The important distinction is scale. `mazeMovement/` explains one agent run.
+ * `fitness.ts` explains how that run is scored. `dashboardManager/` explains
+ * how progress is shown to a human. `evolutionEngine/` explains how many runs
+ * across many generations become one population-level search loop with stop
+ * reasons, telemetry, warm starts, and phase outcomes that the next maze can
+ * reuse.
+ *
+ * This file is the right chapter opening because it names the public nouns of
+ * that loop before the reader hits pooled scratch buffers or hot-path helpers.
+ * It answers four questions quickly: what a caller can configure, what a host
+ * may observe or interrupt, what result the engine returns, and which shared
+ * runtime contexts keep the hot path allocation-light.
+ *
+ * A useful mental model is to treat the engine as a control tower rather than
+ * the aircraft itself. The engine does not move the agent through one maze cell
+ * at a time. It schedules phases, batches generations, preserves deterministic
+ * state, and hands structured outcomes back to browser or terminal hosts.
+ *
+ * Read the chapter in three passes. Start here for the public contracts and the
+ * meaning of a run result. Continue to `engineState.types.ts` when you want the
+ * shared scratch and toggle state that keeps the loop cheap. Finish with
+ * `evolutionLoop.ts`, `evolutionEngine.services.ts`, and `sampling.ts` when you
+ * want the actual orchestration and telemetry mechanics.
+ *
+ * ```mermaid
+ * flowchart LR
+ *   classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+ *   classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+ *
+ *   Caller["Caller or host"]:::base --> Options["IRunMazeEvolutionOptions\nrun inputs"]:::base
+ *   Options --> Engine["EvolutionEngine facade\npopulation-level control"]:::accent
+ *   Engine --> Loop["generation loop\nevaluate mutate telemetry"]:::base
+ *   Loop --> Result["MazeEvolutionRunResult\nbest network + exit reason"]:::base
+ *   Result --> Phase["MazeEvolutionCurriculumPhaseOutcome\ncarry winner forward"]:::base
+ *   Engine --> Host["EvolutionHostAdapter\npause and stop hooks"]:::base
+ * ```
+ *
+ * ```mermaid
+ * flowchart TD
+ *   classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+ *   classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+ *
+ *   EngineFolder["evolutionEngine/"]:::accent --> Contracts["evolutionEngine.types.ts\npublic run contracts"]:::base
+ *   EngineFolder --> Scratch["engineState.types.ts\nshared scratch and toggles"]:::base
+ *   EngineFolder --> Loop["evolutionLoop.ts\nmain generation orchestration"]:::base
+ *   EngineFolder --> Services["evolutionEngine.services.ts\nand helpers"]:::base
+ *   EngineFolder --> Sampling["sampling.ts\nand telemetry support"]:::base
+ * ```
+ *
+ * For background reading on the staged difficulty idea behind the browser and
+ * curriculum-style runs, see Wikipedia contributors,
+ * [Curriculum learning](https://en.wikipedia.org/wiki/Curriculum_learning),
+ * which captures the broader teaching idea of solving easier tasks before
+ * harder ones.
+ *
+ * Example: describe the host adapter and reporting hooks the engine may call.
+ *
+ * ```ts
+ * const hostAdapter: EvolutionHostAdapter = {
+ *   isPauseRequested: () => window.asciiMazePaused === true,
+ *   handleStop: ({ reason, completedGenerations }) => {
+ *     console.log(reason, completedGenerations);
+ *   },
+ * };
+ * ```
+ *
+ * Example: sketch one engine run configuration before execution begins.
+ *
+ * ```ts
+ * const runOptions: IRunMazeEvolutionOptions = {
+ *   mazeConfig: { maze },
+ *   agentSimConfig: { maxSteps: 160 },
+ *   evolutionAlgorithmConfig: { popSize: 120, deterministic: true },
+ *   reportingConfig: { dashboardManager, logEvery: 5 },
+ * };
+ * ```
+ */
+
 import type Network from '../../../../src/architecture/network';
 import type { FitnessEvaluatorFn } from '../fitness.types';
 import type {

package/test/examples/asciiMaze/mazeMovement/README.md

@@ -1,10 +1,87 @@
 # mazeMovement
 
-Public MazeMovement facade for the dedicated mazeMovement module boundary.
+Episode-simulation boundary for one maze-controlled agent.
+
+This folder is where a policy stops being abstract logits and starts paying
+for local decisions. One run moves through perception, direction selection,
+collision-aware movement, shaping, and finalization until the agent reaches
+the exit or exhausts its step budget.
+
+The boundary exists because single-episode logic needs both honesty and
+inspectability. If movement rules, reward shaping, and stop conditions were
+scattered across fitness or evolution helpers, it would be much harder to
+tell whether poor results came from weak policy, thin observations, harsh
+shaping, or simple runtime edge cases.
+
+Read the folder as four cooperating shelves. `runtime/` builds perception,
+visit bookkeeping, and low-level state transitions. `policy/` converts raw
+outputs into concrete directional choices and exploration nudges. `shaping/`
+applies the score semantics that make sparse-goal navigation learnable.
+`finalization/` folds the finished path into one result the engine and
+fitness layers can compare.
+
+The public class stays class-based on purpose. Existing imports remain
+stable, but the real teaching value is now inside the split helpers. The
+facade tells the reader what the episode boundary promises; the subfolders
+explain how that promise is kept.
+
+Read this chapter in three passes. Start with `simulateAgent(...)` when you
+want the whole episode loop. Continue to `selectDirection(...)` and
+`moveAgent(...)` when you want the policy-to-action seam. Finish in the
+runtime, policy, shaping, and finalization folders when you need the exact
+bookkeeping or reward logic behind one run.
+
+```mermaid
+flowchart LR
+  classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+  classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+
+  Vision["vision and visit state"]:::base --> Policy["direction selection\nand exploration nudges"]:::accent
+  Policy --> Move["collision-aware movement"]:::base
+  Move --> Shaping["progress and penalty shaping"]:::base
+  Shaping --> Finalize["episode result\nfitness path progress"]:::base
+```
+
+```mermaid
+flowchart TD
+  classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+  classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+
+  MazeMovement["mazeMovement/"]:::accent --> Facade["mazeMovement.ts\npublic episode facade"]:::base
+  MazeMovement --> Runtime["runtime/\nvision and state"]:::base
+  MazeMovement --> Policy["policy/\naction choice"]:::base
+  MazeMovement --> Shaping["shaping/\nreward and penalties"]:::base
+  MazeMovement --> Finalization["finalization/\nresult folding"]:::base
+```
 
-The folder now owns runtime helpers, policy helpers, shaping helpers, and
-finalization logic. This file keeps the user-facing API in one place while
-the implementation stays split into focused helpers.
+For background on why direction selection talks about probabilities and
+entropy instead of only the raw logits, see Wikipedia contributors,
+[Softmax function](https://en.wikipedia.org/wiki/Softmax_function), which is
+the probability transform used by the action-diagnostics helper layer.
+
+Example: inspect the direction choice implied by one network output vector.
+
+```ts
+const directionStats = MazeMovement.selectDirection([0.4, 1.2, -0.3, 0.1]);
+
+console.log(directionStats.selectedDirection);
+console.log(directionStats.entropy);
+```
+
+Example: simulate one complete maze episode for a candidate network.
+
+```ts
+const result = MazeMovement.simulateAgent(
+  network,
+  encodedMaze,
+  startPos,
+  exitPos,
+  distanceMap,
+  160,
+);
+
+console.log(result.fitness, result.reachedExit);
+```
 
 ## mazeMovement/mazeMovement.types.ts
 

package/test/examples/asciiMaze/mazeMovement/mazeMovement.ts

@@ -1,9 +1,86 @@
 /**
- * Public MazeMovement facade for the dedicated mazeMovement module boundary.
+ * Episode-simulation boundary for one maze-controlled agent.
  *
- * The folder now owns runtime helpers, policy helpers, shaping helpers, and
- * finalization logic. This file keeps the user-facing API in one place while
- * the implementation stays split into focused helpers.
+ * This folder is where a policy stops being abstract logits and starts paying
+ * for local decisions. One run moves through perception, direction selection,
+ * collision-aware movement, shaping, and finalization until the agent reaches
+ * the exit or exhausts its step budget.
+ *
+ * The boundary exists because single-episode logic needs both honesty and
+ * inspectability. If movement rules, reward shaping, and stop conditions were
+ * scattered across fitness or evolution helpers, it would be much harder to
+ * tell whether poor results came from weak policy, thin observations, harsh
+ * shaping, or simple runtime edge cases.
+ *
+ * Read the folder as four cooperating shelves. `runtime/` builds perception,
+ * visit bookkeeping, and low-level state transitions. `policy/` converts raw
+ * outputs into concrete directional choices and exploration nudges. `shaping/`
+ * applies the score semantics that make sparse-goal navigation learnable.
+ * `finalization/` folds the finished path into one result the engine and
+ * fitness layers can compare.
+ *
+ * The public class stays class-based on purpose. Existing imports remain
+ * stable, but the real teaching value is now inside the split helpers. The
+ * facade tells the reader what the episode boundary promises; the subfolders
+ * explain how that promise is kept.
+ *
+ * Read this chapter in three passes. Start with `simulateAgent(...)` when you
+ * want the whole episode loop. Continue to `selectDirection(...)` and
+ * `moveAgent(...)` when you want the policy-to-action seam. Finish in the
+ * runtime, policy, shaping, and finalization folders when you need the exact
+ * bookkeeping or reward logic behind one run.
+ *
+ * ```mermaid
+ * flowchart LR
+ *   classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+ *   classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+ *
+ *   Vision["vision and visit state"]:::base --> Policy["direction selection\nand exploration nudges"]:::accent
+ *   Policy --> Move["collision-aware movement"]:::base
+ *   Move --> Shaping["progress and penalty shaping"]:::base
+ *   Shaping --> Finalize["episode result\nfitness path progress"]:::base
+ * ```
+ *
+ * ```mermaid
+ * flowchart TD
+ *   classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+ *   classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+ *
+ *   MazeMovement["mazeMovement/"]:::accent --> Facade["mazeMovement.ts\npublic episode facade"]:::base
+ *   MazeMovement --> Runtime["runtime/\nvision and state"]:::base
+ *   MazeMovement --> Policy["policy/\naction choice"]:::base
+ *   MazeMovement --> Shaping["shaping/\nreward and penalties"]:::base
+ *   MazeMovement --> Finalization["finalization/\nresult folding"]:::base
+ * ```
+ *
+ * For background on why direction selection talks about probabilities and
+ * entropy instead of only the raw logits, see Wikipedia contributors,
+ * [Softmax function](https://en.wikipedia.org/wiki/Softmax_function), which is
+ * the probability transform used by the action-diagnostics helper layer.
+ *
+ * Example: inspect the direction choice implied by one network output vector.
+ *
+ * ```ts
+ * const directionStats = MazeMovement.selectDirection([0.4, 1.2, -0.3, 0.1]);
+ *
+ * console.log(directionStats.selectedDirection);
+ * console.log(directionStats.entropy);
+ * ```
+ *
+ * Example: simulate one complete maze episode for a candidate network.
+ *
+ * ```ts
+ * const result = MazeMovement.simulateAgent(
+ *   network,
+ *   encodedMaze,
+ *   startPos,
+ *   exitPos,
+ *   distanceMap,
+ *   160,
+ * );
+ *
+ * console.log(result.fitness, result.reachedExit);
+ * ```
  */
 
 import type { INetwork } from '../interfaces';

package/test/examples/flappy_bird/browser-entry/README.md

@@ -1,37 +1,80 @@
 # browser-entry
 
-Browser demo public entry for the Flappy Bird example.
+Browser teaching surface and lifecycle facade for the Flappy Bird example.
+
+This folder is where worker-owned evolution meets human-friendly inspection.
+The browser side owns DOM setup, HUD updates, playback rendering, and network
+visualization. The worker side owns the hot-path simulation and packed frame
+production. `browser-entry/` exists so those responsibilities stay honest
+instead of drifting into one blurry runtime.
+
+That split is the main reason this file stays intentionally small. The public
+`start(...)` surface should feel simple to call even though the surrounding
+system is not simple at all. A caller gets one run handle, while the folder
+behind it fans out into runtime bootstrap, host layout, worker messaging,
+playback rendering, and inspection views.
+
+Read this boundary as the browser-side answer to one practical question:
+how do you make an evolved controller visible and interactive without moving
+simulation authority back onto the main thread? The answer is a stable entry
+facade plus a strict authority split between browser presentation and worker
+execution.
+
+`index.html` is only the local shell that loads the published bundle and then
+reaches this same start boundary through globals. If you want the real
+host/runtime seam, start here rather than with the static shell.
+
+Read the folder in three passes. Start with this file for the public
+lifecycle contract. Continue into `runtime/` and `worker-channel/` for the
+bootstrap and protocol story. Finish with `host/`, `playback/`,
+`network-view/`, and `visualization/` for the teaching surface the browser
+renders around the worker-owned simulation.
 
-This boundary is the hand-off point between library consumers and the demo's
-browser runtime. Calling `start` boots the canvas UI, worker channel, HUD,
-and playback loop without exposing all of that internal orchestration as part
-of the public API.
+```mermaid
+flowchart LR
+  classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+  classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
 
-In other words, this file is intentionally tiny because it acts like a clean
-facade over a much larger interactive system.
+  Start["start()"]:::accent --> Runtime["runtime/\nbootstrap orchestration"]:::base
+  Runtime --> Host["host/\nDOM and canvas shell"]:::base
+  Runtime --> Channel["worker-channel/\nworker protocol"]:::base
+  Channel --> Playback["playback/\npopulation rendering"]:::base
+  Runtime --> Network["network-view + visualization/\nnetwork inspection"]:::base
+```
 
-Educational note:
-`index.html` is only the local browser shell that loads the published bundle
-and then exposes this same start boundary through browser globals. Read this
-file when you want the real host/runtime seam instead of the static shell.
+```mermaid
+flowchart TD
+  classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+  classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+
+  Browser["Main thread browser host"]:::accent --> Ui["canvas HUD and network view"]:::base
+  Browser --> Handle["FlappyBirdRunHandle\nstop isRunning done"]:::base
+  Browser --> Protocol["worker-channel\nmessage transport"]:::base
+  Protocol --> Worker["worker-owned evolution\nand packed playback frames"]:::base
+```
+
+For background on why the boundary keeps simulation authority off the main
+thread, see MDN,
+[Using Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers),
+which captures the browser execution model this example leans on.
+
+Example: start the demo and stop it from embedding code later.
 
-Minimal browser start example:
 ```ts
 import { start } from './browser-entry/browser-entry';
 
 const handle = await start('flappy-bird-output');
-// Later: handle.stop();
+setTimeout(() => handle.stop(), 10_000);
 await handle.done;
 ```
 
-Startup path:
-```mermaid
-flowchart LR
-    Start["start()"] --> Runtime["runtime/\nbootstrap orchestration"]
-    Runtime --> Host["host/\nDOM and canvas shell"]
-    Runtime --> Channel["worker-channel/\nworker protocol"]
-    Channel --> Playback["playback/\npopulation rendering"]
-    Runtime --> Network["network-view + visualization/\nnetwork inspection"]
+Example: watch the lifecycle handle while the browser host is running.
+
+```ts
+const handle = await start('flappy-bird-output');
+
+console.log(handle.isRunning());
+await handle.done;
 ```
 
 ## browser-entry/browser-entry.ts

package/test/examples/flappy_bird/browser-entry/browser-entry.ts

@@ -1,36 +1,79 @@
 /**
- * Browser demo public entry for the Flappy Bird example.
+ * Browser teaching surface and lifecycle facade for the Flappy Bird example.
  *
- * This boundary is the hand-off point between library consumers and the demo's
- * browser runtime. Calling `start` boots the canvas UI, worker channel, HUD,
- * and playback loop without exposing all of that internal orchestration as part
- * of the public API.
+ * This folder is where worker-owned evolution meets human-friendly inspection.
+ * The browser side owns DOM setup, HUD updates, playback rendering, and network
+ * visualization. The worker side owns the hot-path simulation and packed frame
+ * production. `browser-entry/` exists so those responsibilities stay honest
+ * instead of drifting into one blurry runtime.
  *
- * In other words, this file is intentionally tiny because it acts like a clean
- * facade over a much larger interactive system.
+ * That split is the main reason this file stays intentionally small. The public
+ * `start(...)` surface should feel simple to call even though the surrounding
+ * system is not simple at all. A caller gets one run handle, while the folder
+ * behind it fans out into runtime bootstrap, host layout, worker messaging,
+ * playback rendering, and inspection views.
  *
- * Educational note:
- * `index.html` is only the local browser shell that loads the published bundle
- * and then exposes this same start boundary through browser globals. Read this
- * file when you want the real host/runtime seam instead of the static shell.
+ * Read this boundary as the browser-side answer to one practical question:
+ * how do you make an evolved controller visible and interactive without moving
+ * simulation authority back onto the main thread? The answer is a stable entry
+ * facade plus a strict authority split between browser presentation and worker
+ * execution.
+ *
+ * `index.html` is only the local shell that loads the published bundle and then
+ * reaches this same start boundary through globals. If you want the real
+ * host/runtime seam, start here rather than with the static shell.
+ *
+ * Read the folder in three passes. Start with this file for the public
+ * lifecycle contract. Continue into `runtime/` and `worker-channel/` for the
+ * bootstrap and protocol story. Finish with `host/`, `playback/`,
+ * `network-view/`, and `visualization/` for the teaching surface the browser
+ * renders around the worker-owned simulation.
+ *
+ * ```mermaid
+ * flowchart LR
+ *   classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+ *   classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+ *
+ *   Start["start()"]:::accent --> Runtime["runtime/\nbootstrap orchestration"]:::base
+ *   Runtime --> Host["host/\nDOM and canvas shell"]:::base
+ *   Runtime --> Channel["worker-channel/\nworker protocol"]:::base
+ *   Channel --> Playback["playback/\npopulation rendering"]:::base
+ *   Runtime --> Network["network-view + visualization/\nnetwork inspection"]:::base
+ * ```
+ *
+ * ```mermaid
+ * flowchart TD
+ *   classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+ *   classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+ *
+ *   Browser["Main thread browser host"]:::accent --> Ui["canvas HUD and network view"]:::base
+ *   Browser --> Handle["FlappyBirdRunHandle\nstop isRunning done"]:::base
+ *   Browser --> Protocol["worker-channel\nmessage transport"]:::base
+ *   Protocol --> Worker["worker-owned evolution\nand packed playback frames"]:::base
+ * ```
+ *
+ * For background on why the boundary keeps simulation authority off the main
+ * thread, see MDN,
+ * [Using Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers),
+ * which captures the browser execution model this example leans on.
+ *
+ * Example: start the demo and stop it from embedding code later.
  *
- * Minimal browser start example:
  * ```ts
  * import { start } from './browser-entry/browser-entry';
  *
  * const handle = await start('flappy-bird-output');
- * // Later: handle.stop();
+ * setTimeout(() => handle.stop(), 10_000);
  * await handle.done;
  * ```
  *
- * Startup path:
- * ```mermaid
- * flowchart LR
- *     Start["start()"] --> Runtime["runtime/\nbootstrap orchestration"]
- *     Runtime --> Host["host/\nDOM and canvas shell"]
- *     Runtime --> Channel["worker-channel/\nworker protocol"]
- *     Channel --> Playback["playback/\npopulation rendering"]
- *     Runtime --> Network["network-view + visualization/\nnetwork inspection"]
+ * Example: watch the lifecycle handle while the browser host is running.
+ *
+ * ```ts
+ * const handle = await start('flappy-bird-output');
+ *
+ * console.log(handle.isRunning());
+ * await handle.done;
  * ```
  */
 export { start } from './runtime/runtime';

package/test/examples/flappy_bird/flappy-evolution-worker/README.md

@@ -7,16 +7,104 @@ explanation, HUD rendering, and network inspection, while the worker owns the
 hot path: evolving generations, materializing playback state, advancing the
 simulation, and packaging compact snapshots back to the host.
 
-Read this file as the worker chapter's public spine. It is not the place for
-low-level simulation math or message-shape detail. Instead it shows how the
-worker turns a small typed protocol into one long-lived deterministic runtime.
-
-Protocol flow at a glance:
-1. `init` seeds deterministic worker state and creates the NEAT runtime.
-2. `request-generation` evolves one generation and posts a summary message.
-3. `start-playback` materializes worker-local simulation state.
-4. `request-playback-step` advances playback and streams packed snapshots.
-5. `stop` marks the worker as cooperatively stopped.
+That separation is doing two jobs at once. It protects the browser from
+heavy simulation work, and it turns responsibility into something a reader
+can see directly because every cross-thread handoff must become an explicit
+typed message.
+
+Read this folder as the protocol chapter between the browser host and the
+deterministic runtime that actually evolves and replays the flock. The
+important design question is not merely "how do Web Workers run code?" It is
+"which side should own each piece of truth when evolution, playback, and
+inspection all need the same population?"
+
+In this example, the answer is deliberate:
+
+- the host owns controls, HUD state, and network visualization,
+- the worker owns generation requests, playback stepping, and winner
+  selection,
+- packed snapshots are the narrow bridge between those two worlds.
+
+## What This Folder Is Trying To Teach
+
+The worker chapter is organized around four reader questions:
+
+1. How does the browser request evolution work without becoming the
+   simulation authority?
+2. How does one evolved population become a replayable playback session?
+3. Why are snapshots packed into typed arrays instead of posted as nested
+   render objects?
+4. Where should you read next when the protocol is clear but one runtime step
+   still feels opaque?
+
+## Core Worker Map
+
+```mermaid
+flowchart LR
+    Host["browser-entry/\nhost UI and controls"] --> Protocol["protocol service\nlegal message transitions"]
+    Protocol --> Runtime["runtime service\nworker-local NEAT controller"]
+    Runtime --> Evolution["evolution service\nadvance one generation"]
+    Runtime --> Playback["playback service\nmaterialize and step population"]
+    Playback --> Snapshot["snapshot utils\npacked typed-array transport"]
+    Snapshot --> Host
+
+    WarmStart["warm-start service\ngeneration zero bootstrap"] -.-> Evolution
+    Types["worker types\nmessage and DTO contracts"] -.-> Protocol
+
+    classDef boundary fill:#001522,stroke:#0fb5ff,color:#9fdcff,stroke-width:2px;
+    classDef runtime fill:#03111f,stroke:#00e5ff,color:#d8f6ff,stroke-width:2px;
+    classDef highlight fill:#2a1029,stroke:#ff4a8d,color:#ffd7e8,stroke-width:3px;
+
+    class Host,Protocol,Types boundary;
+    class Runtime,Evolution,Playback,Snapshot runtime;
+    class Snapshot highlight;
+```
+
+Read the diagram left to right. The host is allowed to request work, but it
+never takes ownership of the worker's mutable simulation state. The worker
+can then optimize for determinism and throughput while the browser optimizes
+for explanation.
+
+## Choose Your Route
+
+- Start with `flappy-evolution-worker.ts` if you want the high-level message
+  lifecycle.
+- Read `flappy-evolution-worker.protocol.service.ts` next if you want the
+  legal sequencing rules.
+- Read `flappy-evolution-worker.runtime.service.ts` if you want the worker's
+  NEAT runtime setup.
+- Read `flappy-evolution-worker.playback.service.ts` and
+  `flappy-evolution-worker.simulation.frame.service.ts` if you want the hot
+  playback path.
+- Read `flappy-evolution-worker.snapshot.utils.ts` if you want the typed-array
+  transport story.
+
+Minimal host-side sketch:
+
+```ts
+worker.postMessage({
+  type: 'init',
+  payload: { populationSize: 50, elitismCount: 10, rngSeed: 12345 },
+});
+worker.postMessage({ type: 'request-generation' });
+worker.postMessage({
+  type: 'start-playback',
+  payload: { visibleWorldWidthPx: 1280, visibleWorldHeightPx: 720 },
+});
+worker.postMessage({
+  type: 'request-playback-step',
+  payload: {
+    requestId: 1,
+    simulationSteps: 2,
+    visibleWorldWidthPx: 1280,
+    visibleWorldHeightPx: 720,
+  },
+});
+```
+
+If you want background reading before the symbol shelf, the MDN Web Workers
+guide is the fastest practical reference for why this example pushes both
+evolution and playback off the main thread.
 
 ## flappy-evolution-worker/flappy-evolution-worker.ts