@reicek/neataptic-ts 0.1.21 → 0.1.23

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

@@ -0,0 +1,268 @@
+import {
+  FLAPPY_STARFIELD_CANVAS_CONTEXT_ID,
+  FLAPPY_STARFIELD_CYAN_FILL_STYLE,
+  FLAPPY_STARFIELD_COMPOSITE_SOURCE_OVER,
+  FLAPPY_STARFIELD_FULL_ALPHA,
+  FLAPPY_STARFIELD_INCLUSIVE_RANGE_OFFSET,
+  FLAPPY_STARFIELD_MIN_DIMENSION_PX,
+  FLAPPY_STARFIELD_ORIGIN_PX,
+} from '../../constants/constants';
+import { createSeededRandom } from './playback.starfield.utils';
+import type {
+  CreateStarTileCanvasOptions,
+  StarfieldCanvasDimensions,
+  StarPlacement,
+  StarTileImage,
+} from './playback.starfield.types';
+
+/**
+ * Pre-renders a deterministic tile that can be reused across animation frames.
+ *
+ * @param options - Declarative drawing recipe for one parallax layer.
+ * @returns Canvas image source containing the rendered star strip.
+ */
+export function createStarTileCanvas(
+  options: CreateStarTileCanvasOptions,
+): StarTileImage {
+  // Step 1: Allocate a compatible canvas for the requested tile dimensions.
+  const canvas = createCompatibleCanvas(
+    options.tileWidthPx,
+    options.tileHeightPx,
+  );
+
+  // Step 2: Resolve a 2D context when the runtime can actually render.
+  const tileContext = resolveStarTileContext(canvas);
+  if (!tileContext) {
+    return canvas;
+  }
+
+  // Step 3: Initialize drawing state and render deterministic stars.
+  const seededRandom = createSeededRandom(options.seed);
+  initializeStarTileContext({
+    tileContext,
+    canvas,
+  });
+  renderSeededStars({
+    tileContext,
+    seededRandom,
+    canvasOptions: options,
+  });
+
+  // Step 4: Restore neutral drawing state before handing the canvas back.
+  resetStarTileContext(tileContext);
+  return canvas;
+}
+
+/**
+ * Creates a browser-compatible canvas with clamped integer dimensions.
+ *
+ * @param widthPx - Requested tile width in pixels.
+ * @param heightPx - Requested tile height in pixels.
+ * @returns Offscreen canvas when supported, otherwise a DOM canvas fallback.
+ */
+function createCompatibleCanvas(
+  widthPx: number,
+  heightPx: number,
+): HTMLCanvasElement | OffscreenCanvas {
+  const canvasDimensions = normalizeCanvasDimensions(widthPx, heightPx);
+  const offscreenCanvas = createOffscreenCanvasIfSupported(canvasDimensions);
+  if (offscreenCanvas) {
+    return offscreenCanvas;
+  }
+
+  const documentCanvas = createDocumentCanvasIfSupported(canvasDimensions);
+  if (documentCanvas) {
+    return documentCanvas;
+  }
+
+  return createCanvasSizeFallback(canvasDimensions);
+}
+
+/**
+ * Resolves the rendering context used for star tile pre-rendering.
+ *
+ * @param canvas - Compatible canvas returned by the runtime-specific factory.
+ * @returns A 2D drawing context when rendering is supported.
+ */
+function resolveStarTileContext(
+  canvas: HTMLCanvasElement | OffscreenCanvas,
+): OffscreenCanvasRenderingContext2D | CanvasRenderingContext2D | null {
+  return canvas.getContext(FLAPPY_STARFIELD_CANVAS_CONTEXT_ID) as
+    | OffscreenCanvasRenderingContext2D
+    | CanvasRenderingContext2D
+    | null;
+}
+
+/**
+ * Clears the canvas and applies the neutral settings shared by all rendered stars.
+ *
+ * @param options - Context initialization dependencies.
+ * @returns Nothing. The provided context is mutated in place.
+ */
+function initializeStarTileContext(options: {
+  tileContext: OffscreenCanvasRenderingContext2D | CanvasRenderingContext2D;
+  canvas: HTMLCanvasElement | OffscreenCanvas;
+}): void {
+  options.tileContext.clearRect(
+    FLAPPY_STARFIELD_ORIGIN_PX,
+    FLAPPY_STARFIELD_ORIGIN_PX,
+    options.canvas.width,
+    options.canvas.height,
+  );
+  options.tileContext.globalCompositeOperation =
+    FLAPPY_STARFIELD_COMPOSITE_SOURCE_OVER;
+}
+
+/**
+ * Draws all stars for one tile using a seeded random source.
+ *
+ * @param options - Drawing context, seed source, and tile recipe.
+ * @returns Nothing. The provided context is mutated in place.
+ */
+function renderSeededStars(options: {
+  tileContext: OffscreenCanvasRenderingContext2D | CanvasRenderingContext2D;
+  seededRandom: () => number;
+  canvasOptions: CreateStarTileCanvasOptions;
+}): void {
+  for (
+    let starIndex = 0;
+    starIndex < options.canvasOptions.starCount;
+    starIndex += 1
+  ) {
+    const starPlacement = resolveStarPlacement({
+      seededRandom: options.seededRandom,
+      tileWidthPx: options.canvasOptions.tileWidthPx,
+      tileHeightPx: options.canvasOptions.tileHeightPx,
+      minSizePx: options.canvasOptions.minSizePx,
+      maxSizePx: options.canvasOptions.maxSizePx,
+      minAlpha: options.canvasOptions.minAlpha,
+      maxAlpha: options.canvasOptions.maxAlpha,
+    });
+
+    options.tileContext.globalAlpha = starPlacement.alpha;
+    options.tileContext.fillStyle = FLAPPY_STARFIELD_CYAN_FILL_STYLE;
+    options.tileContext.fillRect(
+      starPlacement.xPx,
+      starPlacement.yPx,
+      starPlacement.sizePx,
+      starPlacement.sizePx,
+    );
+  }
+}
+
+/**
+ * Restores neutral drawing state so later canvas consumers start from defaults.
+ *
+ * @param tileContext - 2D context used to render the star tile.
+ * @returns Nothing. The provided context is mutated in place.
+ */
+function resetStarTileContext(
+  tileContext: OffscreenCanvasRenderingContext2D | CanvasRenderingContext2D,
+): void {
+  tileContext.globalAlpha = FLAPPY_STARFIELD_FULL_ALPHA;
+}
+
+/**
+ * Normalizes requested canvas dimensions into positive integer pixel sizes.
+ *
+ * @param widthPx - Requested width in pixels.
+ * @param heightPx - Requested height in pixels.
+ * @returns Clamped integer dimensions safe for canvas allocation.
+ */
+function normalizeCanvasDimensions(
+  widthPx: number,
+  heightPx: number,
+): StarfieldCanvasDimensions {
+  return {
+    width: Math.max(FLAPPY_STARFIELD_MIN_DIMENSION_PX, Math.round(widthPx)),
+    height: Math.max(FLAPPY_STARFIELD_MIN_DIMENSION_PX, Math.round(heightPx)),
+  };
+}
+
+/**
+ * Creates an offscreen canvas when the current runtime supports it.
+ *
+ * @param canvasDimensions - Already-normalized pixel dimensions.
+ * @returns Offscreen canvas instance or `null` when unavailable.
+ */
+function createOffscreenCanvasIfSupported(
+  canvasDimensions: StarfieldCanvasDimensions,
+): OffscreenCanvas | null {
+  if (typeof OffscreenCanvas !== 'undefined') {
+    return new OffscreenCanvas(canvasDimensions.width, canvasDimensions.height);
+  }
+
+  return null;
+}
+
+/**
+ * Creates a DOM canvas when document APIs are available.
+ *
+ * @param canvasDimensions - Already-normalized pixel dimensions.
+ * @returns DOM canvas instance or `null` when unavailable.
+ */
+function createDocumentCanvasIfSupported(
+  canvasDimensions: StarfieldCanvasDimensions,
+): HTMLCanvasElement | null {
+  if (typeof document !== 'undefined') {
+    const canvas = document.createElement('canvas');
+    canvas.width = canvasDimensions.width;
+    canvas.height = canvasDimensions.height;
+    return canvas;
+  }
+
+  return null;
+}
+
+/**
+ * Creates a size-only fallback so non-browser tests can skip rendering safely.
+ *
+ * @param canvasDimensions - Already-normalized pixel dimensions.
+ * @returns Minimal canvas-shaped object cast to the compatible return type.
+ */
+function createCanvasSizeFallback(
+  canvasDimensions: StarfieldCanvasDimensions,
+): HTMLCanvasElement {
+  const canvas = {
+    width: canvasDimensions.width,
+    height: canvasDimensions.height,
+  } as Partial<HTMLCanvasElement> as HTMLCanvasElement;
+  return canvas;
+}
+
+/**
+ * Resolves one deterministic star placement and appearance from the seeded RNG.
+ *
+ * @param options - Random source and star placement bounds.
+ * @returns Pixel location, square size, and alpha for one rendered star.
+ */
+function resolveStarPlacement(options: {
+  seededRandom: () => number;
+  tileWidthPx: number;
+  tileHeightPx: number;
+  minSizePx: number;
+  maxSizePx: number;
+  minAlpha: number;
+  maxAlpha: number;
+}): StarPlacement {
+  const xPx = Math.floor(options.seededRandom() * options.tileWidthPx);
+  const yPx = Math.floor(options.seededRandom() * options.tileHeightPx);
+  const sizePx =
+    options.minSizePx +
+    Math.floor(
+      options.seededRandom() *
+        (options.maxSizePx -
+          options.minSizePx +
+          FLAPPY_STARFIELD_INCLUSIVE_RANGE_OFFSET),
+    );
+  const alpha =
+    options.minAlpha +
+    options.seededRandom() * (options.maxAlpha - options.minAlpha);
+
+  return {
+    xPx,
+    yPx,
+    sizePx,
+    alpha,
+  };
+}

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

