@reicek/neataptic-ts 0.1.21 → 0.1.23

package/test/examples/flappy_bird/browser-entry/playback/frame-render/playback.frame-render.bird.utils.ts

@@ -0,0 +1,180 @@
+import {
+  FLAPPY_BIRD_BODY_GLOW_BLUR_PX,
+  FLAPPY_BIRD_CHAMPION_EXTRA_GLOW_BLUR_PX,
+  FLAPPY_BIRD_RADIUS_PX,
+  FLAPPY_BIRD_X_PX,
+  FLAPPY_NON_CHAMPION_BODY_GLOW_BLUR_PX,
+  FLAPPY_PIPE_OUTLINE_CYAN_GLOW_BLUR_PX,
+  FLAPPY_PIPE_OUTLINE_GLOW_ALPHA,
+  FLAPPY_PIPE_OUTLINE_GLOW_STROKE_WIDTH_PX,
+  FLAPPY_PIPE_OUTLINE_STROKE_WIDTH_PX,
+} from '../../../constants/constants';
+import { resolveBirdRenderStyle } from '../playback.render.utils';
+import type { PlaybackBirdGeometry } from './playback.frame-render.types';
+
+/**
+ * Detailed bird-painting helpers for playback frames.
+ *
+ * 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.
+ */
+
+/**
+ * Draws one active bird body and champion-only highlight passes.
+ *
+ * The champion receives an extra additive-outline treatment so viewers can spot
+ * the leading bird quickly during playback.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param birdYPx - Bird vertical position in world pixels.
+ * @param birdIndex - Index of the bird being rendered.
+ * @param championBirdIndex - Champion index for the current frame.
+ * @returns Nothing.
+ */
+export function renderPlaybackBird(
+  context: CanvasRenderingContext2D,
+  birdYPx: number,
+  birdIndex: number,
+  championBirdIndex: number,
+): void {
+  const birdGeometry = resolvePlaybackBirdGeometry(birdYPx);
+  const birdRenderStyle = resolveBirdRenderStyle(birdIndex, championBirdIndex);
+
+  drawChampionPlaybackBirdGlow(context, birdGeometry, birdRenderStyle);
+  drawPlaybackBirdBody(context, birdGeometry, birdRenderStyle);
+}
+
+/**
+ * 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.
+ *
+ * @param birdYPx - Bird vertical position in world pixels.
+ * @returns Pixel-aligned square geometry for the bird body.
+ */
+export function resolvePlaybackBirdGeometry(
+  birdYPx: number,
+): PlaybackBirdGeometry {
+  const birdSideLengthPx = Math.max(1, Math.round(FLAPPY_BIRD_RADIUS_PX * 2));
+
+  return {
+    birdSideLengthPx,
+    birdLeftPx: Math.round(FLAPPY_BIRD_X_PX - FLAPPY_BIRD_RADIUS_PX),
+    birdTopPx: Math.round(birdYPx - FLAPPY_BIRD_RADIUS_PX),
+  };
+}
+
+/**
+ * Draws the square bird body with its base neon glow.
+ *
+ * This is the standard body pass shared by champion and non-champion birds.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param birdGeometry - Pixel-aligned bird geometry.
+ * @param birdRenderStyle - Resolved bird style payload.
+ * @returns Nothing.
+ */
+export function drawPlaybackBirdBody(
+  context: CanvasRenderingContext2D,
+  birdGeometry: PlaybackBirdGeometry,
+  birdRenderStyle: ReturnType<typeof resolveBirdRenderStyle>,
+): void {
+  context.globalAlpha = birdRenderStyle.birdOpacity;
+  context.fillStyle = birdRenderStyle.birdRenderColor;
+  context.shadowColor = birdRenderStyle.birdRenderColor;
+  context.shadowBlur = resolvePlaybackBirdBodyGlowBlur(birdRenderStyle);
+  context.fillRect(
+    birdGeometry.birdLeftPx,
+    birdGeometry.birdTopPx,
+    birdGeometry.birdSideLengthPx,
+    birdGeometry.birdSideLengthPx,
+  );
+}
+
+/**
+ * Draws the champion bird using the same two-pass additive outline glow method as pipes.
+ *
+ * Reusing the pipe-style glow language helps the whole playback scene feel like
+ * one visual system instead of unrelated rendering effects.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param birdGeometry - Pixel-aligned bird geometry.
+ * @param birdRenderStyle - Resolved bird style payload.
+ * @returns Nothing.
+ */
+export function drawChampionPlaybackBirdGlow(
+  context: CanvasRenderingContext2D,
+  birdGeometry: PlaybackBirdGeometry,
+  birdRenderStyle: ReturnType<typeof resolveBirdRenderStyle>,
+): void {
+  if (!birdRenderStyle.isChampionBird) {
+    return;
+  }
+
+  const previousCompositeOperation = context.globalCompositeOperation;
+  const previousGlobalAlpha = context.globalAlpha;
+  const previousStrokeStyle = context.strokeStyle;
+  const previousShadowColor = context.shadowColor;
+  const previousShadowBlur = context.shadowBlur;
+  const previousLineWidth = context.lineWidth;
+  const previousShadowOffsetX = context.shadowOffsetX;
+  const previousShadowOffsetY = context.shadowOffsetY;
+
+  context.globalCompositeOperation = 'lighter';
+  context.strokeStyle = birdRenderStyle.birdRenderColor;
+  context.globalAlpha = FLAPPY_PIPE_OUTLINE_GLOW_ALPHA;
+  context.shadowColor = birdRenderStyle.birdRenderColor;
+  context.shadowBlur = FLAPPY_PIPE_OUTLINE_CYAN_GLOW_BLUR_PX;
+  context.shadowOffsetX = 0;
+  context.shadowOffsetY = 0;
+  context.lineWidth = FLAPPY_PIPE_OUTLINE_GLOW_STROKE_WIDTH_PX;
+  context.strokeRect(
+    birdGeometry.birdLeftPx,
+    birdGeometry.birdTopPx,
+    birdGeometry.birdSideLengthPx,
+    birdGeometry.birdSideLengthPx,
+  );
+
+  context.globalAlpha = 1;
+  context.shadowBlur = 0;
+  context.shadowColor = 'transparent';
+  context.lineWidth = FLAPPY_PIPE_OUTLINE_STROKE_WIDTH_PX;
+  context.strokeRect(
+    birdGeometry.birdLeftPx,
+    birdGeometry.birdTopPx,
+    birdGeometry.birdSideLengthPx,
+    birdGeometry.birdSideLengthPx,
+  );
+
+  context.globalCompositeOperation = previousCompositeOperation;
+  context.globalAlpha = previousGlobalAlpha;
+  context.strokeStyle = previousStrokeStyle;
+  context.shadowColor = previousShadowColor;
+  context.shadowBlur = previousShadowBlur;
+  context.lineWidth = previousLineWidth;
+  context.shadowOffsetX = previousShadowOffsetX;
+  context.shadowOffsetY = previousShadowOffsetY;
+}
+
+/**
+ * Resolves the body glow blur for one bird render pass.
+ *
+ * Champion birds receive a slightly stronger body glow than the rest of the
+ * population.
+ *
+ * @param birdRenderStyle - Resolved bird style payload.
+ * @returns Blur radius used behind the square bird body.
+ */
+export function resolvePlaybackBirdBodyGlowBlur(
+  birdRenderStyle: ReturnType<typeof resolveBirdRenderStyle>,
+): number {
+  if (!birdRenderStyle.isChampionBird) {
+    return FLAPPY_NON_CHAMPION_BODY_GLOW_BLUR_PX;
+  }
+
+  return (
+    FLAPPY_BIRD_BODY_GLOW_BLUR_PX + FLAPPY_BIRD_CHAMPION_EXTRA_GLOW_BLUR_PX
+  );
+}

