@reicek/neataptic-ts 0.1.21 → 0.1.23

package/test/examples/flappy_bird/browser-entry/playback/playback.worker-channel.utils.ts

@@ -1,123 +1,11 @@
-import type {
-  EvolutionPlaybackStepMessage,
-  PlaybackFrameStats,
-} from '../browser-entry.types';
-
-/**
- * Request payload for one playback-step worker call.
- */
-export interface PlaybackStepRequest {
-  simulationSteps: number;
-  visibleWorldWidthPx: number;
-  visibleWorldHeightPx: number;
-}
-
-/**
- * Input used to resolve next playback-step request and budget remainder.
- */
-export interface ResolvePlaybackStepRequestInput {
-  simulationFrameBudget: number;
-  visibleWorldWidthPx: number;
-  visibleWorldHeightPx: number;
-  emulationSpeedMultiplier: number;
-}
-
-/**
- * Output for resolved playback-step request and frame-budget remainder.
- */
-export interface ResolvePlaybackStepRequestResult {
-  simulationStepsThisRender: number;
-  simulationFrameBudgetRemainder: number;
-  playbackStepRequest: PlaybackStepRequest;
-}
-
-/**
- * Shared alias for worker playback-step payload.
- */
-export type PlaybackStepPayload = EvolutionPlaybackStepMessage['payload'];
-
-/**
- * Resolves step count and request payload for the next worker playback batch.
- *
- * @param input - Current frame budget and viewport dimensions.
- * @returns Request payload plus carried-over fractional frame budget.
- */
-export function resolvePlaybackStepRequest(
-  input: ResolvePlaybackStepRequestInput,
-): ResolvePlaybackStepRequestResult {
-  const updatedSimulationFrameBudget =
-    input.simulationFrameBudget + input.emulationSpeedMultiplier;
-  const simulationStepsThisRender = Math.max(
-    1,
-    Math.floor(updatedSimulationFrameBudget),
-  );
-  const simulationFrameBudgetRemainder =
-    updatedSimulationFrameBudget - simulationStepsThisRender;
-
-  return {
-    simulationStepsThisRender,
-    simulationFrameBudgetRemainder,
-    playbackStepRequest: {
-      simulationSteps: simulationStepsThisRender,
-      visibleWorldWidthPx: input.visibleWorldWidthPx,
-      visibleWorldHeightPx: input.visibleWorldHeightPx,
-    },
-  };
-}
-
-/**
- * Resolves HUD playback frame stats from worker payload and leader metrics.
- *
- * @param playbackStepPayload - Playback payload returned by worker.
- * @param frameIndex - Current render frame index.
- * @param activeBirdCount - Number of alive birds in current frame.
- * @param leaderPipesPassed - Current frame leader pipes passed.
- * @param leaderFramesSurvived - Current frame leader survived frames.
- * @returns Normalized per-frame HUD telemetry payload.
- */
-export function resolvePlaybackFrameStats(
-  playbackStepPayload: PlaybackStepPayload,
-  frameIndex: number,
-  activeBirdCount: number,
-  leaderPipesPassed: number,
-  leaderFramesSurvived: number,
-): PlaybackFrameStats {
-  return {
-    frameIndex,
-    activeBirdCount,
-    leaderPipesPassed,
-    leaderFramesSurvived,
-    activationCallsPerFrame:
-      playbackStepPayload.instrumentation?.activationCallsPerFrame ?? 0,
-    simulationStepsPerRaf:
-      playbackStepPayload.instrumentation?.simulationStepsPerRaf ?? 0,
-  };
-}
-
-/**
- * Resolves final playback summary values when worker reports completion.
- *
- * @param playbackStepPayload - Playback payload returned by worker.
- * @param latestLeaderPipesPassed - Last observed leader pipes passed fallback.
- * @param latestLeaderFramesSurvived - Last observed leader frames fallback.
- * @returns Final aggregate playback summary.
- */
-export function resolvePlaybackCompletionSummary(
-  playbackStepPayload: PlaybackStepPayload,
-  latestLeaderPipesPassed: number,
-  latestLeaderFramesSurvived: number,
-): {
-  averagePipesPassed: number;
-  p90FramesSurvived: number;
-  winnerPipesPassed: number;
-  winnerFramesSurvived: number;
-} {
-  return {
-    averagePipesPassed: playbackStepPayload.averagePipesPassed ?? 0,
-    p90FramesSurvived: playbackStepPayload.p90FramesSurvived ?? 0,
-    winnerPipesPassed:
-      playbackStepPayload.winnerPipesPassed ?? latestLeaderPipesPassed,
-    winnerFramesSurvived:
-      playbackStepPayload.winnerFramesSurvived ?? latestLeaderFramesSurvived,
-  };
-}
+export type {
+  PlaybackStepPayload,
+  PlaybackStepRequest,
+  ResolvePlaybackStepRequestInput,
+  ResolvePlaybackStepRequestResult,
+} from './worker-channel/playback.worker-channel.types';
+export { resolvePlaybackStepRequest } from './worker-channel/playback.worker-channel.request.services';
+export {
+  resolvePlaybackCompletionSummary,
+  resolvePlaybackFrameStats,
+} from './worker-channel/playback.worker-channel.summary.services';

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

