@reicek/neataptic-ts 0.1.26 → 0.1.27

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

@@ -1,14 +1,87 @@
 /**
- * Public browser entry facade for the ASCII Maze demo module boundary.
+ * Browser-hosted curriculum boundary for the ASCII Maze example.
  *
- * 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.
+ * 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.
  *
- * 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.
+ * 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.
+ *
+ * ```ts
+ * const handle = await start('ascii-maze-output');
+ * const unsubscribe = handle.onTelemetry((telemetry) => {
+ *   console.log(telemetry.generation, telemetry.bestFitness);
+ * });
+ *
+ * await handle.done;
+ * unsubscribe();
+ * ```
  */
 
 import { BROWSER_ENTRY_CONSTANTS as C } from './browser-entry.constants';

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

@@ -1,10 +1,74 @@
 # dashboardManager
 
-Public DashboardManager facade for the dedicated dashboardManager module boundary.
+Search-visibility boundary for ASCII Maze browser and terminal hosts.
+
+Evolution is difficult to trust when all you see is a final score. The
+dashboard boundary turns per-generation updates into a live board, a solved
+archive, and a reusable telemetry snapshot so long runs stay legible while
+they are still happening.
+
+That is why this folder exists as a separate boundary instead of staying
+mixed into the engine. The engine should answer whether the search is making
+progress. The dashboard should answer how a human can see that progress:
+current best candidate, recent trends, species counts, complexity drift, and
+solved artifacts worth preserving.
+
+Read the folder as three cooperating shelves. The public `DashboardManager`
+class keeps the stable host-facing API. `dashboardManager.services.ts`
+handles update ingestion, redraws, and telemetry emission. The archive, live,
+and telemetry subfolders keep presentation concerns decomposed so browser and
+terminal hosts can reuse the same core state with different outputs.
+
+The chapter matters because telemetry without presentation quickly becomes a
+pile of numbers, while presentation without a stable telemetry contract
+becomes fragile host-specific logic. This boundary keeps those concerns close
+enough to cooperate and separate enough to evolve independently.
+
+Read this chapter in three passes. Start with the class surface for the
+public update, redraw, and snapshot methods. Continue to the service module
+for the runtime dataflow. Finish in `archive/`, `live/`, and `telemetry/`
+when you want the host-specific rendering details rather than the stable
+dashboard 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;
+
+  Engine["Evolution engine update"]:::base --> Dashboard["DashboardManager.update(...)\npublic ingest surface"]:::accent
+  Dashboard --> Live["live board\ncurrent best and trends"]:::base
+  Dashboard --> Archive["solved archive\nretained artifacts"]:::base
+  Dashboard --> Telemetry["public telemetry snapshot\nhost subscriptions"]:::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;
+
+  Hosts["Browser or terminal host"]:::base --> Facade["DashboardManager\nclass facade"]:::accent
+  Facade --> Services["dashboardManager.services.ts\nstateful orchestration"]:::base
+  Services --> State["history state\ncurrent best\nlast telemetry"]:::base
+  Services --> Views["archive/ live/ telemetry/\nrendering helpers"]:::base
+```
+
+Example: create one dashboard instance for a run and feed it updates.
+
+```ts
+const dashboard = new DashboardManager(clearOutput, logOutput, archiveOutput);
 
-The folder now owns local contracts, constants, pure formatting helpers, and
-stateful rendering and telemetry services. This facade keeps the established
-class-based API stable while delegating the heavy work to focused helpers.
+dashboard.update(maze, result, network, generation, neatInstance);
+dashboard.redraw(maze, neatInstance);
+```
+
+Example: read the latest public telemetry snapshot after several updates.
+
+```ts
+const telemetry = dashboard.getLastTelemetry();
+
+console.log(telemetry.generation);
+console.log(telemetry.bestFitness);
+```
 
 ## dashboardManager/dashboardManager.types.ts
 

package/test/examples/asciiMaze/dashboardManager/dashboardManager.ts

@@ -1,9 +1,73 @@
 /**
- * Public DashboardManager facade for the dedicated dashboardManager module boundary.
+ * Search-visibility boundary for ASCII Maze browser and terminal hosts.
  *
- * The folder now owns local contracts, constants, pure formatting helpers, and
- * stateful rendering and telemetry services. This facade keeps the established
- * class-based API stable while delegating the heavy work to focused helpers.
+ * Evolution is difficult to trust when all you see is a final score. The
+ * dashboard boundary turns per-generation updates into a live board, a solved
+ * archive, and a reusable telemetry snapshot so long runs stay legible while
+ * they are still happening.
+ *
+ * That is why this folder exists as a separate boundary instead of staying
+ * mixed into the engine. The engine should answer whether the search is making
+ * progress. The dashboard should answer how a human can see that progress:
+ * current best candidate, recent trends, species counts, complexity drift, and
+ * solved artifacts worth preserving.
+ *
+ * Read the folder as three cooperating shelves. The public `DashboardManager`
+ * class keeps the stable host-facing API. `dashboardManager.services.ts`
+ * handles update ingestion, redraws, and telemetry emission. The archive, live,
+ * and telemetry subfolders keep presentation concerns decomposed so browser and
+ * terminal hosts can reuse the same core state with different outputs.
+ *
+ * The chapter matters because telemetry without presentation quickly becomes a
+ * pile of numbers, while presentation without a stable telemetry contract
+ * becomes fragile host-specific logic. This boundary keeps those concerns close
+ * enough to cooperate and separate enough to evolve independently.
+ *
+ * Read this chapter in three passes. Start with the class surface for the
+ * public update, redraw, and snapshot methods. Continue to the service module
+ * for the runtime dataflow. Finish in `archive/`, `live/`, and `telemetry/`
+ * when you want the host-specific rendering details rather than the stable
+ * dashboard 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;
+ *
+ *   Engine["Evolution engine update"]:::base --> Dashboard["DashboardManager.update(...)\npublic ingest surface"]:::accent
+ *   Dashboard --> Live["live board\ncurrent best and trends"]:::base
+ *   Dashboard --> Archive["solved archive\nretained artifacts"]:::base
+ *   Dashboard --> Telemetry["public telemetry snapshot\nhost subscriptions"]:::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;
+ *
+ *   Hosts["Browser or terminal host"]:::base --> Facade["DashboardManager\nclass facade"]:::accent
+ *   Facade --> Services["dashboardManager.services.ts\nstateful orchestration"]:::base
+ *   Services --> State["history state\ncurrent best\nlast telemetry"]:::base
+ *   Services --> Views["archive/ live/ telemetry/\nrendering helpers"]:::base
+ * ```
+ *
+ * Example: create one dashboard instance for a run and feed it updates.
+ *
+ * ```ts
+ * const dashboard = new DashboardManager(clearOutput, logOutput, archiveOutput);
+ *
+ * dashboard.update(maze, result, network, generation, neatInstance);
+ * dashboard.redraw(maze, neatInstance);
+ * ```
+ *
+ * Example: read the latest public telemetry snapshot after several updates.
+ *
+ * ```ts
+ * const telemetry = dashboard.getLastTelemetry();
+ *
+ * console.log(telemetry.generation);
+ * console.log(telemetry.bestFitness);
+ * ```
  */
 
 import type Neat from '../../../../src/neat';