package/test/examples/flappy_bird/browser-entry/playback/frame-render/playback.frame-render.canvas.services.ts

@@ -0,0 +1,77 @@
+import type { PlaybackFrameSceneContext } from './playback.frame-render.types';
+
+/**
+ * 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.
+ */
+
+/**
+ * Resets the target canvas and base paint state before frame drawing begins.
+ *
+ * This establishes a predictable baseline before world-space transforms and glow
+ * effects are applied.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @returns Nothing.
+ */
+export function preparePlaybackFrameCanvas(
+  context: CanvasRenderingContext2D,
+): void {
+  // Step 1: Reset base paint state to a predictable source-over draw pass.
+  context.globalAlpha = 1;
+  context.globalCompositeOperation = 'source-over';
+  context.shadowBlur = 0;
+  context.shadowColor = 'transparent';
+  context.shadowOffsetX = 0;
+  context.shadowOffsetY = 0;
+
+  // Step 2: Clear the full backing canvas before drawing the next frame.
+  context.clearRect(0, 0, context.canvas.width, context.canvas.height);
+}
+
+/**
+ * Applies the viewport transform used for world-space frame rendering.
+ *
+ * After this transform, draw calls can work in simulation coordinates instead of
+ * raw canvas pixel coordinates.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param sceneContext - Shared scene geometry for the frame.
+ * @returns Nothing.
+ */
+export function beginPlaybackFrameViewportTransform(
+  context: CanvasRenderingContext2D,
+  sceneContext: PlaybackFrameSceneContext,
+): void {
+  // Step 1: Save the caller state before applying viewport-space transforms.
+  context.save();
+
+  // Step 2: Translate and scale into the current world viewport.
+  context.translate(
+    sceneContext.viewport.offsetXPx,
+    sceneContext.viewport.offsetYPx,
+  );
+  context.scale(sceneContext.viewport.scale, sceneContext.viewport.scale);
+  context.translate(-sceneContext.cameraLeftPx, 0);
+}
+
+/**
+ * Restores the caller canvas state after viewport-space frame drawing.
+ *
+ * This ensures later canvas users do not inherit playback-specific transform or
+ * alpha state.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @returns Nothing.
+ */
+export function finalizePlaybackFrameCanvas(
+  context: CanvasRenderingContext2D,
+): void {
+  // Step 1: Reset global alpha before restoring the caller transform state.
+  context.globalAlpha = 1;
+
+  // Step 2: Restore the caller state saved before viewport transforms.
+  context.restore();
+}

