@reicek/neataptic-ts 0.1.21 → 0.1.23

package/test/examples/flappy_bird/flappy-evolution-worker/flappy-evolution-worker.types.ts

@@ -4,10 +4,21 @@ import type {
   SharedObservationMemoryState,
 } from '../flappy.simulation.shared.utils';
 
-/** Loose JSON-compatible network payload used by worker messages. */
+/**
+ * Loose JSON-compatible network payload used by worker messages.
+ *
+ * The worker never posts live `Network` instances back to the browser host.
+ * Instead it sends the result of `network.toJSON()` so the payload stays
+ * structured-clone safe and easy to inspect in devtools.
+ */
 export type SerializedNetwork = Record<string, unknown>;
 
-/** Mutable pipe state tracked by the worker playback simulation. */
+/**
+ * Mutable pipe state tracked by the worker playback simulation.
+ *
+ * These objects exist only inside the worker runtime. The host later receives a
+ * packed snapshot derived from them rather than these live mutable records.
+ */
 export interface WorkerPopulationPipe {
   id: number;
   xPx: number;
@@ -15,10 +26,16 @@ export interface WorkerPopulationPipe {
   gapSizePx: number;
 }
 
-/** Mutable bird state tracked by the worker playback simulation. */
+/**
+ * Mutable bird state tracked by the worker playback simulation.
+ *
+ * Educational note:
+ * Each bird keeps both physics state and policy state. The observation-memory
+ * field lets feed-forward networks approximate short-term temporal memory by
+ * carrying previous observation features between simulation steps.
+ */
 export interface WorkerPopulationBird {
   network: Network;
-  color: string;
   observationMemoryState: SharedObservationMemoryState;
   yPx: number;
   velocityYPxPerFrame: number;
@@ -29,9 +46,16 @@ export interface WorkerPopulationBird {
   doneReason?: 'collision' | 'out_of_bounds';
 }
 
-/** Mutable simulation state stored between worker playback requests. */
+/**
+ * Mutable simulation state stored between worker playback requests.
+ *
+ * A `start-playback` message creates this state once, and each
+ * `request-playback-step` message advances it by a host-selected number of
+ * simulation steps.
+ */
 export interface WorkerPlaybackState {
   frameIndex: number;
+  cumulativePipeTravelPx: number;
   visibleWorldWidthPx: number;
   visibleWorldHeightPx: number;
   nextPipeId: number;
@@ -43,16 +67,25 @@ export interface WorkerPlaybackState {
   birds: WorkerPopulationBird[];
 }
 
-/** Render-only bird snapshot DTO posted to host. */
+/**
+ * Render-only bird snapshot DTO posted to host.
+ *
+ * This shape is useful conceptually, but the current transport uses the packed
+ * typed-array variant for lower allocation and transfer cost.
+ */
 export interface WorkerFrameBirdSnapshot {
-  color: string;
   yPx: number;
   pipesPassed: number;
   framesSurvived: number;
   done: boolean;
 }
 
-/** Render-only pipe snapshot DTO posted to host. */
+/**
+ * Render-only pipe snapshot DTO posted to host.
+ *
+ * Like `WorkerFrameBirdSnapshot`, this documents the logical payload shape even
+ * though the worker currently sends the packed transport form.
+ */
 export interface WorkerFramePipeSnapshot {
   id: number;
   xPx: number;
@@ -60,16 +93,70 @@ export interface WorkerFramePipeSnapshot {
   gapSizePx: number;
 }
 
-/** Full frame snapshot payload posted to host. */
+/**
+ * Packed typed-array payload for playback pipe snapshot transport.
+ *
+ * Packing the per-pipe fields into column-oriented typed arrays makes the
+ * browser/worker boundary cheaper than sending large arrays of object literals
+ * on every animation frame.
+ */
+export interface WorkerPackedPlaybackPipeSnapshot {
+  xPositionsPx: Float32Array;
+  gapCenterYPositionsPx: Float32Array;
+  gapSizesPx: Float32Array;
+}
+
+/**
+ * Packed typed-array payload for playback bird snapshot transport.
+ *
+ * The host can reconstruct renderer-friendly bird views from these arrays while
+ * the worker keeps the authoritative mutable simulation objects private.
+ */
+export interface WorkerPackedPlaybackBirdSnapshot {
+  yPositionsPx: Float32Array;
+  pipesPassed: Uint32Array;
+  framesSurvived: Uint32Array;
+  doneFlags: Uint8Array;
+}
+
+/**
+ * Full frame snapshot payload posted to host.
+ *
+ * Educational note:
+ * `packed-v1` is a transport contract, not a rendering primitive. The versioned
+ * format string gives the browser host a stable way to decode snapshots even if
+ * the worker later gains additional packed fields or alternate transport modes.
+ *
+ * @example
+ * ```ts
+ * const message = {
+ *   type: 'playback-step',
+ *   payload: {
+ *     requestId: 7,
+ *     snapshot,
+ *     done: false,
+ *   },
+ * };
+ * ```
+ */
 export interface WorkerPlaybackFrameSnapshot {
+  format: 'packed-v1';
   frameIndex: number;
+  cumulativePipeTravelPx: number;
   visibleWorldWidthPx: number;
   visibleWorldHeightPx: number;
-  pipes: WorkerFramePipeSnapshot[];
-  birds: WorkerFrameBirdSnapshot[];
+  pipeCount: number;
+  birdCount: number;
+  pipes: WorkerPackedPlaybackPipeSnapshot;
+  birds: WorkerPackedPlaybackBirdSnapshot;
 }
 
-/** Worker init request message. */
+/**
+ * Worker init request message.
+ *
+ * This is the first message the host should send. It seeds deterministic RNG
+ * state and configures the worker-local NEAT runtime.
+ */
 export interface WorkerInitMessage {
   type: 'init';
   payload: {
@@ -79,12 +166,23 @@ export interface WorkerInitMessage {
   };
 }
 
-/** Worker request asking to evolve one generation. */
+/**
+ * Worker request asking to evolve one generation.
+ *
+ * The worker responds with `generation-ready` once the NEAT runtime finishes
+ * one evolution pass.
+ */
 export interface WorkerRequestGenerationMessage {
   type: 'request-generation';
 }
 
-/** Worker request asking to initialize playback state. */
+/**
+ * Worker request asking to initialize playback state.
+ *
+ * This materializes the mutable world state for the current evolved population.
+ * After this message succeeds, the host can begin issuing playback-step
+ * requests.
+ */
 export interface WorkerStartPlaybackMessage {
   type: 'start-playback';
   payload: {
@@ -93,22 +191,40 @@ export interface WorkerStartPlaybackMessage {
   };
 }
 
-/** Worker request asking to advance playback by N simulation steps. */
+/**
+ * Worker request asking to advance playback by N simulation steps.
+ *
+ * The host typically sends this once per animation frame and chooses
+ * `simulationSteps` based on how much simulation throughput it wants relative to
+ * rendering smoothness.
+ */
 export interface WorkerRequestPlaybackStepMessage {
   type: 'request-playback-step';
   payload: {
+    requestId: number;
     simulationSteps: number;
     visibleWorldWidthPx: number;
     visibleWorldHeightPx: number;
   };
 }
 
-/** Worker stop request message. */
+/**
+ * Worker stop request message.
+ *
+ * This is a cooperative shutdown signal. Long-running worker flows can observe
+ * the stopped flag and fail fast instead of continuing work the UI no longer
+ * cares about.
+ */
 export interface WorkerStopMessage {
   type: 'stop';
 }
 
-/** Union of inbound worker request messages. */
+/**
+ * Union of inbound worker request messages.
+ *
+ * Reading this union top-to-bottom is the quickest way to understand the worker
+ * protocol: initialize, evolve, start playback, step playback, then stop.
+ */
 export type WorkerRequestMessage =
   | WorkerInitMessage
   | WorkerRequestGenerationMessage
@@ -116,7 +232,12 @@ export type WorkerRequestMessage =
   | WorkerRequestPlaybackStepMessage
   | WorkerStopMessage;
 
-/** Worker generation-ready response message. */
+/**
+ * Worker generation-ready response message.
+ *
+ * The browser host uses this message to refresh HUD state and optionally render
+ * the current best network visualization.
+ */
 export interface WorkerGenerationReadyMessage {
   type: 'generation-ready';
   payload: {
@@ -126,10 +247,21 @@ export interface WorkerGenerationReadyMessage {
   };
 }
 
-/** Worker playback-step response message. */
+/**
+ * Worker playback-step response message.
+ *
+ * The message carries the packed frame snapshot plus optional instrumentation
+ * and end-of-run summary statistics when the whole simulated population has
+ * been eliminated.
+ *
+ * The split between per-frame snapshot data and end-of-run summary fields keeps
+ * the hot path compact while still giving the host enough telemetry to update
+ * HUD metrics when a playback session completes.
+ */
 export interface WorkerPlaybackStepMessage {
   type: 'playback-step';
   payload: {
+    requestId: number;
     snapshot: WorkerPlaybackFrameSnapshot;
     instrumentation?: {
       activationCallsPerFrame: number;
@@ -143,7 +275,12 @@ export interface WorkerPlaybackStepMessage {
   };
 }
 
-/** Worker error response message. */
+/**
+ * Worker error response message.
+ *
+ * Errors are normalized into a display-safe string so the host UI can surface
+ * failures without depending on worker-specific exception classes.
+ */
 export interface WorkerErrorMessage {
   type: 'error';
   payload: {
@@ -151,11 +288,22 @@ export interface WorkerErrorMessage {
   };
 }
 
-/** Union of outbound worker response messages. */
+/**
+ * Union of outbound worker response messages.
+ *
+ * Together with `WorkerRequestMessage`, this forms the full host/worker
+ * protocol contract for the demo.
+ */
 export type WorkerResponseMessage =
   | WorkerGenerationReadyMessage
   | WorkerPlaybackStepMessage
   | WorkerErrorMessage;
 
-/** Structured features used by heuristic generation-0 teacher policy. */
+/**
+ * Structured features used by heuristic generation-0 teacher policy.
+ *
+ * The warm-start service reuses the same high-level observation semantics as the
+ * real policy inference path, which keeps the heuristic teacher aligned with the
+ * features evolved networks will later see.
+ */
 export type WorkerHeuristicObservationFeatures = SharedObservationFeatures;

package/test/examples/flappy_bird/flappy-evolution-worker/flappy-evolution-worker.warm-start.service.ts

@@ -0,0 +1,314 @@
+import type { Neat } from '../../../../src/neataptic';
+import type Network from '../../../../src/architecture/network';
+import { createXorshift32 } from '../rng';
+import {
+  commitObservationMemoryStep,
+  resolveFlapDecision,
+  resolveObservationVector,
+} from '../browser-entry/browser-entry.observation.utils';
+import { sampleGapCenterY } from '../browser-entry/browser-entry.spawn.utils';
+import type {
+  WorkerHeuristicObservationFeatures,
+  WorkerPopulationPipe,
+} from './flappy-evolution-worker.types';
+import { FLAPPY_BIRD_VIEWPORT_X_RATIO } from '../constants/constants';
+import {
+  FLAPPY_BIRD_RADIUS_PX,
+  FLAPPY_BIRD_X_PX,
+  FLAPPY_PIPE_COLLISION_ENTRANCE_EXPAND_PX,
+  FLAPPY_PIPE_COLLISION_SIDE_EXPAND_PX,
+  FLAPPY_CONTROL_SUBSTEPS_PER_FRAME,
+  FLAPPY_FLAP_VELOCITY_PX_PER_FRAME,
+  FLAPPY_GRAVITY_PX_PER_FRAME2,
+  FLAPPY_MAX_FALL_SPEED_PX_PER_FRAME,
+  FLAPPY_PIPE_WIDTH_PX,
+  FLAPPY_WORLD_HEIGHT_PX,
+} from '../constants/constants';
+import {
+  FLAPPY_WORKER_GEN0_PRETRAIN_BATCH_SIZE,
+  FLAPPY_WORKER_GEN0_PRETRAIN_BIAS_NOISE_STDDEV,
+  FLAPPY_WORKER_GEN0_PRETRAIN_ITERATIONS,
+  FLAPPY_WORKER_GEN0_PRETRAIN_RATE,
+  FLAPPY_WORKER_GEN0_PRETRAIN_SAMPLE_COUNT,
+  FLAPPY_WORKER_GEN0_PRETRAIN_VISIBLE_WORLD_WIDTH_PX,
+  FLAPPY_WORKER_GEN0_PRETRAIN_WEIGHT_NOISE_STDDEV,
+} from './flappy-evolution-worker.constants';
+import {
+  createSharedObservationMemoryState,
+  resolveAdaptiveDifficultyProfile,
+} from '../flappy.simulation.shared.utils';
+
+/**
+ * State carried between generation requests for one worker runtime.
+ *
+ * The warm-start service is intentionally one-shot. These fields let the worker
+ * remember whether generation 0 has already been bootstrapped and which initial
+ * RNG seed should be reused for deterministic synthetic sample generation.
+ */
+export interface WorkerWarmStartState {
+  workerInitSeed: number;
+  generationZeroWarmStartApplied: boolean;
+}
+
+/**
+ * Applies a one-time generation-0 warm-start to improve initial demo quality.
+ *
+ * Educational note:
+ * The worker entry should stay protocol-first. This service owns the short
+ * supervised bootstrap pass that nudges generation 0 away from pure noise while
+ * preserving the later NEAT-driven search loop.
+ *
+ * Conceptually this is a lightweight behavior-cloning pass. If you want more
+ * background, the Wikipedia article on "imitation learning" is a helpful bridge
+ * between the heuristic teacher used here and the later evolutionary search.
+ *
+ * @param neatController - Initialized NEAT runtime.
+ * @param warmStartState - Mutable warm-start lifecycle state.
+ * @returns Promise resolved when warm-start evaluation finishes.
+ * @example
+ * ```ts
+ * await warmStartWorkerGenerationZeroIfNeeded(neatRuntime, {
+ *   workerInitSeed: 123,
+ *   generationZeroWarmStartApplied: false,
+ * });
+ * ```
+ */
+export async function warmStartWorkerGenerationZeroIfNeeded(
+  neatController: Neat,
+  warmStartState: WorkerWarmStartState,
+): Promise<void> {
+  // Step 1: Exit fast when warm-start is already processed.
+  if (warmStartState.generationZeroWarmStartApplied) return;
+
+  // Step 2: Warm-start only generation 0 to avoid skewing later evolution.
+  if (neatController.generation !== 0) {
+    warmStartState.generationZeroWarmStartApplied = true;
+    return;
+  }
+
+  // Step 3: Validate population availability.
+  const population = neatController.population;
+  if (!Array.isArray(population) || population.length === 0) {
+    warmStartState.generationZeroWarmStartApplied = true;
+    return;
+  }
+
+  // Step 4: Build a small synthetic dataset labeled by a simple heuristic.
+  const warmStartRng = createXorshift32(
+    warmStartState.workerInitSeed ^ 0x9e37_79b9,
+  );
+  const trainingSet = buildHeuristicPretrainSet(
+    warmStartRng,
+    FLAPPY_WORKER_GEN0_PRETRAIN_SAMPLE_COUNT,
+  );
+
+  // Step 5: Train a single template network, then seed the whole population from it.
+  const templateNetwork = population[0]?.clone();
+  if (!templateNetwork) {
+    warmStartState.generationZeroWarmStartApplied = true;
+    return;
+  }
+
+  try {
+    templateNetwork.train(trainingSet, {
+      iterations: FLAPPY_WORKER_GEN0_PRETRAIN_ITERATIONS,
+      rate: FLAPPY_WORKER_GEN0_PRETRAIN_RATE,
+      batchSize: FLAPPY_WORKER_GEN0_PRETRAIN_BATCH_SIZE,
+      optimizer: 'adam',
+      mixedPrecision: false,
+    });
+  } catch {
+    // If training fails for any reason, fall back to pure noise seeding.
+  }
+
+  // Step 6: Copy trained weights/biases into each genome with small noise for diversity.
+  for (const genome of population) {
+    applyTemplateWeightsWithNoise(genome, templateNetwork, warmStartRng, {
+      weightStdDev: FLAPPY_WORKER_GEN0_PRETRAIN_WEIGHT_NOISE_STDDEV,
+      biasStdDev: FLAPPY_WORKER_GEN0_PRETRAIN_BIAS_NOISE_STDDEV,
+    });
+    (genome as unknown as { score?: number }).score = undefined;
+  }
+
+  warmStartState.generationZeroWarmStartApplied = true;
+}
+
+/**
+ * Builds synthetic supervised samples for generation-0 behavior cloning.
+ *
+ * Educational note:
+ * These samples are not recorded gameplay traces. They are synthetic states
+ * generated from the same observation pipeline used during real playback so the
+ * teacher labels and the evolved policy inputs stay in the same feature space.
+ *
+ * @param rng - Deterministic random source.
+ * @param sampleCount - Requested number of synthetic samples.
+ * @returns Supervised dataset of input/output pairs.
+ */
+function buildHeuristicPretrainSet(
+  rng: ReturnType<typeof createXorshift32>,
+  sampleCount: number,
+): Array<{ input: number[]; output: number[] }> {
+  // Step 1: Resolve bounded sample count and a baseline difficulty profile.
+  const clampedSampleCount = Math.max(8, Math.trunc(sampleCount));
+  const difficultyProfile = resolveAdaptiveDifficultyProfile(0, 1);
+  const trainingSet: Array<{ input: number[]; output: number[] }> = [];
+
+  // Step 2: Sample state tuples, encode observations, and attach heuristic labels.
+  for (let sampleIndex = 0; sampleIndex < clampedSampleCount; sampleIndex++) {
+    const pipeGapPx = difficultyProfile.pipeGapPx;
+    const gapHalfPx = pipeGapPx * 0.5;
+
+    const birdYPx = rng.nextFloat01() * FLAPPY_WORLD_HEIGHT_PX;
+    const velocityYPxPerFrame =
+      (rng.nextFloat01() * 2 - 1) * FLAPPY_MAX_FALL_SPEED_PX_PER_FRAME;
+
+    const pipeXMinPx = FLAPPY_BIRD_X_PX + 40;
+    const pipeXMaxPx =
+      FLAPPY_BIRD_X_PX +
+      FLAPPY_WORKER_GEN0_PRETRAIN_VISIBLE_WORLD_WIDTH_PX * 0.92;
+    const pipeXSamplePx =
+      pipeXMinPx + rng.nextFloat01() * Math.max(1, pipeXMaxPx - pipeXMinPx);
+
+    const minGapCenterYPx = gapHalfPx;
+    const maxGapCenterYPx = Math.max(
+      minGapCenterYPx,
+      FLAPPY_WORLD_HEIGHT_PX - gapHalfPx,
+    );
+    const gapCenterYPx =
+      minGapCenterYPx + rng.nextFloat01() * (maxGapCenterYPx - minGapCenterYPx);
+
+    const pipes: WorkerPopulationPipe[] = [
+      {
+        id: 1,
+        xPx: pipeXSamplePx,
+        gapCenterYPx,
+        gapSizePx: pipeGapPx,
+      },
+    ];
+
+    const observationMemoryState = createSharedObservationMemoryState();
+    const observation = resolveObservationVector(
+      birdYPx,
+      velocityYPxPerFrame,
+      pipes,
+      FLAPPY_WORKER_GEN0_PRETRAIN_VISIBLE_WORLD_WIDTH_PX,
+      FLAPPY_WORLD_HEIGHT_PX,
+      difficultyProfile,
+      difficultyProfile.pipeSpawnIntervalFrames,
+      observationMemoryState,
+    );
+
+    const shouldFlap = resolveHeuristicTeacherFlapDecision(
+      observation.observationFeatures,
+    );
+    trainingSet.push({
+      input: observation.observationVector,
+      output: shouldFlap ? [0, 1] : [1, 0],
+    });
+  }
+
+  // Step 3: Return immutable training pairs consumed by Network.train.
+  return trainingSet;
+}
+
+/**
+ * Heuristic teacher policy used to label synthetic pretraining samples.
+ *
+ * The rule intentionally stays simple and interpretable: flap when the bird is
+ * meaningfully below the next gap center, not already rising fast, and either
+ * close to the gap entry or in an urgent approach state.
+ *
+ * @param features - Structured observation features for one synthetic state.
+ * @returns True when the teacher says to flap.
+ */
+function resolveHeuristicTeacherFlapDecision(
+  features: WorkerHeuristicObservationFeatures,
+): boolean {
+  // Step 1: Resolve the few interpretable teacher conditions.
+  const isBelowNextGapCenter = features.normalizedDeltaToNextGap > 0.035;
+  const isNotAlreadyRisingFast = features.normalizedVelocity > -0.25;
+  const isNearGapEntry = features.normalizedFramesToGapEntry < 0.8;
+  const isUrgent = features.normalizedEntryUrgency > 0.18;
+
+  // Step 2: Fold the teacher decision from those conditions.
+  return (
+    isBelowNextGapCenter &&
+    isNotAlreadyRisingFast &&
+    (isNearGapEntry || isUrgent)
+  );
+}
+
+/**
+ * Copies template parameters into a genome and injects small Gaussian noise.
+ *
+ * Educational note:
+ * The template network gives generation 0 a shared prior, while the noise terms
+ * restore diversity so the population is still worth evolving.
+ *
+ * @param genome - Target genome to mutate in-place.
+ * @param template - Trained template source network.
+ * @param rng - Deterministic random source for noise sampling.
+ * @param noise - Standard deviations for weight and bias perturbations.
+ * @returns Nothing.
+ */
+function applyTemplateWeightsWithNoise(
+  genome: Network,
+  template: Network,
+  rng: ReturnType<typeof createXorshift32>,
+  noise: { weightStdDev: number; biasStdDev: number },
+): void {
+  // Step 1: Clamp noise scales to valid non-negative values.
+  const weightStdDev = Math.max(0, noise.weightStdDev);
+  const biasStdDev = Math.max(0, noise.biasStdDev);
+
+  // Step 2: Copy node biases with additive Gaussian noise.
+  const genomeNodes = genome.nodes;
+  const templateNodes = template.nodes;
+  const nodeCopyCount = Math.min(genomeNodes.length, templateNodes.length);
+  for (let nodeIndex = 0; nodeIndex < nodeCopyCount; nodeIndex++) {
+    const templateBias = templateNodes[nodeIndex]?.bias ?? 0;
+    genomeNodes[nodeIndex].bias =
+      templateBias + sampleGaussian(rng) * biasStdDev;
+  }
+
+  // Step 3: Copy connection weights with additive Gaussian noise.
+  const genomeConnections = genome.connections;
+  const templateConnections = template.connections;
+  const connectionCopyCount = Math.min(
+    genomeConnections.length,
+    templateConnections.length,
+  );
+  for (
+    let connectionIndex = 0;
+    connectionIndex < connectionCopyCount;
+    connectionIndex++
+  ) {
+    const templateWeight = templateConnections[connectionIndex]?.weight ?? 0;
+    genomeConnections[connectionIndex].weight =
+      templateWeight + sampleGaussian(rng) * weightStdDev;
+  }
+}
+
+/**
+ * Samples one standard-normal value using the Box-Muller transform.
+ *
+ * If you are unfamiliar with the transform, the Wikipedia article on
+ * "Box-Muller transform" is a useful short background read. The worker uses it
+ * here because it is deterministic, dependency-light, and good enough for small
+ * noise injection during warm-start diversification.
+ *
+ * @param rng - Deterministic random source.
+ * @returns One approximately standard-normal random value.
+ */
+function sampleGaussian(rng: ReturnType<typeof createXorshift32>): number {
+  // Step 1: Avoid log(0) by flooring uniforms away from zero.
+  const epsilon = 1e-12;
+  const uniformA = Math.max(epsilon, rng.nextFloat01());
+  const uniformB = Math.max(epsilon, rng.nextFloat01());
+
+  // Step 2: Convert two uniforms into one normal sample.
+  const magnitude = Math.sqrt(-2 * Math.log(uniformA));
+  const angle = 2 * Math.PI * uniformB;
+  return magnitude * Math.cos(angle);
+}

package/test/examples/flappy_bird/flappy.simulation.shared.utils.ts

@@ -1,3 +1,15 @@
+/**
+ * Compatibility facade for the shared Flappy Bird simulation helpers.
+ *
+ * Educational note:
+ * The Flappy example uses the same observation, spawning, math, and difficulty
+ * logic in multiple places: Node-side evaluation, browser playback, and the
+ * worker runtime. This facade keeps those shared concepts discoverable from the
+ * root folder while the real implementation lives under `simulation-shared/`.
+ *
+ * If you are new to the example, start here to see the cross-cutting helpers,
+ * then follow the re-export targets into the focused submodules.
+ */
 export { resolveAdaptiveDifficultyProfile } from './simulation-shared/simulation-shared.difficulty.utils';
 export { resolveFlapDecision } from './simulation-shared/simulation-shared.control.utils';
 export {
@@ -16,6 +28,11 @@ export {
   clampValue,
   interpolateValue,
 } from './simulation-shared/simulation-shared.math.utils';
+export {
+  computeMean,
+  computePercentile,
+  computePopulationStandardDeviation,
+} from './simulation-shared/simulation-shared.statistics.utils';
 export {
   resolveNextSpawnGapCenterY,
   resolveNextSpawnGapSize,

package/test/examples/flappy_bird/flappyEnvironment.ts

@@ -1,3 +1,16 @@
+/**
+ * Public environment facade for the Flappy Bird example.
+ *
+ * Educational note:
+ * This file presents the Flappy world as a small environment API: create state,
+ * step it forward, and read observations. That makes it the most convenient
+ * entrypoint when you want to treat the game as a control problem rather than a
+ * rendering demo.
+ *
+ * For background reading, the Wikipedia article on "Markov decision process" is
+ * a useful mental model for why the example separates state transition,
+ * observation extraction, and action selection.
+ */
 import type { FlappyRng } from './rng';
 import {
   resolveNextSpawnGapCenterY as resolveSharedNextSpawnGapCenterY,
@@ -24,6 +37,10 @@ export {
 /**
  * Sample a gap center height inside configured bounds.
  *
+ * This root-level helper exists as a convenience export. The underlying spawn
+ * logic lives in the shared simulation layer so browser playback and evaluation
+ * use the same world-generation rules.
+ *
  * @param rng - Random source.
  * @returns Gap center y coordinate (pixels).
  */
@@ -34,6 +51,10 @@ export function sampleGapCenterY(rng: FlappyRng): number {
 /**
  * Resolves next gap-center y while limiting abrupt consecutive transitions.
  *
+ * Keeping consecutive gap centers locally smooth prevents the environment from
+ * generating visually unfair jumps that a feed-forward policy could not react to
+ * consistently.
+ *
  * @param previousGapCenterYPx - Previous spawned gap-center y value.
  * @param rng - Random source.
  * @returns Next gap-center y constrained by transition and world bounds.

package/test/examples/flappy_bird/flappyEvaluation.ts

@@ -1,3 +1,15 @@
+/**
+ * Public evaluation facade for the Flappy Bird example.
+ *
+ * Educational note:
+ * The trainer and worker both need a compact way to score policies. This facade
+ * exposes the evaluation surface without forcing callers to know the internal
+ * rollout and seed-batching module layout.
+ *
+ * The important idea is variance control: the example compares genomes across
+ * shared random seeds so evolution is rewarded for genuinely better behavior,
+ * not for getting an unusually lucky pipe sequence.
+ */
 export {
   evaluateFlappyFitness,
   evaluateFlappyFitnessAcrossSeeds,