@reicek/neataptic-ts 0.1.21 → 0.1.23

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

@@ -1,20 +1,62 @@
-/** Synthetic sample count used for generation-0 warm-start pretraining. */
+/**
+ * Synthetic sample count used for generation-0 warm-start pretraining.
+ *
+ * Educational note:
+ * The warm-start service briefly trains a template network on a heuristic
+ * teacher before the first NEAT generation is evolved. This value controls how
+ * many synthetic state/action examples are generated for that bootstrap pass.
+ * Larger values usually make the teacher signal more stable, but they also
+ * increase startup latency inside the worker.
+ */
 export const FLAPPY_WORKER_GEN0_PRETRAIN_SAMPLE_COUNT = 512;
 
-/** Visible world width used when generating synthetic warm-start samples. */
+/**
+ * Visible world width used when generating synthetic warm-start samples.
+ *
+ * This should roughly match the browser playback framing so the generated
+ * observation vectors look like the states the policy will later see during
+ * real worker playback.
+ */
 export const FLAPPY_WORKER_GEN0_PRETRAIN_VISIBLE_WORLD_WIDTH_PX = 720;
 
-/** Optimizer iteration budget for generation-0 warm-start pretraining. */
+/**
+ * Optimizer iteration budget for generation-0 warm-start pretraining.
+ *
+ * The goal is not to fully solve Flappy Bird with supervised learning. The
+ * worker only needs a short nudge away from completely random action logits so
+ * the first browser-visible generation looks less chaotic.
+ */
 export const FLAPPY_WORKER_GEN0_PRETRAIN_ITERATIONS = 60;
 
-/** Batch size for generation-0 warm-start pretraining. */
+/**
+ * Batch size for generation-0 warm-start pretraining.
+ *
+ * Smaller batches inject a bit more stochasticity into the bootstrap fit,
+ * while still keeping the pass cheap enough for a browser worker.
+ */
 export const FLAPPY_WORKER_GEN0_PRETRAIN_BATCH_SIZE = 32;
 
-/** Learning rate for generation-0 warm-start pretraining. */
+/**
+ * Learning rate for generation-0 warm-start pretraining.
+ *
+ * This is intentionally moderate: the template network should learn a simple
+ * corridor-following prior without overfitting the heuristic teacher.
+ */
 export const FLAPPY_WORKER_GEN0_PRETRAIN_RATE = 0.02;
 
-/** Gaussian stddev used for post-pretrain connection-weight diversification. */
+/**
+ * Gaussian standard deviation used for post-pretrain connection-weight diversification.
+ *
+ * After the template network is trained once, each genome receives a noisy copy
+ * of its weights. That keeps generation 0 visually coherent while preserving
+ * enough diversity for NEAT to search meaningfully.
+ */
 export const FLAPPY_WORKER_GEN0_PRETRAIN_WEIGHT_NOISE_STDDEV = 0.08;
 
-/** Gaussian stddev used for post-pretrain node-bias diversification. */
+/**
+ * Gaussian standard deviation used for post-pretrain node-bias diversification.
+ *
+ * Bias noise is slightly smaller than weight noise so the warm-start remains a
+ * prior, not a rigid clone of the teacher-fitted template.
+ */
 export const FLAPPY_WORKER_GEN0_PRETRAIN_BIAS_NOISE_STDDEV = 0.03;

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

@@ -1,20 +1,40 @@
 import type { WorkerErrorMessage } from './flappy-evolution-worker.types';
 
-/** Worker error emitted when runtime initialization fails unexpectedly. */
+/**
+ * Worker error emitted when runtime initialization fails unexpectedly.
+ *
+ * This message is intentionally stable so the browser host can show a readable
+ * error without leaking internal exception shapes into the UI contract.
+ */
 export const FLAPPY_WORKER_INIT_FAILED_ERROR_MESSAGE =
   'Failed to initialize Flappy evolution worker runtime.';
 