package/test/examples/flappy_bird/browser-entry/playback/frame-render/playback.frame-render.entity.services.ts

@@ -0,0 +1,167 @@
+import {
+  FLAPPY_BIRD_RADIUS_PX,
+  FLAPPY_BIRD_X_PX,
+  FLAPPY_PIPE_WIDTH_PX,
+} from '../../../constants/constants';
+import type {
+  PopulationRenderState,
+  TrailState,
+} from '../../browser-entry.types';
+import { resolvePlaybackGroundGridPipeConnectionProfile } from '../background/ground-grid/playback.background.ground-grid.math.utils';
+import { renderPlaybackBackground } from '../background/playback.background';
+import { drawPipeNeonOutline } from '../playback.render.service';
+import type {
+  PlaybackBirdRenderer,
+  PlaybackFrameSceneContext,
+  PlaybackTrailRenderer,
+  PlaybackTrailStyleResolver,
+} from './playback.frame-render.types';
+
+/**
+ * Entity-layer rendering helpers for playback frames.
+ *
+ * These services paint the world-space contents of a frame once the scene and
+ * canvas transforms have already been resolved.
+ */
+
+/**
+ * Draws the split playback background for the current world viewport.
+ *
+ * Background painting is delegated to the dedicated background subsystem so this
+ * layer can stay focused on frame composition order.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param renderState - Mutable simulation state snapshot.
+ * @param sceneContext - Shared scene geometry for the frame.
+ * @returns Nothing.
+ */
+export function renderPlaybackFrameBackground(
+  context: CanvasRenderingContext2D,
+  renderState: PopulationRenderState,
+  sceneContext: PlaybackFrameSceneContext,
+): void {
+  // Step 1: Render the world-space background behind all gameplay entities.
+  renderPlaybackBackground(context, {
+    viewportLeftXPx: sceneContext.cameraLeftPx,
+    visibleWorldWidthPx: sceneContext.visibleWorldWidthPx,
+    visibleWorldHeightPx: sceneContext.visibleWorldHeightPx,
+    frameIndex: renderState.frameIndex,
+    scrollBasePx: renderState.cumulativePipeTravelPx,
+  });
+}
+
+/**
+ * Draws all visible pipe segments and their neon outlines for the frame.
+ *
+ * Pipes are rendered as upper and lower segments connected to the projected
+ * floor profile used by the background grid.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param renderState - Mutable simulation state snapshot.
+ * @param sceneContext - Shared scene geometry for the frame.
+ * @returns Nothing.
+ */
+export function renderPlaybackFramePipes(
+  context: CanvasRenderingContext2D,
+  renderState: PopulationRenderState,
+  sceneContext: PlaybackFrameSceneContext,
+): void {
+  // Step 1: Resolve the lifted lower-pipe floor from the shared grid projection.
+  const pipeConnectionProfile = resolvePlaybackGroundGridPipeConnectionProfile(
+    sceneContext.visibleWorldHeightPx,
+  );
+
+  // Step 2: Render each pipe pair against the projected floor height.
+  for (const pipe of renderState.pipes) {
+    const gapHalfPx = pipe.gapSizePx * 0.5;
+    const gapTopPx = pipe.gapCenterYPx - gapHalfPx;
+    const gapBottomPx = pipe.gapCenterYPx + gapHalfPx;
+
+    drawPipeNeonOutline(context, pipe.xPx, 0, FLAPPY_PIPE_WIDTH_PX, gapTopPx);
+
+    drawPipeNeonOutline(
+      context,
+      pipe.xPx,
+      gapBottomPx,
+      FLAPPY_PIPE_WIDTH_PX,
+      pipeConnectionProfile.pipeFloorYPx - gapBottomPx,
+    );
+  }
+}
+
+/**
+ * Draws all active birds for the current frame.
+ *
+ * Only live birds are painted so the playback frame reflects the active
+ * population rather than leaving ghost bodies behind.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param renderState - Mutable simulation state snapshot.
+ * @param sceneContext - Shared scene geometry for the frame.
+ * @param renderBird - Bird body renderer owned by the detailed utility layer.
+ * @returns Nothing.
+ */
+export function renderPlaybackFrameBirds(
+  context: CanvasRenderingContext2D,
+  renderState: PopulationRenderState,
+  sceneContext: PlaybackFrameSceneContext,
+  renderBird: PlaybackBirdRenderer,
+): void {
+  // Step 1: Render only currently active birds.
+  renderState.birds.forEach((bird, birdIndex) => {
+    if (bird.done) {
+      return;
+    }
+
+    renderBird(context, bird.yPx, birdIndex, sceneContext.championBirdIndex);
+  });
+}
+
+/**
+ * Draws stepped trails for all active birds in the frame.
+ *
+ * In practice the trail cache usually contains only the champion trail, but the
+ * renderer stays generic and asks the trail-style policy how each active bird
+ * should be painted.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param renderState - Mutable simulation state snapshot.
+ * @param trailState - Leader trail render cache.
+ * @param sceneContext - Shared scene geometry for the frame.
+ * @param resolveTrailStyle - Trail style resolver owned by the detailed utility layer.
+ * @param renderTrail - Trail segment renderer owned by the detailed utility layer.
+ * @returns Nothing.
+ */
+export function renderPlaybackFrameTrails(
+  context: CanvasRenderingContext2D,
+  renderState: PopulationRenderState,
+  trailState: TrailState,
+  sceneContext: PlaybackFrameSceneContext,
+  resolveTrailStyle: PlaybackTrailStyleResolver,
+  renderTrail: PlaybackTrailRenderer,
+): void {
+  // Step 1: Render only trails for active birds with available trail data.
+  renderState.birds.forEach((bird, birdIndex) => {
+    if (bird.done) {
+      return;
+    }
+
+    const birdTrailPoints = trailState.birdTrailsY[birdIndex];
+    if (!birdTrailPoints || birdTrailPoints.length === 0) {
+      return;
+    }
+
+    const { baseOpacity, trailColor } = resolveTrailStyle(
+      birdIndex,
+      sceneContext.championBirdIndex,
+    );
+    renderTrail(
+      context,
+      birdTrailPoints,
+      trailColor,
+      FLAPPY_BIRD_X_PX - FLAPPY_BIRD_RADIUS_PX,
+      baseOpacity,
+      sceneContext.edgeBounds,
+    );
+  });
+}