@@ -0,0 +1,91 @@
+/**
+ * Starfield and parallax rendering contracts for playback backgrounds.
+ *
+ * The playback view uses a cached layered starfield to add depth without paying
+ * a large per-frame rendering cost. These types define the tile, layer, and
+ * deterministic placement data needed for that effect.
+ */
+
+/**
+ * Shared type contract for starfield tile rendering layers.
+ *
+ * A tile is pre-rendered and repeated horizontally to draw efficient
+ * parallax backgrounds during playback.
+ */
+export type StarTileImage = HTMLCanvasElement | OffscreenCanvas;
+
+/**
+ * Shared type contract for starfield tile rendering layers.
+ *
+ * A tile is pre-rendered and repeated horizontally to draw efficient
+ * parallax backgrounds during playback.
+ *
+ * Separating the image type from the tile record lets the same starfield logic
+ * work with ordinary canvases and `OffscreenCanvas` when available.
+ */
+export type StarTile = {
+  image: StarTileImage;
+  tileWidthPx: number;
+  tileHeightPx: number;
+  scrollRatio: number;
+};
+
+/**
+ * Declarative recipe for building one cached starfield parallax layer.
+ *
+ * Each layer spec describes how dense, bright, blurred, and fast one visual
+ * depth plane should feel.
+ */
+export type PlaybackStarfieldLayerSpec = {
+  seed: number;
+  scrollRatio: number;
+  starCount: number;
+  minSizePx: number;
+  maxSizePx: number;
+  minAlpha: number;
+  maxAlpha: number;
+  blurPx: number;
+};
+
+/**
+ * Input contract for pre-rendering one deterministic starfield tile.
+ *
+ * The generated tile is cached and repeated horizontally during playback,
+ * so every field here affects both the visual look and the parallax cost.
+ */
+export type CreateStarTileCanvasOptions = {
+  seed: number;
+  tileWidthPx: number;
+  tileHeightPx: number;
+  starCount: number;
+  minSizePx: number;
+  maxSizePx: number;
+  minAlpha: number;
+  maxAlpha: number;
+  blurPx: number;
+};
+
+/**
+ * Normalized canvas dimensions used by browser and offscreen tile creation.
+ *
+ * The creation path works with both `HTMLCanvasElement` and `OffscreenCanvas`,
+ * so dimensions are stored in a narrow shared shape rather than tied to one DOM
+ * type.
+ */
+export type StarfieldCanvasDimensions = {
+  width: number;
+  height: number;
+};
+
+/**
+ * Deterministic placement and appearance for one rendered star sprite.
+ *
+ * Determinism matters here because cached starfield tiles should remain stable
+ * across redraws instead of sparkling randomly every frame.
+ */
+export type StarPlacement = {
+  xPx: number;
+  yPx: number;
+  sizePx: number;
+  alpha: number;
+};

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

