@reicek/neataptic-ts 0.1.26 → 0.1.27

package/src/neat/neat.defaults.constants.ts

@@ -1,23 +1,101 @@
 import type { NeatConstructorDefaults } from './init/neat.init';
 
 /**
- * Public default knobs for the root `Neat` controller.
+ * Root chapter map and public default knobs for the internal `src/neat` controller surface.
  *
- * These constants describe the controller personality a caller gets before a
- * custom option bag starts bending the run toward a different search style.
- * Keeping them in their own root chapter lets `src/neat.ts` stay focused on
- * orchestration while the `init/` chapter consumes one shared defaults packet.
+ * `src/neat.ts` is the public control desk. `src/neat/` is the machine room
+ * behind it. This folder owns the controller chapters that make a run real:
+ * initialization, evaluation, evolution, mutation, speciation, telemetry,
+ * persistence, and the shared bookkeeping that keeps experiments deterministic
+ * instead of magical. Promoting the defaults file to the chapter opening is
+ * intentional because default knobs are the quickest way to make the
+ * controller's personality legible before a reader dives into implementation
+ * detail.
  *
- * The constants fall into four small families:
+ * The most helpful reading move is to split the folder into four working
+ * lanes. `init/`, `evaluate/`, and `evolve/` explain how a population is
+ * created, scored, and replaced. `mutation/`, `selection/`, and `speciation/`
+ * explain how search pressure and diversity are managed. `telemetry/`,
+ * `lineage/`, `diversity/`, and `multiobjective/` explain how the run becomes
+ * inspectable. `export/`, `rng/`, `cache/`, `maintenance/`, and `pruning/`
+ * explain how the controller stays reproducible and tractable as experiments
+ * get larger.
  *
- * - search volume and tempo,
- * - speciation pressure,
- * - structural ceilings,
- * - observability sampling.
+ * The flat root files are small bridges rather than the whole story.
+ * `neat.defaults.constants.ts` and `neat.types.ts` keep the public constructor
+ * and option bag readable. `neat.lineage.ts` and `neat.constants.ts` keep
+ * small shared logic close to the root when multiple chapters need it. The
+ * deeper folders own the heavier policy and runtime details.
  *
- * Read them as the public defaults shelf, not as hidden implementation trivia.
- * These values are the baseline promises the root controller makes when a user
- * says, "give me an ordinary NEAT run," without specifying every knob.
+ * These defaults matter because they are the baseline promises the controller
+ * makes when a caller says "give me an ordinary NEAT run." Population size,
+ * mutation tempo, compatibility pressure, structural ceilings, and
+ * observability sampling are not random numbers. They are the quiet assumptions
+ * that decide whether the controller behaves like a conservative search, an
+ * exploratory search, or an unstable one.
+ *
+ * That design follows the original NEAT intuition: protect structural
+ * innovation long enough for it to compete, rather than forcing every new
+ * topology to beat established species immediately. See Stanley and
+ * Miikkulainen,
+ * [Evolving Neural Networks through Augmenting Topologies](https://nn.cs.utexas.edu/?stanley:ec02),
+ * for the background behind the compatibility and growth vocabulary that keeps
+ * surfacing across this folder.
+ *
+ * Read this root chapter in three passes. Start with this defaults file and
+ * `neat.types.ts` for the public knobs and broad contracts. Continue into
+ * `evaluate/`, `evolve/`, and `speciation/` for the live search loop. Finish
+ * with `telemetry/`, `lineage/`, `multiobjective/`, `export/`, and `rng/` when
+ * you want to inspect, replay, or compare runs rather than only advance them.
+ *
+ * ```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;
+ *
+ *   Root["src/neat root"]:::accent --> Loop["init / evaluate / evolve"]:::base
+ *   Root --> Pressure["mutation / selection / speciation"]:::base
+ *   Root --> Observe["telemetry / lineage / diversity / multiobjective"]:::base
+ *   Root --> Replay["export / rng / cache / maintenance / pruning"]:::base
+ *   Root --> Bridges["root bridges<br/>defaults / types / constants"]:::base
+ * ```
+ *
+ * ```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;
+ *
+ *   Defaults[Root defaults]:::accent --> Population[popsize elitism provenance]:::base
+ *   Defaults --> Variation[mutationRate mutationAmount]:::base
+ *   Defaults --> Species[compatibility and weight coefficients]:::base
+ *   Defaults --> Observation[diversity and novelty samples]:::base
+ *   Population --> Run[Controller behavior]:::base
+ *   Variation --> Run
+ *   Species --> Run
+ *   Observation --> Run
+ * ```
+ *
+ * Example: build one explicit baseline options bag from the documented root
+ * defaults.
+ *
+ * ```ts
+ * const baselineOptions = {
+ *   popsize: DEFAULT_POPULATION_SIZE,
+ *   mutationRate: DEFAULT_MUTATION_RATE,
+ *   compatibilityThreshold: DEFAULT_COMPATIBILITY_THRESHOLD,
+ * };
+ * ```
+ *
+ * Example: keep the observability defaults visible when teaching or
+ * benchmarking runs.
+ *
+ * ```ts
+ * const observabilityDefaults = {
+ *   diversityPairSample: DEFAULT_DIVERSITY_PAIR_SAMPLE,
+ *   diversityGraphletSample: DEFAULT_DIVERSITY_GRAPHLET_SAMPLE,
+ *   noveltyK: DEFAULT_NOVELTY_K,
+ * };
+ * ```
  */
 
 /**

package/src/neat.ts

@@ -90,34 +90,100 @@ import * as neatTelemetryFacade from './neat/telemetry/facade/telemetry.facade';
 /**
  * Root orchestration surface for NeuroEvolution of Augmenting Topologies (NEAT) in NeatapticTS.
  *
- * Within the broader `src` surface, this file is the public chapter map for the
- * library's evolutionary controller.
- * The heavy algorithmic work lives in focused `src/neat/**` modules, but this
- * root surface keeps the user-facing workflow readable: configure a population,
- * evaluate genomes, evolve the next generation, inspect telemetry, and persist
- * the state when a run becomes worth keeping.
+ * This root chapter is the public control desk for the library. The
+ * architecture surfaces explain what a network graph is. The `src/neat/**`
+ * chapters explain how evaluation, reproduction, speciation, telemetry, and
+ * persistence work in detail. This file sits between those two layers and
+ * answers the first practical reader question: how do I run one evolutionary
+ * experiment without learning every subsystem in the same breath?
  *
- * What this file covers:
- * - the high-level lifecycle of a NEAT run,
- * - the default knobs that shape population growth and speciation,
- * - reproducibility helpers such as seeded RNG snapshots and state export,
- * - educational inspection hooks for telemetry, species history, diversity, and Pareto fronts.
+ * That boundary matters because a useful NEAT run is more than "mutate a
+ * network." A controller has to keep a population alive, protect enough
+ * diversity to avoid early collapse, score genomes fairly, record what
+ * happened, and give the caller a deterministic way to pause or resume the
+ * search. The root surface is where those responsibilities become one readable
+ * workflow instead of a pile of helper calls.
  *
- * What you can learn here:
- * - how the top-level controller stays orchestration-first even after the internal SOLID split,
- * - which public methods belong to setup, evolution, diagnostics, and persistence,
- * - which subsystem README to open next when you want the underlying mechanics.
+ * One helpful mental model is to read the controller as four shelves. The setup
+ * shelf decides population size, defaults, and reproducibility. The search
+ * shelf drives `evaluate()`, `evolve()`, and the public mutation hooks. The
+ * observability shelf exposes telemetry, lineage, diversity, species, and
+ * Pareto views. The persistence shelf turns a live run into replayable state
+ * through `toJSON()`, `exportState()`, and RNG snapshots.
+ *
+ * The chapter also exists to keep the public class orchestration-first after
+ * the internal split. `src/neat/**` now owns the heavier policy chapters:
+ * `evaluate/` scores genomes, `evolve/` creates the next generation,
+ * `speciation/` manages compatibility pressure, `telemetry/` records what the
+ * run did, and `export/` plus `rng/` keep experiments reproducible. If you can
+ * read the root workflow first, the subchapters become "why does this step
+ * work?" reads instead of "where do I even start?" reads.
+ *
+ * The guiding historical idea comes from Stanley and Miikkulainen's NEAT
+ * paper: evolve both weights and topology while protecting innovation long
+ * enough for new structures to prove useful. See Stanley and Miikkulainen,
+ * [Evolving Neural Networks through Augmenting Topologies](https://nn.cs.utexas.edu/?stanley:ec02),
+ * for the compact background behind the controller vocabulary that appears all
+ * through this surface.
+ *
+ * Read this root when you want to answer one of three questions quickly: how to
+ * start a run, how to move it forward generation by generation, or how to
+ * inspect and persist it without diving into every implementation chapter. Read
+ * the narrower `src/neat/**` READMEs when the next question becomes about one
+ * specific policy family rather than the whole experiment loop.
  *
  * ```mermaid
  * flowchart LR
- *   Configure["Configure run<br/>sizes + fitness + options"] --> Seed["Seed or restore<br/>constructor / createPool / import"]
- *   Seed --> Score["Score population<br/>evaluate()"]
- *   Score --> Breed["Breed next generation<br/>evolve() / mutate()"]
- *   Breed --> Observe["Observe search pressure<br/>telemetry / species / diversity / Pareto"]
- *   Observe --> Persist["Persist or replay<br/>exportState() / toJSON() / RNG state"]
+ *   classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+ *   classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+ *
+ *   Configure["Configure run<br/>sizes + fitness + options"]:::accent --> Seed["Seed or restore<br/>constructor / createPool / import"]:::base
+ *   Seed --> Score["Score population<br/>evaluate()"]:::base
+ *   Score --> Breed["Breed next generation<br/>evolve() / mutate()"]:::accent
+ *   Breed --> Observe["Observe pressure<br/>telemetry / species / diversity / Pareto"]:::base
+ *   Observe --> Persist["Persist or replay<br/>exportState() / toJSON() / RNG state"]:::base
  *   Breed --> Score
  * ```
  *
+ * ```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;
+ *
+ *   Root["src root controller"]:::accent --> Setup["Defaults and initialization<br/>constructor / createPool / import"]:::base
+ *   Root --> Search["Search loop<br/>evaluate / evolve / mutate"]:::base
+ *   Root --> Observe["Diagnostics<br/>telemetry / species / lineage / Pareto"]:::base
+ *   Root --> Replay["Persistence<br/>toJSON / exportState / RNG"]:::base
+ *   Search --> Chapters["Detailed policy chapters<br/>src/neat/**"]:::base
+ * ```
+ *
+ * Example: start a small deterministic run and inspect the best score after one
+ * generation.
+ *
+ * ```ts
+ * const neat = new Neat(2, 1, fitness, {
+ *   popsize: 50,
+ *   seed: 7,
+ *   fastMode: true,
+ * });
+ *
+ * await neat.evaluate();
+ * const bestGenome = await neat.evolve();
+ *
+ * console.log(bestGenome.score);
+ * ```
+ *
+ * Example: capture telemetry and a replayable snapshot after the current run
+ * step.
+ *
+ * ```ts
+ * const latestTelemetry = neat.getTelemetry().at(-1);
+ * const exportedState = neat.exportState();
+ *
+ * console.log(latestTelemetry?.generation);
+ * console.log(exportedState.neat.generation);
+ * ```
+ *
  * Recommended reading after this root chapter:
  * - `./neat/evaluate/README.md` for scoring flow and objective handling
  * - `./neat/evolve/README.md` for reproduction orchestration

package/src/utils/README.md

@@ -1,23 +1,44 @@
 # utils
 
-Memory instrumentation utilities (Phase 0).
+Memory instrumentation chapter for slab, pool, and heap comparisons.
 
 This chapter exists for one practical learning problem: memory behavior is
 one of the easiest parts of an evolutionary system to feel, but one of the
 hardest parts to explain from raw runtime objects alone. Networks grow,
 slabs reserve capacity ahead of immediate need, pools trade fresh allocation
 pressure for reuse, and the JavaScript engine adds object overhead that is
-hard to see directly from the outside.
+difficult to see directly from the outside.
 
 Instead of pretending to be a precise profiler, this boundary offers a fast,
 educational snapshot. The goal is to make design choices visible enough that
-readers can compare runs and ask better questions:
-
-- Did moving toward slab-backed storage reduce object-heavy overhead?
-- Is pooling shifting pressure away from fresh allocations?
-- How much reserved typed-array capacity is currently going unused?
-- Are browser or Node heap readings moving in the same direction as the
-  heuristic network summary?
+readers can compare runs and ask better questions: did slab-backed storage
+reduce object-heavy overhead, is pooling shifting pressure away from fresh
+allocations, how much reserved typed-array capacity is currently unused, and
+are browser or Node heap readings moving in the same direction as the
+library-specific heuristics?
+
+The most important design choice is scope. `memoryStats()` is not trying to
+replace a full heap profiler. It is trying to put library-shaped numbers next
+to runtime-shaped numbers so a reader can compare architecture decisions with
+less guesswork. The result is intentionally strongest at trend questions such
+as "did the slab version get leaner?" or "did pooling reduce fresh pressure?"
+rather than forensic questions about one exact byte count.
+
+A useful mental model is to treat the snapshot as four cooperating layers.
+The network layer counts connections, nodes, and estimated totals. The slab
+layer explains reserved versus used typed-array capacity. The pool layer
+exposes reuse infrastructure. The environment layer shows the coarser browser
+or Node counters surrounding the library's own heuristics.
+
+The environment metrics are intentionally coarser than the network heuristics.
+See MDN,
+[Performance.memory](https://developer.mozilla.org/en-US/docs/Web/API/Performance/memory),
+and the Node.js docs,
+[process.memoryUsage()](https://nodejs.org/api/process.html#processmemoryusage),
+for the runtime-level counters this chapter folds alongside its own snapshot.
+They are useful context, but they do not know the difference between live
+network structure, reserved slab capacity, and reusable pools the way this
+module does.
 
 Read the chapter in three passes:
 
@@ -26,20 +47,49 @@ Read the chapter in three passes:
 3. `memory.utils.ts` when you want the aggregation, environment probing, and
    slab-accounting mechanics behind the snapshot.
 
-Design principles:
-
-- Lightweight: avoid deep graph walks or JSON serialization.
-- Pay-for-use: if no networks are registered the snapshot stays small.
-- Cross-environment: gather what the browser or Node can expose safely.
-- Extensible: keep room for later phases that add more exact accounting.
-
 ```mermaid
 flowchart TD
-  Networks[Tracked or explicit networks] --> Aggregation[Heuristic network aggregation]
-  Aggregation --> Snapshot[MemoryStats snapshot]
-  Config[Config and allocator flags] --> Snapshot
-  Environment[Browser or Node heap probes] --> Snapshot
-  Snapshot --> Questions[Compare storage strategy, pooling, and capacity behavior]
+  classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+  classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+
+  Networks[Tracked or explicit networks]:::base --> Aggregation[Heuristic network aggregation]:::accent
+  Aggregation --> Snapshot[MemoryStats snapshot]:::base
+  Config[Config and allocator flags]:::base --> Snapshot
+  Environment[Browser or Node heap probes]:::base --> Snapshot
+  Snapshot --> Questions[Compare storage strategy, pooling, and capacity behavior]:::base
+```
+
+```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;
+
+  Stats[MemoryStats]:::accent --> NetworkLayer[connections nodes estimatedTotalBytes]:::base
+  Stats --> SlabLayer[slabBytes reservedBytes usedBytes fragmentationPct]:::base
+  Stats --> PoolLayer[nodePool reuse snapshot]:::base
+  Stats --> EnvironmentLayer[browser heap or Node RSS counters]:::base
+```
+
+Example: register one network once, then capture snapshots later without
+threading the target through every call.
+
+```ts
+registerTrackedNetwork(network);
+const snapshot = memoryStats();
+
+console.log(snapshot.estimatedTotalBytes);
+console.log(snapshot.slabs.fragmentationPct);
+```
+
+Example: compare two explicit network sets when you want the memory story to
+stay local to one experiment.
+
+```ts
+const baselineSnapshot = memoryStats([baselineNetwork]);
+const pooledSnapshot = memoryStats([pooledNetwork]);
+
+console.log(baselineSnapshot.estimatedTotalBytes);
+console.log(pooledSnapshot.slabs.pooledFraction);
 ```
 
 ## utils/memory.ts

package/src/utils/memory.ts

@@ -1,22 +1,43 @@
 /**
- * Memory instrumentation utilities (Phase 0).
+ * Memory instrumentation chapter for slab, pool, and heap comparisons.
  *
  * This chapter exists for one practical learning problem: memory behavior is
  * one of the easiest parts of an evolutionary system to feel, but one of the
  * hardest parts to explain from raw runtime objects alone. Networks grow,
  * slabs reserve capacity ahead of immediate need, pools trade fresh allocation
  * pressure for reuse, and the JavaScript engine adds object overhead that is
- * hard to see directly from the outside.
+ * difficult to see directly from the outside.
  *
  * Instead of pretending to be a precise profiler, this boundary offers a fast,
  * educational snapshot. The goal is to make design choices visible enough that
- * readers can compare runs and ask better questions:
+ * readers can compare runs and ask better questions: did slab-backed storage
+ * reduce object-heavy overhead, is pooling shifting pressure away from fresh
+ * allocations, how much reserved typed-array capacity is currently unused, and
+ * are browser or Node heap readings moving in the same direction as the
+ * library-specific heuristics?
  *
- * - Did moving toward slab-backed storage reduce object-heavy overhead?
- * - Is pooling shifting pressure away from fresh allocations?
- * - How much reserved typed-array capacity is currently going unused?
- * - Are browser or Node heap readings moving in the same direction as the
- *   heuristic network summary?
+ * The most important design choice is scope. `memoryStats()` is not trying to
+ * replace a full heap profiler. It is trying to put library-shaped numbers next
+ * to runtime-shaped numbers so a reader can compare architecture decisions with
+ * less guesswork. The result is intentionally strongest at trend questions such
+ * as "did the slab version get leaner?" or "did pooling reduce fresh pressure?"
+ * rather than forensic questions about one exact byte count.
+ *
+ * A useful mental model is to treat the snapshot as four cooperating layers.
+ * The network layer counts connections, nodes, and estimated totals. The slab
+ * layer explains reserved versus used typed-array capacity. The pool layer
+ * exposes reuse infrastructure. The environment layer shows the coarser browser
+ * or Node counters surrounding the library's own heuristics.
+ *
+ * The environment metrics are intentionally coarser than the network heuristics.
+ * See MDN,
+ * [Performance.memory](https://developer.mozilla.org/en-US/docs/Web/API/Performance/memory),
+ * and the Node.js docs,
+ * [process.memoryUsage()](https://nodejs.org/api/process.html#processmemoryusage),
+ * for the runtime-level counters this chapter folds alongside its own snapshot.
+ * They are useful context, but they do not know the difference between live
+ * network structure, reserved slab capacity, and reusable pools the way this
+ * module does.
  *
  * Read the chapter in three passes:
  *
@@ -25,20 +46,49 @@
  * 3. `memory.utils.ts` when you want the aggregation, environment probing, and
  *    slab-accounting mechanics behind the snapshot.
  *
- * Design principles:
+ * ```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;
  *
- * - Lightweight: avoid deep graph walks or JSON serialization.
- * - Pay-for-use: if no networks are registered the snapshot stays small.
- * - Cross-environment: gather what the browser or Node can expose safely.
- * - Extensible: keep room for later phases that add more exact accounting.
+ *   Networks[Tracked or explicit networks]:::base --> Aggregation[Heuristic network aggregation]:::accent
+ *   Aggregation --> Snapshot[MemoryStats snapshot]:::base
+ *   Config[Config and allocator flags]:::base --> Snapshot
+ *   Environment[Browser or Node heap probes]:::base --> Snapshot
+ *   Snapshot --> Questions[Compare storage strategy, pooling, and capacity behavior]:::base
+ * ```
  *
  * ```mermaid
- * flowchart TD
- *   Networks[Tracked or explicit networks] --> Aggregation[Heuristic network aggregation]
- *   Aggregation --> Snapshot[MemoryStats snapshot]
- *   Config[Config and allocator flags] --> Snapshot
- *   Environment[Browser or Node heap probes] --> Snapshot
- *   Snapshot --> Questions[Compare storage strategy, pooling, and capacity behavior]
+ * 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;
+ *
+ *   Stats[MemoryStats]:::accent --> NetworkLayer[connections nodes estimatedTotalBytes]:::base
+ *   Stats --> SlabLayer[slabBytes reservedBytes usedBytes fragmentationPct]:::base
+ *   Stats --> PoolLayer[nodePool reuse snapshot]:::base
+ *   Stats --> EnvironmentLayer[browser heap or Node RSS counters]:::base
+ * ```
+ *
+ * Example: register one network once, then capture snapshots later without
+ * threading the target through every call.
+ *
+ * ```ts
+ * registerTrackedNetwork(network);
+ * const snapshot = memoryStats();
+ *
+ * console.log(snapshot.estimatedTotalBytes);
+ * console.log(snapshot.slabs.fragmentationPct);
+ * ```
+ *
+ * Example: compare two explicit network sets when you want the memory story to
+ * stay local to one experiment.
+ *
+ * ```ts
+ * const baselineSnapshot = memoryStats([baselineNetwork]);
+ * const pooledSnapshot = memoryStats([pooledNetwork]);
+ *
+ * console.log(baselineSnapshot.estimatedTotalBytes);
+ * console.log(pooledSnapshot.slabs.pooledFraction);
  * ```
  */
 import { config } from '../config';

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