package/test/examples/flappy_bird/browser-entry/playback/frame-render/playback.frame-render.scene.services.ts

@@ -0,0 +1,57 @@
+import {
+  FLAPPY_BIRD_VIEWPORT_X_RATIO,
+  FLAPPY_BIRD_X_PX,
+} from '../../../constants/constants';
+import type { PopulationRenderState } from '../../browser-entry.types';
+import { resolveWorldViewport } from '../../browser-entry.viewport.utils';
+import { resolveChampionBirdIndex } from '../playback.render.utils';
+import type { PlaybackFrameSceneContext } from './playback.frame-render.types';
+
+/**
+ * Scene-resolution helpers for playback frame rendering.
+ *
+ * Before anything can be painted, the renderer needs a camera-relative view of
+ * the world: viewport scale, visible bounds, camera origin, and which bird is
+ * currently the champion.
+ */
+
+/**
+ * Resolves the shared scene contract used by one frame render pass.
+ *
+ * The camera is anchored so the focal bird region stays at a readable screen
+ * position while the world scrolls beneath it.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param renderState - Mutable simulation state snapshot.
+ * @returns Viewport, camera, and edge-bounds state for the frame.
+ */
+export function resolvePlaybackFrameSceneContext(
+  context: CanvasRenderingContext2D,
+  renderState: PopulationRenderState,
+): PlaybackFrameSceneContext {
+  // Step 1: Resolve viewport scaling and visible world bounds.
+  const viewport = resolveWorldViewport(context.canvas);
+  const visibleWorldWidthPx = Math.max(1, renderState.visibleWorldWidthPx);
+  const visibleWorldHeightPx = Math.max(1, renderState.visibleWorldHeightPx);
+
+  // Step 2: Resolve camera position and champion index for this frame.
+  const desiredBirdScreenXPx =
+    visibleWorldWidthPx * FLAPPY_BIRD_VIEWPORT_X_RATIO;
+  const cameraLeftPx = FLAPPY_BIRD_X_PX - desiredBirdScreenXPx;
+  const championBirdIndex = resolveChampionBirdIndex(renderState);
+
+  // Step 3: Return the shared frame scene context.
+  return {
+    viewport,
+    visibleWorldWidthPx,
+    visibleWorldHeightPx,
+    cameraLeftPx,
+    championBirdIndex,
+    edgeBounds: {
+      leftXPx: cameraLeftPx,
+      rightXPx: cameraLeftPx + visibleWorldWidthPx,
+      topYPx: 0,
+      bottomYPx: visibleWorldHeightPx,
+    },
+  };
+}