@@ -1,3 +1,10 @@
+import {
+  FLAPPY_STARFIELD_UNSIGNED_NORMALIZATION_DIVISOR,
+  FLAPPY_STARFIELD_XORSHIFT_LEFT_SHIFT_FINAL,
+  FLAPPY_STARFIELD_XORSHIFT_LEFT_SHIFT_PRIMARY,
+  FLAPPY_STARFIELD_XORSHIFT_RIGHT_SHIFT,
+} from '../../constants/constants';
+
 /**
  * Creates a deterministic pseudo-random generator for starfield tile layouts.
  *
@@ -9,15 +16,15 @@ export function createSeededRandom(seed: number): () => number {
 
   return () => {
     // Step 1: Apply xorshift32 state transitions.
-    randomState ^= randomState << 13;
+    randomState ^= randomState << FLAPPY_STARFIELD_XORSHIFT_LEFT_SHIFT_PRIMARY;
     randomState >>>= 0;
-    randomState ^= randomState >> 17;
+    randomState ^= randomState >> FLAPPY_STARFIELD_XORSHIFT_RIGHT_SHIFT;
     randomState >>>= 0;
-    randomState ^= randomState << 5;
+    randomState ^= randomState << FLAPPY_STARFIELD_XORSHIFT_LEFT_SHIFT_FINAL;
     randomState >>>= 0;
 
     // Step 2: Normalize 32-bit unsigned state into [0, 1).
-    return randomState / 0x1_0000_0000;
+    return randomState / FLAPPY_STARFIELD_UNSIGNED_NORMALIZATION_DIVISOR;
   };
 }
 

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

@@ -1,86 +1,9 @@
-import {
-  FLAPPY_TRAIL_EDGE_FADE_DISTANCE_PX,
-  FLAPPY_TRAIL_MAX_POINTS,
-} from '../../constants/constants';
-import type { PlaybackEdgeBounds } from './playback.types';
-import type { TrailPoint } from '../browser-entry.types';
-
-/**
- * Appends one trail point while enforcing max retained history length.
- *
- * @param trailPoints - Mutable trail collection.
- * @param frameIndex - Source frame index.
- * @param yPosition - Bird y position.
- * @returns Nothing.
- */
-export function pushTrailPoint(
-  trailPoints: TrailPoint[],
-  frameIndex: number,
-  yPosition: number,
-): void {
-  trailPoints.push({ frameIndex, yPx: yPosition });
-  const maxTrailPoints = FLAPPY_TRAIL_MAX_POINTS;
-  if (trailPoints.length > maxTrailPoints) {
-    trailPoints.splice(0, trailPoints.length - maxTrailPoints);
-  }
-}
-
-/**
- * Converts distance-to-edge into a normalized opacity factor.
- *
- * 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.
- *
- * 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.
- *
- * @param value - Candidate value.
- * @returns Clamped value.
- */
-export function clamp01(value: number): number {
-  return Math.max(0, Math.min(1, value));
-}
+export {
+  pushChampionTrailPoint,
+  pushTrailPoint,
+} from './trail/playback.trail.history.services';
+export {
+  clamp01,
+  resolveEdgeOpacityFactor,
+  resolveTrailLifetimeOpacityFactor,
+} from './trail/playback.trail.opacity.utils';

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

