@reicek/neataptic-ts 0.1.24 → 0.1.26

package/test/examples/flappy_bird/flappy-evolution-worker/README.md

@@ -20,20 +20,65 @@ Protocol flow at a glance:
 
 ## flappy-evolution-worker/flappy-evolution-worker.ts
 
-### createWorkerMutableRuntimeState
+### beginWorkerGenerationRequest
 
 ```ts
-createWorkerMutableRuntimeState(): WorkerMutableRuntimeState
+beginWorkerGenerationRequest(
+  workerMutableRuntimeState: WorkerMutableRuntimeState,
+): void
 ```
 
-Creates the mutable worker runtime state container.
+Begins one asynchronous generation request and captures failures.
 
-Educational note:
-The worker keeps one small mutable state bag instead of scattering globals.
-That makes the protocol flow easier to explain and lets the entrypoint pass a
-single dependency object through the orchestration helpers.
+This is intentionally fire-and-forget from the protocol perspective. The
+actual completion signal is the later `generation-ready` or `error` message
+posted back to the host.
 
-Returns: Mutable worker runtime state.
+Parameters:
+- `workerMutableRuntimeState` - - Mutable worker runtime state.
+
+Returns: Nothing.
+
+### beginWorkerInitialization
+
+```ts
+beginWorkerInitialization(
+  workerMutableRuntimeState: WorkerMutableRuntimeState,
+  initPayload: { populationSize: number; elitismCount: number; rngSeed: number; },
+): void
+```
+
+Begins worker initialization and captures asynchronous failures.
+
+The worker retains the initialization promise so later generation requests can
+await setup completion instead of racing against it.
+
+Parameters:
+- `workerMutableRuntimeState` - - Mutable worker runtime state.
+- `initPayload` - - Initialization payload.
+
+Returns: Nothing.
+
+### beginWorkerPlayback
+
+```ts
+beginWorkerPlayback(
+  workerMutableRuntimeState: WorkerMutableRuntimeState,
+  payload: { visibleWorldWidthPx: number; visibleWorldHeightPx: number; },
+): void
+```
+
+Begins a new playback session from the current evolved population.
+
+A playback session is a deterministic simulation snapshot seeded from the
+current population. Each new session resets playback RNG and world state so
+the host can replay generations cleanly.
+
+Parameters:
+- `workerMutableRuntimeState` - - Mutable worker runtime state.
+- `payload` - - Playback start payload.
+
+Returns: Nothing.
 
 ### createWorkerMessageHandler
 
@@ -60,6 +105,21 @@ Example:
 self.onmessage = createWorkerMessageHandler(workerMutableRuntimeState);
 ```
 
+### createWorkerMutableRuntimeState
+
+```ts
+createWorkerMutableRuntimeState(): WorkerMutableRuntimeState
+```
+
+Creates the mutable worker runtime state container.
+
+Educational note:
+The worker keeps one small mutable state bag instead of scattering globals.
+That makes the protocol flow easier to explain and lets the entrypoint pass a
+single dependency object through the orchestration helpers.
+
+Returns: Mutable worker runtime state.
+
 ### createWorkerProtocolHandlers
 
 ```ts
@@ -79,31 +139,6 @@ Parameters:
 
 Returns: Protocol handler bundle.
 
-### initializeRuntime
-
-```ts
-initializeRuntime(
-  workerMutableRuntimeState: WorkerMutableRuntimeState,
-  initPayload: { populationSize: number; elitismCount: number; rngSeed: number; },
-): Promise<void>
-```
-
-Initializes the worker-local NEAT runtime used by browser evolution playback.
-
-Educational note:
-The runtime is configured once with deterministic RNG state and a lightweight
-early-termination fitness rollout. Keeping this setup centralized helps ensure
-reproducibility between runs and keeps host<->worker contracts simple.
-
-This function only prepares the evolutionary controller. It does not start
-playback and it does not evolve a generation yet; those remain separate
-protocol steps so the host can control them explicitly.
-
-Parameters:
-- `initPayload` - - Initialization values from the browser host.
-
-Returns: Promise resolved when runtime setup is complete.
-
 ### evolveAndPublishGeneration
 
 ```ts
@@ -121,63 +156,48 @@ a compact payload for UI state updates.
 
 Returns: Promise resolved after generation payload is posted.
 
-### beginWorkerInitialization
+### initializeRuntime
 
 ```ts
