@reicek/neataptic-ts 0.1.24 → 0.1.26

package/test/examples/flappy_bird/browser-entry/README.md

@@ -36,6 +36,10 @@ flowchart LR
 
 ## browser-entry/browser-entry.ts
 
+### FlappyBirdRunHandle
+
+Handle returned by `start` for controlling demo execution lifecycle.
+
 ### start
 
 ```ts
@@ -66,10 +70,6 @@ runHandle.stop();
 await runHandle.done;
 ```
 
-### FlappyBirdRunHandle
-
-Handle returned by `start` for controlling demo execution lifecycle.
-
 ## browser-entry/browser-entry.types.ts
 
 Aggregated public type surface for the Flappy Bird browser runtime.
@@ -99,42 +99,33 @@ flowchart TB
     PublicTypes --> Viz["visualization types\nlegend and color scales"]
 ```
 
-### FlappyBirdRunHandle
-
-Handle returned by `start` for controlling demo execution lifecycle.
-
-### RuntimeWindow
-
-Runtime window contract for the Flappy Bird browser demo.
+### BrowserDifficultyProfile
 
-The demo exposes a small debug-friendly surface on `window` so manual browser
-experiments and docs examples can start the simulation without importing the
-bundle as a module.
+Difficulty profile consumed by simulation observation helpers.
 
-### FlappyStatsKey
+This bundles the three variables that define how demanding a stretch of the
+course is: corridor width, pipe speed, and spawn cadence.
 
-Runtime stats table key union used across browser-entry helpers.
+### BrowserPopulationBirdLike
 
-### FlappyStatsRowDescriptor
+Bird shape used by utility winner/leader resolver helpers.
 
-Declarative row descriptor for the runtime stats table.
+### BrowserPopulationPipeLike
 
-Each row is described as data first so the HUD can be assembled in a stable,
-testable order instead of being hand-written imperatively.
+Pipe shape used by utility observation-vector helpers.
 
-### FlappyStatsTableCells
+### ColorLegendRow
 
-Runtime lookup map of stat keys to writable value cells.
+Legend row model for network visualization color legends.
 
-This acts like a small DOM index so the update loop can mutate the correct
-cells directly without repeatedly querying the document.
+Each row labels a numeric interval and the color used to render it.
 
-### FlappyStatsCategoryColors
+### ColorTier
 
-Color pair used for stats category key/value styling.
+Connection or bias tier used for color mapping ramps.
 
-The HUD uses paired colors so labels and values stay visually grouped while
-still separating categories such as current run, telemetry, and best-so-far.
+Visualization buckets continuous weights into legible color bands so humans
+can scan sign and magnitude at a glance.
 
 ### CreateFlappyStatsTableRowsInput
 
@@ -143,39 +134,6 @@ Input contract for declarative runtime stats table row builder.
 The builder needs both the target table and a small policy surface that says
 whether instrumentation rows should appear and how rows should be colored.
 
-### SerializedNetwork
-
-Loose JSON-compatible network payload used by worker messages.
-
-### PopulationPipe
-
-Renderable pipe state snapshot emitted by the playback worker.
-
-This is the smallest pipe shape the browser renderer needs for one frame:
-horizontal position plus the vertical corridor geometry.
-
-### PopulationBird
-
-Renderable bird state snapshot emitted by the playback worker.
-
-The browser does not receive full neural state here. It only gets the fields
-needed for presentation and HUD summaries, which keeps per-frame transport
-light.
-
-### PackedPlaybackPipeSnapshot
-
-Packed typed-array payload for playback pipe snapshot transport.
-
-Typed arrays keep frame payloads compact and predictable, which matters when
-the worker is streaming many birds and pipes across animation frames.
-
-### PackedPlaybackBirdSnapshot
-
-Packed typed-array payload for playback bird snapshot transport.
-
-This mirrors the pipe packing strategy so playback can move large population
-snapshots with less allocation pressure than object-per-bird messages.
-
 ### EvolutionGenerationPayload
 
 Worker payload describing evolved generation summary values.
@@ -188,9 +146,13 @@ network for visualization or playback.
 
 Worker message emitted when a generation has completed evolving.
 
-### EvolutionWorkerErrorMessage
+### EvolutionPlaybackStepMessage
 
-Worker message emitted for simulation/playback errors.
+Worker message carrying one playback step and aggregate markers.
+
+Besides the frame snapshot itself, this message also carries summary values
+used by the HUD so the browser can show performance and progress without
+recomputing population-wide statistics on the main thread.
 
 ### EvolutionPlaybackStepSnapshot
 
@@ -200,13 +162,9 @@ A snapshot combines geometry, packed population state, and lightweight world
 metadata so the browser can render a deterministic frame without rerunning
 the simulation locally.
 
-### EvolutionPlaybackStepMessage
-
-Worker message carrying one playback step and aggregate markers.
+### EvolutionWorkerErrorMessage
 
-Besides the frame snapshot itself, this message also carries summary values
-used by the HUD so the browser can show performance and progress without
-recomputing population-wide statistics on the main thread.
+Worker message emitted for simulation/playback errors.
 
 ### EvolutionWorkerMessage
 
@@ -215,6 +173,67 @@ Union of all supported worker messages consumed by browser entry.
 A closed union keeps the main-thread message handler explicit and easy to
 audit when the protocol evolves.
 
+### FlappyBirdRunHandle
+
+Handle returned by `start` for controlling demo execution lifecycle.
+
+### FlappyStatsCategoryColors
+
+Color pair used for stats category key/value styling.
+
+The HUD uses paired colors so labels and values stay visually grouped while
+still separating categories such as current run, telemetry, and best-so-far.
+
+### FlappyStatsKey
+
+Runtime stats table key union used across browser-entry helpers.
+
+### FlappyStatsRowDescriptor
+
+Declarative row descriptor for the runtime stats table.
+
+Each row is described as data first so the HUD can be assembled in a stable,
+testable order instead of being hand-written imperatively.
+
+### FlappyStatsTableCells
+
+Runtime lookup map of stat keys to writable value cells.
+
+This acts like a small DOM index so the update loop can mutate the correct
+cells directly without repeatedly querying the document.
+
+### NetworkLegendLayout
+
+Precomputed legend panel layout used by visualization renderer.
+
+Layout is resolved up front so the draw path can stay focused on painting,
+not recomputing geometry every frame.
+
+### NetworkNodeDimensionsLike
+
+Pixel dimensions used for network-node rectangle rendering.
+
+Keeping node box dimensions explicit makes legend and topology layout easier
+to tune without hidden drawing constants.
+
+### NetworkVisualizationHandle
+
+Draw callback contract for network architecture panel updates.
+
+### PackedPlaybackBirdSnapshot
+
+Packed typed-array payload for playback bird snapshot transport.
+
+This mirrors the pipe packing strategy so playback can move large population
+snapshots with less allocation pressure than object-per-bird messages.
+
+### PackedPlaybackPipeSnapshot
+
+Packed typed-array payload for playback pipe snapshot transport.
+
+Typed arrays keep frame payloads compact and predictable, which matters when
+the worker is streaming many birds and pipes across animation frames.
+
 ### PlaybackFrameStats
 
 Lightweight per-frame telemetry emitted to HUD update callback.
@@ -223,20 +242,20 @@ These values are the browser-friendly metrics shown in the live status panel:
 how many birds remain, how far the leader has progressed, and how expensive
 the current playback cadence is.
 
-### BrowserPopulationBirdLike
-
-Bird shape used by utility winner/leader resolver helpers.
+### PopulationBird
 
-### BrowserPopulationPipeLike
+Renderable bird state snapshot emitted by the playback worker.
 
-Pipe shape used by utility observation-vector helpers.
+The browser does not receive full neural state here. It only gets the fields
+needed for presentation and HUD summaries, which keeps per-frame transport
+light.
 
-### BrowserDifficultyProfile
+### PopulationPipe
 
-Difficulty profile consumed by simulation observation helpers.
+Renderable pipe state snapshot emitted by the playback worker.
 
-This bundles the three variables that define how demanding a stretch of the
-course is: corridor width, pipe speed, and spawn cadence.
+This is the smallest pipe shape the browser renderer needs for one frame:
+horizontal position plus the vertical corridor geometry.
 
 ### PopulationRenderState
 
@@ -246,19 +265,23 @@ The playback layer incrementally updates this state as worker snapshots
 arrive, which lets rendering stay deterministic without re-deriving world
 history from scratch each frame.
 
-### TrailPoint
+### PositionedNetworkNodeLike
 
-Trail point used by playback trail rendering cache.
+Positioned node instance used by network visualization drawing.
 
-A trail point stores where one bird was at one frame so the UI can draw a
-short motion history behind active agents.
+Layout and rendering are split: first a node is assigned screen coordinates,
+then the renderer paints it.
 
-### TrailState
+### RenderClosedOuterBoxInput
 
-Mutable trail cache keyed by bird index for frame rendering.
+Input contract for outer frame rendering helper.
 
-This cache exists purely for visualization ergonomics; it is not part of the
-worker simulation state.
+The outer frame is the decorative shell that visually separates the playable
+world and telemetry panels from the rest of the page.
+
+### RenderStandaloneTitleBoxInput
+
+Input contract for standalone title frame rendering helper.
 
 ### RngLike
 
@@ -267,23 +290,17 @@ Minimal random source contract used by utility random helpers.
 The narrow contract keeps deterministic spawn utilities portable across
 browser and test contexts.
 
-### RenderStandaloneTitleBoxInput
-
-Input contract for standalone title frame rendering helper.
-
-### RenderClosedOuterBoxInput
-
-Input contract for outer frame rendering helper.
+### RuntimeWindow
 
-The outer frame is the decorative shell that visually separates the playable
-world and telemetry panels from the rest of the page.
+Runtime window contract for the Flappy Bird browser demo.
 
-### ViewportInfo
+The demo exposes a small debug-friendly surface on `window` so manual browser
+experiments and docs examples can start the simulation without importing the
+bundle as a module.
 
-Viewport transform values for world-to-canvas rendering.
+### SerializedNetwork
 
-These numbers answer the classic graphics question: how does one unit in the
-simulated world map into the current canvas rectangle?
+Loose JSON-compatible network payload used by worker messages.
 
 ### TextFrameMetrics
 
@@ -292,29 +309,26 @@ Canvas text-grid metrics used for frame rendering layout helpers.
 The frame renderer measures glyph and row geometry once, then uses that grid
 to place ASCII-style UI elements consistently.
 
-### NetworkVisualizationHandle
-
-Draw callback contract for network architecture panel updates.
-
-### ColorTier
+### TrailPoint
 
-Connection or bias tier used for color mapping ramps.
+Trail point used by playback trail rendering cache.
 
-Visualization buckets continuous weights into legible color bands so humans
-can scan sign and magnitude at a glance.
+A trail point stores where one bird was at one frame so the UI can draw a
+short motion history behind active agents.
 
-### ColorLegendRow
+### TrailState
 
-Legend row model for network visualization color legends.
+Mutable trail cache keyed by bird index for frame rendering.
 
-Each row labels a numeric interval and the color used to render it.
+This cache exists purely for visualization ergonomics; it is not part of the
+worker simulation state.
 
-### NetworkLegendLayout
+### ViewportInfo
 
-Precomputed legend panel layout used by visualization renderer.
+Viewport transform values for world-to-canvas rendering.
 
-Layout is resolved up front so the draw path can stay focused on painting,
-not recomputing geometry every frame.
+These numbers answer the classic graphics question: how does one unit in the
+simulated world map into the current canvas rectangle?
 
 ### VisualNetworkConnectionLike
 
@@ -330,27 +344,27 @@ Lightweight node shape used by network visualization drawing.
 This shape keeps the renderer independent from the concrete Network class
 while still exposing the semantic fields that matter visually.
 
-### PositionedNetworkNodeLike
+## browser-entry/browser-entry.stats.types.ts
 
-Positioned node instance used by network visualization drawing.
+HUD and runtime stats contracts for the Flappy Bird browser demo.
 
-Layout and rendering are split: first a node is assigned screen coordinates,
-then the renderer paints it.
+The browser HUD is intentionally declarative: keys describe what should be
+shown, and helper utilities map those keys to DOM rows and live values. That
+keeps the status panel readable even as telemetry grows.
 
-### NetworkNodeDimensionsLike
+### CreateFlappyStatsTableRowsInput
 
-Pixel dimensions used for network-node rectangle rendering.
+Input contract for declarative runtime stats table row builder.
 
-Keeping node box dimensions explicit makes legend and topology layout easier
-to tune without hidden drawing constants.
+The builder needs both the target table and a small policy surface that says
+whether instrumentation rows should appear and how rows should be colored.
 
-## browser-entry/browser-entry.stats.types.ts
+### FlappyStatsCategoryColors
 
-HUD and runtime stats contracts for the Flappy Bird browser demo.
+Color pair used for stats category key/value styling.
 
-The browser HUD is intentionally declarative: keys describe what should be
-shown, and helper utilities map those keys to DOM rows and live values. That
-keeps the status panel readable even as telemetry grows.
+The HUD uses paired colors so labels and values stay visually grouped while
+still separating categories such as current run, telemetry, and best-so-far.
 
 ### FlappyStatsKey
 
@@ -370,20 +384,6 @@ Runtime lookup map of stat keys to writable value cells.
 This acts like a small DOM index so the update loop can mutate the correct
 cells directly without repeatedly querying the document.
 
-### FlappyStatsCategoryColors
-
-Color pair used for stats category key/value styling.
-
-The HUD uses paired colors so labels and values stay visually grouped while
-still separating categories such as current run, telemetry, and best-so-far.
-
-### CreateFlappyStatsTableRowsInput
-
-Input contract for declarative runtime stats table row builder.
-
-The builder needs both the target table and a small policy surface that says
-whether instrumentation rows should appear and how rows should be colored.
-
 ## browser-entry/browser-entry.render.types.ts
 
 Canvas frame-layout contracts for the Flappy Bird browser demo.
@@ -392,10 +392,6 @@ These types support the demo's deliberately stylized text-frame chrome: title
 boxes, outer borders, and viewport transforms that make the example feel more
 like an instrument panel than a plain canvas game.
 
-### RenderStandaloneTitleBoxInput
-
-Input contract for standalone title frame rendering helper.
-
 ### RenderClosedOuterBoxInput
 
 Input contract for outer frame rendering helper.
@@ -403,12 +399,9 @@ Input contract for outer frame rendering helper.
 The outer frame is the decorative shell that visually separates the playable
 world and telemetry panels from the rest of the page.
 
-### ViewportInfo
-
-Viewport transform values for world-to-canvas rendering.
+### RenderStandaloneTitleBoxInput
 
-These numbers answer the classic graphics question: how does one unit in the
-simulated world map into the current canvas rectangle?
+Input contract for standalone title frame rendering helper.
 
 ### TextFrameMetrics
 
@@ -417,6 +410,13 @@ Canvas text-grid metrics used for frame rendering layout helpers.
 The frame renderer measures glyph and row geometry once, then uses that grid
 to place ASCII-style UI elements consistently.
 
+### ViewportInfo
+
+Viewport transform values for world-to-canvas rendering.
+
+These numbers answer the classic graphics question: how does one unit in the
+simulated world map into the current canvas rectangle?
+
 ## browser-entry/browser-entry.worker.types.ts
 
 Worker transport contracts for the Flappy Bird browser runtime.
@@ -429,39 +429,6 @@ transferred frame-by-frame, and which events advance the demo state.
 If you want background reading, the Wikipedia article on "message passing"
 provides a useful conceptual frame for this boundary.
 
-### SerializedNetwork
-
-Loose JSON-compatible network payload used by worker messages.
-
-### PopulationPipe
-
-Renderable pipe state snapshot emitted by the playback worker.
-
-This is the smallest pipe shape the browser renderer needs for one frame:
-horizontal position plus the vertical corridor geometry.
-
-### PopulationBird
-
-Renderable bird state snapshot emitted by the playback worker.
-
-The browser does not receive full neural state here. It only gets the fields
-needed for presentation and HUD summaries, which keeps per-frame transport
-light.
-
-### PackedPlaybackPipeSnapshot
-
-Packed typed-array payload for playback pipe snapshot transport.
-
-Typed arrays keep frame payloads compact and predictable, which matters when
-the worker is streaming many birds and pipes across animation frames.
-
-### PackedPlaybackBirdSnapshot
-
-Packed typed-array payload for playback bird snapshot transport.
-
-This mirrors the pipe packing strategy so playback can move large population
-snapshots with less allocation pressure than object-per-bird messages.
-
 ### EvolutionGenerationPayload
 
 Worker payload describing evolved generation summary values.
@@ -474,9 +441,13 @@ network for visualization or playback.
 
 Worker message emitted when a generation has completed evolving.
 
-### EvolutionWorkerErrorMessage
+### EvolutionPlaybackStepMessage
 
-Worker message emitted for simulation/playback errors.
+Worker message carrying one playback step and aggregate markers.
+
+Besides the frame snapshot itself, this message also carries summary values
+used by the HUD so the browser can show performance and progress without
+recomputing population-wide statistics on the main thread.
 
 ### EvolutionPlaybackStepSnapshot
 
@@ -486,13 +457,9 @@ A snapshot combines geometry, packed population state, and lightweight world
 metadata so the browser can render a deterministic frame without rerunning
 the simulation locally.
 
-### EvolutionPlaybackStepMessage
-
-Worker message carrying one playback step and aggregate markers.
+### EvolutionWorkerErrorMessage
 
-Besides the frame snapshot itself, this message also carries summary values
-used by the HUD so the browser can show performance and progress without
-recomputing population-wide statistics on the main thread.
+Worker message emitted for simulation/playback errors.
 
 ### EvolutionWorkerMessage
 
@@ -501,6 +468,20 @@ Union of all supported worker messages consumed by browser entry.
 A closed union keeps the main-thread message handler explicit and easy to
 audit when the protocol evolves.
 
+### PackedPlaybackBirdSnapshot
+
+Packed typed-array payload for playback bird snapshot transport.
+
+This mirrors the pipe packing strategy so playback can move large population
+snapshots with less allocation pressure than object-per-bird messages.
+
+### PackedPlaybackPipeSnapshot
+
+Packed typed-array payload for playback pipe snapshot transport.
+
+Typed arrays keep frame payloads compact and predictable, which matters when
+the worker is streaming many birds and pipes across animation frames.
+
 ### PlaybackFrameStats
 
 Lightweight per-frame telemetry emitted to HUD update callback.
@@ -509,6 +490,25 @@ These values are the browser-friendly metrics shown in the live status panel:
 how many birds remain, how far the leader has progressed, and how expensive
 the current playback cadence is.
 
+### PopulationBird
+
+Renderable bird state snapshot emitted by the playback worker.
+
+The browser does not receive full neural state here. It only gets the fields
+needed for presentation and HUD summaries, which keeps per-frame transport
+light.
+
+### PopulationPipe
+
+Renderable pipe state snapshot emitted by the playback worker.
+
+This is the smallest pipe shape the browser renderer needs for one frame:
+horizontal position plus the vertical corridor geometry.
+
+### SerializedNetwork
+
+Loose JSON-compatible network payload used by worker messages.
+
 ## browser-entry/browser-entry.runtime.types.ts
 
 Public lifecycle contracts for the Flappy Bird browser runtime.
@@ -537,6 +537,13 @@ Simulation-facing browser contracts shared by playback helpers.
 These types describe the minimum world state the browser needs while it is
 reconstructing, rendering, or summarizing worker-produced frames.
 
+### BrowserDifficultyProfile
+
+Difficulty profile consumed by simulation observation helpers.
+
+This bundles the three variables that define how demanding a stretch of the
+course is: corridor width, pipe speed, and spawn cadence.
+
 ### BrowserPopulationBirdLike
 
 Bird shape used by utility winner/leader resolver helpers.
@@ -545,13 +552,6 @@ Bird shape used by utility winner/leader resolver helpers.
 
 Pipe shape used by utility observation-vector helpers.
 
-### BrowserDifficultyProfile
-
-Difficulty profile consumed by simulation observation helpers.
-
-This bundles the three variables that define how demanding a stretch of the
-course is: corridor width, pipe speed, and spawn cadence.
-
 ### PopulationRenderState
 
 Mutable render-state model consumed by the population frame renderer.
@@ -560,6 +560,13 @@ The playback layer incrementally updates this state as worker snapshots
 arrive, which lets rendering stay deterministic without re-deriving world
 history from scratch each frame.
 
+### RngLike
+
+Minimal random source contract used by utility random helpers.
+
+The narrow contract keeps deterministic spawn utilities portable across
+browser and test contexts.
+
 ### TrailPoint
 
 Trail point used by playback trail rendering cache.
@@ -574,13 +581,6 @@ Mutable trail cache keyed by bird index for frame rendering.
 This cache exists purely for visualization ergonomics; it is not part of the
 worker simulation state.
 
-### RngLike
-
-Minimal random source contract used by utility random helpers.
-
-The narrow contract keeps deterministic spawn utilities portable across
-browser and test contexts.
-
 ## browser-entry/browser-entry.visualization.types.ts
 
 Network-visualization contracts for the Flappy Bird browser demo.
@@ -590,9 +590,11 @@ controllers as structures, not just as scores. These types describe the
 lightweight shapes used by the architecture panel so rendering logic can stay
 decoupled from the full internal network implementation.
 
-### NetworkVisualizationHandle
+### ColorLegendRow
 
-Draw callback contract for network architecture panel updates.
+Legend row model for network visualization color legends.
+
+Each row labels a numeric interval and the color used to render it.
 
 ### ColorTier
 
@@ -601,12 +603,6 @@ Connection or bias tier used for color mapping ramps.
 Visualization buckets continuous weights into legible color bands so humans
 can scan sign and magnitude at a glance.
 
-### ColorLegendRow
-
-Legend row model for network visualization color legends.
-
-Each row labels a numeric interval and the color used to render it.
-
 ### NetworkLegendLayout
 
 Precomputed legend panel layout used by visualization renderer.
@@ -614,19 +610,16 @@ Precomputed legend panel layout used by visualization renderer.
 Layout is resolved up front so the draw path can stay focused on painting,
 not recomputing geometry every frame.
 
-### VisualNetworkConnectionLike
-
-Lightweight connection shape used by network visualization drawing.
+### NetworkNodeDimensionsLike
 
-The renderer only needs connectivity, weight, and enabled state, not the full
-training-time behavior of a connection object.
+Pixel dimensions used for network-node rectangle rendering.
 
-### VisualNetworkNodeLike
+Keeping node box dimensions explicit makes legend and topology layout easier
+to tune without hidden drawing constants.
 
-Lightweight node shape used by network visualization drawing.
+### NetworkVisualizationHandle
 
-This shape keeps the renderer independent from the concrete Network class
-while still exposing the semantic fields that matter visually.
+Draw callback contract for network architecture panel updates.
 
 ### PositionedNetworkNodeLike
 
@@ -635,12 +628,19 @@ Positioned node instance used by network visualization drawing.
 Layout and rendering are split: first a node is assigned screen coordinates,
 then the renderer paints it.
 
-### NetworkNodeDimensionsLike
+### VisualNetworkConnectionLike
 
-Pixel dimensions used for network-node rectangle rendering.
+Lightweight connection shape used by network visualization drawing.
 
-Keeping node box dimensions explicit makes legend and topology layout easier
-to tune without hidden drawing constants.
+The renderer only needs connectivity, weight, and enabled state, not the full
+training-time behavior of a connection object.
+
+### VisualNetworkNodeLike
+
+Lightweight node shape used by network visualization drawing.
+
+This shape keeps the renderer independent from the concrete Network class
+while still exposing the semantic fields that matter visually.
 
 ## browser-entry/browser-entry.host.utils.ts
 
@@ -685,6 +685,23 @@ Returns: Nothing.
 
 ## browser-entry/browser-entry.math.utils.ts
 
+### applyAlphaToHexColor
+
+```ts
+applyAlphaToHexColor(
+  hexColor: string,
+  alphaValue: number,
+): string
+```
+
+Converts a six-digit hex color to rgba with the requested alpha.
+
+Parameters:
+- `hexColor` - - Color in `#RRGGBB` form.
+- `alphaValue` - - Alpha value to apply.
+
+Returns: rgba color string, or original value when not 6-digit hex.
+
 ### clamp
 
 ```ts
@@ -738,41 +755,44 @@ Parameters:
 
 Returns: Interpolated value.
 
-### applyAlphaToHexColor
+## browser-entry/browser-entry.spawn.utils.ts
+
+### createBirdColor
 
 ```ts