@@ -1,26 +1,50 @@
 import type { PlaybackFrameStats } from '../browser-entry.types';
-import { animatePopulationEpisodeInternal } from '../browser-entry.playback.utils';
+import { renderPopulationFrame } from './frame-render/playback.frame-render.service';
+import { runPlaybackLoop } from './playback.iteration.services';
+import type { PlaybackEpisodeSummary } from './playback.orchestration.types';
+import {
+  initializePlaybackSessionContext,
+  resolvePlaybackEpisodeSummary,
+} from './playback.session.services';
+
+export type { PlaybackEpisodeSummary } from './playback.orchestration.types';
+
+/**
+ * Public playback orchestration for the Flappy Bird browser demo.
+ *
+ * Playback is the bridge between off-thread simulation and on-screen
+ * visualization. The worker advances the world and streams packed snapshots;
+ * this layer mirrors enough state locally to animate those snapshots at browser
+ * frame cadence, render trails and backgrounds, and emit HUD telemetry.
+ */
 
 /**
  * Public playback entry point used by browser runtime orchestration.
  *
+ * Conceptually, this answers: "play one worker-produced episode on the canvas
+ * until it is done, and tell me what happened along the way".
+ *
  * @param canvas - Target playback canvas.
  * @param context - Canvas 2D context.
  * @param evolutionWorker - Worker owning playback simulation state.
  * @param onFrameStats - Callback receiving per-frame playback telemetry.
  * @returns Aggregate playback summary for the current episode.
+ * @example
+ * ```ts
+ * const summary = await animatePopulationEpisode(
+ *   canvas,
+ *   context,
+ *   evolutionWorker,
+ *   (stats) => updateHud(stats),
+ * );
+ * ```
  */
 export async function animatePopulationEpisode(
   canvas: HTMLCanvasElement,
   context: CanvasRenderingContext2D,
   evolutionWorker: Worker,
   onFrameStats: (stats: PlaybackFrameStats) => void,
-): Promise<{
-  averagePipesPassed: number;
-  p90FramesSurvived: number;
-  winnerPipesPassed: number;
-  winnerFramesSurvived: number;
-}> {
+): Promise<PlaybackEpisodeSummary> {
   return animatePopulationEpisodeInternal(
     canvas,
     context,
@@ -28,3 +52,47 @@ export async function animatePopulationEpisode(
     onFrameStats,
   );
 }
+
+/**
+ * Internal playback orchestration entry retained for compatibility re-exports.
+ *
+ * The implementation is shared with the public entry so legacy imports and the
+ * newer folderized surface behave identically.
+ *
+ * @param canvas - Target playback canvas.
+ * @param context - Canvas 2D context.
+ * @param evolutionWorker - Worker owning playback simulation state.
+ * @param onFrameStats - Callback receiving per-frame playback telemetry.
+ * @returns Aggregate playback summary for the current episode.
+ */
+export async function animatePopulationEpisodeInternal(
+  canvas: HTMLCanvasElement,
+  context: CanvasRenderingContext2D,
+  evolutionWorker: Worker,
+  onFrameStats: (stats: PlaybackFrameStats) => void,
+): Promise<PlaybackEpisodeSummary> {
+  // Step 1: Initialize worker playback state and local render mirrors.
+  const sessionContext = initializePlaybackSessionContext(
+    canvas,
+    evolutionWorker,
+  );
+
+  // Step 2: Run playback iterations until the worker reports completion.
+  await runPlaybackLoop({
+    canvas,
+    context,
+    evolutionWorker,
+    onFrameStats,
+    sessionContext,
+  });
+
+  // Step 3: Render the final settled frame for the completed episode.
+  renderPopulationFrame(
+    context,
+    sessionContext.renderState,
+    sessionContext.trailState,
+  );
+
+  // Step 4: Fold the mutable loop summary into the public return shape.
+  return resolvePlaybackEpisodeSummary(sessionContext.loopState.summary);
+}

package/test/examples/flappy_bird/browser-entry/playback/playback.types.ts

@@ -1,18 +1,21 @@
+export type {
+  PlaybackStarfieldLayerSpec,
+  StarTile,
+} from './playback.starfield.types';
+
 /**
- * Shared type contract for starfield tile rendering layers.
+ * Shared playback utility types for the browser-entry subsystem.
  *
- * A tile is pre-rendered and repeated horizontally to draw efficient
- * parallax backgrounds during playback.
+ * These types support rendering concerns that cut across multiple playback
+ * helpers, such as edge-aware trail fading and cached parallax backgrounds.
  */
-export type StarTile = {
-  image: CanvasImageSource;
-  tileWidthPx: number;
-  tileHeightPx: number;
-  scrollRatio: number;
-};
 
 /**
  * Axis-aligned visible world bounds used for edge-aware trail fading.
+ *
+ * Trail rendering needs a quick answer to "is this point still visually inside
+ * the active world rectangle?" so fading logic can taper paths near the edges
+ * instead of drawing abrupt cutoffs.
  */
 export type PlaybackEdgeBounds = {
   leftXPx: number;