-/** Worker error emitted when playback start is requested before evolution output exists. */
+/**
+ * Worker error emitted when playback start is requested before evolution output exists.
+ *
+ * Playback is defined over an already-evolved population snapshot. The host must
+ * request at least one generation before asking the worker to start playback.
+ */
 export const FLAPPY_WORKER_PLAYBACK_START_REQUIRES_GENERATION_ERROR_MESSAGE =
   'Cannot start playback before a generation is available. Request a generation first.';
 
-/** Worker error emitted when playback stepping is requested before playback start. */
+/**
+ * Worker error emitted when playback stepping is requested before playback start.
+ *
+ * The protocol is stateful: `start-playback` materializes the mutable playback
+ * state that later `request-playback-step` messages advance.
+ */
 export const FLAPPY_WORKER_PLAYBACK_STEP_REQUIRES_START_ERROR_MESSAGE =
   'Playback step requested before playback was initialized. Send start-playback first.';
 
 /**
  * Resolves unknown error-like values into display-safe worker error messages.
  *
+ * Educational note:
+ * Browser workers can throw anything, including strings or arbitrary objects.
+ * Normalizing that value here gives the rest of the protocol a simple
+ * `string`-only error surface.
+ *
  * @param error - Unknown error value thrown by worker logic.
  * @returns Normalized error message string.
  */
