@reicek/neataptic-ts 0.1.21 → 0.1.23

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

@@ -0,0 +1,184 @@
+import type { PopulationRenderState, TrailState } from '../browser-entry.types';
+import {
+  resolveVisibleWorldHeightPx,
+  resolveVisibleWorldWidthPx,
+} from '../browser-entry.viewport.utils';
+import type {
+  PlaybackEpisodeSummary,
+  PlaybackLoopState,
+  PlaybackMutableSummary,
+  PlaybackSessionContext,
+} from './playback.orchestration.types';
+
+/**
+ * Session initialization and summary-folding helpers for playback.
+ *
+ * These services answer three orchestration questions:
+ * 1. What viewport is the browser currently showing?
+ * 2. What local mirror state should exist before the first worker snapshot?
+ * 3. How should mutable loop state be folded back into a public summary?
+ */
+
+/**
+ * Resolves the current visible playback viewport dimensions from the canvas.
+ *
+ * Playback sizing is derived from the live canvas rather than a hard-coded
+ * constant so resizing can flow into the worker/session boundary cleanly.
+ *
+ * @param canvas - Target playback canvas.
+ * @returns Visible world width and height in pixels.
+ */
+export function resolvePlaybackViewportDimensions(canvas: HTMLCanvasElement): {
+  visibleWorldWidthPx: number;
+  visibleWorldHeightPx: number;
+} {
+  // Step 1: Read the current world-space viewport dimensions.
+  return {
+    visibleWorldWidthPx: resolveVisibleWorldWidthPx(canvas),
+    visibleWorldHeightPx: resolveVisibleWorldHeightPx(canvas),
+  };
+}
+
+/**
+ * Creates the initial render state used before the first worker snapshot.
+ *
+ * The browser starts from an empty-but-shaped render state so rendering helpers
+ * can assume the object graph exists even before the worker has emitted any
+ * population geometry.
+ *
+ * @param viewportDimensions - Current visible world dimensions.
+ * @returns Initialized population render state.
+ */
+export function createInitialRenderState(viewportDimensions: {
+  visibleWorldWidthPx: number;
+  visibleWorldHeightPx: number;
+}): PopulationRenderState {
+  // Step 1: Seed render fields with viewport dimensions and empty entities.
+  return {
+    frameIndex: 0,
+    cumulativePipeTravelPx: 0,
+    visibleWorldWidthPx: viewportDimensions.visibleWorldWidthPx,
+    visibleWorldHeightPx: viewportDimensions.visibleWorldHeightPx,
+    nextPipeId: 0,
+    lastSpawnedPipeGapPx: 0,
+    lastSpawnedPipeGapCenterYPx: 0,
+    lastSpawnedPipeSpawnIntervalFrames: 0,
+    framesUntilNextPipeSpawn: 0,
+    pipes: [],
+    birds: [],
+  };
+}
+
+/**
+ * Creates the initial trail state used before any snapshots have been applied.
+ *
+ * Trails are purely visual history, so they begin empty and accumulate only as
+ * playback frames are observed.
+ *
+ * @returns Empty trail state for all birds.
+ */
+export function createInitialTrailState(): TrailState {
+  // Step 1: Initialize the trail cache as empty arrays.
+  return {
+    birdTrailsY: [],
+  };
+}
+
+/**
+ * Creates the mutable loop state used while processing playback steps.
+ *
+ * This is the browser's running notebook for one episode: budget, completion
+ * flag, and the latest known aggregate outcome metrics.
+ *
+ * @returns Initialized loop state and aggregate summary values.
+ */
+export function createInitialPlaybackLoopState(): PlaybackLoopState {
+  // Step 1: Initialize frame-budget and completion tracking.
+  return {
+    simulationFrameBudget: 0,
+    finished: false,
+    summary: {
+      averagePipesPassed: 0,
+      p90FramesSurvived: 0,
+      winnerPipesPassed: 0,
+      winnerFramesSurvived: 0,
+      latestLeaderPipesPassed: 0,
+      latestLeaderFramesSurvived: 0,
+    },
+  };
+}
+
+/**
+ * Initializes worker playback and local state mirrors for one episode.
+ *
+ * This is the point where the browser and worker agree on a fresh episode. The
+ * browser sends the initial viewport dimensions to the worker, then builds the
+ * local render and summary mirrors that will be updated as snapshots arrive.
+ *
+ * @param canvas - Target playback canvas.
+ * @param evolutionWorker - Worker owning playback simulation state.
+ * @returns Session context shared across the playback loop.
+ */
+export function initializePlaybackSessionContext(
+  canvas: HTMLCanvasElement,
+  evolutionWorker: Worker,
+): PlaybackSessionContext {
+  // Step 1: Resolve the current viewport dimensions.
+  const viewportDimensions = resolvePlaybackViewportDimensions(canvas);
+
+  // Step 2: Start playback in the worker using the current viewport.
+  evolutionWorker.postMessage({
+    type: 'start-playback',
+    payload: viewportDimensions,
+  });
+
+  // Step 3: Build local render, trail, and loop state mirrors.
+  return {
+    renderState: createInitialRenderState(viewportDimensions),
+    trailState: createInitialTrailState(),
+    loopState: createInitialPlaybackLoopState(),
+  };
+}
+
+/**
+ * Synchronizes the render state viewport fields with the current canvas size.
+ *
+ * Playback can continue while the canvas size changes, so the browser refreshes
+ * its local viewport mirror rather than assuming dimensions stay fixed.
+ *
+ * @param canvas - Target playback canvas.
+ * @param renderState - Mutable render state updated in place.
+ * @returns Nothing.
+ */
+export function syncPlaybackViewportDimensions(
+  canvas: HTMLCanvasElement,
+  renderState: PopulationRenderState,
+): void {
+  // Step 1: Resolve current viewport dimensions from the canvas.
+  const viewportDimensions = resolvePlaybackViewportDimensions(canvas);
+
+  // Step 2: Store the current viewport dimensions on the mutable render state.
+  renderState.visibleWorldWidthPx = viewportDimensions.visibleWorldWidthPx;
+  renderState.visibleWorldHeightPx = viewportDimensions.visibleWorldHeightPx;
+}
+
+/**
+ * Folds the mutable loop summary into the public playback summary shape.
+ *
+ * The public summary is intentionally smaller than the internal loop state. It
+ * exposes the outcome, not the browser's intermediate bookkeeping.
+ *
+ * @param summary - Mutable loop summary accumulated during playback.
+ * @returns Public playback episode summary.
+ */
+export function resolvePlaybackEpisodeSummary(
+  summary: PlaybackMutableSummary,
+): PlaybackEpisodeSummary {
+  // Step 1: Return only the public aggregate fields.
+  return {
+    averagePipesPassed: summary.averagePipesPassed,
+    p90FramesSurvived: summary.p90FramesSurvived,
+    winnerPipesPassed: summary.winnerPipesPassed,
+    winnerFramesSurvived: summary.winnerFramesSurvived,
+  };
+}

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

