@reicek/neataptic-ts 0.1.21 → 0.1.23

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

@@ -0,0 +1,192 @@
+import {
+  resolveAliveBirdCount,
+  resolveLeaderPipesPassed,
+} from '../browser-entry.observation.utils';
+import { requestWorkerPlaybackStep } from '../worker-channel/worker-channel';
+import { FLAPPY_EMULATION_SPEED_MULTIPLIER } from '../../constants/constants';
+import {
+  renderPopulationFrame,
+  updateTrailState,
+} from './frame-render/playback.frame-render.service';
+import { nextAnimationFrame } from './playback.loop.service';
+import {
+  applyPlaybackSnapshot,
+  resolveLeaderFramesSurvived,
+} from './playback.snapshot.utils';
+import type {
+  PlaybackIterationContext,
+  PlaybackLoopState,
+  PlaybackSessionContext,
+} from './playback.orchestration.types';
+import { syncPlaybackViewportDimensions } from './playback.session.services';
+import {
+  resolvePlaybackCompletionSummary,
+  resolvePlaybackFrameStats,
+  resolvePlaybackStepRequest,
+} from './playback.worker-channel.utils';
+
+/**
+ * Runs playback iterations until the worker reports that the episode is done.
+ *
+ * @param iterationContext - Shared loop dependencies and mutable playback state.
+ * @returns Nothing.
+ */
+export async function runPlaybackLoop(
+  iterationContext: PlaybackIterationContext,
+): Promise<void> {
+  // Step 1: Continue iterating until the mutable loop state reports completion.
+  while (!iterationContext.sessionContext.loopState.finished) {
+    await runPlaybackIteration(iterationContext);
+  }
+}
+
+/**
+ * Executes one playback iteration from viewport sync through render pacing.
+ *
+ * @param iterationContext - Shared loop dependencies and mutable playback state.
+ * @returns Nothing.
+ */
+export async function runPlaybackIteration(
+  iterationContext: PlaybackIterationContext,
+): Promise<void> {
+  // Step 1: Sync viewport size and request the next worker playback step.
+  syncPlaybackViewportDimensions(
+    iterationContext.canvas,
+    iterationContext.sessionContext.renderState,
+  );
+  const playbackStepPayload =
+    await requestPlaybackStepPayload(iterationContext);
+
+  // Step 2: Fold the worker snapshot into local render and trail state.
+  applyPlaybackStepSnapshot(
+    iterationContext.sessionContext,
+    playbackStepPayload.snapshot,
+  );
+
+  // Step 3: Resolve telemetry metrics and emit the frame stats callback.
+  emitPlaybackFrameStats(iterationContext, playbackStepPayload);
+
+  // Step 4: Update loop completion state when the worker marks playback done.
+  updatePlaybackLoopCompletion(
+    iterationContext.sessionContext.loopState,
+    playbackStepPayload,
+  );
+
+  // Step 5: Render the frame and yield to the browser when playback continues.
+  renderPopulationFrame(
+    iterationContext.context,
+    iterationContext.sessionContext.renderState,
+    iterationContext.sessionContext.trailState,
+  );
+  if (!iterationContext.sessionContext.loopState.finished) {
+    await nextAnimationFrame();
+  }
+}
+
+/**
+ * Requests one playback step batch from the evolution worker.
+ *
+ * @param iterationContext - Shared loop dependencies and mutable playback state.
+ * @returns Worker playback step payload for the current iteration.
+ */
+export async function requestPlaybackStepPayload(
+  iterationContext: PlaybackIterationContext,
+): Promise<Awaited<ReturnType<typeof requestWorkerPlaybackStep>>> {
+  // Step 1: Resolve the worker request from the current loop budget and viewport.
+  const { renderState, loopState } = iterationContext.sessionContext;
+  const { simulationFrameBudgetRemainder, playbackStepRequest } =
+    resolvePlaybackStepRequest({
+      simulationFrameBudget: loopState.simulationFrameBudget,
+      visibleWorldWidthPx: renderState.visibleWorldWidthPx,
+      visibleWorldHeightPx: renderState.visibleWorldHeightPx,
+      emulationSpeedMultiplier: FLAPPY_EMULATION_SPEED_MULTIPLIER,
+    });
+  loopState.simulationFrameBudget = simulationFrameBudgetRemainder;
+
+  // Step 2: Request the next playback step from the worker.
+  return requestWorkerPlaybackStep(
+    iterationContext.evolutionWorker,
+    playbackStepRequest,
+  );
+}
+
+/**
+ * Applies the latest worker snapshot to render state and trail caches.
+ *
+ * @param sessionContext - Shared mutable playback session state.
+ * @param snapshot - Worker snapshot for the current playback batch.
+ * @returns Nothing.
+ */
+export function applyPlaybackStepSnapshot(
+  sessionContext: PlaybackSessionContext,
+  snapshot: Parameters<typeof applyPlaybackSnapshot>[1],
+): void {
+  // Step 1: Fold the worker snapshot into the mutable render state.
+  applyPlaybackSnapshot(sessionContext.renderState, snapshot);
+
+  // Step 2: Refresh the bird trail cache from the updated render state.
+  updateTrailState(sessionContext.trailState, sessionContext.renderState);
+}
+
+/**
+ * Resolves leader telemetry and emits the public frame-stats callback.
+ *
+ * @param iterationContext - Shared loop dependencies and mutable playback state.
+ * @param playbackStepPayload - Worker playback result for the current iteration.
+ * @returns Nothing.
+ */
+export function emitPlaybackFrameStats(
+  iterationContext: PlaybackIterationContext,
+  playbackStepPayload: Awaited<ReturnType<typeof requestWorkerPlaybackStep>>,
+): void {
+  // Step 1: Resolve leader metrics from the updated render state.
+  const { renderState, loopState } = iterationContext.sessionContext;
+  const leaderPipesPassed = resolveLeaderPipesPassed(renderState.birds);
+  const leaderFramesSurvived = resolveLeaderFramesSurvived(renderState);
+  loopState.summary.latestLeaderPipesPassed = leaderPipesPassed;
+  loopState.summary.latestLeaderFramesSurvived = leaderFramesSurvived;
+
+  // Step 2: Emit frame telemetry for HUD and runtime consumers.
+  iterationContext.onFrameStats(
+    resolvePlaybackFrameStats(
+      playbackStepPayload,
+      renderState.frameIndex,
+      resolveAliveBirdCount(renderState.birds),
+      leaderPipesPassed,
+      leaderFramesSurvived,
+    ),
+  );
+}
+
+/**
+ * Updates the loop summary when the worker reports playback completion.
+ *
+ * @param loopState - Mutable playback loop state.
+ * @param playbackStepPayload - Worker playback result for the current iteration.
+ * @returns Nothing.
+ */
+export function updatePlaybackLoopCompletion(
+  loopState: PlaybackLoopState,
+  playbackStepPayload: Awaited<ReturnType<typeof requestWorkerPlaybackStep>>,
+): void {
+  // Step 1: Skip summary folding until the worker marks playback complete.
+  if (!playbackStepPayload.done) {
+    return;
+  }
+
+  // Step 2: Fold the final aggregate summary into the mutable loop state.
+  const playbackCompletionSummary = resolvePlaybackCompletionSummary(
+    playbackStepPayload,
+    loopState.summary.latestLeaderPipesPassed,
+    loopState.summary.latestLeaderFramesSurvived,
+  );
+  loopState.finished = true;
+  loopState.summary.averagePipesPassed =
+    playbackCompletionSummary.averagePipesPassed;
+  loopState.summary.p90FramesSurvived =
+    playbackCompletionSummary.p90FramesSurvived;
+  loopState.summary.winnerPipesPassed =
+    playbackCompletionSummary.winnerPipesPassed;
+  loopState.summary.winnerFramesSurvived =
+    playbackCompletionSummary.winnerFramesSurvived;
+}

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

