@reicek/neataptic-ts 0.1.24 → 0.1.26

package/test/examples/flappy_bird/browser-entry/playback/frame-render/README.md

@@ -80,13 +80,6 @@ boundary.
 Together they describe the inputs and intermediate state needed to paint one
 world-space frame on the browser canvas.
 
-### PlaybackFrameSceneContext
-
-Shared scene contract used by one playback frame render pass.
-
-This collects the camera, viewport, and champion metadata that multiple frame
-render helpers need during the same paint pass.
-
 ### PlaybackBirdGeometry
 
 Pixel-aligned square geometry used by bird paint helpers.
@@ -94,12 +87,12 @@ Pixel-aligned square geometry used by bird paint helpers.
 Bird geometry is resolved once so the detailed bird renderer can reuse a
 stable square body box across glow and fill passes.
 
-### PlaybackTrailRenderStyle
+### PlaybackBirdPaintInput
 
-Resolved opacity and color for one bird trail render pass.
+Bird-paint input shared by the bird render helper module.
 
-Trails use a lighter-weight style record than birds because they only need a
-base opacity plus stroke color.
+This combines geometry and style into one small input object for lower-level
+drawing helpers.
 
 ### PlaybackBirdRenderer
 
@@ -117,19 +110,12 @@ Bird body renderer contract used by frame-render orchestration helpers.
 Keeping the renderer as an injected function makes the high-level frame pass
 independent from the detailed bird-paint implementation.
 
-### PlaybackTrailStyleResolver
-
-```ts
-PlaybackTrailStyleResolver(
-  birdIndex: number,
-  championBirdIndex: number,
-): PlaybackTrailRenderStyle
-```
+### PlaybackFrameSceneContext
 
-Trail style resolver used by frame-render orchestration helpers.
+Shared scene contract used by one playback frame render pass.
 
-This lets orchestration ask for champion-vs-non-champion trail styling
-without embedding color policy directly in the frame pass.
+This collects the camera, viewport, and champion metadata that multiple frame
+render helpers need during the same paint pass.
 
 ### PlaybackTrailRenderer
 
@@ -149,12 +135,26 @@ Trail segment renderer used by frame-render orchestration helpers.
 The detailed trail painter owns edge fading and stepped segments; the frame
 orchestration only decides when to call it.
 
-### PlaybackBirdPaintInput
+### PlaybackTrailRenderStyle
 
-Bird-paint input shared by the bird render helper module.
+Resolved opacity and color for one bird trail render pass.
 
-This combines geometry and style into one small input object for lower-level
-drawing helpers.
+Trails use a lighter-weight style record than birds because they only need a
+base opacity plus stroke color.
+
+### PlaybackTrailStyleResolver
+
+```ts
+PlaybackTrailStyleResolver(
+  birdIndex: number,
+  championBirdIndex: number,
+): PlaybackTrailRenderStyle
+```
+
+Trail style resolver used by frame-render orchestration helpers.
+
+This lets orchestration ask for champion-vs-non-champion trail styling
+without embedding color policy directly in the frame pass.
 
 ## browser-entry/playback/frame-render/playback.frame-render.services.ts
 
@@ -366,56 +366,56 @@ Canvas-state helpers for playback frame rendering.
 These functions isolate the mutable canvas setup and teardown needed for one
 frame so the orchestration layer can read as declarative world rendering.
 
-### preparePlaybackFrameCanvas
+### beginPlaybackFrameViewportTransform
 
 ```ts
-preparePlaybackFrameCanvas(
+beginPlaybackFrameViewportTransform(
   context: CanvasRenderingContext2D,
+  sceneContext: PlaybackFrameSceneContext,
 ): void
 ```
 
-Resets the target canvas and base paint state before frame drawing begins.
+Applies the viewport transform used for world-space frame rendering.
 
-This establishes a predictable baseline before world-space transforms and glow
-effects are applied.
+After this transform, draw calls can work in simulation coordinates instead of
+raw canvas pixel coordinates.
 
 Parameters:
 - `context` - - Canvas 2D drawing context.
+- `sceneContext` - - Shared scene geometry for the frame.
 
 Returns: Nothing.
 