-beginWorkerInitialization(
+initializeRuntime(
   workerMutableRuntimeState: WorkerMutableRuntimeState,
   initPayload: { populationSize: number; elitismCount: number; rngSeed: number; },
-): void
+): Promise<void>
 ```
 
-Begins worker initialization and captures asynchronous failures.
-
-The worker retains the initialization promise so later generation requests can
-await setup completion instead of racing against it.
-
-Parameters:
-- `workerMutableRuntimeState` - - Mutable worker runtime state.
-- `initPayload` - - Initialization payload.
-
-Returns: Nothing.
-
-### beginWorkerGenerationRequest
-
-```ts
-beginWorkerGenerationRequest(
-  workerMutableRuntimeState: WorkerMutableRuntimeState,
-): void
-```
+Initializes the worker-local NEAT runtime used by browser evolution playback.
 
-Begins one asynchronous generation request and captures failures.
+Educational note:
+The runtime is configured once with deterministic RNG state and a lightweight
+early-termination fitness rollout. Keeping this setup centralized helps ensure
+reproducibility between runs and keeps host<->worker contracts simple.
 
-This is intentionally fire-and-forget from the protocol perspective. The
-actual completion signal is the later `generation-ready` or `error` message
-posted back to the host.
+This function only prepares the evolutionary controller. It does not start
+playback and it does not evolve a generation yet; those remain separate
+protocol steps so the host can control them explicitly.
 
 Parameters:
-- `workerMutableRuntimeState` - - Mutable worker runtime state.
+- `initPayload` - - Initialization values from the browser host.
 
-Returns: Nothing.
+Returns: Promise resolved when runtime setup is complete.
 
-### beginWorkerPlayback
+### postWorkerMessage
 
 ```ts
