@reicek/neataptic-ts 0.1.21 → 0.1.23

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

@@ -1,7 +1,24 @@
+/**
+ * Worker transport contracts for the Flappy Bird browser runtime.
+ *
+ * The browser UI and the evolution worker communicate through a deliberately
+ * explicit message protocol. The goal is educational as well as practical: it
+ * makes it obvious which values are computed off-thread, which snapshots are
+ * transferred frame-by-frame, and which events advance the demo state.
+ *
+ * If you want background reading, the Wikipedia article on "message passing"
+ * provides a useful conceptual frame for this boundary.
+ */
+
 /** Loose JSON-compatible network payload used by worker messages. */
 export type SerializedNetwork = Record<string, unknown>;
 
-/** Renderable pipe state snapshot emitted by the playback worker. */
+/**
+ * Renderable pipe state snapshot emitted by the playback worker.
+ *
+ * This is the smallest pipe shape the browser renderer needs for one frame:
+ * horizontal position plus the vertical corridor geometry.
+ */
 export interface PopulationPipe {
   id: number;
   xPx: number;
@@ -9,16 +26,52 @@ export interface PopulationPipe {
   gapSizePx: number;
 }
 
-/** Renderable bird state snapshot emitted by the playback worker. */
+/**
+ * Renderable bird state snapshot emitted by the playback worker.
+ *
+ * The browser does not receive full neural state here. It only gets the fields
+ * needed for presentation and HUD summaries, which keeps per-frame transport
+ * light.
+ */
 export interface PopulationBird {
-  color: string;
   yPx: number;
   pipesPassed: number;
   framesSurvived: number;
   done: boolean;
 }
 
-/** Worker payload describing evolved generation summary values. */
+/**
+ * Packed typed-array payload for playback pipe snapshot transport.
+ *
+ * Typed arrays keep frame payloads compact and predictable, which matters when
+ * the worker is streaming many birds and pipes across animation frames.
+ */
+export interface PackedPlaybackPipeSnapshot {
+  xPositionsPx: Float32Array;
+  gapCenterYPositionsPx: Float32Array;
+  gapSizesPx: Float32Array;
+}
+
+/**
+ * Packed typed-array payload for playback bird snapshot transport.
+ *
+ * This mirrors the pipe packing strategy so playback can move large population
+ * snapshots with less allocation pressure than object-per-bird messages.
+ */
+export interface PackedPlaybackBirdSnapshot {
+  yPositionsPx: Float32Array;
+  pipesPassed: Uint32Array;
+  framesSurvived: Uint32Array;
+  doneFlags: Uint8Array;
+}
+
+/**
+ * Worker payload describing evolved generation summary values.
+ *
+ * This is the browser-facing summary of one completed NEAT generation: what
+ * generation finished, how fit the best genome was, and optionally the best
+ * network for visualization or playback.
+ */
 export interface EvolutionGenerationPayload {
   generation: number;
   bestFitness: number;
@@ -39,19 +92,36 @@ export interface EvolutionWorkerErrorMessage {
   };
 }
 
-/** Per-frame snapshot received from the worker playback channel. */
+/**
+ * Per-frame snapshot received from the worker playback channel.
+ *
+ * A snapshot combines geometry, packed population state, and lightweight world
+ * metadata so the browser can render a deterministic frame without rerunning
+ * the simulation locally.
+ */
 export interface EvolutionPlaybackStepSnapshot {
+  format: 'packed-v1';
   frameIndex: number;
+  cumulativePipeTravelPx: number;
   visibleWorldWidthPx: number;
   visibleWorldHeightPx: number;
-  pipes: PopulationPipe[];
-  birds: PopulationBird[];
+  pipeCount: number;
+  birdCount: number;
+  pipes: PackedPlaybackPipeSnapshot;
+  birds: PackedPlaybackBirdSnapshot;
 }
 
-/** Worker message carrying one playback step and aggregate markers. */
+/**
+ * Worker message carrying one playback step and aggregate markers.
+ *
+ * Besides the frame snapshot itself, this message also carries summary values
+ * used by the HUD so the browser can show performance and progress without
+ * recomputing population-wide statistics on the main thread.
+ */
 export interface EvolutionPlaybackStepMessage {
   type: 'playback-step';
   payload: {
+    requestId: number;
     snapshot: EvolutionPlaybackStepSnapshot;
     instrumentation?: {
       activationCallsPerFrame: number;
@@ -65,13 +135,24 @@ export interface EvolutionPlaybackStepMessage {
   };
 }
 
-/** Union of all supported worker messages consumed by browser entry. */
+/**
+ * Union of all supported worker messages consumed by browser entry.
+ *
+ * A closed union keeps the main-thread message handler explicit and easy to
+ * audit when the protocol evolves.
+ */
 export type EvolutionWorkerMessage =
   | EvolutionGenerationReadyMessage
   | EvolutionPlaybackStepMessage
   | EvolutionWorkerErrorMessage;
 
-/** Lightweight per-frame telemetry emitted to HUD update callback. */
+/**
+ * Lightweight per-frame telemetry emitted to HUD update callback.
+ *
+ * These values are the browser-friendly metrics shown in the live status panel:
+ * how many birds remain, how far the leader has progressed, and how expensive
+ * the current playback cadence is.
+ */
 export interface PlaybackFrameStats {
   frameIndex: number;
   activeBirdCount: number;

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

@@ -0,0 +1,318 @@
+# browser-entry/host
+
+## browser-entry/host/host.types.ts
+
+### CanvasHostResult
+
+Public type contracts for the browser-entry host boundary.
+
+These types describe what the host builder returns to the runtime and how HUD
+value updates are represented once the UI tree exists.
+
+### HostStatsPartialValues
+
+Partial stats update map keyed by stats-table keys.
+
+Using a partial map lets the runtime update only the HUD fields that changed
+on a given tick.
+
+## browser-entry/host/host.ts
+
+### createCanvasHost
+
+`(containerElement: HTMLElement) => import("test/examples/flappy_bird/browser-entry/host/host.types").CanvasHostResult`
+
+Builds the browser demo host tree and returns rendering handles.
+
+This is the public host entrypoint used by the runtime startup path.
+
+Parameters:
+- `containerElement` - - Root host container.
+
+Returns: Canvas handles, stats cells and network render callback.
+
+### createCanvasHostInternal
+
+`(containerElement: HTMLElement) => import("test/examples/flappy_bird/browser-entry/host/host.types").CanvasHostResult`
+
+Builds the browser demo host tree and returns rendering handles.
+
+The orchestration is deliberately step-shaped: clear old DOM, build layout,
+create canvases, wire resize behavior, render placeholders, then return the
+handles the runtime will mutate during execution.
+
+Parameters:
+- `containerElement` - - Root host container.
+
+Returns: Canvas handles, stats cells and network render callback.
+
+### createHeaderFrameRenderer
+
+`(headerCanvas: HTMLCanvasElement, headerContext: CanvasRenderingContext2D) => () => void`
+
+Creates the reusable title-frame renderer for the header canvas.
+
+Parameters:
+- `headerCanvas` - - Header canvas element.
+- `headerContext` - - Header canvas 2D context.
+
+Returns: Callback that redraws the framed title.
+
+### createHostCanvasElements
+
+`(hostVisualPrimitives: HostVisualPrimitives) => HostCanvasElements`
+
+Creates the canvases and 2D contexts used by the host UI.
+
+The host manages three canvas surfaces with different jobs: a title/header
+frame, the main simulation view, and the side-panel network visualization.
+
+Parameters:
+- `hostVisualPrimitives` - - Shared visual primitives for border and shadow styling.
+
+Returns: Simulation, header, and network canvases with required contexts.
+
+### createHostLayoutElements
+
+`(hostVisualPrimitives: HostVisualPrimitives) => HostLayoutElements`
+
+Creates the host layout elements used to assemble the browser UI tree.
+
+This creates the structural DOM only. Canvases, stats content, and
+visualization wiring are layered on afterward.
+
+Parameters:
+- `hostVisualPrimitives` - - Shared visual primitives for border and shadow styling.
+
+Returns: Layout elements grouped by host responsibility.
+
+### createHostNetworkVisualizationController
+
+`(networkCanvasHost: HTMLDivElement, networkCanvas: HTMLCanvasElement, networkContext: CanvasRenderingContext2D) => HostNetworkVisualizationController`
+
+Creates the network visualization renderer and redraw controller.
+
+Parameters:
+- `networkCanvasHost` - - Host element wrapping the network canvas.
+- `networkCanvas` - - Network visualization canvas.
+- `networkContext` - - Network visualization 2D context.
+
+Returns: Renderer and redraw callbacks for the network panel.
+
+### HostVisualPrimitives
+
+Browser host assembly for the Flappy Bird demo UI.
+
+The host boundary is responsible for building the browser-side shell around
+the simulation: framed title, main canvas, stats panel, and network
+visualization panel. It does not run evolution itself; it prepares the stage
+on which the runtime loop renders.
+
+### installCanvasHostResizeHooks
+
+`(canvas: HTMLCanvasElement, hostLayoutElements: HostLayoutElements, networkCanvas: HTMLCanvasElement, drawHeaderFrame: () => void, hostNetworkVisualizationController: HostNetworkVisualizationController) => void`
+
+Installs responsive resize hooks for the simulation canvas and side panel.
+
+Parameters:
+- `canvas` - - Simulation canvas.
+- `hostLayoutElements` - - Prepared layout containers.
+- `networkCanvas` - - Network visualization canvas.
+- `drawHeaderFrame` - - Callback that redraws the header title.
+- `hostNetworkVisualizationController` - - Network panel resize/redraw controller.
+
+Returns: Nothing.
+
+### mountCanvasHostTree
+
+`(containerElement: HTMLElement, hostLayoutElements: HostLayoutElements, headerCanvas: HTMLCanvasElement, canvas: HTMLCanvasElement, networkCanvas: HTMLCanvasElement) => void`
+
+Mounts the completed host DOM tree into the container in final order.
+
+Parameters:
+- `containerElement` - - Root host container.
+- `hostLayoutElements` - - Prepared layout containers.
+- `headerCanvas` - - Header title canvas.
+- `canvas` - - Main simulation canvas.
+- `networkCanvas` - - Network visualization canvas.
+
+Returns: Nothing.
+
+### renderInitialCanvasHostState
+
+`(drawHeaderFrame: () => void, renderNetworkArchitecture: (network: import("src/architecture/network").default | undefined, inputSize: number, outputSize: number) => void) => void`
+
+Renders the initial header and placeholder network visualization state.
+
+Parameters:
+- `drawHeaderFrame` - - Callback that redraws the header title.
+- `renderNetworkArchitecture` - - Network visualization renderer.
+
+Returns: Nothing.
+
+### resetHostContainer
+
+`(containerElement: HTMLElement) => void`
+
+Clears any previous runtime DOM before rebuilding the browser host tree.
+
+The demo rebuilds the host from scratch on each startup so repeated runs begin
+from a known clean DOM state.
+
+Parameters:
+- `containerElement` - - Root host container.
+
+Returns: Nothing.
+
+### resolveHostVisualPrimitives
+
+`() => HostVisualPrimitives`
+
+Resolves shared border, shadow, and padding values for host assembly.
+
+Centralizing these primitives keeps the DOM-building code focused on layout
+structure instead of duplicating presentation constants everywhere.
+
+Returns: Shared visual primitives reused across host sections.
+
+### updateStatsTableValues
+
+`(statsValueByKey: Partial<Record<import("test/examples/flappy_bird/browser-entry/browser-entry.stats.types").FlappyStatsKey, HTMLTableCellElement>>, partialValues: Partial<Record<import("test/examples/flappy_bird/browser-entry/browser-entry.stats.types").FlappyStatsKey, string>>) => void`
+
+Applies partial stat updates to the rendered stats table.
+
+The runtime writes HUD values incrementally, so the host exposes a narrow
+partial-update helper rather than requiring full table redraws.
+
+Parameters:
+- `statsValueByKey` - - Lookup of stat keys to value cells.
+- `partialValues` - - Subset of values to write this tick.
+
+Returns: Nothing.
+
+## browser-entry/host/host.constants.ts
+
+### host.constants
+
+Shared presentation constants for browser host assembly.
+
+These values tune the spacing and responsiveness of the host HUD and side
+panels without burying layout numbers inside DOM-building code.
+
+### FLAPPY_HOST_PANEL_PADDING
+
+### FLAPPY_HOST_PANEL_TRANSITION
+
+### FLAPPY_HOST_STATS_SPLIT_GAP
+
+### FLAPPY_HOST_TABLE_FONT_SIZE
+
+### FLAPPY_HOST_TABLE_HOST_PADDING
+
+## browser-entry/host/host.dom.service.ts
+
+### host.dom.service
+
+Low-level DOM safety helpers for the browser host boundary.
+
+Host assembly depends on several canvases. This helper turns the browser's
+nullable `getContext` API into a strict contract before higher-level host
+assembly begins.
+
+### resolveRequiredCanvas2dContext
+
+`(canvas: HTMLCanvasElement, errorMessage: string) => CanvasRenderingContext2D`
+
+Low-level DOM safety helpers for the browser host boundary.
+
+Host assembly depends on several canvases. This helper turns the browser's
+nullable `getContext` API into a strict contract before higher-level host
+assembly begins.
+
+## browser-entry/host/host.stats.service.ts
+
+### createAndAttachHostStatsTable
+
+`(statsTableHost: HTMLElement) => Partial<Record<import("test/examples/flappy_bird/browser-entry/browser-entry.stats.types").FlappyStatsKey, HTMLTableCellElement>>`
+
+Stats-table creation and update helpers for the browser host HUD.
+
+The host treats the stats table as a small indexed dashboard: build it once,
+keep direct references to value cells, then apply partial text updates during
+the runtime loop.
+
+### updateStatsTableValues
+
+`(statsValueByKey: Partial<Record<import("test/examples/flappy_bird/browser-entry/browser-entry.stats.types").FlappyStatsKey, HTMLTableCellElement>>, partialValues: Partial<Record<import("test/examples/flappy_bird/browser-entry/browser-entry.stats.types").FlappyStatsKey, string>>) => void`
+
+Applies partial stat updates to the rendered stats table.
+
+This keeps HUD writes cheap and explicit: only supplied keys are rewritten,
+and architecture values receive their display formatting in one place.
+
+Parameters:
+- `statsValueByKey` - - Lookup of stat keys to value cells.
+- `partialValues` - - Subset of values to write this tick.
+
+Returns: Nothing.
+
+## browser-entry/host/host.canvas.service.ts
+
+### host.canvas.service
+
+Canvas sizing helpers for the browser host boundary.
+
+These utilities keep host layout and backing-store sizing aligned so the
+simulation and network canvases render crisply without stretching artifacts.
+
+### applyCanvasBackingSize
+
+`(canvas: HTMLCanvasElement, widthPx: number, heightPx: number) => boolean`
+
+Canvas sizing helpers for the browser host boundary.
+
+These utilities keep host layout and backing-store sizing aligned so the
+simulation and network canvases render crisply without stretching artifacts.
+
+### applySimulationCanvasBounds
+
+`(canvas: HTMLCanvasElement, widthPx: number, heightPx: number) => boolean`
+
+Applies fixed simulation-canvas bounds so layout does not stretch unexpectedly.
+
+The main simulation canvas uses fixed bounds because the world renderer is
+tuned for a controlled viewport rather than fluid DOM stretching.
+
+Parameters:
+- `canvas` - - Simulation canvas element.
+- `widthPx` - - Desired width in pixels.
+- `heightPx` - - Desired height in pixels.
+
+Returns: True when backing-store dimensions changed.
+
+### resolveNetworkCanvasSizePx
+
+`(networkCanvasHost: HTMLElement, hostInsetPx: number) => { widthPx: number; heightPx: number; }`
+
+Computes the drawable network canvas size from host element dimensions.
+
+The side-panel network view needs the drawable size after panel insets are
+accounted for, not just the raw host client box.
+
+Parameters:
+- `networkCanvasHost` - - Host element wrapping the network canvas.
+- `hostInsetPx` - - Total inset to subtract from both dimensions.
+
+Returns: Width/height pair in pixels.
+
+## browser-entry/host/host.resize.service.ts
+
+### installResponsiveViewportSizing
+
+`(canvas: HTMLCanvasElement, containerElement: HTMLElement, mainSplitContainer: HTMLElement, statsContainer: HTMLElement, statsSplitContainer: HTMLElement, statsTableHost: HTMLElement, networkCanvas: HTMLCanvasElement, networkCanvasHost: HTMLElement, onNetworkResize: () => void) => void`
+
+Top-level responsive sizing orchestration for the browser host.
+
+This module wires the host resize lifecycle together: gather the relevant DOM
+elements, run the initial layout pass, and keep canvas sizing synchronized with
+viewport changes over time.

package/test/examples/flappy_bird/browser-entry/host/host.canvas.service.ts

@@ -1,6 +1,16 @@
+/**
+ * Canvas sizing helpers for the browser host boundary.
+ *
+ * These utilities keep host layout and backing-store sizing aligned so the
+ * simulation and network canvases render crisply without stretching artifacts.
+ */
+
 /**
  * Applies a canvas backing store size and CSS width/height.
  *
+ * Browser canvases have both backing-store dimensions and CSS box dimensions;
+ * this helper updates both together.
+ *
  * @param canvas - Target canvas element.
  * @param widthPx - Desired backing-store width in pixels.
  * @param heightPx - Desired backing-store height in pixels.
@@ -28,6 +38,9 @@ export function applyCanvasBackingSize(
 /**
  * Applies fixed simulation-canvas bounds so layout does not stretch unexpectedly.
  *
+ * The main simulation canvas uses fixed bounds because the world renderer is
+ * tuned for a controlled viewport rather than fluid DOM stretching.
+ *
  * @param canvas - Simulation canvas element.
  * @param widthPx - Desired width in pixels.
  * @param heightPx - Desired height in pixels.
@@ -52,6 +65,9 @@ export function applySimulationCanvasBounds(
 /**
  * Computes the drawable network canvas size from host element dimensions.
  *
+ * The side-panel network view needs the drawable size after panel insets are
+ * accounted for, not just the raw host client box.
+ *
  * @param networkCanvasHost - Host element wrapping the network canvas.
  * @param hostInsetPx - Total inset to subtract from both dimensions.
  * @returns Width/height pair in pixels.

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

@@ -1,24 +1,44 @@
+/**
+ * Shared presentation constants for browser host assembly.
+ *
+ * These values tune the spacing and responsiveness of the host HUD and side
+ * panels without burying layout numbers inside DOM-building code.
+ */
+
 /**
  * Shared panel padding used by the host stats container.
+ *
+ * This controls the interior breathing room of the main stats panel.
  */
 export const FLAPPY_HOST_PANEL_PADDING = '8px';
 
 /**
  * Shared table host padding used by the stats value section.
+ *
+ * The table host gets slightly different padding so dense stat rows remain
+ * readable without wasting horizontal space.
  */
 export const FLAPPY_HOST_TABLE_HOST_PADDING = '6px 8px';
 
 /**
  * Shared stats table font size.
+ *
+ * The table uses a compact monospace size so many HUD rows fit comfortably in
+ * the host panel.
  */
 export const FLAPPY_HOST_TABLE_FONT_SIZE = '12px';
 
 /**
  * Shared panel max-height transition.
+ *
+ * This supports the subtle host-panel resize behavior during responsive layout
+ * changes.
  */
 export const FLAPPY_HOST_PANEL_TRANSITION = 'max-height 120ms ease-out';
 
 /**
  * Shared stats split gap.
+ *
+ * This controls the gutter between the table column and the network panel.
  */
 export const FLAPPY_HOST_STATS_SPLIT_GAP = '8px';

package/test/examples/flappy_bird/browser-entry/host/host.dom.service.ts

@@ -1,6 +1,16 @@
+/**
+ * Low-level DOM safety helpers for the browser host boundary.
+ *
+ * Host assembly depends on several canvases. This helper turns the browser's
+ * nullable `getContext` API into a strict contract before higher-level host
+ * assembly begins.
+ */
+
 /**
  * Resolves a required 2D context from a canvas element.
  *
+ * Failing early here keeps later rendering code free from repeated null checks.
+ *
  * @param canvas - Target canvas element.
  * @param errorMessage - Error message when 2D context is unavailable.
  * @returns Canvas 2D rendering context.