-### beginPlaybackFrameViewportTransform
+### finalizePlaybackFrameCanvas
 
 ```ts
-beginPlaybackFrameViewportTransform(
+finalizePlaybackFrameCanvas(
   context: CanvasRenderingContext2D,
-  sceneContext: PlaybackFrameSceneContext,
 ): void
 ```
 
-Applies the viewport transform used for world-space frame rendering.
+Restores the caller canvas state after viewport-space frame drawing.
 
-After this transform, draw calls can work in simulation coordinates instead of
-raw canvas pixel coordinates.
+This ensures later canvas users do not inherit playback-specific transform or
+alpha state.
 
 Parameters:
 - `context` - - Canvas 2D drawing context.
-- `sceneContext` - - Shared scene geometry for the frame.
 
 Returns: Nothing.
 
-### finalizePlaybackFrameCanvas
+### preparePlaybackFrameCanvas
 
 ```ts
-finalizePlaybackFrameCanvas(
+preparePlaybackFrameCanvas(
   context: CanvasRenderingContext2D,
 ): void
 ```
 
-Restores the caller canvas state after viewport-space frame drawing.
+Resets the target canvas and base paint state before frame drawing begins.
 
-This ensures later canvas users do not inherit playback-specific transform or
-alpha state.
+This establishes a predictable baseline before world-space transforms and glow
+effects are applied.
 
 Parameters:
 - `context` - - Canvas 2D drawing context.
@@ -451,49 +451,49 @@ Parameters:
 
 Returns: Nothing.
 
-### renderPlaybackFramePipes
+### renderPlaybackFrameBirds
 
 ```ts
-renderPlaybackFramePipes(
+renderPlaybackFrameBirds(
   context: CanvasRenderingContext2D,
   renderState: PopulationRenderState,
   sceneContext: PlaybackFrameSceneContext,
+  renderBird: PlaybackBirdRenderer,
 ): void
 ```
 
-Draws all visible pipe segments and their neon outlines for the frame.
+Draws all active birds for the current frame.
 
-Pipes are rendered as upper and lower segments connected to the projected
-floor profile used by the background grid.
+Only live birds are painted so the playback frame reflects the active
+population rather than leaving ghost bodies behind.
 
 Parameters:
 - `context` - - Canvas 2D drawing context.
 - `renderState` - - Mutable simulation state snapshot.
 - `sceneContext` - - Shared scene geometry for the frame.
+- `renderBird` - - Bird body renderer owned by the detailed utility layer.
 
 Returns: Nothing.
 
-### renderPlaybackFrameBirds
+### renderPlaybackFramePipes
 
 ```ts
-renderPlaybackFrameBirds(
+renderPlaybackFramePipes(
   context: CanvasRenderingContext2D,
   renderState: PopulationRenderState,
   sceneContext: PlaybackFrameSceneContext,
-  renderBird: PlaybackBirdRenderer,
 ): void
 ```
 
-Draws all active birds for the current frame.
+Draws all visible pipe segments and their neon outlines for the frame.
 
-Only live birds are painted so the playback frame reflects the active
-population rather than leaving ghost bodies behind.
+Pipes are rendered as upper and lower segments connected to the projected
+floor profile used by the background grid.
 
 Parameters:
 - `context` - - Canvas 2D drawing context.
 - `renderState` - - Mutable simulation state snapshot.
 - `sceneContext` - - Shared scene geometry for the frame.
-- `renderBird` - - Bird body renderer owned by the detailed utility layer.
 
 Returns: Nothing.
 
@@ -571,6 +571,34 @@ Parameters:
 
 Returns: Nothing.
 