@@ -0,0 +1,55 @@
+# browser-entry/playback/snapshot
+
+## browser-entry/playback/snapshot/playback.snapshot.services.ts
+
+### applyPlaybackSnapshot
+
+`(renderState: import("test/examples/flappy_bird/browser-entry/browser-entry.simulation.types").PopulationRenderState, snapshot: import("test/examples/flappy_bird/browser-entry/browser-entry.worker.types").EvolutionPlaybackStepSnapshot) => void`
+
+Snapshot synchronization helpers for playback.
+
+The worker streams packed typed-array snapshots, while the browser renderer
+wants stable mutable arrays of pipes and birds. This module performs that
+translation in place so playback can stay fast and allocation-light.
+
+### syncPlaybackSnapshotBirds
+
+`(renderState: import("test/examples/flappy_bird/browser-entry/browser-entry.simulation.types").PopulationRenderState, snapshot: import("test/examples/flappy_bird/browser-entry/browser-entry.worker.types").EvolutionPlaybackStepSnapshot) => void`
+
+Synchronizes packed bird snapshot fields into the reusable render-state bird array.
+
+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.
+- `snapshot` - - Packed worker playback snapshot for the current render tick.
+
+Returns: Nothing.
+
+### syncPlaybackSnapshotPipes
+
+`(renderState: import("test/examples/flappy_bird/browser-entry/browser-entry.simulation.types").PopulationRenderState, snapshot: import("test/examples/flappy_bird/browser-entry/browser-entry.worker.types").EvolutionPlaybackStepSnapshot) => void`
+
+Synchronizes packed pipe snapshot fields into the reusable render-state pipe array.
+
+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.
+- `snapshot` - - Packed worker playback snapshot for the current render tick.
+
+Returns: Nothing.
+
+## browser-entry/playback/snapshot/playback.snapshot.summary.utils.ts
+
+### resolveLeaderFramesSurvived
+
+`(renderState: import("test/examples/flappy_bird/browser-entry/browser-entry.simulation.types").PopulationRenderState) => number`
+
+Small summary helpers derived from hydrated playback render state.
+
+Once a packed snapshot has been synchronized into the browser render state,
+these helpers compute simple aggregate values needed by the HUD and playback
+reporting flow.

package/test/examples/flappy_bird/browser-entry/playback/snapshot/playback.snapshot.services.ts