-beginWorkerPlayback(
-  workerMutableRuntimeState: WorkerMutableRuntimeState,
-  payload: { visibleWorldWidthPx: number; visibleWorldHeightPx: number; },
+postWorkerMessage(
+  workerMessage: WorkerResponseMessage,
+  transferList: Transferable[] | undefined,
 ): void
 ```
 
-Begins a new playback session from the current evolved population.
+Posts a typed message from worker to host.
 
-A playback session is a deterministic simulation snapshot seeded from the
-current population. Each new session resets playback RNG and world state so
-the host can replay generations cleanly.
+This is the narrowest possible transport helper: all message construction is
+done elsewhere so the README can point to one stable worker-to-host boundary.
 
 Parameters:
-- `workerMutableRuntimeState` - - Mutable worker runtime state.
-- `payload` - - Playback start payload.
+- `workerMessage` - - Outbound worker response payload.
+- `transferList` - - Optional transferable buffers moved with the payload.
 
 Returns: Nothing.
 
@@ -205,26 +225,6 @@ Parameters:
 
 Returns: Nothing.
 
-### postWorkerMessage
-
-```ts
-postWorkerMessage(
-  workerMessage: WorkerResponseMessage,
-  transferList: Transferable[] | undefined,
-): void
-```
-
-Posts a typed message from worker to host.
-
-This is the narrowest possible transport helper: all message construction is
-done elsewhere so the README can point to one stable worker-to-host boundary.
-
-Parameters:
-- `workerMessage` - - Outbound worker response payload.
-- `transferList` - - Optional transferable buffers moved with the payload.
-
-Returns: Nothing.
-
 ## flappy-evolution-worker/flappy-evolution-worker.types.ts
 
 ### SerializedNetwork
@@ -235,29 +235,12 @@ 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.
 
-### WorkerPopulationPipe
-
-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.
-
-### WorkerPopulationBird
-
-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.
-
-### WorkerPlaybackState
+### WorkerErrorMessage
 
-Mutable simulation state stored between worker playback requests.
+Worker error response message.
 
-A `start-playback` message creates this state once, and each
-`request-playback-step` message advances it by a host-selected number of
-simulation steps.
+Errors are normalized into a display-safe string so the host UI can surface
+failures without depending on worker-specific exception classes.
 
 ### WorkerFrameBirdSnapshot
 
@@ -273,13 +256,27 @@ 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.
 
-### WorkerPackedPlaybackPipeSnapshot
+### WorkerGenerationReadyMessage
 
-Packed typed-array payload for playback pipe snapshot transport.
+Worker generation-ready response message.
 
-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.
+The browser host uses this message to refresh HUD state and optionally render
+the current best network visualization.
+
+### WorkerHeuristicObservationFeatures
+
+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.
+
+### WorkerInitMessage
+
+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.
 
 ### WorkerPackedPlaybackBirdSnapshot
 
@@ -288,6 +285,14 @@ 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.
 
+### WorkerPackedPlaybackPipeSnapshot
+
+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.
+
 ### WorkerPlaybackFrameSnapshot
 
 Full frame snapshot payload posted to host.
@@ -310,43 +315,48 @@ const message = {
 };
 ```
 
-### WorkerInitMessage
+### WorkerPlaybackState
 
-Worker init request message.
+Mutable simulation state stored between worker playback requests.
 
-This is the first message the host should send. It seeds deterministic RNG
-state and configures the worker-local NEAT runtime.
+A `start-playback` message creates this state once, and each
+`request-playback-step` message advances it by a host-selected number of
+simulation steps.
 
-### WorkerRequestGenerationMessage
+### WorkerPlaybackStepMessage
 
-Worker request asking to evolve one generation.
+Worker playback-step response message.
 
-The worker responds with `generation-ready` once the NEAT runtime finishes
-one evolution pass.
+The message carries the packed frame snapshot plus optional instrumentation
+and end-of-run summary statistics when the whole simulated population has
+been eliminated.
 
-### WorkerStartPlaybackMessage
+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.
 
-Worker request asking to initialize playback state.
+### WorkerPopulationBird
 
-This materializes the mutable world state for the current evolved population.
-After this message succeeds, the host can begin issuing playback-step
-requests.
+Mutable bird state tracked by the worker playback simulation.
 
-### WorkerRequestPlaybackStepMessage
+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.
 
-Worker request asking to advance playback by N simulation steps.
+### WorkerPopulationPipe
 
-The host typically sends this once per animation frame and chooses
-`simulationSteps` based on how much simulation throughput it wants relative to
-rendering smoothness.
+Mutable pipe state tracked by the worker playback simulation.
 
-### WorkerStopMessage
+These objects exist only inside the worker runtime. The host later receives a
+packed snapshot derived from them rather than these live mutable records.
 
-Worker stop request message.
+### WorkerRequestGenerationMessage
 
-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.
+Worker request asking to evolve one generation.
+
+The worker responds with `generation-ready` once the NEAT runtime finishes
+one evolution pass.
 
 ### WorkerRequestMessage
 
@@ -355,31 +365,13 @@ 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.
 
-### WorkerGenerationReadyMessage
-
-Worker generation-ready response message.
-
-The browser host uses this message to refresh HUD state and optionally render
-the current best network visualization.
-
-### WorkerPlaybackStepMessage
-
-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.
-
-### WorkerErrorMessage
+### WorkerRequestPlaybackStepMessage
 
-Worker error response message.
+Worker request asking to advance playback by N simulation steps.
 
-Errors are normalized into a display-safe string so the host UI can surface
-failures without depending on worker-specific exception classes.
+The host typically sends this once per animation frame and chooses
+`simulationSteps` based on how much simulation throughput it wants relative to
+rendering smoothness.
 
 ### WorkerResponseMessage
 
@@ -388,13 +380,21 @@ Union of outbound worker response messages.
 Together with `WorkerRequestMessage`, this forms the full host/worker
 protocol contract for the demo.
 
-### WorkerHeuristicObservationFeatures
+### WorkerStartPlaybackMessage
 
-Structured features used by heuristic generation-0 teacher policy.
+Worker request asking to initialize playback state.
 
-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.
+This materializes the mutable world state for the current evolved population.
+After this message succeeds, the host can begin issuing playback-step
+requests.
+
+### WorkerStopMessage
+
+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.
 
 ## flappy-evolution-worker/flappy-evolution-worker.runtime.service.ts
 
@@ -690,49 +690,52 @@ const playbackState = createWorkerPopulationRenderState(
 
 ## flappy-evolution-worker/flappy-evolution-worker.simulation.frame.service.ts
 
-### stepWorkerPopulationFrame
+### advanceBirdPhysics
 
 ```ts
-stepWorkerPopulationFrame(
-  renderState: WorkerPlaybackState,
-  rng: RngLike,
-  difficultyProfile: SharedDifficultyProfile,
-): number
+advanceBirdPhysics(
+  frameContext: WorkerPlaybackFrameContext,
+): void
 ```
 
-Advances the whole population simulation by one logical frame.
+Integrates bird velocity and vertical motion for one control substep.
 
-Educational note:
-One logical frame is internally split into smaller control substeps so the
-worker can make flap decisions, apply gravity, move pipes, spawn new pipes,
-and resolve collisions with better numerical stability than a single large
-integration jump.
+Parameters:
+- `frameContext` - - Shared frame context for this logical frame.
 
-This function is the main simulation ownership boundary for the folder.
-The companion `simulation.utils` file creates initial state; this service is
-responsible for mutating that state over time.
+Returns: Nothing.
+
+### advancePipes
+
+```ts
+advancePipes(
+  frameContext: WorkerPlaybackFrameContext,
+): void
+```
+
+Advances all visible pipes and culls those that have left the camera window.
 
 Parameters:
-- `renderState` - - Mutable simulation state.
-- `rng` - - Deterministic random source for spawn variation.
-- `difficultyProfile` - - Active dynamic difficulty profile.
+- `frameContext` - - Shared frame context for this logical frame.
 
-Returns: Number of policy activation calls made in this frame.
+Returns: Nothing.
 
-### resolveCameraLeftXPx
+### commitPassedPipeProgress
 
 ```ts
-resolveCameraLeftXPx(
-  visibleWorldWidthPx: number,
-): number
+commitPassedPipeProgress(
+  bird: WorkerPopulationBird,
+  pipe: WorkerPopulationPipe,
+): void
 ```
 
-Resolves the current left-edge of the visible world in world-space pixels.
+Commits one passed-pipe progress increment for a bird when eligible.
 
 Parameters:
-- `visibleWorldWidthPx` - - Current visible world width.
+- `bird` - - Mutable bird state.
+- `pipe` - - Pipe candidate to mark as passed.
 
-Returns: Left edge x-position in world coordinates.
+Returns: Nothing.
 
 ### incrementLivingBirdFrameCounters
 
@@ -749,20 +752,24 @@ Parameters:
 
 Returns: Nothing.
 
-### runWorkerPopulationControlSubstep
+### resolveBirdCollisionAgainstPipe
 
 ```ts
-runWorkerPopulationControlSubstep(
+resolveBirdCollisionAgainstPipe(
+  bird: WorkerPopulationBird,
+  pipe: WorkerPopulationPipe,
   frameContext: WorkerPlaybackFrameContext,
-): number
+): boolean
 ```
 
-Advances one control substep of the worker playback simulation.
+Resolves whether a bird collides with one pipe corridor during this substep.
 
 Parameters:
+- `bird` - - Mutable bird state.
+- `pipe` - - Pipe candidate to test.
 - `frameContext` - - Shared frame context for this logical frame.
 
-Returns: Number of activation calls performed in the substep.
+Returns: `true` when the bird overlaps the pipe body instead of the gap.
 
 ### resolveBirdControlActions
 
@@ -779,50 +786,22 @@ Parameters:
 
 Returns: Number of activation calls performed in the substep.
 
-### advanceBirdPhysics
-
-```ts
-advanceBirdPhysics(
-  frameContext: WorkerPlaybackFrameContext,
-): void
-```
-
-Integrates bird velocity and vertical motion for one control substep.
-
-Parameters:
-- `frameContext` - - Shared frame context for this logical frame.
-
-Returns: Nothing.
-
-### advancePipes
-
-```ts
-advancePipes(
-  frameContext: WorkerPlaybackFrameContext,
-): void
-```
-
-Advances all visible pipes and culls those that have left the camera window.
-
-Parameters:
-- `frameContext` - - Shared frame context for this logical frame.
-
-Returns: Nothing.
-
-### spawnPipeIfNeeded
+### resolveBirdOutOfBounds
 
 ```ts
-spawnPipeIfNeeded(
-  frameContext: WorkerPlaybackFrameContext,
-): void
+resolveBirdOutOfBounds(
+  bird: WorkerPopulationBird,
+  visibleWorldHeightPx: number,
+): boolean
 ```
 
-Spawns a new pipe when the substep budget crosses the spawn boundary.
+Resolves whether a bird has exceeded the vertical play area.
 
 Parameters:
-- `frameContext` - - Shared frame context for this logical frame.
+- `bird` - - Mutable bird state.
+- `visibleWorldHeightPx` - - Current visible world height.
 
-Returns: Nothing.
+Returns: `true` when the bird is outside the vertical bounds.
 
 ### resolveBirdTerminationAndProgress
 
@@ -839,112 +818,106 @@ Parameters:
 
 Returns: Nothing.
 
-### resolveBirdOutOfBounds
+### resolveCameraLeftXPx
 
 ```ts
-resolveBirdOutOfBounds(
-  bird: WorkerPopulationBird,
-  visibleWorldHeightPx: number,
-): boolean
+resolveCameraLeftXPx(
+  visibleWorldWidthPx: number,
+): number
 ```
 
-Resolves whether a bird has exceeded the vertical play area.
+Resolves the current left-edge of the visible world in world-space pixels.
 
 Parameters:
-- `bird` - - Mutable bird state.
-- `visibleWorldHeightPx` - - Current visible world height.
+- `visibleWorldWidthPx` - - Current visible world width.
 
-Returns: `true` when the bird is outside the vertical bounds.
+Returns: Left edge x-position in world coordinates.
 
-### resolveBirdCollisionAgainstPipe
+### runWorkerPopulationControlSubstep
 
 ```ts
-resolveBirdCollisionAgainstPipe(
-  bird: WorkerPopulationBird,
-  pipe: WorkerPopulationPipe,
+runWorkerPopulationControlSubstep(
   frameContext: WorkerPlaybackFrameContext,
-): boolean
+): number
 ```
 
-Resolves whether a bird collides with one pipe corridor during this substep.
+Advances one control substep of the worker playback simulation.
 
 Parameters:
-- `bird` - - Mutable bird state.
-- `pipe` - - Pipe candidate to test.
 - `frameContext` - - Shared frame context for this logical frame.
 
-Returns: `true` when the bird overlaps the pipe body instead of the gap.
+Returns: Number of activation calls performed in the substep.
 
-### commitPassedPipeProgress
+### spawnPipeIfNeeded
 
 ```ts
-commitPassedPipeProgress(
-  bird: WorkerPopulationBird,
-  pipe: WorkerPopulationPipe,
+spawnPipeIfNeeded(
+  frameContext: WorkerPlaybackFrameContext,
 ): void
 ```
 
-Commits one passed-pipe progress increment for a bird when eligible.
+Spawns a new pipe when the substep budget crosses the spawn boundary.
 
 Parameters:
-- `bird` - - Mutable bird state.
-- `pipe` - - Pipe candidate to mark as passed.
+- `frameContext` - - Shared frame context for this logical frame.
 
 Returns: Nothing.
 
-## flappy-evolution-worker/flappy-evolution-worker.warm-start.service.ts
-
-### warmStartWorkerGenerationZeroIfNeeded
+### stepWorkerPopulationFrame
 
 ```ts
-warmStartWorkerGenerationZeroIfNeeded(
-  neatController: default,
-  warmStartState: WorkerWarmStartState,
-  dependencies: WorkerWarmStartDependencies,
-): Promise<void>
+stepWorkerPopulationFrame(
+  renderState: WorkerPlaybackState,
+  rng: RngLike,
+  difficultyProfile: SharedDifficultyProfile,
+): number
 ```
 
-Applies a one-time generation-0 warm-start to improve initial demo quality.
+Advances the whole population simulation by one logical frame.
 
 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.
+One logical frame is internally split into smaller control substeps so the
+worker can make flap decisions, apply gravity, move pipes, spawn new pipes,
+and resolve collisions with better numerical stability than a single large
+integration jump.
 
-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.
+This function is the main simulation ownership boundary for the folder.
+The companion `simulation.utils` file creates initial state; this service is
+responsible for mutating that state over time.
 
 Parameters:
-- `neatController` - - Initialized NEAT runtime.
-- `warmStartState` - - Mutable warm-start lifecycle state.
+- `renderState` - - Mutable simulation state.
+- `rng` - - Deterministic random source for spawn variation.
+- `difficultyProfile` - - Active dynamic difficulty profile.
 
-Returns: Promise resolved when warm-start evaluation finishes.
+Returns: Number of policy activation calls made in this frame.
 
-Example:
+## flappy-evolution-worker/flappy-evolution-worker.warm-start.service.ts
+
+### applyTemplateWeightsWithNoise
 
 ```ts
-await warmStartWorkerGenerationZeroIfNeeded(neatRuntime, {
-  workerInitSeed: 123,
-  generationZeroWarmStartApplied: false,
-});
+applyTemplateWeightsWithNoise(
+  genome: default,
+  template: default,
+  rng: FlappyRng,
+  noise: { weightStdDev: number; biasStdDev: number; },
+): void
 ```
 
-### WorkerWarmStartState
-
-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.
+Copies template parameters into a genome and injects small Gaussian noise.
 
-### WorkerWarmStartDependencies
+Educational note:
+The template network gives generation 0 a shared prior, while the noise terms
+restore diversity so the population is still worth evolving.
 
-Dependency bag for generation-0 warm-start orchestration.
+Parameters:
+- `genome` - - Target genome to mutate in-place.
+- `template` - - Trained template source network.
+- `rng` - - Deterministic random source for noise sampling.
+- `noise` - - Standard deviations for weight and bias perturbations.
 
-The production path uses the real heuristic dataset builder and rollout-guided
-template refinement. Tests can override these seams to keep assertions small
-and deterministic.
+Returns: Nothing.
 
 ### buildHeuristicPretrainSet
 
@@ -953,43 +926,20 @@ buildHeuristicPretrainSet(
   rng: FlappyRng,
   sampleCount: number,
 ): { input: number[]; output: number[]; }[]
-```
-
-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.
-
-Parameters:
-- `rng` - - Deterministic random source.
-- `sampleCount` - - Requested number of synthetic samples.
-
-Returns: Supervised dataset of input/output pairs.
-
-### optimizeWarmStartTemplateNetwork
-
-```ts
-optimizeWarmStartTemplateNetwork(
-  templateNetwork: default,
-  workerInitSeed: number,
-): default
-```
-
-Refines the generation-0 template against real Flappy rollouts.
-
-The warm-start teacher gets the template out of pure-random territory, but it
-still only imitates a simple flap heuristic. This refinement pass keeps the
-topology fixed and searches the parameter surface directly against actual
-rollout fitness so the first visible generation starts closer to competent
-control.
+```
+
+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.
 
 Parameters:
-- `templateNetwork` - - Heuristic-pretrained template network.
-- `workerInitSeed` - - Deterministic worker seed.
+- `rng` - - Deterministic random source.
+- `sampleCount` - - Requested number of synthetic samples.
 
-Returns: Best rollout-refined template found within the bounded budget.
+Returns: Supervised dataset of input/output pairs.
 
 ### buildWarmStartRolloutSeedBatch
 
@@ -1025,6 +975,25 @@ Parameters:
 
 Returns: Aggregate shared-seed evaluation.
 
+### interpolateValue
+
+```ts
+interpolateValue(
+  startValue: number,
+  endValue: number,
+  ratio: number,
+): number
+```
+
+Linearly interpolates between two scalar values.
+
+Parameters:
+- `startValue` - - Value at ratio `0`.
+- `endValue` - - Value at ratio `1`.
+- `ratio` - - Interpolation ratio.
+
+Returns: Interpolated value.
+
 ### isWarmStartEvaluationBetter
 
 ```ts
@@ -1046,22 +1015,28 @@ Parameters:
 
 Returns: True when the candidate should replace the incumbent template.
 
-### resolveWarmStartAnnealRatio
+### optimizeWarmStartTemplateNetwork
 
 ```ts
-resolveWarmStartAnnealRatio(
-  optimizationStepIndex: number,
-  totalOptimizationSteps: number,
-): number
+optimizeWarmStartTemplateNetwork(
+  templateNetwork: default,
+  workerInitSeed: number,
+): default
 ```
 
-Resolves the annealing ratio for rollout-guided warm-start refinement.
+Refines the generation-0 template against real Flappy rollouts.
+
+The warm-start teacher gets the template out of pure-random territory, but it
+still only imitates a simple flap heuristic. This refinement pass keeps the
+topology fixed and searches the parameter surface directly against actual
+rollout fitness so the first visible generation starts closer to competent
+control.
 
 Parameters:
-- `optimizationStepIndex` - - Zero-based optimization step index.
-- `totalOptimizationSteps` - - Total number of optimization steps.
+- `templateNetwork` - - Heuristic-pretrained template network.
+- `workerInitSeed` - - Deterministic worker seed.
 
-Returns: Clamped ratio in the inclusive range [0, 1].
+Returns: Best rollout-refined template found within the bounded budget.
 
 ### perturbNetworkParametersInPlace
 
@@ -1086,25 +1061,6 @@ Parameters:
 
 Returns: Nothing.
 
-### interpolateValue
-
-```ts
-interpolateValue(
-  startValue: number,
-  endValue: number,
-  ratio: number,
-): number
-```
-
-Linearly interpolates between two scalar values.
-
-Parameters:
-- `startValue` - - Value at ratio `0`.
-- `endValue` - - Value at ratio `1`.
-- `ratio` - - Interpolation ratio.
-
-Returns: Interpolated value.
-
 ### resolveHeuristicTeacherFlapDecision
 
 ```ts
@@ -1124,30 +1080,22 @@ Parameters:
 
 Returns: True when the teacher says to flap.
 
-### applyTemplateWeightsWithNoise
+### resolveWarmStartAnnealRatio
 
 ```ts
-applyTemplateWeightsWithNoise(
-  genome: default,
-  template: default,
-  rng: FlappyRng,
-  noise: { weightStdDev: number; biasStdDev: number; },
-): void
+resolveWarmStartAnnealRatio(
+  optimizationStepIndex: number,
+  totalOptimizationSteps: number,
+): number
 ```
 
-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.
+Resolves the annealing ratio for rollout-guided warm-start refinement.
 
 Parameters:
-- `genome` - - Target genome to mutate in-place.
-- `template` - - Trained template source network.
-- `rng` - - Deterministic random source for noise sampling.
-- `noise` - - Standard deviations for weight and bias perturbations.
+- `optimizationStepIndex` - - Zero-based optimization step index.
+- `totalOptimizationSteps` - - Total number of optimization steps.
 
-Returns: Nothing.
+Returns: Clamped ratio in the inclusive range [0, 1].
 
 ### sampleGaussian
 
@@ -1169,27 +1117,59 @@ Parameters:
 
 Returns: One approximately standard-normal random value.
 
-## flappy-evolution-worker/flappy-evolution-worker.errors.ts
-
-### resolveWorkerUnknownErrorMessage
+### warmStartWorkerGenerationZeroIfNeeded
 
 ```ts
-resolveWorkerUnknownErrorMessage(
-  error: unknown,
-): string
+warmStartWorkerGenerationZeroIfNeeded(
+  neatController: default,
+  warmStartState: WorkerWarmStartState,
+  dependencies: WorkerWarmStartDependencies,
+): Promise<void>
 ```
 
-Resolves unknown error-like values into display-safe worker error messages.
+Applies a one-time generation-0 warm-start to improve initial demo quality.
 
 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.
+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.
 
 Parameters:
-- `error` - - Unknown error value thrown by worker logic.
+- `neatController` - - Initialized NEAT runtime.
+- `warmStartState` - - Mutable warm-start lifecycle state.
 
-Returns: Normalized error message string.
+Returns: Promise resolved when warm-start evaluation finishes.
+
+Example:
+
+```ts
+await warmStartWorkerGenerationZeroIfNeeded(neatRuntime, {
+  workerInitSeed: 123,
+  generationZeroWarmStartApplied: false,
+});
+```
+
+### WorkerWarmStartDependencies
+
+Dependency bag for generation-0 warm-start orchestration.
+
+The production path uses the real heuristic dataset builder and rollout-guided
+template refinement. Tests can override these seams to keep assertions small
+and deterministic.
+
+### WorkerWarmStartState
+
+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.
+
+## flappy-evolution-worker/flappy-evolution-worker.errors.ts
 
 ### createWorkerErrorMessage
 
@@ -1254,18 +1234,27 @@ 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.
 
-## flappy-evolution-worker/flappy-evolution-worker.constants.ts
+### resolveWorkerUnknownErrorMessage
 
-Synthetic sample count used for generation-0 warm-start pretraining.
+```ts
+resolveWorkerUnknownErrorMessage(
+  error: unknown,
+): string
+```
+
+Resolves unknown error-like values into display-safe worker error messages.
 
 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.
+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.
 
-### FLAPPY_WORKER_GEN0_PRETRAIN_SAMPLE_COUNT
+Parameters:
+- `error` - - Unknown error value thrown by worker logic.
+
+Returns: Normalized error message string.
+
+## flappy-evolution-worker/flappy-evolution-worker.constants.ts
 
 Synthetic sample count used for generation-0 warm-start pretraining.
 
@@ -1276,13 +1265,19 @@ 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.
 
-### FLAPPY_WORKER_GEN0_PRETRAIN_VISIBLE_WORLD_WIDTH_PX
+### FLAPPY_WORKER_GEN0_PRETRAIN_BATCH_SIZE
 
-Visible world width used when generating synthetic warm-start samples.
+Batch size for generation-0 warm-start pretraining.
 
-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.
+Smaller batches inject a bit more stochasticity into the bootstrap fit,
+while still keeping the pass cheap enough for a browser worker.
+
+### FLAPPY_WORKER_GEN0_PRETRAIN_BIAS_NOISE_STDDEV
+
+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.
 
 ### FLAPPY_WORKER_GEN0_PRETRAIN_ITERATIONS
 
@@ -1292,13 +1287,6 @@ 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.
 
-### FLAPPY_WORKER_GEN0_PRETRAIN_BATCH_SIZE
-
-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.
-
 ### FLAPPY_WORKER_GEN0_PRETRAIN_RATE
 
 Learning rate for generation-0 warm-start pretraining.
@@ -1306,14 +1294,13 @@ 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.
 
-### FLAPPY_WORKER_GEN0_PRETRAIN_ROLLOUT_SEED_COUNT
+### FLAPPY_WORKER_GEN0_PRETRAIN_ROLLOUT_BIAS_STDDEV_END
 
-Shared-seed batch size used by rollout-guided generation-0 template refinement.
+Final node-bias noise scale for rollout-guided template refinement.
 
-After the heuristic teacher fit, the worker evaluates the fixed topology on a
-few real Flappy rollouts so the warm-start prior is pushed toward trajectories
-that actually survive the environment instead of only matching the synthetic
-teacher labels.
+### FLAPPY_WORKER_GEN0_PRETRAIN_ROLLOUT_BIAS_STDDEV_START
+
+Initial node-bias noise scale for rollout-guided template refinement.
 
 ### FLAPPY_WORKER_GEN0_PRETRAIN_ROLLOUT_OPTIMIZATION_STEPS
 
@@ -1323,6 +1310,19 @@ Each step perturbs the current best template, evaluates it on the shared
 rollout seed batch, and keeps the candidate only when it improves robust
 fitness. The budget stays intentionally small so worker startup remains fast.
 
+### FLAPPY_WORKER_GEN0_PRETRAIN_ROLLOUT_SEED_COUNT
+
+Shared-seed batch size used by rollout-guided generation-0 template refinement.
+
+After the heuristic teacher fit, the worker evaluates the fixed topology on a
+few real Flappy rollouts so the warm-start prior is pushed toward trajectories
+that actually survive the environment instead of only matching the synthetic
+teacher labels.
+
+### FLAPPY_WORKER_GEN0_PRETRAIN_ROLLOUT_WEIGHT_STDDEV_END
+
+Final connection-weight noise scale for rollout-guided template refinement.
+
 ### FLAPPY_WORKER_GEN0_PRETRAIN_ROLLOUT_WEIGHT_STDDEV_START
 
 Initial connection-weight noise scale for rollout-guided template refinement.
@@ -1330,17 +1330,24 @@ Initial connection-weight noise scale for rollout-guided template refinement.
 Early optimization steps search broadly, then later steps cool toward the
 smaller end scale below for finer local refinement.
 
-### FLAPPY_WORKER_GEN0_PRETRAIN_ROLLOUT_WEIGHT_STDDEV_END
+### FLAPPY_WORKER_GEN0_PRETRAIN_SAMPLE_COUNT
 
-Final connection-weight noise scale for rollout-guided template refinement.
+Synthetic sample count used for generation-0 warm-start pretraining.
 
-### FLAPPY_WORKER_GEN0_PRETRAIN_ROLLOUT_BIAS_STDDEV_START
+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.
 
-Initial node-bias noise scale for rollout-guided template refinement.
+### FLAPPY_WORKER_GEN0_PRETRAIN_VISIBLE_WORLD_WIDTH_PX
 
-### FLAPPY_WORKER_GEN0_PRETRAIN_ROLLOUT_BIAS_STDDEV_END
+Visible world width used when generating synthetic warm-start samples.
 
-Final node-bias noise scale for rollout-guided template refinement.
+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.
 
 ### FLAPPY_WORKER_GEN0_PRETRAIN_WEIGHT_NOISE_STDDEV
 
@@ -1349,10 +1356,3 @@ Gaussian standard deviation used for post-pretrain connection-weight diversifica
 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.
-
-### FLAPPY_WORKER_GEN0_PRETRAIN_BIAS_NOISE_STDDEV
-
-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.