+### drawTrail
+
+```ts
+drawTrail(
+  context: CanvasRenderingContext2D,
+  trailPoints: TrailPoint[],
+  color: string,
+  anchorX: number,
+  baseOpacity: number,
+  edgeBounds: PlaybackEdgeBounds,
+): void
+```
+
+Draws the stepped trail history for one active bird.
+
+The stepped shape makes the trajectory feel more schematic and readable than a
+perfectly smooth spline, which fits the overall instrument-panel aesthetic.
+
+Parameters:
+- `context` - - Canvas 2D drawing context.
+- `trailPoints` - - Cached per-frame trail points for one bird.
+- `color` - - Stroke color for the trail.
+- `anchorX` - - Bird anchor x-position in world space.
+- `baseOpacity` - - Base opacity before edge and lifetime fading.
+- `edgeBounds` - - Visible world bounds used for edge fading.
+
+Returns: Nothing.
+
 ### renderPlaybackBird
 
 ```ts
@@ -631,34 +659,6 @@ Parameters:
 
 Returns: Pixel-aligned square geometry for the bird body.
 
-### drawTrail
-
-```ts
-drawTrail(
-  context: CanvasRenderingContext2D,
-  trailPoints: TrailPoint[],
-  color: string,
-  anchorX: number,
-  baseOpacity: number,
-  edgeBounds: PlaybackEdgeBounds,
-): void
-```
-
-Draws the stepped trail history for one active bird.
-
-The stepped shape makes the trajectory feel more schematic and readable than a
-perfectly smooth spline, which fits the overall instrument-panel aesthetic.
-
-Parameters:
-- `context` - - Canvas 2D drawing context.
-- `trailPoints` - - Cached per-frame trail points for one bird.
-- `color` - - Stroke color for the trail.
-- `anchorX` - - Bird anchor x-position in world space.
-- `baseOpacity` - - Base opacity before edge and lifetime fading.
-- `edgeBounds` - - Visible world bounds used for edge fading.
-
-Returns: Nothing.
-
 ### resolvePlaybackTrailStyle
 
 ```ts
@@ -687,48 +687,28 @@ The bird renderer keeps the body intentionally simple and geometric: a neon
 square with optional champion glow passes. That makes the population readable
 at a glance even when many birds overlap.
 
-### renderPlaybackBird
+### drawChampionPlaybackBirdGlow
 
 ```ts
-renderPlaybackBird(
+drawChampionPlaybackBirdGlow(
   context: CanvasRenderingContext2D,
-  birdYPx: number,
-  birdIndex: number,
-  championBirdIndex: number,
+  birdGeometry: PlaybackBirdGeometry,
+  birdRenderStyle: PlaybackBirdRenderStyle,
 ): void
 ```
 
-Draws one active bird body and champion-only highlight passes.
+Draws the champion bird using the same two-pass additive outline glow method as pipes.
 
-The champion receives an extra additive-outline treatment so viewers can spot
-the leading bird quickly during playback.
+Reusing the pipe-style glow language helps the whole playback scene feel like
+one visual system instead of unrelated rendering effects.
 
 Parameters:
 - `context` - - Canvas 2D drawing context.
-- `birdYPx` - - Bird vertical position in world pixels.
-- `birdIndex` - - Index of the bird being rendered.
-- `championBirdIndex` - - Champion index for the current frame.
+- `birdGeometry` - - Pixel-aligned bird geometry.
+- `birdRenderStyle` - - Resolved bird style payload.
 
 Returns: Nothing.
 
-### resolvePlaybackBirdGeometry
-
-```ts
-resolvePlaybackBirdGeometry(
-  birdYPx: number,
-): PlaybackBirdGeometry
-```
-
-Resolves the fixed bird geometry used by all body rendering passes.
-
-Geometry is snapped to integer pixels so the square body stays crisp instead
-of blurring across subpixel boundaries.
-
-Parameters:
-- `birdYPx` - - Bird vertical position in world pixels.
-
-Returns: Pixel-aligned square geometry for the bird body.
-
 ### drawPlaybackBirdBody
 
 ```ts
@@ -750,25 +730,27 @@ Parameters:
 
 Returns: Nothing.
 
-### drawChampionPlaybackBirdGlow
+### renderPlaybackBird
 
 ```ts