@@ -0,0 +1,103 @@
+import type {
+  EvolutionPlaybackStepSnapshot,
+  PopulationRenderState,
+} from '../../browser-entry.types';
+
+/**
+ * Snapshot synchronization helpers for playback.
+ *
+ * The worker streams packed typed-array snapshots, while the browser renderer
+ * wants stable mutable arrays of pipes and birds. This module performs that
+ * translation in place so playback can stay fast and allocation-light.
+ */
+
+/**
+ * Applies worker snapshot data to the mutable playback render state.
+ *
+ * This is the top-level hydration step for one frame: copy scalar frame fields,
+ * then synchronize packed pipe and bird arrays into reusable browser-side
+ * objects.
+ *
+ * @param renderState - Mutable render state mirror used by the browser.
+ * @param snapshot - Worker playback snapshot for the current render tick.
+ * @returns Nothing.
+ */
+export function applyPlaybackSnapshot(
+  renderState: PopulationRenderState,
+  snapshot: EvolutionPlaybackStepSnapshot,
+): void {
+  renderState.frameIndex = snapshot.frameIndex;
+  renderState.cumulativePipeTravelPx = snapshot.cumulativePipeTravelPx;
+  renderState.visibleWorldWidthPx = snapshot.visibleWorldWidthPx;
+  renderState.visibleWorldHeightPx = snapshot.visibleWorldHeightPx;
+  syncPlaybackSnapshotPipes(renderState, snapshot);
+  syncPlaybackSnapshotBirds(renderState, snapshot);
+}
+
+/**
+ * Synchronizes packed pipe snapshot fields into the reusable render-state pipe array.
+ *
+ * Instead of recreating pipe objects every frame, the browser grows the array as
+ * needed and then mutates the existing records in place.
+ *
+ * @param renderState - Mutable render state mirror used by the browser.
+ * @param snapshot - Packed worker playback snapshot for the current render tick.
+ * @returns Nothing.
+ */
+function syncPlaybackSnapshotPipes(
+  renderState: PopulationRenderState,
+  snapshot: EvolutionPlaybackStepSnapshot,
+): void {
+  const targetPipeCount = snapshot.pipeCount;
+  while (renderState.pipes.length < targetPipeCount) {
+    renderState.pipes.push({
+      id: 0,
+      xPx: 0,
+      gapCenterYPx: 0,
+      gapSizePx: 0,
+    });
+  }
+
+  renderState.pipes.length = targetPipeCount;
+  for (let pipeIndex = 0; pipeIndex < targetPipeCount; pipeIndex += 1) {
+    const pipe = renderState.pipes[pipeIndex];
+    pipe.id = pipeIndex;
+    pipe.xPx = snapshot.pipes.xPositionsPx[pipeIndex] ?? 0;
+    pipe.gapCenterYPx = snapshot.pipes.gapCenterYPositionsPx[pipeIndex] ?? 0;
+    pipe.gapSizePx = snapshot.pipes.gapSizesPx[pipeIndex] ?? 0;
+  }
+}
+
+/**
+ * Synchronizes packed bird snapshot fields into the reusable render-state bird array.
+ *
+ * This mirrors the pipe strategy: keep a stable array shape when possible and
+ * update fields in place from the packed worker buffers.
+ *
+ * @param renderState - Mutable render state mirror used by the browser.
+ * @param snapshot - Packed worker playback snapshot for the current render tick.
+ * @returns Nothing.
+ */
+function syncPlaybackSnapshotBirds(
+  renderState: PopulationRenderState,
+  snapshot: EvolutionPlaybackStepSnapshot,
+): void {
+  const targetBirdCount = snapshot.birdCount;
+  while (renderState.birds.length < targetBirdCount) {
+    renderState.birds.push({
+      yPx: 0,
+      pipesPassed: 0,
+      framesSurvived: 0,
+      done: false,
+    });
+  }
+
+  renderState.birds.length = targetBirdCount;
+  for (let birdIndex = 0; birdIndex < targetBirdCount; birdIndex += 1) {
+    const bird = renderState.birds[birdIndex];
+    bird.yPx = snapshot.birds.yPositionsPx[birdIndex] ?? 0;
+    bird.pipesPassed = snapshot.birds.pipesPassed[birdIndex] ?? 0;
+    bird.framesSurvived = snapshot.birds.framesSurvived[birdIndex] ?? 0;
+    bird.done = (snapshot.birds.doneFlags[birdIndex] ?? 0) === 1;
+  }
+}

package/test/examples/flappy_bird/browser-entry/playback/snapshot/playback.snapshot.summary.utils.test.ts