package/test/examples/flappy_bird/browser-entry/playback/frame-render/playback.frame-render.service.test.ts

@@ -0,0 +1,176 @@
+import type {
+  PopulationRenderState,
+  TrailState,
+} from '../../../../../../test/examples/flappy_bird/browser-entry/browser-entry.types';
+import { updateTrailState } from '../../../../../../test/examples/flappy_bird/browser-entry/playback/frame-render/playback.frame-render.service';
+import { renderPlaybackFrameBirds } from '../../../../../../test/examples/flappy_bird/browser-entry/playback/frame-render/playback.frame-render.services';
+import { renderPlaybackBird } from '../../../../../../test/examples/flappy_bird/browser-entry/playback/frame-render/playback.frame-render.utils';
+import { FLAPPY_CHAMPION_TRAIL_MAX_POINTS } from '../../../../../../test/examples/flappy_bird/constants/constants.birds';
+
+describe('updateTrailState', () => {
+  it('retains a trail for the current champion only', () => {
+    const renderState = createRenderState({
+      birds: [
+        createBird({ pipesPassed: 1, framesSurvived: 10 }),
+        createBird({ pipesPassed: 3, framesSurvived: 20 }),
+      ],
+    });
+    const trailState: TrailState = {
+      birdTrailsY: [[{ frameIndex: 4, yPx: 10 }], []],
+    };
+
+    updateTrailState(trailState, renderState);
+
+    expect(trailState.birdTrailsY.map((birdTrail) => birdTrail.length)).toEqual(
+      [0, 1],
+    );
+  });
+
+  it('clears trail history for eliminated birds', () => {
+    const renderState = createRenderState({
+      birds: [createBird({ done: true, pipesPassed: 5, framesSurvived: 30 })],
+    });
+    const trailState: TrailState = {
+      birdTrailsY: [[{ frameIndex: 7, yPx: 24 }]],
+    };
+
+    updateTrailState(trailState, renderState);
+
+    expect(trailState.birdTrailsY[0].length).toBe(0);
+  });
+
+  it('caps champion trail history to the short champion limit', () => {
+    const renderState = createRenderState({
+      frameIndex: FLAPPY_CHAMPION_TRAIL_MAX_POINTS + 5,
+      birds: [createBird({ pipesPassed: 2, framesSurvived: 12 })],
+    });
+    const trailState: TrailState = {
+      birdTrailsY: [
+        Array.from(
+          { length: FLAPPY_CHAMPION_TRAIL_MAX_POINTS },
+          (_, frameIndex) => ({
+            frameIndex,
+            yPx: frameIndex,
+          }),
+        ),
+      ],
+    };
+
+    updateTrailState(trailState, renderState);
+
+    expect(trailState.birdTrailsY[0].length).toBe(
+      FLAPPY_CHAMPION_TRAIL_MAX_POINTS,
+    );
+  });
+
+  it('keeps rendering all active birds while trails stay champion-only', () => {
+    const renderBird = jest.fn();
+    const renderState = createRenderState({
+      birds: [
+        createBird({ pipesPassed: 1, framesSurvived: 10 }),
+        createBird({ pipesPassed: 3, framesSurvived: 20 }),
+        createBird({ done: true, pipesPassed: 0, framesSurvived: 5 }),
+      ],
+    });
+
+    renderPlaybackFrameBirds(
+      {} as CanvasRenderingContext2D,
+      renderState,
+      createSceneContext(),
+      renderBird,
+    );
+
+    expect(renderBird.mock.calls.map(([, , birdIndex]) => birdIndex)).toEqual([
+      0, 1,
+    ]);
+  });
+
+  it('renders non-champion birds without champion highlight passes', () => {
+    const drawingContext = createMockDrawingContext();
+
+    renderPlaybackBird(drawingContext, 40, 0, 1);
+
+    expect(drawingContext.strokeRect).not.toHaveBeenCalled();
+  });
+
+  it('keeps champion highlight passes for the current leader', () => {
+    const drawingContext = createMockDrawingContext();
+
+    renderPlaybackBird(drawingContext, 40, 1, 1);
+
+    expect(drawingContext.strokeRect).toHaveBeenCalledTimes(2);
+  });
+});
+
+function createRenderState(overrides?: {
+  frameIndex?: number;
+  birds?: PopulationRenderState['birds'];
+}): PopulationRenderState {
+  return {
+    frameIndex: overrides?.frameIndex ?? 8,
+    cumulativePipeTravelPx: 0,
+    visibleWorldWidthPx: 640,
+    visibleWorldHeightPx: 480,
+    nextPipeId: 0,
+    lastSpawnedPipeGapPx: 0,
+    lastSpawnedPipeGapCenterYPx: 0,
+    lastSpawnedPipeSpawnIntervalFrames: 0,
+    framesUntilNextPipeSpawn: 0,
+    pipes: [],
+    birds: overrides?.birds ?? [],
+  };
+}
+
+function createBird(overrides?: {
+  yPx?: number;
+  pipesPassed?: number;
+  framesSurvived?: number;
+  done?: boolean;
+}): PopulationRenderState['birds'][number] {
+  return {
+    yPx: overrides?.yPx ?? 32,
+    pipesPassed: overrides?.pipesPassed ?? 0,
+    framesSurvived: overrides?.framesSurvived ?? 0,
+    done: overrides?.done ?? false,
+  };
+}
+
+function createSceneContext() {
+  return {
+    viewport: {
+      offsetXPx: 0,
+      offsetYPx: 0,
+      scale: 1,
+    },
+    visibleWorldWidthPx: 640,
+    visibleWorldHeightPx: 480,
+    cameraLeftPx: 0,
+    championBirdIndex: 1,
+    edgeBounds: {
+      leftXPx: 0,
+      rightXPx: 640,
+      topYPx: 0,
+      bottomYPx: 480,
+    },
+  };
+}
+
+function createMockDrawingContext(): CanvasRenderingContext2D {
+  return {
+    fillRect: jest.fn(),
+    strokeRect: jest.fn(),
+    beginPath: jest.fn(),
+    moveTo: jest.fn(),
+    lineTo: jest.fn(),
+    stroke: jest.fn(),
+    globalAlpha: 1,
+    globalCompositeOperation: 'source-over',
+    fillStyle: '#000000',
+    strokeStyle: '#000000',
+    shadowColor: 'transparent',
+    shadowBlur: 0,
+    shadowOffsetX: 0,
+    shadowOffsetY: 0,
+    lineWidth: 1,
+  } as unknown as CanvasRenderingContext2D;
+}