-drawChampionPlaybackBirdGlow(
+renderPlaybackBird(
   context: CanvasRenderingContext2D,
-  birdGeometry: PlaybackBirdGeometry,
-  birdRenderStyle: PlaybackBirdRenderStyle,
+  birdYPx: number,
+  birdIndex: number,
+  championBirdIndex: number,
 ): void
 ```
 
-Draws the champion bird using the same two-pass additive outline glow method as pipes.
+Draws one active bird body and champion-only highlight passes.
 
-Reusing the pipe-style glow language helps the whole playback scene feel like
-one visual system instead of unrelated rendering effects.
+The champion receives an extra additive-outline treatment so viewers can spot
+the leading bird quickly during playback.
 
 Parameters:
 - `context` - - Canvas 2D drawing context.
-- `birdGeometry` - - Pixel-aligned bird geometry.
-- `birdRenderStyle` - - Resolved bird style payload.
+- `birdYPx` - - Bird vertical position in world pixels.
+- `birdIndex` - - Index of the bird being rendered.
+- `championBirdIndex` - - Champion index for the current frame.
 
 Returns: Nothing.
 
@@ -790,32 +772,30 @@ Parameters:
 
 Returns: Blur radius used behind the square bird body.
 
-## browser-entry/playback/frame-render/playback.frame-render.trail.utils.ts
-
-Detailed trail-painting helpers for playback frames.
-
-Trails are rendered as stepped segments with both lifetime fading and edge
-fading so motion remains legible without overwhelming the scene.
-
-### resolvePlaybackTrailStyle
+### resolvePlaybackBirdGeometry
 
 ```ts
-resolvePlaybackTrailStyle(
-  birdIndex: number,
-  championBirdIndex: number,
-): PlaybackTrailRenderStyle
+resolvePlaybackBirdGeometry(
+  birdYPx: number,
+): PlaybackBirdGeometry
 ```
 
-Resolves the trail style used for one bird's stepped trail.
+Resolves the fixed bird geometry used by all body rendering passes.
 
-Champion trails are emphasized while non-champion trails, when present, are
-intentionally subdued.
+Geometry is snapped to integer pixels so the square body stays crisp instead
+of blurring across subpixel boundaries.
 
 Parameters:
-- `birdIndex` - - Index of the bird being rendered.
-- `championBirdIndex` - - Champion index for the current frame.
+- `birdYPx` - - Bird vertical position in world pixels.
 
-Returns: Base opacity and color for the bird trail.
+Returns: Pixel-aligned square geometry for the bird body.
+
+## browser-entry/playback/frame-render/playback.frame-render.trail.utils.ts
+
+Detailed trail-painting helpers for playback frames.
+
+Trails are rendered as stepped segments with both lifetime fading and edge
+fading so motion remains legible without overwhelming the scene.
 
 ### drawTrail
 
@@ -880,3 +860,23 @@ Parameters:
 - `maximumTrailFrameOffset` - - Oldest visible trail age.
 
 Returns: Nothing.
+
+### resolvePlaybackTrailStyle
+
+```ts
+resolvePlaybackTrailStyle(
+  birdIndex: number,
+  championBirdIndex: number,
+): PlaybackTrailRenderStyle
+```
+
+Resolves the trail style used for one bird's stepped trail.
+
+Champion trails are emphasized while non-champion trails, when present, are
+intentionally subdued.
+
+Parameters:
+- `birdIndex` - - Index of the bird being rendered.
+- `championBirdIndex` - - Champion index for the current frame.
+
+Returns: Base opacity and color for the bird trail.

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

@@ -47,19 +47,19 @@ Parameters:
 
 Returns: Nothing.
 
-### syncPlaybackSnapshotPipes
+### syncPlaybackSnapshotBirds
 
 ```ts
-syncPlaybackSnapshotPipes(
+syncPlaybackSnapshotBirds(
   renderState: PopulationRenderState,
   snapshot: EvolutionPlaybackStepSnapshot,
 ): void
 ```
 
-Synchronizes packed pipe snapshot fields into the reusable render-state pipe array.
+Synchronizes packed bird snapshot fields into the reusable render-state bird array.
 
-Instead of recreating pipe objects every frame, the browser grows the array as
-needed and then mutates the existing records in place.
+This mirrors the pipe strategy: keep a stable array shape when possible and
+update fields in place from the packed worker buffers.
 
 Parameters:
 - `renderState` - - Mutable render state mirror used by the browser.
@@ -67,19 +67,19 @@ Parameters:
 
 Returns: Nothing.
 
-### syncPlaybackSnapshotBirds
+### syncPlaybackSnapshotPipes
 
 ```ts
-syncPlaybackSnapshotBirds(
+syncPlaybackSnapshotPipes(
   renderState: PopulationRenderState,
   snapshot: EvolutionPlaybackStepSnapshot,
 ): void
 ```
 
-Synchronizes packed bird snapshot fields into the reusable render-state bird array.
+Synchronizes packed pipe snapshot fields into the reusable render-state pipe array.
 
-This mirrors the pipe strategy: keep a stable array shape when possible and
-update fields in place from the packed worker buffers.
+Instead of recreating pipe objects every frame, the browser grows the array as
+needed and then mutates the existing records in place.
 
 Parameters:
 - `renderState` - - Mutable render state mirror used by the browser.

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

@@ -14,6 +14,30 @@ pushTrailPoint(trailPoints, 11, 136, 2);
 
 ## browser-entry/playback/trail/playback.trail.history.services.ts
 
+### pushChampionTrailPoint
+
+```ts
+pushChampionTrailPoint(
+  trailPoints: TrailPoint[],
+  frameIndex: number,
+  yPosition: number,
+): void
+```
+
+Appends one point to the champion-only short trail history.
+
+The browser highlights the current leader with a shorter, denser trail than
+the rest of the flock. Using a dedicated helper keeps that policy explicit in
+the call site instead of scattering champion-specific retention numbers
+through the playback renderer.
+
+Parameters:
+- `trailPoints` - - Mutable champion trail collection.
+- `frameIndex` - - Source frame index.
+- `yPosition` - - Bird y position.
+
+Returns: Nothing.
+
 ### pushTrailPoint
 
 ```ts
@@ -47,30 +71,6 @@ const trailPoints = [{ frameIndex: 10, yPx: 140 }];
 pushTrailPoint(trailPoints, 11, 136, 2);
 ```
 
-### pushChampionTrailPoint
-
-```ts
-pushChampionTrailPoint(
-  trailPoints: TrailPoint[],
-  frameIndex: number,
-  yPosition: number,
-): void
-```
-
-Appends one point to the champion-only short trail history.
-
-The browser highlights the current leader with a shorter, denser trail than
-the rest of the flock. Using a dedicated helper keeps that policy explicit in
-the call site instead of scattering champion-specific retention numbers
-through the playback renderer.
-
-Parameters:
-- `trailPoints` - - Mutable champion trail collection.
-- `frameIndex` - - Source frame index.
-- `yPosition` - - Bird y position.
-
-Returns: Nothing.
-
 ## browser-entry/playback/trail/playback.trail.opacity.utils.ts
 
 Opacity helpers for playback trail fading.
@@ -86,6 +86,25 @@ const ageOpacity = resolveTrailLifetimeOpacityFactor(3, 12);
 const alpha = edgeOpacity * ageOpacity;
 ```
 
+### clamp01
+
+```ts
+clamp01(
+  value: number,
+): number
+```
+
+Clamps a number to the inclusive [0, 1] range.
+
+The trail renderer combines several normalized fade factors, so keeping this
+utility local to the module makes the intent obvious: every opacity channel
+must remain safe for direct canvas alpha use.
+
+Parameters:
+- `value` - - Candidate value.
+
+Returns: Clamped value.
+
 ### resolveEdgeOpacityFactor
 
 ```ts
@@ -142,22 +161,3 @@ Parameters:
 - `maxTrailFrameOffset` - - Oldest age offset currently retained by trail.
 
 Returns: Opacity multiplier in [0, 1].
-
-### clamp01
-
-```ts
-clamp01(
-  value: number,
-): number
-```
-
-Clamps a number to the inclusive [0, 1] range.
-
-The trail renderer combines several normalized fade factors, so keeping this
-utility local to the module makes the intent obvious: every opacity channel
-must remain safe for direct canvas alpha use.
-
-Parameters:
-- `value` - - Candidate value.
-
-Returns: Clamped value.