@@ -0,0 +1,45 @@
+import type { PopulationRenderState } from '../../browser-entry.types';
+import { resolveLeaderFramesSurvived } from './playback.snapshot.summary.utils';
+
+describe('resolveLeaderFramesSurvived', () => {
+  it('returns the maximum survived-frame count across all birds', () => {
+    const renderState = createRenderState();
+
+    expect(resolveLeaderFramesSurvived(renderState)).toBe(17);
+  });
+});
+
+function createRenderState(): PopulationRenderState {
+  return {
+    frameIndex: 0,
+    cumulativePipeTravelPx: 0,
+    visibleWorldWidthPx: 1,
+    visibleWorldHeightPx: 1,
+    nextPipeId: 0,
+    lastSpawnedPipeGapPx: 0,
+    lastSpawnedPipeGapCenterYPx: 0,
+    lastSpawnedPipeSpawnIntervalFrames: 0,
+    framesUntilNextPipeSpawn: 0,
+    pipes: [],
+    birds: [
+      {
+        yPx: 10,
+        pipesPassed: 1,
+        framesSurvived: 4,
+        done: false,
+      },
+      {
+        yPx: 20,
+        pipesPassed: 2,
+        framesSurvived: 17,
+        done: true,
+      },
+      {
+        yPx: 30,
+        pipesPassed: 0,
+        framesSurvived: 9,
+        done: false,
+      },
+    ],
+  };
+}

package/test/examples/flappy_bird/browser-entry/playback/snapshot/playback.snapshot.summary.utils.ts

@@ -0,0 +1,28 @@
+import type { PopulationRenderState } from '../../browser-entry.types';
+
+/**
+ * Small summary helpers derived from hydrated playback render state.
+ *
+ * Once a packed snapshot has been synchronized into the browser render state,
+ * these helpers compute simple aggregate values needed by the HUD and playback
+ * reporting flow.
+ */
+
+/**
+ * Resolves the maximum survived-frame count in the current render state.
+ *
+ * This is the "leader frames survived" view of the current frame: the best raw
+ * frame count among all birds currently represented in the render state.
+ *
+ * @param renderState - Current render state.
+ * @returns Maximum frames survived by any bird.
+ */
+export function resolveLeaderFramesSurvived(
+  renderState: PopulationRenderState,
+): number {
+  return renderState.birds.reduce(
+    (maximumFramesSurvived, bird) =>
+      Math.max(maximumFramesSurvived, bird.framesSurvived),
+    0,
+  );
+}

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