@@ -0,0 +1,121 @@
+import type {
+  EvolutionPlaybackStepSnapshot,
+  PopulationRenderState,
+} from '../browser-entry.types';
+import { applyPlaybackSnapshot } from './playback.snapshot.utils';
+
+describe('applyPlaybackSnapshot', () => {
+  it('reuses the existing bird objects while decoding the packed snapshot', () => {
+    const snapshot = createSnapshot();
+    const renderState = createRenderStateWithOneBirdAndOnePipe();
+    const originalBirdReference = renderState.birds[0];
+
+    applyPlaybackSnapshot(renderState, snapshot);
+
+    expect(renderState.birds[0]).toBe(originalBirdReference);
+  });
+
+  it('decodes packed bird and pipe scalars into the reusable render state', () => {
+    const snapshot = createSnapshot();
+    const renderState = createRenderState();
+
+    applyPlaybackSnapshot(renderState, snapshot);
+
+    expect(renderState).toEqual({
+      frameIndex: 21,
+      cumulativePipeTravelPx: 84,
+      visibleWorldWidthPx: 640,
+      visibleWorldHeightPx: 480,
+      nextPipeId: 0,
+      lastSpawnedPipeGapPx: 0,
+      lastSpawnedPipeGapCenterYPx: 0,
+      lastSpawnedPipeSpawnIntervalFrames: 0,
+      framesUntilNextPipeSpawn: 0,
+      pipes: [
+        {
+          id: 0,
+          xPx: 250,
+          gapCenterYPx: 200,
+          gapSizePx: 110,
+        },
+      ],
+      birds: [
+        {
+          yPx: 150,
+          pipesPassed: 2,
+          framesSurvived: 17,
+          done: false,
+        },
+      ],
+    });
+  });
+});
+
+function createSnapshot(): EvolutionPlaybackStepSnapshot {
+  return {
+    format: 'packed-v1',
+    frameIndex: 21,
+    cumulativePipeTravelPx: 84,
+    visibleWorldWidthPx: 640,
+    visibleWorldHeightPx: 480,
+    pipeCount: 1,
+    birdCount: 1,
+    pipes: {
+      xPositionsPx: new Float32Array([250]),
+      gapCenterYPositionsPx: new Float32Array([200]),
+      gapSizesPx: new Float32Array([110]),
+    },
+    birds: {
+      yPositionsPx: new Float32Array([150]),
+      pipesPassed: new Uint32Array([2]),
+      framesSurvived: new Uint32Array([17]),
+      doneFlags: new Uint8Array([0]),
+    },
+  };
+}
+
+function createRenderStateWithOneBirdAndOnePipe(): PopulationRenderState {
+  return {
+    frameIndex: 0,
+    cumulativePipeTravelPx: 0,
+    visibleWorldWidthPx: 1,
+    visibleWorldHeightPx: 1,
+    nextPipeId: 0,
+    lastSpawnedPipeGapPx: 0,
+    lastSpawnedPipeGapCenterYPx: 0,
+    lastSpawnedPipeSpawnIntervalFrames: 0,
+    framesUntilNextPipeSpawn: 0,
+    pipes: [
+      {
+        id: 0,
+        xPx: 1,
+        gapCenterYPx: 2,
+        gapSizePx: 3,
+      },
+    ],
+    birds: [
+      {
+        yPx: 1,
+        pipesPassed: 2,
+        framesSurvived: 3,
+        done: true,
+      },
+    ],
+  };
+}
+
+function createRenderState(): PopulationRenderState {
+  return {
+    frameIndex: 0,
+    cumulativePipeTravelPx: 0,
+    visibleWorldWidthPx: 1,
+    visibleWorldHeightPx: 1,
+    nextPipeId: 0,
+    lastSpawnedPipeGapPx: 0,
+    lastSpawnedPipeGapCenterYPx: 0,
+    lastSpawnedPipeSpawnIntervalFrames: 0,
+    framesUntilNextPipeSpawn: 0,
+    pipes: [],
+    birds: [],
+  };
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Compatibility facade for playback snapshot helpers.
+ *
+ * Legacy imports still reach snapshot synchronization through this file while
+ * the implementation now lives in the dedicated snapshot folder.
+ */
+export { applyPlaybackSnapshot } from './snapshot/playback.snapshot.services';
+export { resolveLeaderFramesSurvived } from './snapshot/playback.snapshot.summary.utils';

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

@@ -0,0 +1,36 @@
+import { FLAPPY_STARFIELD_TILE_WIDTH_PX } from '../../constants/constants';
+import { createStarTileCanvas } from './playback.starfield.services';
+import type {
+  PlaybackStarfieldLayerSpec,
+  StarTile,
+} from './playback.starfield.types';
+
+/**
+ * Creates one cached tile layer from a declarative layer specification.
+ *
+ * @param layerSpec - Density and motion contract for a starfield layer.
+ * @param tileHeightPx - Height of the visible sky band in pixels.
+ * @returns Cached tile metadata for parallax drawing.
+ */
+export function createStarTile(
+  layerSpec: PlaybackStarfieldLayerSpec,
+  tileHeightPx: number,
+): StarTile {
+  // Step 1: Pre-render one deterministic tile for the requested layer.
+  return {
+    image: createStarTileCanvas({
+      seed: layerSpec.seed,
+      tileWidthPx: FLAPPY_STARFIELD_TILE_WIDTH_PX,
+      tileHeightPx,
+      starCount: layerSpec.starCount,
+      minSizePx: layerSpec.minSizePx,
+      maxSizePx: layerSpec.maxSizePx,
+      minAlpha: layerSpec.minAlpha,
+      maxAlpha: layerSpec.maxAlpha,
+      blurPx: layerSpec.blurPx,
+    }),
+    tileWidthPx: FLAPPY_STARFIELD_TILE_WIDTH_PX,
+    tileHeightPx,
+    scrollRatio: layerSpec.scrollRatio,
+  };
+}

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

@@ -1,13 +1,10 @@
 import {
-  FLAPPY_STARFIELD_CYAN_FILL_STYLE,
-  FLAPPY_STARFIELD_FAR_SCROLL_RATIO,
-  FLAPPY_STARFIELD_MID_SCROLL_RATIO,
-  FLAPPY_STARFIELD_NEAR_SCROLL_RATIO,
-  FLAPPY_STARFIELD_TILE_WIDTH_PX,
+  FLAPPY_STARFIELD_LAYER_SPECS,
+  FLAPPY_STARFIELD_MIN_DIMENSION_PX,
 } from '../../constants/constants';
 import { cachedStarfieldTilesByHeight } from './playback.constants';
-import { createSeededRandom } from './playback.starfield.utils';
-import type { StarTile } from './playback.types';
+import { createStarTile } from './playback.starfield.layer.services';
+import type { StarTile } from './playback.starfield.types';
 
 /**
  * Resolves (and lazily creates) cached starfield tile layers for the viewport.
@@ -18,132 +15,18 @@ import type { StarTile } from './playback.types';
 export function resolveStarfieldTiles(
   visibleWorldHeightPx: number,
 ): readonly StarTile[] {
-  const tileHeightPx = Math.max(1, Math.round(visibleWorldHeightPx));
+  const tileHeightPx = Math.max(
+    FLAPPY_STARFIELD_MIN_DIMENSION_PX,
+    Math.round(visibleWorldHeightPx),
+  );
   const cachedTilesForHeight = cachedStarfieldTilesByHeight.get(tileHeightPx);
   if (cachedTilesForHeight) {
     return cachedTilesForHeight;
   }
 
-  const farTile: StarTile = {
-    image: createStarTileCanvas({
-      seed: 1_337,
-      tileWidthPx: FLAPPY_STARFIELD_TILE_WIDTH_PX,
-      tileHeightPx,
-      starCount: 35,
-      minSizePx: 1,
-      maxSizePx: 2,
-      minAlpha: 0.08,
-      maxAlpha: 0.22,
-      blurPx: 4,
-    }),
-    tileWidthPx: FLAPPY_STARFIELD_TILE_WIDTH_PX,
-    tileHeightPx,
-    scrollRatio: FLAPPY_STARFIELD_FAR_SCROLL_RATIO,
-  };
-  const midTile: StarTile = {
-    image: createStarTileCanvas({
-      seed: 2_777,
-      tileWidthPx: FLAPPY_STARFIELD_TILE_WIDTH_PX,
-      tileHeightPx,
-      starCount: 28,
-      minSizePx: 1,
-      maxSizePx: 3,
-      minAlpha: 0.1,
-      maxAlpha: 0.28,
-      blurPx: 6,
-    }),
-    tileWidthPx: FLAPPY_STARFIELD_TILE_WIDTH_PX,
-    tileHeightPx,
-    scrollRatio: FLAPPY_STARFIELD_MID_SCROLL_RATIO,
-  };
-  const nearTile: StarTile = {
-    image: createStarTileCanvas({
-      seed: 4_242,
-      tileWidthPx: FLAPPY_STARFIELD_TILE_WIDTH_PX,
-      tileHeightPx,
-      starCount: 23,
-      minSizePx: 2,
-      maxSizePx: 4,
-      minAlpha: 0.12,
-      maxAlpha: 0.34,
-      blurPx: 8,
-    }),
-    tileWidthPx: FLAPPY_STARFIELD_TILE_WIDTH_PX,
-    tileHeightPx,
-    scrollRatio: FLAPPY_STARFIELD_NEAR_SCROLL_RATIO,
-  };
-
-  const resolvedTiles = [farTile, midTile, nearTile] as const;
+  const resolvedTiles = FLAPPY_STARFIELD_LAYER_SPECS.map((layerSpec) =>
+    createStarTile(layerSpec, tileHeightPx),
+  );
   cachedStarfieldTilesByHeight.set(tileHeightPx, resolvedTiles);
   return resolvedTiles;
 }
-
-function createStarTileCanvas(options: {
-  seed: number;
-  tileWidthPx: number;
-  tileHeightPx: number;
-  starCount: number;
-  minSizePx: number;
-  maxSizePx: number;
-  minAlpha: number;
-  maxAlpha: number;
-  blurPx: number;
-}): CanvasImageSource {
-  const canvas = createCompatibleCanvas(
-    options.tileWidthPx,
-    options.tileHeightPx,
-  );
-  const tileContext = canvas.getContext('2d');
-  if (!tileContext) {
-    return canvas;
-  }
-
-  const seededRandom = createSeededRandom(options.seed);
-
-  tileContext.clearRect(0, 0, canvas.width, canvas.height);
-  tileContext.globalCompositeOperation = 'source-over';
-  tileContext.shadowColor = FLAPPY_STARFIELD_CYAN_FILL_STYLE;
-  tileContext.shadowBlur = options.blurPx;
-
-  for (let starIndex = 0; starIndex < options.starCount; starIndex += 1) {
-    const xPx = Math.floor(seededRandom() * options.tileWidthPx);
-    const yPx = Math.floor(seededRandom() * options.tileHeightPx);
-    const sizePx =
-      options.minSizePx +
-      Math.floor(seededRandom() * (options.maxSizePx - options.minSizePx + 1));
-    const alpha =
-      options.minAlpha + seededRandom() * (options.maxAlpha - options.minAlpha);
-
-    tileContext.globalAlpha = alpha;
-    tileContext.fillStyle = FLAPPY_STARFIELD_CYAN_FILL_STYLE;
-    tileContext.fillRect(xPx, yPx, sizePx, sizePx);
-  }
-
-  tileContext.shadowBlur = 0;
-  tileContext.shadowColor = 'transparent';
-  tileContext.globalAlpha = 1;
-  return canvas;
-}
-
-function createCompatibleCanvas(
-  widthPx: number,
-  heightPx: number,
-): HTMLCanvasElement | OffscreenCanvas {
-  const width = Math.max(1, Math.round(widthPx));
-  const height = Math.max(1, Math.round(heightPx));
-
-  if (typeof OffscreenCanvas !== 'undefined') {
-    return new OffscreenCanvas(width, height);
-  }
-
-  if (typeof document !== 'undefined') {
-    const canvas = document.createElement('canvas');
-    canvas.width = width;
-    canvas.height = height;
-    return canvas;
-  }
-
-  // Fallback: non-browser environments won't render, but should not crash.
-  const canvas = { width, height } as unknown as HTMLCanvasElement;
-  return canvas;
-}