@@ -25,6 +45,13 @@ export function resolveWorkerUnknownErrorMessage(error: unknown): string {
 /**
  * Creates a typed worker error response payload from a message string.
  *
+ * @example
+ * ```ts
+ * postWorkerMessage(
+ *   createWorkerErrorMessage('Playback step requested before playback start.'),
+ * );
+ * ```
+ *
  * @param message - Error message text.
  * @returns Worker error response message.
  */
@@ -38,6 +65,10 @@ export function createWorkerErrorMessage(message: string): WorkerErrorMessage {
 /**
  * Creates a typed worker error response payload from an unknown thrown value.
  *
+ * This helper keeps the protocol boundary narrow: worker internals can use
+ * regular exceptions, while the browser host still receives one predictable
+ * `WorkerErrorMessage` shape.
+ *
  * @param error - Unknown thrown value.
  * @returns Worker error response message.
  */

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

@@ -4,6 +4,12 @@ import type { WorkerGenerationReadyMessage } from './flappy-evolution-worker.typ
 
 /**
  * Dependencies required to evolve one generation and prepare host payload output.
+ *
+ * Educational note:
+ * This interface isolates the evolution step from the worker entrypoint. That
+ * makes the README easier to follow: the entrypoint owns protocol orchestration,
+ * while this service owns one well-defined "run generation -> publish summary"
+ * slice of behavior.
  */
 export interface WorkerEvolutionServiceOptions {
   initializationPromise?: Promise<void>;
@@ -16,6 +22,22 @@ export interface WorkerEvolutionServiceOptions {
 /**
  * Evolves one generation and creates the compact generation-ready response payload.
  *
+ * Educational note:
+ * The worker does not stream the whole population back to the UI after each
+ * evolution step. Instead it emits a compact summary containing the generation
+ * index, best fitness, and a serializable best-network snapshot for inspection.
+ *
+ * @example
+ * ```ts
+ * const generationMessage = await evolveAndBuildGenerationReadyMessage({
+ *   initializationPromise,
+ *   neatRuntime,
+ *   isStopped: () => false,
+ *   warmStartGenerationZeroIfNeeded,
+ *   setCurrentPopulation,
+ * });
+ * ```
+ *
  * @param options - Evolution dependencies and runtime state accessors.
  * @returns Generation-ready worker response payload.
  */

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

@@ -5,8 +5,11 @@ import {
   resolveFramePrimaryWinnerIndex,
   resolveLeaderPipesPassed,
 } from '../browser-entry/browser-entry.observation.utils';
-import { resolveDifficultyProfile } from '../browser-entry/browser-entry.spawn.utils';
 import { FLAPPY_ENABLE_RUNTIME_INSTRUMENTATION } from '../constants/constants';
+import {
+  resolveAdaptiveDifficultyProfile,
+  type SharedDifficultyProfile,
+} from '../flappy.simulation.shared.utils';
 import type {
   WorkerPlaybackFrameSnapshot,
   WorkerPlaybackState,
@@ -19,6 +22,20 @@ import type { Neat } from '../../../../src/neataptic';
 /**
  * Creates a fresh worker playback session state from the current evolved population.
  *
+ * Educational note:
+ * Evolution and playback are intentionally separated. Evolution produces a new
+ * population, then playback freezes that population into a deterministic
+ * simulation state that the host can step frame-by-frame for rendering.
+ *
+ * @example
+ * ```ts
+ * const session = beginWorkerPlaybackSession({
+ *   currentPopulation,
+ *   payload: { visibleWorldWidthPx: 1280, visibleWorldHeightPx: 720 },
+ *   createPopulationRenderState,
+ * });
+ * ```
+ *
  * @param currentPopulation - Current evolved population.
  * @param payload - Playback start viewport payload.
  * @param createPopulationRenderState - Callback that builds initial simulation state.
@@ -56,6 +73,12 @@ export function beginWorkerPlaybackSession(options: {
 /**
  * Processes one worker playback-step request including completion/finalization logic.
  *
+ * Educational note:
+ * One playback request may advance multiple simulation steps. This lets the
+ * host trade visual smoothness against throughput while keeping the worker in
+ * control of simulation correctness, winner selection, and packed snapshot
+ * publishing.
+ *
  * @param options - Playback step dependencies and mutable runtime state.
  * @returns Updated playback runtime state after processing this step.
  */
@@ -68,16 +91,18 @@ export function processWorkerPlaybackStep(options: {
   stepPopulationFrame: (
     renderState: WorkerPlaybackState,
     rng: ReturnType<typeof createXorshift32>,
-    difficultyProfile: {
-      pipeGapPx: number;
-      pipeSpeedPxPerFrame: number;
-      pipeSpawnIntervalFrames: number;
-    },
+    difficultyProfile: SharedDifficultyProfile,
   ) => number;
   createPlaybackSnapshot: (
     playbackState: WorkerPlaybackState,
   ) => WorkerPlaybackFrameSnapshot;
-  postWorkerMessage: (workerMessage: WorkerResponseMessage) => void;
+  resolvePlaybackSnapshotTransferList: (
+    snapshot: WorkerPlaybackFrameSnapshot,
+  ) => Transferable[];
+  postWorkerMessage: (
+    workerMessage: WorkerResponseMessage,
+    transferList?: Transferable[],
+  ) => void;
 }): {
   currentPlaybackState: WorkerPlaybackState | undefined;
   currentPlaybackRng: ReturnType<typeof createXorshift32> | undefined;
@@ -92,6 +117,7 @@ export function processWorkerPlaybackStep(options: {
     neatRuntime,
     stepPopulationFrame,
     createPlaybackSnapshot,
+    resolvePlaybackSnapshotTransferList,
     postWorkerMessage,
   } = options;
 
@@ -112,8 +138,9 @@ export function processWorkerPlaybackStep(options: {
     hasAliveBirds(currentPlaybackState.birds);
     simulationStepIndex++
   ) {
-    const difficultyProfile = resolveDifficultyProfile(
+    const difficultyProfile = resolveAdaptiveDifficultyProfile(
       resolveLeaderPipesPassed(currentPlaybackState.birds),
+      1,
     );
     totalActivationCalls += stepPopulationFrame(
       currentPlaybackState,
@@ -135,16 +162,21 @@ export function processWorkerPlaybackStep(options: {
     : undefined;
 
   const snapshot = createPlaybackSnapshot(currentPlaybackState);
+  const snapshotTransferList = resolvePlaybackSnapshotTransferList(snapshot);
 
   if (hasAliveBirds(currentPlaybackState.birds)) {
-    postWorkerMessage({
-      type: 'playback-step',
-      payload: {
-        snapshot,
-        instrumentation: instrumentationPayload,
-        done: false,
+    postWorkerMessage(
+      {
+        type: 'playback-step',
+        payload: {
+          requestId: playbackStepPayload.requestId,
+          snapshot,
+          instrumentation: instrumentationPayload,
+          done: false,
+        },
       },
-    });
+      snapshotTransferList,
+    );
     return {
       currentPlaybackState,
       currentPlaybackRng,
@@ -190,18 +222,22 @@ export function processWorkerPlaybackStep(options: {
   const p90FramesSurvived =
     sortedFramesSurvived.length > 0 ? sortedFramesSurvived[p90FrameIndex] : 0;
 
-  postWorkerMessage({
-    type: 'playback-step',
-    payload: {
-      snapshot,
-      instrumentation: instrumentationPayload,
-      done: true,
-      averagePipesPassed,
-      p90FramesSurvived,
-      winnerPipesPassed: winnerBird?.pipesPassed ?? 0,
-      winnerFramesSurvived: winnerBird?.framesSurvived ?? 0,
+  postWorkerMessage(
+    {
+      type: 'playback-step',
+      payload: {
+        requestId: playbackStepPayload.requestId,
+        snapshot,
+        instrumentation: instrumentationPayload,
+        done: true,
+        averagePipesPassed,
+        p90FramesSurvived,
+        winnerPipesPassed: winnerBird?.pipesPassed ?? 0,
+        winnerFramesSurvived: winnerBird?.framesSurvived ?? 0,
+      },
     },
-  });
+    snapshotTransferList,
+  );
 
   return {
     currentPlaybackState: undefined,

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

@@ -13,6 +13,11 @@ import {
 
 /**
  * Callback bundle used by worker protocol routing.
+ *
+ * Each callback corresponds to one legal transition in the worker message
+ * protocol. Keeping the router dependent on this narrow interface makes the
+ * protocol easy to read in generated docs and easy to test independently from
+ * the worker-global `self.onmessage` hook.
  */
 export interface WorkerProtocolHandlers {
   markStopped: () => void;
@@ -24,12 +29,33 @@ export interface WorkerProtocolHandlers {
   ) => void;
   hasPopulation: () => boolean;
   hasPlaybackState: () => boolean;
-  postWorkerMessage: (workerMessage: WorkerResponseMessage) => void;
+  postWorkerMessage: (
+    workerMessage: WorkerResponseMessage,
+    transferList?: Transferable[],
+  ) => void;
 }
 
 /**
  * Routes one inbound worker request message to the corresponding runtime action.
  *
+ * Educational note:
+ * This router is the protocol gatekeeper for the worker. It enforces the two
+ * important sequencing rules in the demo:
+ * - playback requires a previously evolved population,
+ * - playback stepping requires an active playback session.
+ *
+ * In practice this acts like a tiny finite-state machine. If you want a quick
+ * conceptual refresher, the Wikipedia article on "finite-state machine" maps
+ * well onto the worker's init -> evolve -> start playback -> step playback flow.
+ *
+ * @example
+ * ```ts
+ * routeWorkerProtocolMessage(
+ *   { type: 'request-generation' },
+ *   workerProtocolHandlers,
+ * );
+ * ```
+ *
  * @param workerMessage - Inbound worker request payload.
  * @param handlers - Runtime action callbacks and state probes.
  * @returns Nothing.

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

@@ -12,6 +12,29 @@ import {
 /**
  * Creates and configures the worker-local NEAT runtime used by browser evolution playback.
  *
+ * Educational note:
+ * The browser worker reuses the same core NeatapticTS runtime as the Node-side
+ * trainer, but trims configuration down to the pieces needed for an interactive
+ * example: deterministic seeding, feed-forward mutation policy, and a fitness
+ * function that favors quick browser-visible iteration.
+ *
+ * The resulting runtime is both the evolution engine and the source of the
+ * population that later playback requests visualize.
+ *
+ * For background reading, the Wikipedia article on "Neuroevolution of
+ * augmenting topologies" is a useful overview of the family of ideas this demo
+ * is exercising, even though the repository implements its own detailed runtime
+ * behavior and modern extensions.
+ *
+ * @example
+ * ```ts
+ * const neatRuntime = createInitializedWorkerRuntime({
+ *   populationSize: 50,
+ *   elitismCount: 10,
+ *   rngSeed: 12345,
+ * });
+ * ```
+ *
  * @param initPayload - Initialization values from the browser host.
  * @returns Initialized NEAT runtime.
  */