@@ -1,15 +1,88 @@
 # browser-entry
 
-Public browser entry facade for the ASCII Maze demo module boundary.
+Browser-hosted curriculum boundary for the ASCII Maze example.
+
+This folder is where a long-running maze experiment becomes a browser
+experience a human can actually steer and inspect. The evolution engine still
+owns search, scoring, and curriculum advancement. The browser-entry boundary
+owns host elements, resize behavior, telemetry fan-out, globals
+compatibility, and the lifecycle handle that embedding code talks to.
+
+Read it as a boundary between two clocks. One clock belongs to the maze
+curriculum that carries refined winners into larger procedural mazes. The
+other clock belongs to the browser host that has to paint dashboards, react
+to cancellation, and stay polite to resize or unload events. `browser-entry/`
+exists so those clocks can cooperate without collapsing into one monolithic
+demo script.
+
+That separation matters because `index.html` is intentionally thin. The page
+only loads the published bundle from `docs/assets`, exposes a globals bridge,
+and then hands off to this start surface. If you want the real host/runtime
+seam, start here instead of with the HTML shell.
+
+A second useful mental model is ownership. This folder does not own maze
+fitness, winner refinement, or solve thresholds. Those stay in
+`evolutionEngine/`. The host boundary owns container resolution, dashboard
+plumbing, cooperative abort wiring, and the stable run handle that browser
+callers can stop, await, or subscribe to.
+
+Read the chapter in three passes. Start with `browser-entry.ts` for the
+public `start(...)` surface. Continue to `browser-entry.services.ts` for host
+assembly, globals wiring, and curriculum hand-off. Finish with the constants,
+curriculum, and host helper files when you want the browser-specific
+mechanics rather than the public lifecycle contract.
+
+```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;
+
+  HtmlShell["index.html\nbundle loader"]:::base --> Globals["window globals\ncompatibility bridge"]:::base
+  Globals --> Start["start(...)\npublic browser entry"]:::accent
+  Start --> Host["host services\ndashboard + resize + container"]:::base
+  Start --> Curriculum["runBrowserEntryCurriculum\nphase orchestration"]:::base
+  Curriculum --> Engine["Evolution engine\nsearch and solve logic"]:::base
+  Host --> Handle["AsciiMazeRunHandle\nstop done telemetry"]:::base
+  Curriculum --> Handle
+```
+
+```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;
+
+  BrowserEntry["browser-entry/"]:::accent --> PublicApi["browser-entry.ts\npublic start surface"]:::base
+  BrowserEntry --> Services["browser-entry.services.ts\nhost and globals assembly"]:::base
+  BrowserEntry --> Curriculum["browser-entry.curriculum.services.ts\nphase hand-off"]:::base
+  BrowserEntry --> HostUtils["browser-entry.host.services.ts\nand utils"]:::base
+  BrowserEntry --> Types["browser-entry.types.ts\nrun-handle contracts"]:::base
+```
+
+For background reading on the cooperative stop side of the boundary, see
+MDN, [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController),
+which is the browser primitive this entry layer uses to compose internal and
+caller-provided cancellation without moving DOM concerns into the engine.
+
+Example: boot the browser demo from embedding code and stop it later.
+
+```ts
+const handle = await start('ascii-maze-output');
+
+setTimeout(() => handle.stop(), 5_000);
+await handle.done;
+```
+
+Example: subscribe to telemetry while the curriculum advances.
 
-The folder now owns host bootstrap, runtime orchestration, globals
-compatibility, and resize handling behind focused helpers. This facade keeps
-the public API stable while presenting a small orchestration-first surface.
+```ts
+const handle = await start('ascii-maze-output');
+const unsubscribe = handle.onTelemetry((telemetry) => {
+  console.log(telemetry.generation, telemetry.bestFitness);
+});
 
-Educational note:
-`index.html` is only the browser shell that loads the prebuilt bundle and
-forwards into this API through window globals. If you want the real browser
-host boundary, start here rather than with the HTML loader.
+await handle.done;
+unsubscribe();
+```
 
 ## browser-entry/browser-entry.types.ts