-applyAlphaToHexColor(
-  hexColor: string,
-  alphaValue: number,
+createBirdColor(
+  birdIndex: number,
+  totalBirds: number,
 ): string
 ```
 
-Converts a six-digit hex color to rgba with the requested alpha.
+Resolves deterministic bird color from palette index.
 
 Parameters:
-- `hexColor` - - Color in `#RRGGBB` form.
-- `alphaValue` - - Alpha value to apply.
-
-Returns: rgba color string, or original value when not 6-digit hex.
+- `birdIndex` - - Bird index in current population.
+- `totalBirds` - - Population size.
 
-## browser-entry/browser-entry.spawn.utils.ts
+Returns: Hex color string.
 
-### sampleGapCenterY
+### resolveGapCenterUpperBoundYPx
 
 ```ts
-sampleGapCenterY(
-  rng: RngLike,
+resolveGapCenterUpperBoundYPx(
   worldHeightPx: number,
 ): number
 ```
 
-Samples a random gap center y-position.
+Resolves the exclusive upper bound used for gap-center sampling.
+
+Educational note:
+We cap dynamic viewport-derived bounds at the shared simulation maximum to
+keep browser playback distribution aligned with trainer/evaluation defaults,
+while still supporting smaller world heights.
 
 Parameters:
-- `rng` - - Deterministic RNG.
-- `worldHeightPx` - - World height used to derive valid gap-center bounds.
+- `worldHeightPx` - - Current world height.
 
-Returns: Sampled y-position.
+Returns: Exclusive upper bound for `nextInt(minInclusive, maxExclusive)`.
 
 ### resolveNextSpawnGapCenterY
 
@@ -793,23 +813,6 @@ Parameters:
 
 Returns: Next gap center y-position.
 
-### createBirdColor
-
-```ts
-createBirdColor(
-  birdIndex: number,
-  totalBirds: number,
-): string
-```
-
-Resolves deterministic bird color from palette index.
-
-Parameters:
-- `birdIndex` - - Bird index in current population.
-- `totalBirds` - - Population size.
-
-Returns: Hex color string.
-
 ### resolveNextSpawnGapSize
 
 ```ts
@@ -846,25 +849,22 @@ Parameters:
 
 Returns: Next spawn interval in frames.
 
-### resolveGapCenterUpperBoundYPx
+### sampleGapCenterY
 
 ```ts
-resolveGapCenterUpperBoundYPx(
+sampleGapCenterY(
+  rng: RngLike,
   worldHeightPx: number,
 ): number
 ```
 
-Resolves the exclusive upper bound used for gap-center sampling.
-
-Educational note:
-We cap dynamic viewport-derived bounds at the shared simulation maximum to
-keep browser playback distribution aligned with trainer/evaluation defaults,
-while still supporting smaller world heights.
+Samples a random gap center y-position.
 
 Parameters:
-- `worldHeightPx` - - Current world height.
+- `rng` - - Deterministic RNG.
+- `worldHeightPx` - - World height used to derive valid gap-center bounds.
 
-Returns: Exclusive upper bound for `nextInt(minInclusive, maxExclusive)`.
+Returns: Sampled y-position.
 
 ## browser-entry/browser-entry.stats.utils.ts
 
@@ -934,164 +934,158 @@ Returns: Aggregate playback summary for the current episode.
 
 ## browser-entry/browser-entry.viewport.utils.ts
 
-### resolveWorldViewport
+### resolvePipeSpawnXPx
 
 ```ts
-resolveWorldViewport(
-  canvas: HTMLCanvasElement,
-): ViewportInfo
+resolvePipeSpawnXPx(
+  visibleWorldWidthPx: number,
+): number
 ```
 
-Resolves world viewport transformation based on canvas size.
+Resolves the world-space x spawn position for new pipes.
 
 Parameters:
-- `canvas` - - Playback canvas.
+- `visibleWorldWidthPx` - - Current visible world width.
 
-Returns: Viewport scale and offsets.
+Returns: Spawn x-position.
 
-### resolveVisibleWorldWidthPx
+### resolveVisibleWorldHeightPx
 
 ```ts
-resolveVisibleWorldWidthPx(
+resolveVisibleWorldHeightPx(
   canvas: HTMLCanvasElement,
 ): number
 ```
 
-Resolves visible world width represented by the current canvas.
+Resolves visible world height represented by the current canvas.
 
 Educational note:
 The current viewport model uses a 1:1 mapping between canvas pixels and
-world-space pixels, so visible width is the canvas width directly.
+world-space pixels, so visible height is the canvas height directly.
 
 Parameters:
 - `canvas` - - Playback canvas.
 
-Returns: Visible width in world-space pixels.
+Returns: Visible height in world-space pixels.
 
-### resolveVisibleWorldHeightPx
+### resolveVisibleWorldWidthPx
 
 ```ts
-resolveVisibleWorldHeightPx(
+resolveVisibleWorldWidthPx(
   canvas: HTMLCanvasElement,
 ): number
 ```
 
-Resolves visible world height represented by the current canvas.
+Resolves visible world width represented by the current canvas.
 
 Educational note:
 The current viewport model uses a 1:1 mapping between canvas pixels and
-world-space pixels, so visible height is the canvas height directly.
+world-space pixels, so visible width is the canvas width directly.
 
 Parameters:
 - `canvas` - - Playback canvas.
 
-Returns: Visible height in world-space pixels.
+Returns: Visible width in world-space pixels.
 
-### resolvePipeSpawnXPx
+### resolveWorldViewport
 
 ```ts
-resolvePipeSpawnXPx(
-  visibleWorldWidthPx: number,
-): number
+resolveWorldViewport(
+  canvas: HTMLCanvasElement,
+): ViewportInfo
 ```
 
-Resolves the world-space x spawn position for new pipes.
+Resolves world viewport transformation based on canvas size.
 
 Parameters:
-- `visibleWorldWidthPx` - - Current visible world width.
+- `canvas` - - Playback canvas.
 
-Returns: Spawn x-position.
+Returns: Viewport scale and offsets.
 
 ## browser-entry/browser-entry.telemetry.utils.ts
 
-### trimSamplesToWindow
+### createMinorGcObserver
 
 ```ts
-trimSamplesToWindow(
-  samples: number[],
-  windowMs: number,
-  nowMs: number,
-): void
+createMinorGcObserver(
+  minorGcTimestampsMs: number[],
+): PerformanceObserver | undefined
 ```
 
-Trims timestamp samples to a sliding time window.
+Creates a PerformanceObserver that tracks minor GC events when supported.
 
 Parameters:
-- `samples` - - Mutable timestamp buffer.
-- `windowMs` - - Window width in milliseconds.
-- `nowMs` - - Current timestamp.
+- `minorGcTimestampsMs` - - Mutable minor-GC timestamp buffer.
 
-Returns: Nothing.
+Returns: Observer when supported; otherwise `undefined`.
 
-### resolveHudUpdatesPerSecond
+### resolveEventsPerMinute
 
 ```ts
-resolveHudUpdatesPerSecond(
+resolveEventsPerMinute(
   samples: number[],
 ): number
 ```
 
-Resolves HUD updates per second from the latest sample window.
+Resolves events per minute from the latest sample window.
 
 Parameters:
-- `samples` - - HUD update timestamps.
+- `samples` - - Event timestamps.
 
-Returns: Updates-per-second estimate.
+Returns: Events-per-minute estimate.
 
-### resolveEventsPerMinute
+### resolveHudUpdatesPerSecond
 
 ```ts
-resolveEventsPerMinute(
+resolveHudUpdatesPerSecond(
   samples: number[],
 ): number
 ```
 
-Resolves events per minute from the latest sample window.
+Resolves HUD updates per second from the latest sample window.
 
 Parameters:
-- `samples` - - Event timestamps.
+- `samples` - - HUD update timestamps.
 
-Returns: Events-per-minute estimate.
+Returns: Updates-per-second estimate.
 
-### createMinorGcObserver
+### trimSamplesToWindow
 
 ```ts
-createMinorGcObserver(
-  minorGcTimestampsMs: number[],
-): PerformanceObserver | undefined
+trimSamplesToWindow(
+  samples: number[],
+  windowMs: number,
+  nowMs: number,
+): void
 ```
 
-Creates a PerformanceObserver that tracks minor GC events when supported.
+Trims timestamp samples to a sliding time window.
 
 Parameters:
-- `minorGcTimestampsMs` - - Mutable minor-GC timestamp buffer.
+- `samples` - - Mutable timestamp buffer.
+- `windowMs` - - Window width in milliseconds.
+- `nowMs` - - Current timestamp.
 
-Returns: Observer when supported; otherwise `undefined`.
+Returns: Nothing.
 
 ## browser-entry/browser-entry.text-frame.utils.ts
 
-### resolveTextFrameMetrics
+### buildCenteredTitleBoxLines
 
 ```ts
-resolveTextFrameMetrics(
-  frameWidthPx: number,
-  frameHeightPx: number,
-  glyphWidthPx: number,
-  rowHeightPx: number,
-  minimumColumns: number,
-): TextFrameMetrics
+buildCenteredTitleBoxLines(
+  centeredColumns: number,
+  titleText: string,
+): string[]
 ```
 
-Resolves core text-frame metrics for glyph box rendering.
+Builds an ASCII centered title box.
 
 Parameters:
-- `frameWidthPx` - - Frame width.
-- `frameHeightPx` - - Frame height.
-- `glyphWidthPx` - - Measured glyph width.
-- `rowHeightPx` - - Glyph row height.
-- `minimumColumns` - - Minimum column count.
+- `centeredColumns` - - Available centered column count.
+- `titleText` - - Title text.
 
-Returns: Text frame metrics.
+Returns: Three-row title box.
 
 ### buildOuterBoxLines
 
@@ -1110,22 +1104,20 @@ Parameters:
 
 Returns: Frame lines.
 
-### buildCenteredTitleBoxLines
+### renderClosedOuterBox
 
 ```ts
-buildCenteredTitleBoxLines(
-  centeredColumns: number,
-  titleText: string,
-): string[]
+renderClosedOuterBox(
+  input: RenderClosedOuterBoxInput,
+): void
 ```
 
-Builds an ASCII centered title box.
+Renders a complete closed outer glyph box.
 
 Parameters:
-- `centeredColumns` - - Available centered column count.
-- `titleText` - - Title text.
+- `input` - - Rendering input object.
 
-Returns: Three-row title box.
+Returns: Nothing.
 
 ### renderStandaloneTitleBox
 
@@ -1142,21 +1134,6 @@ Parameters:
 
 Returns: Nothing.
 
-### renderClosedOuterBox
-
-```ts
-renderClosedOuterBox(
-  input: RenderClosedOuterBoxInput,
-): void
-```
-
-Renders a complete closed outer glyph box.
-
-Parameters:
-- `input` - - Rendering input object.
-
-Returns: Nothing.
-
 ### resolveGlyphWidthPx
 
 ```ts
@@ -1172,36 +1149,30 @@ Parameters:
 
 Returns: Floored glyph width clamped to a minimum pixel value.
 
-## browser-entry/browser-entry.observation.utils.ts
-
-### resolveObservationVector
+### resolveTextFrameMetrics
 
 ```ts
-resolveObservationVector(
-  birdYPx: number,
-  velocityYPxPerFrame: number,
-  pipes: BrowserPopulationPipeLike[],
-  visibleWorldWidthPx: number,
-  worldHeightPx: number,
-  difficultyProfile: BrowserDifficultyProfile,
-  activeSpawnIntervalFrames: number,
-  observationMemoryState: SharedObservationMemoryState,
-): { observationVector: number[]; observationFeatures: SharedObservationFeatures; }
+resolveTextFrameMetrics(
+  frameWidthPx: number,
+  frameHeightPx: number,
+  glyphWidthPx: number,
+  rowHeightPx: number,
+  minimumColumns: number,
+): TextFrameMetrics
 ```
 
-Builds the normalized observation vector consumed by bird networks.
+Resolves core text-frame metrics for glyph box rendering.
 
 Parameters:
-- `birdYPx` - - Bird y position.
-- `velocityYPxPerFrame` - - Bird vertical velocity.
-- `pipes` - - Current pipe list.
-- `visibleWorldWidthPx` - - Current visible world width.
-- `worldHeightPx` - - Current world height used for normalization and bounds.
-- `difficultyProfile` - - Active difficulty profile.
-- `activeSpawnIntervalFrames` - - Current spawn interval.
-- `observationMemoryState` - - Temporal memory state for recurrent observation features.
+- `frameWidthPx` - - Frame width.
+- `frameHeightPx` - - Frame height.
+- `glyphWidthPx` - - Measured glyph width.
+- `rowHeightPx` - - Glyph row height.
+- `minimumColumns` - - Minimum column count.
 
-Returns: Ordered normalized observation vector.
+Returns: Text frame metrics.
+
+## browser-entry/browser-entry.observation.utils.ts
 
 ### commitObservationMemoryStep
 
@@ -1222,20 +1193,35 @@ Parameters:
 
 Returns: Nothing.
 
-### resolveUpcomingPipes
+### hasAliveBirds
 
 ```ts
-resolveUpcomingPipes(
-  pipes: BrowserPopulationPipeLike[],
-): [BrowserPopulationPipeLike | undefined, BrowserPopulationPipeLike | undefined]
+hasAliveBirds(
+  birds: BrowserPopulationBirdLike[],
+): boolean
+```
+
+Checks whether at least one bird remains alive.
+
+Parameters:
+- `birds` - - Population birds.
+
+Returns: True when any bird is alive.
+
+### resolveAliveBirdCount
+
+```ts
+resolveAliveBirdCount(
+  birds: BrowserPopulationBirdLike[],
+): number
 ```
 
-Resolves the next two upcoming pipes in front of the bird.
+Counts birds that are still alive.
 
 Parameters:
-- `pipes` - - Current pipe list.
+- `birds` - - Population birds.
 
-Returns: Tuple of first and second upcoming pipes.
+Returns: Alive bird count.
 
 ### resolveFlapDecision
 
@@ -1252,20 +1238,22 @@ Parameters:
 
 Returns: True when flap should trigger.
 
-### resolveAliveBirdCount
+### resolveFramePrimaryWinnerIndex
 
 ```ts
-resolveAliveBirdCount(
+resolveFramePrimaryWinnerIndex(
   birds: BrowserPopulationBirdLike[],
+  includeAliveOnly: boolean,
 ): number
 ```
 
-Counts birds that are still alive.
+Resolves winner index for current frame.
 
 Parameters:
 - `birds` - - Population birds.
+- `includeAliveOnly` - - When true, ignores dead birds.
 
-Returns: Alive bird count.
+Returns: Winner index, or `-1` when unavailable.
 
 ### resolveLeaderPipesPassed
 
@@ -1282,37 +1270,49 @@ Parameters:
 
 Returns: Maximum pipes passed.
 
-### resolveFramePrimaryWinnerIndex
+### resolveObservationVector
 
 ```ts
-resolveFramePrimaryWinnerIndex(
-  birds: BrowserPopulationBirdLike[],
-  includeAliveOnly: boolean,
-): number
+resolveObservationVector(
+  birdYPx: number,
+  velocityYPxPerFrame: number,
+  pipes: BrowserPopulationPipeLike[],
+  visibleWorldWidthPx: number,
+  worldHeightPx: number,
+  difficultyProfile: BrowserDifficultyProfile,
+  activeSpawnIntervalFrames: number,
+  observationMemoryState: SharedObservationMemoryState,
+): { observationVector: number[]; observationFeatures: SharedObservationFeatures; }
 ```
 
-Resolves winner index for current frame.
+Builds the normalized observation vector consumed by bird networks.
 
 Parameters:
-- `birds` - - Population birds.
-- `includeAliveOnly` - - When true, ignores dead birds.
+- `birdYPx` - - Bird y position.
+- `velocityYPxPerFrame` - - Bird vertical velocity.
+- `pipes` - - Current pipe list.
+- `visibleWorldWidthPx` - - Current visible world width.
+- `worldHeightPx` - - Current world height used for normalization and bounds.
+- `difficultyProfile` - - Active difficulty profile.
+- `activeSpawnIntervalFrames` - - Current spawn interval.
+- `observationMemoryState` - - Temporal memory state for recurrent observation features.
 
-Returns: Winner index, or `-1` when unavailable.
+Returns: Ordered normalized observation vector.
 
-### hasAliveBirds
+### resolveUpcomingPipes
 
 ```ts
-hasAliveBirds(
-  birds: BrowserPopulationBirdLike[],
-): boolean
+resolveUpcomingPipes(
+  pipes: BrowserPopulationPipeLike[],
+): [BrowserPopulationPipeLike | undefined, BrowserPopulationPipeLike | undefined]
 ```
 
-Checks whether at least one bird remains alive.
+Resolves the next two upcoming pipes in front of the bird.
 
 Parameters:
-- `birds` - - Population birds.
+- `pipes` - - Current pipe list.
 
-Returns: True when any bird is alive.
+Returns: Tuple of first and second upcoming pipes.
 
 ## browser-entry/browser-entry.network-view.utils.ts
 
@@ -1436,6 +1436,26 @@ Compatibility facade for browser-entry network visualization helpers.
 Legacy imports still flow through this file while the visualization subsystem
 is organized into smaller, clearer modules under the dedicated folder.
 
+### createColorLegendRows
+
+```ts
+createColorLegendRows(
+  scale: DynamicColorScale,
+  symbol: "w" | "b",
+): ColorLegendRow[]
+```
+
+Creates legend rows from ordered tiers.
+
+Each row describes one closed numeric interval and the swatch used to paint
+it, making the dynamic color scale legible to a human reader.
+
+Parameters:
+- `scale` - - Dynamic color scale containing bounds, tiers, and overflow color.
+- `symbol` - - Label symbol.
+
+Returns: Legend rows.
+
 ### createLogDivergingColorTiers
 
 ```ts
@@ -1455,83 +1475,6 @@ Parameters:
 
 Returns: Ordered tier list.
 
-### resolveBiasRangeColor
-
-```ts
-resolveBiasRangeColor(
-  nodeBias: number,
-): string
-```
-
-Resolves bias color for a raw node bias.
-
-Bias colors follow the same diverging logic as connection colors so the legend
-remains conceptually consistent across channels.
-
-Parameters:
-- `nodeBias` - - Node bias.
-
-Returns: Tier color.
-
-### resolveConnectionRangeColor
-
-```ts
-resolveConnectionRangeColor(
-  connectionWeight: number,
-): string
-```
-
-Resolves connection color for a raw weight.
-
-This small helper is useful when one-off drawing code wants the same color
-semantics as the full dynamic scale machinery.
-
-Parameters:
-- `connectionWeight` - - Connection weight.
-
-Returns: Tier color.
-
-### resolveNetworkVisualizationColorScales
-
-```ts
-resolveNetworkVisualizationColorScales(
-  network: default | undefined,
-): NetworkVisualizationColorScales
-```
-
-Resolves dynamic connection/bias color scales from the active network range.
-
-The active network may contain only a narrow slice of the full theoretical
-value range, so the legend adapts to what is currently present instead of
-always rendering a fixed generic scale.
-
-Parameters:
-- `network` - - Active network.
-
-Returns: Dynamic scales used by graph drawing and legend rows.
-
-### resolveTierColor
-
-```ts
-resolveTierColor(
-  value: number,
-  tiers: ColorTier[],
-  aboveTierColor: string,
-): string
-```
-
-Resolves a color from ordered tier definitions.
-
-This is the final classification step that maps one numeric weight or bias to
-the swatch color the renderer should paint.
-
-Parameters:
-- `value` - - Numeric value to classify.
-- `tiers` - - Ordered tier list.
-- `aboveTierColor` - - Fallback color for values above the last tier.
-
-Returns: Resolved color string.
-
 ### drawBiasNodesLayer
 
 ```ts
@@ -1624,25 +1567,59 @@ Parameters:
 
 Returns: Nothing.
 
-### createColorLegendRows
+### formatNodeBiasLabel
 
 ```ts
-createColorLegendRows(
-  scale: DynamicColorScale,
-  symbol: "w" | "b",
-): ColorLegendRow[]
+formatNodeBiasLabel(
+  nodeBias: number,
+): string
 ```
 
-Creates legend rows from ordered tiers.
+Formats node bias labels with fixed sign and precision.
 
-Each row describes one closed numeric interval and the swatch used to paint
-it, making the dynamic color scale legible to a human reader.
+Consistent sign and precision make dense node labels easier to scan quickly in
+the rendered network panel.
 
 Parameters:
-- `scale` - - Dynamic color scale containing bounds, tiers, and overflow color.
-- `symbol` - - Label symbol.
+- `nodeBias` - - Node bias value.
 
-Returns: Legend rows.
+Returns: Label text.
+
+### resolveBiasRangeColor
+
+```ts
+resolveBiasRangeColor(
+  nodeBias: number,
+): string
+```
+
+Resolves bias color for a raw node bias.
+
+Bias colors follow the same diverging logic as connection colors so the legend
+remains conceptually consistent across channels.
+
+Parameters:
+- `nodeBias` - - Node bias.
+
+Returns: Tier color.
+
+### resolveConnectionRangeColor
+
+```ts
+resolveConnectionRangeColor(
+  connectionWeight: number,
+): string
+```
+
+Resolves connection color for a raw weight.
+
+This small helper is useful when one-off drawing code wants the same color
+semantics as the full dynamic scale machinery.
+
+Parameters:
+- `connectionWeight` - - Connection weight.
+
+Returns: Tier color.
 
 ### resolveDefaultNetworkLegendLayout
 
@@ -1688,23 +1665,24 @@ Parameters:
 
 Returns: Computed legend layout.
 
-### formatNodeBiasLabel
+### resolveNetworkVisualizationColorScales
 
 ```ts
-formatNodeBiasLabel(
-  nodeBias: number,
-): string
+resolveNetworkVisualizationColorScales(
+  network: default | undefined,
+): NetworkVisualizationColorScales
 ```
 
-Formats node bias labels with fixed sign and precision.
+Resolves dynamic connection/bias color scales from the active network range.
 
-Consistent sign and precision make dense node labels easier to scan quickly in
-the rendered network panel.
+The active network may contain only a narrow slice of the full theoretical
+value range, so the legend adapts to what is currently present instead of
+always rendering a fixed generic scale.
 
 Parameters:
-- `nodeBias` - - Node bias value.
+- `network` - - Active network.
 
-Returns: Label text.
+Returns: Dynamic scales used by graph drawing and legend rows.
 
 ### resolveNetworkVisualizationLayers
 
@@ -1734,6 +1712,28 @@ Parameters:
 
 Returns: Layered nodes for rendering.
 
+### resolveTierColor
+
+```ts
+resolveTierColor(
+  value: number,
+  tiers: ColorTier[],
+  aboveTierColor: string,
+): string
+```
+
+Resolves a color from ordered tier definitions.
+
+This is the final classification step that maps one numeric weight or bias to
+the swatch color the renderer should paint.
+
+Parameters:
+- `value` - - Numeric value to classify.
+- `tiers` - - Ordered tier list.
+- `aboveTierColor` - - Fallback color for values above the last tier.
+
+Returns: Resolved color string.
+
 ## browser-entry/browser-entry.worker-channel.utils.ts
 
 ### createEvolutionWorker