@reicek/neataptic-ts 0.1.21 → 0.1.22

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.

package/scripts/assets/theme.css

@@ -1,34 +1,221 @@
-:root{--bg:#0b0f14;--panel:#121a24;--panel-2:#0f1722;--text:#d7e4f3;--muted:#8aa0b8;--line:#263446;--brand:#5a86ff;--brand-2:#88a8ff;--code:#0f141c}
-*{box-sizing:border-box}
-html,body{margin:0;padding:0;background:var(--bg);color:var(--text);font-family:'Open Sans',system-ui,-apple-system,Segoe UI,Roboto,Arial,sans-serif}
-a{color:var(--brand-2);text-decoration:none}
-a:hover{text-decoration:underline}
-.topbar{position:sticky;top:0;z-index:30;background:rgba(10,14,20,.9);backdrop-filter:blur(8px);border-bottom:1px solid var(--line)}
-.topbar .inner{max-width:1400px;margin:0 auto;padding:12px 18px;display:flex;align-items:center;justify-content:space-between;gap:20px}
-.brand a{font-family:'Raleway',sans-serif;font-weight:700;color:#fff;font-size:1.1rem}
-.main-nav{display:flex;gap:14px;flex-wrap:wrap}
-.main-nav a{padding:6px 10px;border-radius:8px;color:var(--muted)}
-.main-nav a.active,.main-nav a:hover{background:#1a2533;color:#fff;text-decoration:none}
-.layout{max-width:1400px;margin:0 auto;display:grid;grid-template-columns:280px minmax(0,1fr)280px;gap:20px;padding:20px 18px 30px}
-.sidebar,.toc{position:sticky;top:72px;max-height:calc(100vh - 90px);overflow:auto;background:var(--panel-2);border:1px solid var(--line);border-radius:12px;padding:12px}
-.content{min-width:0;background:var(--panel);border:1px solid var(--line);border-radius:12px;padding:24px}
-.sidebar-sections{list-style:none;padding:0;margin:0;display:flex;flex-direction:column;gap:8px}
-.sidebar-sections ul{list-style:none;padding-left:12px;margin:8px 0 0}
-.sidebar-sections li a{display:block;padding:5px 8px;border-radius:7px;color:var(--muted)}
-.sidebar-sections li.current>a,.sidebar-sections li a:hover{background:#1a2533;color:#fff;text-decoration:none}
-.g-head{font-family:'Raleway',sans-serif;font-weight:700;color:#c7d6ea;padding:6px 8px}
-h1,h2,h3,h4{font-family:'Raleway',sans-serif;color:#fff;line-height:1.25}
-h1{margin-top:0}
-p,li,td,th{line-height:1.6}
-pre,code{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}
-code{background:var(--code);padding:.1rem .35rem;border-radius:6px;border:1px solid #1c2634}
-pre{background:var(--code);padding:14px;border-radius:10px;border:1px solid #1c2634;overflow:auto}
-table{width:100%;border-collapse:collapse;display:block;overflow:auto}
-th,td{border:1px solid var(--line);padding:8px 10px;text-align:left}
-th{background:#172231}
-blockquote{margin:0;padding:12px 14px;border-left:3px solid var(--brand);background:#121d2b;border-radius:8px}
-.page-toc h2{margin:0 0 8px}
-.toc-file{margin:0 0 8px}
-.site-footer{margin-top:28px;padding-top:14px;border-top:1px solid var(--line);color:var(--muted);font-size:.92rem}
-@media (max-width:1180px){.layout{grid-template-columns:260px minmax(0,1fr)}.toc{display:none}}
-@media (max-width:900px){.layout{grid-template-columns:1fr}.sidebar{position:static;max-height:none}.content{padding:18px}}
+:root {
+  --bg: #0b0f14;
+  --panel: #121a24;
+  --panel-2: #0f1722;
+  --text: #d7e4f3;
+  --muted: #8aa0b8;
+  --line: #263446;
+  --brand: #5a86ff;
+  --brand-2: #88a8ff;
+  --code: #0f141c;
+}
+* {
+  box-sizing: border-box;
+}
+html,
+body {
+  margin: 0;
+  padding: 0;
+  background: var(--bg);
+  color: var(--text);
+  font-family:
+    'Open Sans',
+    system-ui,
+    -apple-system,
+    Segoe UI,
+    Roboto,
+    Arial,
+    sans-serif;
+}
+a {
+  color: var(--brand-2);
+  text-decoration: none;
+}
+a:hover {
+  text-decoration: underline;
+}
+.topbar {
+  position: sticky;
+  top: 0;
+  z-index: 30;
+  background: rgba(10, 14, 20, 0.9);
+  backdrop-filter: blur(8px);
+  border-bottom: 1px solid var(--line);
+}
+.topbar .inner {
+  max-width: 1400px;
+  margin: 0 auto;
+  padding: 12px 18px;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 20px;
+}
+.brand a {
+  font-family: 'Raleway', sans-serif;
+  font-weight: 700;
+  color: #fff;
+  font-size: 1.1rem;
+}
+.main-nav {
+  display: flex;
+  gap: 14px;
+  flex-wrap: wrap;
+}
+.main-nav a {
+  padding: 6px 10px;
+  border-radius: 8px;
+  color: var(--muted);
+}
+.main-nav a.active,
+.main-nav a:hover {
+  background: #1a2533;
+  color: #fff;
+  text-decoration: none;
+}
+.layout {
+  max-width: 1400px;
+  margin: 0 auto;
+  display: grid;
+  grid-template-columns: 280px minmax(0, 1fr) 280px;
+  gap: 20px;
+  padding: 20px 18px 30px;
+}
+.sidebar,
+.toc {
+  position: sticky;
+  top: 72px;
+  max-height: calc(100vh - 90px);
+  overflow: auto;
+  background: var(--panel-2);
+  border: 1px solid var(--line);
+  border-radius: 12px;
+  padding: 12px;
+}
+.content {
+  min-width: 0;
+  background: var(--panel);
+  border: 1px solid var(--line);
+  border-radius: 12px;
+  padding: 24px;
+}
+.sidebar-sections {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+.sidebar-sections ul {
+  list-style: none;
+  padding-left: 12px;
+  margin: 8px 0 0;
+}
+.sidebar-sections li a {
+  display: block;
+  padding: 5px 8px;
+  border-radius: 7px;
+  color: var(--muted);
+}
+.sidebar-sections li.current > a,
+.sidebar-sections li a:hover {
+  background: #1a2533;
+  color: #fff;
+  text-decoration: none;
+}
+.g-head {
+  font-family: 'Raleway', sans-serif;
+  font-weight: 700;
+  color: #c7d6ea;
+  padding: 6px 8px;
+}
+h1,
+h2,
+h3,
+h4 {
+  font-family: 'Raleway', sans-serif;
+  color: #fff;
+  line-height: 1.25;
+}
+h1 {
+  margin-top: 0;
+}
+p,
+li,
+td,
+th {
+  line-height: 1.6;
+}
+pre,
+code {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+}
+code {
+  background: var(--code);
+  padding: 0.1rem 0.35rem;
+  border-radius: 6px;
+  border: 1px solid #1c2634;
+}
+pre {
+  background: var(--code);
+  padding: 14px;
+  border-radius: 10px;
+  border: 1px solid #1c2634;
+  overflow: auto;
+}
+table {
+  width: 100%;
+  border-collapse: collapse;
+  display: block;
+  overflow: auto;
+}
+th,
+td {
+  border: 1px solid var(--line);
+  padding: 8px 10px;
+  text-align: left;
+}
+th {
+  background: #172231;
+}
+blockquote {
+  margin: 0;
+  padding: 12px 14px;
+  border-left: 3px solid var(--brand);
+  background: #121d2b;
+  border-radius: 8px;
+}
+.page-toc h2 {
+  margin: 0 0 8px;
+}
+.toc-file {
+  margin: 0 0 8px;
+}
+.site-footer {
+  margin-top: 28px;
+  padding-top: 14px;
+  border-top: 1px solid var(--line);
+  color: var(--muted);
+  font-size: 0.92rem;
+}
+@media (max-width: 1180px) {
+  .layout {
+    grid-template-columns: 260px minmax(0, 1fr);
+  }
+  .toc {
+    display: none;
+  }
+}
+@media (max-width: 900px) {
+  .layout {
+    grid-template-columns: 1fr;
+  }
+  .sidebar {
+    position: static;
+    max-height: none;
+  }
+  .content {
+    padding: 18px;
+  }
+}

package/scripts/copy-examples.mjs

@@ -6,7 +6,7 @@ function copyAsciiMaze() {
   const srcDir = path.resolve('test', 'examples', 'asciiMaze');
   if (!fs.existsSync(srcDir)) {
     console.warn(
-      '[docs:examples] asciiMaze source directory not found, skipping'
+      '[docs:examples] asciiMaze source directory not found, skipping',
     );
     return;
   }
@@ -26,7 +26,7 @@ function copyFlappyBird() {
   const srcDir = path.resolve('test', 'examples', 'flappy_bird');
   if (!fs.existsSync(srcDir)) {
     console.warn(
-      '[docs:examples] flappy_bird source directory not found, skipping'
+      '[docs:examples] flappy_bird source directory not found, skipping',
     );
     return;
   }
@@ -47,7 +47,11 @@ function writeExamplesLandingPage() {
   fs.mkdirSync(examplesDir, { recursive: true });
 
   const demoEntries = [
-    { dirName: 'asciiMaze', label: 'asciiMaze', title: 'ASCII Maze (NeatapticTS)' },
+    {
+      dirName: 'asciiMaze',
+      label: 'asciiMaze',
+      title: 'ASCII Maze (NeatapticTS)',
+    },
     {
       dirName: 'flappy_bird',
       label: 'flappy_bird',
@@ -57,11 +61,11 @@ function writeExamplesLandingPage() {
 
   const linksMarkup = demoEntries
     .filter((entry) =>
-      fs.existsSync(path.join(examplesDir, entry.dirName, 'index.html'))
+      fs.existsSync(path.join(examplesDir, entry.dirName, 'index.html')),
     )
     .map(
       (entry) =>
-        `<li><a href="./${entry.dirName}/index.html">${entry.title}</a> <span class="demo-path">(examples/${entry.label})</span></li>`
+        `<li><a href="./${entry.dirName}/index.html">${entry.title}</a> <span class="demo-path">(examples/${entry.label})</span></li>`,
     )
     .join('');
 

package/scripts/export-onnx.mjs

@@ -21,7 +21,7 @@ const flag = (name) => args.includes(name);
 
 if (flag('--help') || flag('-h')) {
   console.log(
-    `Usage: node scripts/export-onnx.mjs --in network.json --out model.onnx.json [--metadata] [--batch] [--legacy] [--partial] [--mixed]\n`
+    `Usage: node scripts/export-onnx.mjs --in network.json --out model.onnx.json [--metadata] [--batch] [--legacy] [--partial] [--mixed]\n`,
   );
   process.exit(0);
 }
@@ -48,7 +48,7 @@ async function loadDist() {
     // Fallback to network/network.onnx if direct path changed
     return import(
       pathToFileURL(
-        path.resolve('dist', 'architecture', 'network', 'network.onnx.js')
+        path.resolve('dist', 'architecture', 'network', 'network.onnx.js'),
       ).href
     );
   });
@@ -76,7 +76,7 @@ async function loadDist() {
     fs.writeFileSync(
       path.resolve(outputFile),
       JSON.stringify(onnx, null, 2),
-      'utf8'
+      'utf8',
     );
     console.log(`ONNX JSON written to ${outputFile}`);
   } catch (err) {

package/scripts/generate-bench-tables.mjs

@@ -61,10 +61,10 @@ function buildVariantDeltaTable(artifact) {
   const ordered = Array.from(sizes).sort((a, b) => parseInt(a) - parseInt(b));
   const rows = [];
   rows.push(
-    'Size    Metric            Src Mean      Dist Mean     Δ Abs         Δ %        Flag          Result'
+    'Size    Metric            Src Mean      Dist Mean     Δ Abs         Δ %        Flag          Result',
   );
   rows.push(
-    '------  ----------------- ------------- ------------- ------------- ---------- ------------- ------------------------------------------------------------'
+    '------  ----------------- ------------- ------------- ------------- ---------- ------------- ------------------------------------------------------------',
   );
   const metrics = ['buildMs', 'fwdAvgMs', 'bytesPerConn'];
   for (const size of ordered) {
@@ -91,8 +91,8 @@ function buildVariantDeltaTable(artifact) {
             ? 'Dist bytes divergence'
             : 'Parity'
           : flag === '(REG)'
-          ? `Dist ${dAbs > 0 ? 'slower' : 'faster'} ${metric}`
-          : 'Parity';
+            ? `Dist ${dAbs > 0 ? 'slower' : 'faster'} ${metric}`
+            : 'Parity';
       rows.push(
         cell(size, 6) +
           '  ' +
@@ -106,19 +106,19 @@ function buildVariantDeltaTable(artifact) {
             typeof dAbs === 'number'
               ? (dAbs >= 0 ? '+' : '') + fmtNum(dAbs, 4)
               : '',
-            13
+            13,
           ) +
           ' ' +
           cell(
             typeof dPct === 'number'
               ? (dPct >= 0 ? '+' : '') + fmtNum(dPct, 2)
               : '',
-            10
+            10,
           ) +
           ' ' +
           cell(flag, 13) +
           ' ' +
-          note
+          note,
       );
     }
   }
@@ -130,10 +130,10 @@ function buildHeapTable(artifact) {
   const ordered = Array.from(sizes).sort((a, b) => parseInt(a) - parseInt(b));
   const rows = [];
   rows.push(
-    'Size    Metric         Src Bytes    Dist Bytes    Src MB    Dist MB   Δ Bytes      Δ %     Note'
+    'Size    Metric         Src Bytes    Dist Bytes    Src MB    Dist MB   Δ Bytes      Δ %     Note',
   );
   rows.push(
-    '------  -------------- ------------ ------------ --------- --------- ----------- ------- -------------------------------------------------'
+    '------  -------------- ------------ ------------ --------- --------- ----------- ------- -------------------------------------------------',
   );
   for (const size of ordered) {
     for (const metric of ['heapUsed', 'rss']) {
@@ -159,7 +159,7 @@ function buildHeapTable(artifact) {
           ' ' +
           cell((dPct >= 0 ? '+' : '') + dPct.toFixed(2), 7) +
           ' ' +
-          'Informational'
+          'Informational',
       );
     }
   }