@reicek/neataptic-ts 0.1.21 → 0.1.23

package/test/examples/flappy_bird/browser-entry/runtime/runtime.evolution-loop.service.ts

@@ -20,8 +20,20 @@ import type {
 } from '../browser-entry.types';
 import type { RuntimeTelemetryState } from './runtime.telemetry.service';
 
+/**
+ * Long-running evolution/playback orchestration for the browser runtime.
+ *
+ * This loop is the heart of the interactive demo. It repeatedly asks the worker
+ * for the next evolved generation, updates the HUD and network view, plays back
+ * that generation on the canvas, then folds the outcome into best-so-far
+ * browser state.
+ */
+
 /**
  * Dependencies required to run the browser runtime evolution loop.
+ *
+ * Grouping these dependencies into one object keeps the public loop entry more
+ * declarative and avoids a long positional parameter list.
  */
 export interface RuntimeEvolutionLoopOptions {
   evolutionWorker: Worker;
@@ -40,6 +52,13 @@ export interface RuntimeEvolutionLoopOptions {
 /**
  * Runs generation orchestration and playback until a stop signal is observed.
  *
+ * The loop alternates between two phases:
+ * 1. Evolve off-thread until the worker emits the next best-generation summary.
+ * 2. Play that generation back on the main thread while streaming HUD updates.
+ *
+ * This rhythm makes the demo feel like a live training dashboard instead of a
+ * one-shot batch job.
+ *
  * @param options - Runtime evolution dependencies and mutable state accessors.
  * @returns Nothing.
  */

package/test/examples/flappy_bird/browser-entry/runtime/runtime.lifecycle.service.ts

@@ -0,0 +1,96 @@
+import { disconnectRuntimeTelemetry } from './runtime.telemetry.service';
+import type {
+  RuntimeMutableLifecycleState,
+  RuntimeRunHandle,
+  RuntimeStartContext,
+} from './runtime.types';
+
+/**
+ * Lifecycle and teardown helpers for the browser runtime.
+ *
+ * The runtime behaves like a small application process. These helpers create the
+ * mutable state and public handle needed to stop it cleanly, terminate the
+ * worker, and resolve the completion promise exactly once.
+ */
+
+/**
+ * Creates mutable lifecycle state for stop semantics and completion signaling.
+ *
+ * The returned object is shared across runtime orchestration paths so both
+ * expected shutdown and failure-driven shutdown follow the same completion flow.
+ *
+ * @returns Mutable lifecycle state used by the run handle.
+ */
+export function createRuntimeLifecycleState(): RuntimeMutableLifecycleState {
+  let resolveDone: (() => void) | undefined;
+  const done = new Promise<void>((resolve) => {
+    resolveDone = resolve;
+  });
+
+  // Step 1: Return idempotent lifecycle state with an externally resolvable promise.
+  return {
+    stopped: false,
+    resolveDone,
+    done,
+  };
+}
+
+/**
+ * Builds the public run handle and binds it to runtime teardown behavior.
+ *
+ * The handle is the user-facing control surface for the demo. Internally it is
+ * just a thin closure layer over the mutable lifecycle state and startup
+ * context.
+ *
+ * @param runtimeStartContext - Shared runtime start context.
+ * @param runtimeLifecycleState - Mutable lifecycle state for stop semantics.
+ * @returns Public run handle exposed to callers.
+ */
+export function createRuntimeRunHandle(
+  runtimeStartContext: RuntimeStartContext,
+  runtimeLifecycleState: RuntimeMutableLifecycleState,
+): RuntimeRunHandle {
+  /**
+   * Stops the running demo and performs idempotent resource teardown.
+   *
+   * @returns Nothing.
+   */
+  const stop = () => {
+    // Step 1: Keep stop idempotent for repeated calls from multiple paths.
+    if (runtimeLifecycleState.stopped) {
+      return;
+    }
+
+    // Step 2: Flip the loop guard before releasing runtime resources.
+    runtimeLifecycleState.stopped = true;
+
+    // Step 3: Disconnect telemetry, notify the worker, and terminate it.
+    disconnectRuntimeTelemetry(runtimeStartContext.runtimeTelemetryState);
+    runtimeStartContext.evolutionWorker.postMessage({ type: 'stop' });
+    runtimeStartContext.evolutionWorker.terminate();
+
+    // Step 4: Resolve the externally visible completion promise.
+    runtimeLifecycleState.resolveDone?.();
+  };
+
+  /**
+   * Reports whether the runtime loop has been stopped.
+   *
+   * @returns `true` when the runtime has been stopped.
+   */
+  const isStopped = () => runtimeLifecycleState.stopped;
+
+  /**
+   * Reports whether the runtime loop is currently active.
+   *
+   * @returns `true` while the runtime remains active.
+   */
+  const isRunning = () => !isStopped();
+
+  // Step 1: Return the public lifecycle handle bound to the mutable state.
+  return {
+    stop,
+    isRunning,
+    done: runtimeLifecycleState.done,
+  };
+}

package/test/examples/flappy_bird/browser-entry/runtime/runtime.startup.service.ts

@@ -0,0 +1,92 @@
+import { createCanvasHost, updateStatsTableValues } from '../host/host';
+import { createEvolutionWorker } from '../worker-channel/worker-channel';
+import {
+  FLAPPY_BROWSER_ELITISM_COUNT,
+  FLAPPY_BROWSER_POPULATION_SIZE,
+  FLAPPY_HUD_INITIALIZING_TEXT,
+  FLAPPY_HUD_ZERO_TEXT,
+} from '../../constants/constants';
+import {
+  FLAPPY_NETWORK_INPUT_SIZE,
+  FLAPPY_NETWORK_OUTPUT_SIZE,
+} from '../../constants/constants';
+import { resolveRequiredRuntimeHostElement } from './runtime.errors';
+import { createRuntimeTelemetryState } from './runtime.telemetry.service';
+import type {
+  RuntimeContainerTarget,
+  RuntimeStartConfig,
+  RuntimeStartContext,
+} from './runtime.types';
+
+/**
+ * Runtime startup helpers for the Flappy Bird browser demo.
+ *
+ * These functions cover the pre-loop phase: resolve the host container, build a
+ * typed browser view, derive static config, create telemetry state, spawn the
+ * worker, and paint the initial HUD before evolution begins.
+ */
+
+/**
+ * Creates the shared runtime startup dependencies used by the entry orchestration.
+ *
+ * This is the main bootstrap fold for browser startup. After it returns, the
+ * runtime has a host view, a worker channel, telemetry state, and a resolved
+ * configuration object.
+ *
+ * @param container - Element id or HTMLElement to host the demo.
+ * @returns Shared runtime start context for setup and loop launch.
+ */
+export function createRuntimeStartContext(
+  container: RuntimeContainerTarget,
+): RuntimeStartContext {
+  // Step 1: Resolve and validate the runtime host element.
+  const hostElement = resolveRequiredRuntimeHostElement(container);
+
+  // Step 2: Construct the static runtime configuration values.
+  const config = createRuntimeStartConfig();
+
+  // Step 3: Create the browser host, telemetry state, and worker channel.
+  return {
+    config,
+    viewContext: createCanvasHost(hostElement),
+    runtimeTelemetryState: createRuntimeTelemetryState(),
+    evolutionWorker: createEvolutionWorker(),
+  };
+}
+
+/**
+ * Paints the initial runtime HUD values before the evolution loop starts.
+ *
+ * The HUD is seeded immediately so the page communicates that startup is in
+ * progress rather than appearing blank while the worker and loop are booting.
+ *
+ * @param runtimeStartContext - Shared runtime start context.
+ * @returns Nothing.
+ */
+export function initializeRuntimeHud(
+  runtimeStartContext: RuntimeStartContext,
+): void {
+  // Step 1: Publish the initializing state and empty bird counters.
+  updateStatsTableValues(runtimeStartContext.viewContext.statsValueByKey, {
+    status: FLAPPY_HUD_INITIALIZING_TEXT,
+    birds: `${FLAPPY_HUD_ZERO_TEXT}/${runtimeStartContext.config.populationSize}`,
+  });
+}
+
+/**
+ * Resolves the static runtime configuration used during browser startup.
+ *
+ * Centralizing the configuration fold here makes the runtime entry read as
+ * orchestration instead of constant plumbing.
+ *
+ * @returns Runtime configuration derived from shared constants.
+ */
+function createRuntimeStartConfig(): RuntimeStartConfig {
+  // Step 1: Fold shared runtime constants into one descriptive config object.
+  return {
+    inputSize: FLAPPY_NETWORK_INPUT_SIZE,
+    outputSize: FLAPPY_NETWORK_OUTPUT_SIZE,
+    populationSize: FLAPPY_BROWSER_POPULATION_SIZE,
+    elitismCount: FLAPPY_BROWSER_ELITISM_COUNT,
+  };
+}

package/test/examples/flappy_bird/browser-entry/runtime/runtime.telemetry.service.ts

@@ -13,8 +13,20 @@ import {
 } from '../../constants/constants';
 import type { PlaybackFrameStats } from '../browser-entry.types';
 
+/**
+ * Runtime telemetry helpers for live browser HUD updates.
+ *
+ * The runtime tracks a small rolling window of operational signals such as HUD
+ * update frequency and minor GC activity. These are not part of the simulation
+ * itself; they are observability features for understanding how expensive the
+ * browser playback loop is.
+ */
+
 /**
  * Runtime telemetry mutable state used for rolling HUD metrics.
+ *
+ * The state keeps timestamp windows rather than pre-aggregated counters so the
+ * HUD can report smoothed recent rates instead of lifetime totals.
  */
 export interface RuntimeTelemetryState {
   hudUpdateTimestampsMs: number[];
@@ -25,6 +37,9 @@ export interface RuntimeTelemetryState {
 /**
  * Creates telemetry state and attaches optional minor-GC observer.
  *
+ * Instrumentation is feature-gated so the demo can run in a low-noise mode when
+ * telemetry is not desired.
+ *
  * @returns Initialized telemetry state.
  */
 export function createRuntimeTelemetryState(): RuntimeTelemetryState {
@@ -41,6 +56,9 @@ export function createRuntimeTelemetryState(): RuntimeTelemetryState {
 /**
  * Disconnects runtime telemetry observers.
  *
+ * This is part of runtime teardown and prevents instrumentation observers from
+ * lingering after the demo has stopped.
+ *
  * @param telemetryState - Runtime telemetry state.
  * @returns Nothing.
  */
@@ -53,6 +71,9 @@ export function disconnectRuntimeTelemetry(
 /**
  * Resolves default telemetry HUD values used before first playback updates.
  *
+ * The initial values make the instrumentation section self-describing even
+ * before the first playback frame arrives.
+ *
  * @returns Initial telemetry field values.
  */
 export function resolveInitialRuntimeTelemetryHudValues(): {
@@ -82,6 +103,9 @@ export function resolveInitialRuntimeTelemetryHudValues(): {
 /**
  * Resolves per-frame telemetry HUD values and updates rolling windows.
  *
+ * On each published playback frame, the runtime folds the new telemetry sample
+ * into rolling windows and emits human-readable HUD strings.
+ *
  * @param frameStats - Playback frame stats for the current frame.
  * @param telemetryState - Runtime telemetry mutable state.
  * @returns Formatted telemetry HUD values for this frame.

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

@@ -1,26 +1,14 @@
-import { createCanvasHost, updateStatsTableValues } from '../host/host';
-import {
-  createRuntimeTelemetryState,
-  disconnectRuntimeTelemetry,
-} from './runtime.telemetry.service';
-import { createEvolutionWorker } from '../worker-channel/worker-channel';
-import {
-  FLAPPY_BROWSER_ELITISM_COUNT,
-  FLAPPY_BROWSER_POPULATION_SIZE,
-  DEFAULT_CONTAINER_ID,
-  FLAPPY_HUD_INITIALIZING_TEXT,
-  FLAPPY_HUD_ZERO_TEXT,
-} from '../../constants/constants';
+import { DEFAULT_CONTAINER_ID } from '../../constants/constants';
+import { installRuntimeBrowserGlobals } from './runtime.browser-globals.service';
+import { launchRuntimeEvolution } from './runtime.evolution-launch.service';
 import {
-  FLAPPY_NETWORK_INPUT_SIZE,
-  FLAPPY_NETWORK_OUTPUT_SIZE,
-} from '../../constants/constants';
+  createRuntimeLifecycleState,
+  createRuntimeRunHandle,
+} from './runtime.lifecycle.service';
 import {
-  resolveRequiredRuntimeHostElement,
-  resolveRuntimeHudErrorStatus,
-} from './runtime.errors';
-import { runRuntimeEvolutionLoop } from './runtime.evolution-loop.service';
-import { installRuntimeBrowserGlobals } from './runtime.browser-globals.service';
+  createRuntimeStartContext,
+  initializeRuntimeHud,
+} from './runtime.startup.service';
 import type { RuntimeContainerTarget, RuntimeRunHandle } from './runtime.types';
 
 export type { RuntimeRunHandle as FlappyBirdRunHandle } from './runtime.types';
@@ -48,106 +36,28 @@ export type { RuntimeRunHandle as FlappyBirdRunHandle } from './runtime.types';
 export const start = async (
   container: RuntimeContainerTarget = DEFAULT_CONTAINER_ID,
 ): Promise<RuntimeRunHandle> => {
-  // Step 1: Resolve and validate the host element where the demo will render.
-  const hostElement = resolveRequiredRuntimeHostElement(container);
-
-  /** Network input width used when rendering architecture labels. */
-  const inputSize = FLAPPY_NETWORK_INPUT_SIZE;
-  /** Network output width used when rendering architecture labels. */
-  const outputSize = FLAPPY_NETWORK_OUTPUT_SIZE;
-  /** Worker initialization population size for browser evolution/playback. */
-  const populationSize = FLAPPY_BROWSER_POPULATION_SIZE;
-  /** Worker initialization elitism count for browser evolution/playback. */
-  const elitismCount = FLAPPY_BROWSER_ELITISM_COUNT;
-
-  // Step 2: Create the browser host (canvas + HUD + network panel render hook).
-  const { canvas, context, statsValueByKey, renderNetworkArchitecture } =
-    createCanvasHost(hostElement);
-
-  // Step 3: Attach optional runtime instrumentation observer when enabled.
-  const runtimeTelemetryState = createRuntimeTelemetryState();
-
-  // Step 4: Paint initial status before worker bootstrapping starts.
-  updateStatsTableValues(statsValueByKey, {
-    status: FLAPPY_HUD_INITIALIZING_TEXT,
-    birds: `${FLAPPY_HUD_ZERO_TEXT}/${populationSize}`,
-  });
-
-  // Step 5: Create the evolution worker channel used by the orchestrator loop.
-  const evolutionWorker = createEvolutionWorker();
-
-  /** Mutable stop flag consulted by all loop and callback paths. */
-  let stopped = false;
-  /** Resolver captured for the externally exposed completion promise. */
-  let resolveDone: (() => void) | undefined;
-  /** Promise that resolves exactly once after stop/teardown is complete. */
-  const done = new Promise<void>((resolve) => {
-    resolveDone = resolve;
-  });
-
-  /**
-   * Stops the running demo and performs idempotent resource teardown.
-   *
-   * Teardown includes:
-   * - disconnecting instrumentation observers,
-   * - notifying and terminating the worker,
-   * - resolving the `done` promise exactly once.
-   *
-   * @returns Nothing.
-   */
-  const stop = () => {
-    // Step 1: Keep stop idempotent for repeated calls from multiple paths.
-    if (stopped) {
-      return;
-    }
-
-    // Step 2: Flip loop guard first so no new async work starts.
-    stopped = true;
-
-    // Step 3: Release runtime resources in deterministic order.
-    disconnectRuntimeTelemetry(runtimeTelemetryState);
-    evolutionWorker.postMessage({ type: 'stop' });
-    evolutionWorker.terminate();
-
-    // Step 4: Resolve external completion handle.
-    resolveDone?.();
-  };
-
-  /**
-   * Reports whether the demo loop has been stopped.
-   *
-   * @returns `true` when stopped.
-   */
-  const isStopped = () => stopped;
-
-  /**
-   * Reports whether the demo loop is currently active.
-   *
-   * @returns `true` when not stopped.
-   */
-  const isRunning = () => !stopped;
-
-  // Step 6: Start orchestration loop and route unexpected errors to HUD + teardown.
-  void runRuntimeEvolutionLoop({
-    evolutionWorker,
-    canvas,
-    context,
-    statsValueByKey,
-    renderNetworkArchitecture,
-    populationSize,
-    elitismCount,
-    inputSize,
-    outputSize,
-    runtimeTelemetryState,
-    isStopped,
-  }).catch((error: unknown) => {
-    updateStatsTableValues(statsValueByKey, {
-      status: resolveRuntimeHudErrorStatus(error),
-    });
-    stop();
-  });
-
-  return { stop, isRunning, done };
+  // Step 1: Resolve the runtime view, worker, telemetry, and static config.
+  const runtimeStartContext = createRuntimeStartContext(container);
+
+  // Step 2: Paint the initial HUD state before evolution bootstrapping starts.
+  initializeRuntimeHud(runtimeStartContext);
+
+  // Step 3: Create lifecycle state and externally exposed run-handle methods.
+  const runtimeLifecycleState = createRuntimeLifecycleState();
+  const runtimeRunHandle = createRuntimeRunHandle(
+    runtimeStartContext,
+    runtimeLifecycleState,
+  );
+
+  // Step 4: Launch the runtime evolution loop with error-to-HUD routing.
+  launchRuntimeEvolution(
+    runtimeStartContext,
+    runtimeLifecycleState,
+    runtimeRunHandle.stop,
+  );
+
+  // Step 5: Return the public lifecycle controls to the caller.
+  return runtimeRunHandle;
 };
 
 installRuntimeBrowserGlobals(start);

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

@@ -1,19 +1,84 @@
+import { createCanvasHost } from '../host/host';
 import type {
   FlappyBirdRunHandle,
   RuntimeWindow,
 } from '../browser-entry.types';
+import type { RuntimeTelemetryState } from './runtime.telemetry.service';
+
+/**
+ * Core runtime contracts for the Flappy Bird browser demo.
+ *
+ * The runtime boundary is where the browser-side application comes together:
+ * DOM host setup, worker creation, telemetry wiring, lifecycle control, and the
+ * configuration passed into the evolution loop.
+ */
 
 /**
  * Public run handle returned by the browser runtime entrypoint.
+ *
+ * The handle is intentionally minimal so callers can treat the demo like a
+ * long-running process with start/stop/status semantics.
  */
 export type RuntimeRunHandle = FlappyBirdRunHandle;
 
 /**
  * Browser `window` extension shape used for global runtime wiring.
+ *
+ * This keeps the auto-start and compatibility globals typed without coupling
+ * the runtime modules directly to ad hoc window-property access.
  */
 export type RuntimeGlobalWindow = RuntimeWindow;
 
 /**
  * Container argument accepted by the browser runtime start function.
+ *
+ * Callers can either pass a host element directly or provide an element id for
+ * late resolution inside the runtime startup path.
  */
 export type RuntimeContainerTarget = string | HTMLElement;
+
+/**
+ * Static runtime configuration resolved before the browser loop starts.
+ *
+ * These values define the high-level NEAT and network shape used for the whole
+ * browser session.
+ */
+export interface RuntimeStartConfig {
+  inputSize: number;
+  outputSize: number;
+  populationSize: number;
+  elitismCount: number;
+}
+
+/**
+ * Browser host view handles used by the runtime entry orchestration.
+ *
+ * This is the typed bundle of canvas, HUD, and visualization handles returned
+ * by the host layer once the browser DOM has been prepared.
+ */
+export type RuntimeHostViewContext = ReturnType<typeof createCanvasHost>;
+
+/**
+ * Mutable lifecycle state used to coordinate stop semantics and completion.
+ *
+ * The runtime loop is asynchronous and long-lived, so the browser keeps a small
+ * shared lifecycle object for idempotent shutdown and completion signaling.
+ */
+export interface RuntimeMutableLifecycleState {
+  stopped: boolean;
+  resolveDone?: () => void;
+  done: Promise<void>;
+}
+
+/**
+ * Shared runtime startup dependencies created before evolution begins.
+ *
+ * Once this context exists, the browser has everything it needs to launch the
+ * actual evolution/playback loop.
+ */
+export interface RuntimeStartContext {
+  config: RuntimeStartConfig;
+  viewContext: RuntimeHostViewContext;
+  runtimeTelemetryState: RuntimeTelemetryState;
+  evolutionWorker: Worker;
+}