@@ -1,8 +1,20 @@
 import { PlaybackAnimationFrameUnavailableError } from './playback.errors';
 
+/**
+ * Browser frame-pacing helpers for playback animation.
+ *
+ * The playback loop advances worker simulation in batches but still presents
+ * frames at browser animation cadence. This module isolates the
+ * `requestAnimationFrame` dependency so playback orchestration can read more
+ * clearly and fail with a targeted error when RAF is unavailable.
+ */
+
 /**
  * Yields until the next browser animation frame.
  *
+ * In browser rendering terms, this is the pacing boundary between simulation
+ * work and visible painting.
+ *
  * @returns Promise resolved on next animation frame.
  */
 export function nextAnimationFrame(): Promise<void> {

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

@@ -0,0 +1,78 @@
+import type {
+  PlaybackFrameStats,
+  PopulationRenderState,
+  TrailState,
+} from '../browser-entry.types';
+
+/**
+ * Playback orchestration contracts for the Flappy Bird browser demo.
+ *
+ * These types describe the moving pieces of one playback episode: the public
+ * summary returned at the end, the mutable loop bookkeeping used while frames
+ * are streaming, and the session context mirrored locally in the browser.
+ */
+
+/**
+ * Public aggregate playback summary returned after one episode completes.
+ *
+ * The summary captures the headline outcomes of the just-finished population
+ * run without exposing all internal frame-by-frame details.
+ */
+export type PlaybackEpisodeSummary = {
+  averagePipesPassed: number;
+  p90FramesSurvived: number;
+  winnerPipesPassed: number;
+  winnerFramesSurvived: number;
+};
+
+/**
+ * Mutable playback summary extended with latest leader telemetry fallbacks.
+ *
+ * During playback the browser may need temporary "latest known" values before
+ * the worker emits final aggregate statistics, so the mutable form carries both
+ * final fields and rolling fallbacks.
+ */
+export type PlaybackMutableSummary = PlaybackEpisodeSummary & {
+  latestLeaderPipesPassed: number;
+  latestLeaderFramesSurvived: number;
+};
+
+/**
+ * Mutable loop bookkeeping shared across playback iterations.
+ *
+ * This is the browser-side state machine for the playback loop: how much
+ * simulation budget is being requested, whether the episode has finished, and
+ * what aggregate summary has been observed so far.
+ */
+export type PlaybackLoopState = {
+  simulationFrameBudget: number;
+  finished: boolean;
+  summary: PlaybackMutableSummary;
+};
+
+/**
+ * Shared mutable playback state mirrored locally while worker playback runs.
+ *
+ * The worker remains the source of truth for simulation, but the browser keeps
+ * lightweight mirrored state for rendering, trail accumulation, and loop
+ * orchestration.
+ */
+export type PlaybackSessionContext = {
+  renderState: PopulationRenderState;
+  trailState: TrailState;
+  loopState: PlaybackLoopState;
+};
+
+/**
+ * Shared dependencies and mutable state used by one playback iteration.
+ *
+ * Grouping these fields into one context object keeps the iteration services
+ * declarative and avoids long parameter lists across the playback loop.
+ */
+export type PlaybackIterationContext = {
+  canvas: HTMLCanvasElement;
+  context: CanvasRenderingContext2D;
+  evolutionWorker: Worker;
+  onFrameStats: (stats: PlaybackFrameStats) => void;
+  sessionContext: PlaybackSessionContext;
+};

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

@@ -0,0 +1,128 @@
+import {
+  FLAPPY_PIPE_ENTRY_RIM_INSET_PX,
+  FLAPPY_NEON_PALETTE,
+  FLAPPY_PIPE_OUTLINE_CYAN_GLOW_BLUR_PX,
+  FLAPPY_PIPE_OUTLINE_CYAN_GLOW_COLOR,
+  FLAPPY_PIPE_OUTLINE_GLOW_ALPHA,
+  FLAPPY_PIPE_OUTLINE_GLOW_STROKE_WIDTH_PX,
+  FLAPPY_PIPE_OUTLINE_STROKE_WIDTH_PX,
+} from '../../constants/constants';
+
+/**
+ * Draws a simplified neon outline around a pipe rectangle.
+ *
+ * @param context - Canvas 2D context.
+ * @param rectangleLeftPx - Rectangle left position.
+ * @param rectangleTopPx - Rectangle top position.
+ * @param rectangleWidthPx - Rectangle width.
+ * @param rectangleHeightPx - Rectangle height.
+ * @returns Nothing.
+ */
+export function drawPipeNeonOutline(
+  context: CanvasRenderingContext2D,
+  rectangleLeftPx: number,
+  rectangleTopPx: number,
+  rectangleWidthPx: number,
+  rectangleHeightPx: number,
+): void {
+  context.save();
+  if (rectangleWidthPx <= 0 || rectangleHeightPx <= 0) {
+    context.restore();
+    return;
+  }
+
+  const alignedRectangle = resolveAlignedPipeOutlineRectangle({
+    rectangleLeftPx,
+    rectangleTopPx,
+    rectangleWidthPx,
+    rectangleHeightPx,
+  });
+  const pipeOutlinePath = resolvePipeOutlinePath(alignedRectangle);
+
+  const previousCompositeOperation = context.globalCompositeOperation;
+  context.globalCompositeOperation = 'lighter';
+  context.strokeStyle = FLAPPY_NEON_PALETTE.pipeFill;
+
+  context.globalAlpha = FLAPPY_PIPE_OUTLINE_GLOW_ALPHA;
+  context.shadowColor = FLAPPY_PIPE_OUTLINE_CYAN_GLOW_COLOR;
+  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.stroke(pipeOutlinePath);
+
+  context.globalAlpha = 1;
+  context.shadowBlur = 0;
+  context.shadowColor = 'transparent';
+  context.lineWidth = FLAPPY_PIPE_OUTLINE_STROKE_WIDTH_PX;
+  context.stroke(pipeOutlinePath);
+
+  context.globalCompositeOperation = previousCompositeOperation;
+  context.restore();
+}
+
+/**
+ * Resolves a pixel-aligned rectangle used by the pipe outline renderer.
+ *
+ * @param input - Raw pipe rectangle values.
+ * @returns Aligned rectangle ready for outline rendering.
+ */
+function resolveAlignedPipeOutlineRectangle(input: {
+  rectangleLeftPx: number;
+  rectangleTopPx: number;
+  rectangleWidthPx: number;
+  rectangleHeightPx: number;
+}): {
+  alignedLeftPx: number;
+  alignedTopPx: number;
+  alignedWidthPx: number;
+  alignedHeightPx: number;
+} {
+  return {
+    alignedLeftPx: Math.round(input.rectangleLeftPx),
+    alignedTopPx: Math.round(input.rectangleTopPx),
+    alignedWidthPx: Math.max(1, Math.round(input.rectangleWidthPx)),
+    alignedHeightPx: Math.max(1, Math.round(input.rectangleHeightPx)),
+  };
+}
+
+/**
+ * Resolves the reusable outline path for one pipe body and its entrance rim.
+ *
+ * @param alignedRectangle - Pixel-aligned rectangle used by the outline renderer.
+ * @returns Path containing the outer pipe outline and optional entrance rim.
+ */
+function resolvePipeOutlinePath(alignedRectangle: {
+  alignedLeftPx: number;
+  alignedTopPx: number;
+  alignedWidthPx: number;
+  alignedHeightPx: number;
+}): Path2D {
+  const isTopPipeSegment = alignedRectangle.alignedTopPx === 0;
+  const entranceLineYPx = isTopPipeSegment
+    ? alignedRectangle.alignedTopPx +
+      alignedRectangle.alignedHeightPx -
+      FLAPPY_PIPE_ENTRY_RIM_INSET_PX
+    : alignedRectangle.alignedTopPx + FLAPPY_PIPE_ENTRY_RIM_INSET_PX;
+  const pipeOutlinePath = new Path2D();
+
+  pipeOutlinePath.rect(
+    alignedRectangle.alignedLeftPx,
+    alignedRectangle.alignedTopPx,
+    alignedRectangle.alignedWidthPx,
+    alignedRectangle.alignedHeightPx,
+  );
+  if (
+    entranceLineYPx > alignedRectangle.alignedTopPx &&
+    entranceLineYPx <
+      alignedRectangle.alignedTopPx + alignedRectangle.alignedHeightPx
+  ) {
+    pipeOutlinePath.moveTo(alignedRectangle.alignedLeftPx, entranceLineYPx);
+    pipeOutlinePath.lineTo(
+      alignedRectangle.alignedLeftPx + alignedRectangle.alignedWidthPx,
+      entranceLineYPx,
+    );
+  }
+
+  return pipeOutlinePath;
+}

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

@@ -1,116 +1 @@
-import {
-  FLAPPY_NEON_PALETTE,
-  FLAPPY_PIPE_OUTLINE_CYAN_GLOW_BLUR_PX,
-  FLAPPY_PIPE_OUTLINE_CYAN_GLOW_COLOR,
-  FLAPPY_PIPE_OUTLINE_ENTRANCE_GAP_PX,
-  FLAPPY_PIPE_OUTLINE_GLOW_ALPHA,
-  FLAPPY_PIPE_OUTLINE_GLOW_STROKE_WIDTH_PX,
-  FLAPPY_PIPE_OUTLINE_SIDE_GAP_PX,
-  FLAPPY_PIPE_OUTLINE_STROKE_WIDTH_PX,
-} from '../../constants/constants';
-
-/**
- * Draws a simplified neon outline around a pipe rectangle.
- *
- * @param context - Canvas 2D context.
- * @param rectangleLeftPx - Rectangle left position.
- * @param rectangleTopPx - Rectangle top position.
- * @param rectangleWidthPx - Rectangle width.
- * @param rectangleHeightPx - Rectangle height.
- * @returns Nothing.
- */
-export function drawPipeNeonOutline(
-  context: CanvasRenderingContext2D,
-  rectangleLeftPx: number,
-  rectangleTopPx: number,
-  rectangleWidthPx: number,
-  rectangleHeightPx: number,
-): void {
-  context.save();
-  // Step 1: Guard degenerate rectangles.
-  if (rectangleWidthPx <= 0 || rectangleHeightPx <= 0) {
-    context.restore();
-    return;
-  }
-
-  const alignedLeftPx = Math.round(rectangleLeftPx);
-  const alignedTopPx = Math.round(rectangleTopPx);
-  const alignedWidthPx = Math.max(1, Math.round(rectangleWidthPx));
-  const alignedHeightPx = Math.max(1, Math.round(rectangleHeightPx));
-
-  // Step 2: Compute outline geometry.
-  // We want a small side gap and a larger "entrance" gap (top for bottom pipe,
-  // bottom for top pipe) to suggest a pipe rim.
-  const outlineStrokeWidthPx = FLAPPY_PIPE_OUTLINE_STROKE_WIDTH_PX;
-  const outlineStrokeHalfPx = outlineStrokeWidthPx / 2;
-  const sideExpandPx = Math.round(
-    FLAPPY_PIPE_OUTLINE_SIDE_GAP_PX + outlineStrokeHalfPx,
-  );
-  const entranceExpandPx = Math.round(
-    FLAPPY_PIPE_OUTLINE_ENTRANCE_GAP_PX + outlineStrokeHalfPx,
-  );
-
-  const isTopPipeSegment = alignedTopPx === 0;
-  const outlineTopExpandPx = isTopPipeSegment ? sideExpandPx : entranceExpandPx;
-  const outlineBottomExpandPx = isTopPipeSegment
-    ? entranceExpandPx
-    : sideExpandPx;
-
-  const outlineLeftPx = alignedLeftPx - sideExpandPx;
-  const outlineTopPx = alignedTopPx - outlineTopExpandPx;
-  const outlineWidthPx = alignedWidthPx + sideExpandPx * 2;
-  const outlineHeightPx =
-    alignedHeightPx + outlineTopExpandPx + outlineBottomExpandPx;
-
-  // Step 3: Define pixel-aligned stroke helper to avoid blurry edges.
-  const strokeAlignedRect = (
-    leftPx: number,
-    topPx: number,
-    widthPx: number,
-    heightPx: number,
-    lineWidthPx: number,
-  ): void => {
-    const oddLineAlignmentOffsetPx = lineWidthPx % 2 === 1 ? 0.5 : 0;
-    context.lineWidth = lineWidthPx;
-    context.strokeRect(
-      Math.round(leftPx) + oddLineAlignmentOffsetPx,
-      Math.round(topPx) + oddLineAlignmentOffsetPx,
-      Math.max(1, Math.round(widthPx)),
-      Math.max(1, Math.round(heightPx)),
-    );
-  };
-
-  // Step 4: Draw neon-green outline with cyan neon glow.
-  const previousCompositeOperation = context.globalCompositeOperation;
-  context.globalCompositeOperation = 'lighter';
-  context.strokeStyle = FLAPPY_NEON_PALETTE.pipeFill;
-
-  // Step 4.1: Soft glow pass (thicker stroke + cyan shadow).
-  context.globalAlpha = FLAPPY_PIPE_OUTLINE_GLOW_ALPHA;
-  context.shadowColor = FLAPPY_PIPE_OUTLINE_CYAN_GLOW_COLOR;
-  context.shadowBlur = FLAPPY_PIPE_OUTLINE_CYAN_GLOW_BLUR_PX;
-  context.shadowOffsetX = 0;
-  context.shadowOffsetY = 0;
-  strokeAlignedRect(
-    outlineLeftPx,
-    outlineTopPx,
-    outlineWidthPx,
-    outlineHeightPx,
-    FLAPPY_PIPE_OUTLINE_GLOW_STROKE_WIDTH_PX,
-  );
-
-  // Step 4.2: Crisp outline pass (no shadow).
-  context.globalAlpha = 1;
-  context.shadowBlur = 0;
-  context.shadowColor = 'transparent';
-  strokeAlignedRect(
-    outlineLeftPx,
-    outlineTopPx,
-    outlineWidthPx,
-    outlineHeightPx,
-    outlineStrokeWidthPx,
-  );
-
-  context.globalCompositeOperation = previousCompositeOperation;
-  context.restore();
-}
+export { drawPipeNeonOutline } from './playback.render.pipe-outline.service';