@@ -0,0 +1,95 @@
+# browser-entry/playback/trail
+
+## browser-entry/playback/trail/playback.trail.history.services.ts
+
+### pushChampionTrailPoint
+
+`(trailPoints: import("test/examples/flappy_bird/browser-entry/browser-entry.simulation.types").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
+
+`(trailPoints: import("test/examples/flappy_bird/browser-entry/browser-entry.simulation.types").TrailPoint[], frameIndex: number, yPosition: number, maxRetainedPoints: number) => void`
+
+Appends one trail point while enforcing the maximum retained history length.
+
+Playback trails are intentionally modeled as short rolling histories rather
+than unbounded path logs. That keeps the neon afterimage readable, prevents
+old turns from dominating the current frame, and avoids per-frame growth in a
+long-running browser session.
+
+Parameters:
+- `trailPoints` - - Mutable trail collection.
+- `frameIndex` - - Source frame index.
+- `yPosition` - - Bird y position.
+- `maxRetainedPoints` - - Optional maximum retained trail history length.
+
+Returns: Nothing.
+
+## browser-entry/playback/trail/playback.trail.opacity.utils.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
+
+`(pointXPx: number, pointYPx: number, edgeBounds: import("test/examples/flappy_bird/browser-entry/playback/playback.types").PlaybackEdgeBounds) => number`
+
+Converts distance-to-edge into a normalized opacity factor.
+
+Trail points fade as they approach the viewport border so the rendered path
+feels cropped by the camera instead of abruptly chopped off. This mirrors the
+common animation principle of easing visual intensity near a frame boundary.
+
+Returns 0 exactly on or beyond an edge and rises to 1 once distance exceeds
+the configured fade band.
+
+Parameters:
+- `pointXPx` - - Point x position.
+- `pointYPx` - - Point y position.
+- `edgeBounds` - - Visible world bounds used for edge distance checks.
+
+Returns: Opacity multiplier in [0, 1].
+
+### resolveTrailLifetimeOpacityFactor
+
+`(frameOffset: number, maxTrailFrameOffset: number) => number`
+
+Converts trail age into a normalized opacity factor.
+
+This helper implements the other half of the afterimage effect: recent trail
+samples should read as energetic and bright, while older samples should fade
+away smoothly so the viewer's eye stays anchored to the current flock motion.
+
+Oldest retained history approaches 0 opacity; newest approaches 1.
+
+Parameters:
+- `frameOffset` - - Frames between this point and newest trail point.
+- `maxTrailFrameOffset` - - Oldest age offset currently retained by trail.
+
+Returns: Opacity multiplier in [0, 1].

package/test/examples/flappy_bird/browser-entry/playback/trail/playback.trail.history.services.test.ts

@@ -0,0 +1,35 @@
+import type { TrailPoint } from '../../browser-entry.types';
+import {
+  pushChampionTrailPoint,
+  pushTrailPoint,
+} from './playback.trail.history.services';
+
+describe('pushTrailPoint', () => {
+  it('trims the oldest points when the trail exceeds the retained maximum', () => {
+    const trailPoints = createTrailPoints();
+
+    pushTrailPoint(trailPoints, 3, 30, 2);
+
+    expect(trailPoints).toEqual([
+      { frameIndex: 2, yPx: 20 },
+      { frameIndex: 3, yPx: 30 },
+    ]);
+  });
+});
+
+describe('pushChampionTrailPoint', () => {
+  it('appends the latest champion point to the trail history', () => {
+    const trailPoints: TrailPoint[] = [];
+
+    pushChampionTrailPoint(trailPoints, 7, 42);
+
+    expect(trailPoints.at(-1)).toEqual({ frameIndex: 7, yPx: 42 });
+  });
+});
+
+function createTrailPoints(): TrailPoint[] {
+  return [
+    { frameIndex: 1, yPx: 10 },
+    { frameIndex: 2, yPx: 20 },
+  ];
+}

package/test/examples/flappy_bird/browser-entry/playback/trail/playback.trail.history.services.ts

@@ -0,0 +1,64 @@
+import {
+  FLAPPY_CHAMPION_TRAIL_MAX_POINTS,
+  FLAPPY_TRAIL_MAX_POINTS,
+} from '../../../constants/constants';
+import type { TrailPoint } from '../../browser-entry.types';
+
+/**
+ * Appends one trail point while enforcing the maximum retained history length.
+ *
+ * Playback trails are intentionally modeled as short rolling histories rather
+ * than unbounded path logs. That keeps the neon afterimage readable, prevents
+ * old turns from dominating the current frame, and avoids per-frame growth in a
+ * long-running browser session.
+ *
+ * @param trailPoints - Mutable trail collection.
+ * @param frameIndex - Source frame index.
+ * @param yPosition - Bird y position.
+ * @param maxRetainedPoints - Optional maximum retained trail history length.
+ * @returns Nothing.
+ *
+ * @example
+ * ```ts
+ * const trailPoints = [{ frameIndex: 10, yPx: 140 }];
+ * pushTrailPoint(trailPoints, 11, 136, 2);
+ * // trailPoints now contains the two newest samples only.
+ * ```
+ */
+export function pushTrailPoint(
+  trailPoints: TrailPoint[],
+  frameIndex: number,
+  yPosition: number,
+  maxRetainedPoints: number = FLAPPY_TRAIL_MAX_POINTS,
+): void {
+  trailPoints.push({ frameIndex, yPx: yPosition });
+  if (trailPoints.length > maxRetainedPoints) {
+    trailPoints.splice(0, trailPoints.length - maxRetainedPoints);
+  }
+}
+
+/**
+ * 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.
+ *
+ * @param trailPoints - Mutable champion trail collection.
+ * @param frameIndex - Source frame index.
+ * @param yPosition - Bird y position.
+ * @returns Nothing.
+ */
+export function pushChampionTrailPoint(
+  trailPoints: TrailPoint[],
+  frameIndex: number,
+  yPosition: number,
+): void {
+  pushTrailPoint(
+    trailPoints,
+    frameIndex,
+    yPosition,
+    FLAPPY_CHAMPION_TRAIL_MAX_POINTS,
+  );
+}

package/test/examples/flappy_bird/browser-entry/playback/trail/playback.trail.opacity.utils.test.ts

@@ -0,0 +1,37 @@
+import type { PlaybackEdgeBounds } from '../playback.types';
+import {
+  clamp01,
+  resolveEdgeOpacityFactor,
+  resolveTrailLifetimeOpacityFactor,
+} from './playback.trail.opacity.utils';
+
+describe('resolveEdgeOpacityFactor', () => {
+  it('returns full opacity when the point is safely inside the fade band', () => {
+    expect(resolveEdgeOpacityFactor(100, 100, createEdgeBounds())).toBe(1);
+  });
+
+  it('returns zero opacity when the point is on the edge', () => {
+    expect(resolveEdgeOpacityFactor(0, 100, createEdgeBounds())).toBe(0);
+  });
+});
+
+describe('resolveTrailLifetimeOpacityFactor', () => {
+  it('returns half opacity for a midpoint trail age', () => {
+    expect(resolveTrailLifetimeOpacityFactor(5, 10)).toBe(0.5);
+  });
+});
+
+describe('clamp01', () => {
+  it('caps values above one to the upper bound', () => {
+    expect(clamp01(2)).toBe(1);
+  });
+});
+
+function createEdgeBounds(): PlaybackEdgeBounds {
+  return {
+    leftXPx: 0,
+    rightXPx: 200,
+    topYPx: 0,
+    bottomYPx: 200,
+  };
+}

package/test/examples/flappy_bird/browser-entry/playback/trail/playback.trail.opacity.utils.ts

@@ -0,0 +1,74 @@
+import { FLAPPY_TRAIL_EDGE_FADE_DISTANCE_PX } from '../../../constants/constants';
+import type { PlaybackEdgeBounds } from '../playback.types';
+
+/**
+ * Converts distance-to-edge into a normalized opacity factor.
+ *
+ * Trail points fade as they approach the viewport border so the rendered path
+ * feels cropped by the camera instead of abruptly chopped off. This mirrors the
+ * common animation principle of easing visual intensity near a frame boundary.
+ *
+ * Returns 0 exactly on or beyond an edge and rises to 1 once distance exceeds
+ * the configured fade band.
+ *
+ * @param pointXPx - Point x position.
+ * @param pointYPx - Point y position.
+ * @param edgeBounds - Visible world bounds used for edge distance checks.
+ * @returns Opacity multiplier in [0, 1].
+ */
+export function resolveEdgeOpacityFactor(
+  pointXPx: number,
+  pointYPx: number,
+  edgeBounds: PlaybackEdgeBounds,
+): number {
+  const distanceToLeftEdgePx = pointXPx - edgeBounds.leftXPx;
+  const distanceToRightEdgePx = edgeBounds.rightXPx - pointXPx;
+  const distanceToTopEdgePx = pointYPx - edgeBounds.topYPx;
+  const distanceToBottomEdgePx = edgeBounds.bottomYPx - pointYPx;
+
+  const nearestEdgeDistancePx = Math.min(
+    distanceToLeftEdgePx,
+    distanceToRightEdgePx,
+    distanceToTopEdgePx,
+    distanceToBottomEdgePx,
+  );
+  const fadeProgress =
+    nearestEdgeDistancePx / FLAPPY_TRAIL_EDGE_FADE_DISTANCE_PX;
+  return clamp01(fadeProgress);
+}
+
+/**
+ * Converts trail age into a normalized opacity factor.
+ *
+ * This helper implements the other half of the afterimage effect: recent trail
+ * samples should read as energetic and bright, while older samples should fade
+ * away smoothly so the viewer's eye stays anchored to the current flock motion.
+ *
+ * Oldest retained history approaches 0 opacity; newest approaches 1.
+ *
+ * @param frameOffset - Frames between this point and newest trail point.
+ * @param maxTrailFrameOffset - Oldest age offset currently retained by trail.
+ * @returns Opacity multiplier in [0, 1].
+ */
+export function resolveTrailLifetimeOpacityFactor(
+  frameOffset: number,
+  maxTrailFrameOffset: number,
+): number {
+  const normalizedLifetimeProgress =
+    1 - frameOffset / Math.max(1, maxTrailFrameOffset);
+  return clamp01(normalizedLifetimeProgress);
+}
+
+/**
+ * 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.
+ *
+ * @param value - Candidate value.
+ * @returns Clamped value.
+ */
+export function clamp01(value: number): number {
+  return Math.max(0, Math.min(1, value));
+}