@reicek/neataptic-ts 0.1.21 → 0.1.22

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

@@ -0,0 +1,45 @@
+import { updateStatsTableValues } from '../host/host';
+import { resolveRuntimeHudErrorStatus } from './runtime.errors';
+import { runRuntimeEvolutionLoop } from './runtime.evolution-loop.service';
+import type {
+  RuntimeMutableLifecycleState,
+  RuntimeStartContext,
+} from './runtime.types';
+
+/**
+ * Starts the runtime evolution loop and routes unexpected failures to the HUD.
+ *
+ * @param runtimeStartContext - Shared runtime start context.
+ * @param runtimeLifecycleState - Mutable lifecycle state used for stop checks.
+ * @param stop - Idempotent stop function bound to the current runtime handle.
+ * @returns Nothing.
+ */
+export function launchRuntimeEvolution(
+  runtimeStartContext: RuntimeStartContext,
+  runtimeLifecycleState: RuntimeMutableLifecycleState,
+  stop: () => void,
+): void {
+  const { config, evolutionWorker, runtimeTelemetryState, viewContext } =
+    runtimeStartContext;
+
+  // Step 1: Start the long-running evolution orchestration loop.
+  void runRuntimeEvolutionLoop({
+    evolutionWorker,
+    canvas: viewContext.canvas,
+    context: viewContext.context,
+    statsValueByKey: viewContext.statsValueByKey,
+    renderNetworkArchitecture: viewContext.renderNetworkArchitecture,
+    populationSize: config.populationSize,
+    elitismCount: config.elitismCount,
+    inputSize: config.inputSize,
+    outputSize: config.outputSize,
+    runtimeTelemetryState,
+    isStopped: () => runtimeLifecycleState.stopped,
+  }).catch((error: unknown) => {
+    // Step 2: Surface unexpected failures in the HUD and tear down the runtime.
+    updateStatsTableValues(viewContext.statsValueByKey, {
+      status: resolveRuntimeHudErrorStatus(error),
+    });
+    stop();
+  });
+}

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

@@ -0,0 +1,81 @@
+import { disconnectRuntimeTelemetry } from './runtime.telemetry.service';
+import type {
+  RuntimeMutableLifecycleState,
+  RuntimeRunHandle,
+  RuntimeStartContext,
+} from './runtime.types';
+
+/**
+ * Creates mutable lifecycle state for stop semantics and completion signaling.
+ *
+ * @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.
+ *
+ * @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,74 @@
+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';
+
+/**
+ * Creates the shared runtime startup dependencies used by the entry orchestration.
+ *
+ * @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.
+ *
+ * @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.
+ *
+ * @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.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,7 +1,9 @@
+import { createCanvasHost } from '../host/host';
 import type {
   FlappyBirdRunHandle,
   RuntimeWindow,
 } from '../browser-entry.types';
+import type { RuntimeTelemetryState } from './runtime.telemetry.service';
 
 /**
  * Public run handle returned by the browser runtime entrypoint.
@@ -17,3 +19,37 @@ export type RuntimeGlobalWindow = RuntimeWindow;
  * Container argument accepted by the browser runtime start function.
  */
 export type RuntimeContainerTarget = string | HTMLElement;
+
+/**
+ * Static runtime configuration resolved before the browser loop starts.
+ */
+export interface RuntimeStartConfig {
+  inputSize: number;
+  outputSize: number;
+  populationSize: number;
+  elitismCount: number;
+}
+
+/**
+ * Browser host view handles used by the runtime entry orchestration.
+ */
+export type RuntimeHostViewContext = ReturnType<typeof createCanvasHost>;
+
+/**
+ * Mutable lifecycle state used to coordinate stop semantics and completion.
+ */
+export interface RuntimeMutableLifecycleState {
+  stopped: boolean;
+  resolveDone?: () => void;
+  done: Promise<void>;
+}
+
+/**
+ * Shared runtime startup dependencies created before evolution begins.
+ */
+export interface RuntimeStartContext {
+  config: RuntimeStartConfig;
+  viewContext: RuntimeHostViewContext;
+  runtimeTelemetryState: RuntimeTelemetryState;
+  evolutionWorker: Worker;
+}