@reicek/neataptic-ts 0.1.21 → 0.1.23

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

@@ -1,3 +1,11 @@
+/**
+ * Canvas frame-layout contracts for the Flappy Bird browser demo.
+ *
+ * These types support the demo's deliberately stylized text-frame chrome: title
+ * boxes, outer borders, and viewport transforms that make the example feel more
+ * like an instrument panel than a plain canvas game.
+ */
+
 /** Input contract for standalone title frame rendering helper. */
 export interface RenderStandaloneTitleBoxInput {
   context: CanvasRenderingContext2D;
@@ -8,7 +16,12 @@ export interface RenderStandaloneTitleBoxInput {
   font: string;
 }
 
-/** Input contract for outer frame rendering helper. */
+/**
+ * Input contract for outer frame rendering helper.
+ *
+ * The outer frame is the decorative shell that visually separates the playable
+ * world and telemetry panels from the rest of the page.
+ */
 export interface RenderClosedOuterBoxInput {
   context: CanvasRenderingContext2D;
   widthPx: number;
@@ -17,14 +30,24 @@ export interface RenderClosedOuterBoxInput {
   font: string;
 }
 
-/** Viewport transform values for world-to-canvas rendering. */
+/**
+ * Viewport transform values for world-to-canvas rendering.
+ *
+ * These numbers answer the classic graphics question: how does one unit in the
+ * simulated world map into the current canvas rectangle?
+ */
 export interface ViewportInfo {
   offsetXPx: number;
   offsetYPx: number;
   scale: number;
 }
 
-/** Canvas text-grid metrics used for frame rendering layout helpers. */
+/**
+ * Canvas text-grid metrics used for frame rendering layout helpers.
+ *
+ * The frame renderer measures glyph and row geometry once, then uses that grid
+ * to place ASCII-style UI elements consistently.
+ */
 export interface TextFrameMetrics {
   centeredColumns: number;
   offsetXPx: number;

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

@@ -1,3 +1,12 @@
+/**
+ * Public lifecycle contracts for the Flappy Bird browser runtime.
+ *
+ * These types describe how the demo is started, stopped, and exposed on the
+ * browser `window` object. They are intentionally small because callers should
+ * control the demo at a high level without depending on private implementation
+ * details.
+ */
+
 /** Handle returned by `start` for controlling demo execution lifecycle. */
 export interface FlappyBirdRunHandle {
   stop: () => void;
@@ -5,7 +14,13 @@ export interface FlappyBirdRunHandle {
   done: Promise<void>;
 }
 
-/** Runtime window contract for the Flappy Bird browser demo. */
+/**
+ * Runtime window contract for the Flappy Bird browser demo.
+ *
+ * The demo exposes a small debug-friendly surface on `window` so manual browser
+ * experiments and docs examples can start the simulation without importing the
+ * bundle as a module.
+ */
 export interface RuntimeWindow extends Window {
   flappyBird?: {
     start?: (container?: string | HTMLElement) => Promise<FlappyBirdRunHandle>;

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

@@ -3,6 +3,13 @@ import type {
   PopulationPipe,
 } from './browser-entry.worker.types';
 
+/**
+ * Simulation-facing browser contracts shared by playback helpers.
+ *
+ * These types describe the minimum world state the browser needs while it is
+ * reconstructing, rendering, or summarizing worker-produced frames.
+ */
+
 /** Bird shape used by utility winner/leader resolver helpers. */
 export interface BrowserPopulationBirdLike {
   done: boolean;
@@ -17,16 +24,28 @@ export interface BrowserPopulationPipeLike {
   gapSizePx: number;
 }
 
-/** Difficulty profile consumed by simulation observation helpers. */
+/**
+ * Difficulty profile consumed by simulation observation helpers.
+ *
+ * This bundles the three variables that define how demanding a stretch of the
+ * course is: corridor width, pipe speed, and spawn cadence.
+ */
 export interface BrowserDifficultyProfile {
   pipeGapPx: number;
   pipeSpeedPxPerFrame: number;
   pipeSpawnIntervalFrames: number;
 }
 
-/** Mutable render-state model consumed by the population frame renderer. */
+/**
+ * Mutable render-state model consumed by the population frame renderer.
+ *
+ * The playback layer incrementally updates this state as worker snapshots
+ * arrive, which lets rendering stay deterministic without re-deriving world
+ * history from scratch each frame.
+ */
 export interface PopulationRenderState {
   frameIndex: number;
+  cumulativePipeTravelPx: number;
   visibleWorldWidthPx: number;
   visibleWorldHeightPx: number;
   nextPipeId: number;
@@ -38,18 +57,33 @@ export interface PopulationRenderState {
   birds: PopulationBird[];
 }
 
-/** Trail point used by playback trail rendering cache. */
+/**
+ * Trail point used by playback trail rendering cache.
+ *
+ * A trail point stores where one bird was at one frame so the UI can draw a
+ * short motion history behind active agents.
+ */
 export interface TrailPoint {
   frameIndex: number;
   yPx: number;
 }
 
-/** Mutable trail cache keyed by bird index for frame rendering. */
+/**
+ * Mutable trail cache keyed by bird index for frame rendering.
+ *
+ * This cache exists purely for visualization ergonomics; it is not part of the
+ * worker simulation state.
+ */
 export interface TrailState {
   birdTrailsY: TrailPoint[][];
 }
 
-/** Minimal random source contract used by utility random helpers. */
+/**
+ * Minimal random source contract used by utility random helpers.
+ *
+ * The narrow contract keeps deterministic spawn utilities portable across
+ * browser and test contexts.
+ */
 export interface RngLike {
   nextInt: (min: number, max: number) => number;
 }

package/test/examples/flappy_bird/browser-entry/browser-entry.spawn.utils.ts

@@ -1,15 +1,14 @@
 import { FLAPPY_NEON_BIRD_PALETTE } from '../constants/constants';
 import {
   FLAPPY_PIPE_GAP_CENTER_MAX_Y_PX,
-  FLAPPY_PIPE_GAP_CENTER_MAX_DELTA_PX,
   FLAPPY_PIPE_GAP_CENTER_MIN_Y_PX,
   FLAPPY_WORLD_HEIGHT_PX,
 } from '../constants/constants';
 import {
-  type SharedDifficultyProfile,
-  resolveAdaptiveDifficultyProfile,
+  resolveNextSpawnGapCenterY as resolveSharedNextSpawnGapCenterY,
   resolveNextSpawnGapSize as resolveSharedNextSpawnGapSize,
   resolveNextSpawnIntervalFrames as resolveSharedNextSpawnIntervalFrames,
+  sampleGapCenterY as sampleSharedGapCenterY,
 } from '../flappy.simulation.shared.utils';
 import type { BrowserDifficultyProfile, RngLike } from './browser-entry.types';
 
@@ -24,9 +23,10 @@ export function sampleGapCenterY(
   rng: RngLike,
   worldHeightPx: number = FLAPPY_WORLD_HEIGHT_PX,
 ): number {
-  const lowerBoundGapCenterYPx = FLAPPY_PIPE_GAP_CENTER_MIN_Y_PX;
-  const upperBoundGapCenterYPx = resolveGapCenterUpperBoundYPx(worldHeightPx);
-  return rng.nextInt(lowerBoundGapCenterYPx, upperBoundGapCenterYPx);
+  return sampleSharedGapCenterY(
+    rng,
+    resolveGapCenterUpperBoundYPx(worldHeightPx),
+  );
 }
 
 /**
@@ -42,18 +42,10 @@ export function resolveNextSpawnGapCenterY(
   rng: RngLike,
   worldHeightPx: number = FLAPPY_WORLD_HEIGHT_PX,
 ): number {
-  const sampledGapCenterYPx = sampleGapCenterY(rng, worldHeightPx);
-  const minimumGapCenterYPx = Math.max(
-    FLAPPY_PIPE_GAP_CENTER_MIN_Y_PX,
-    previousGapCenterYPx - FLAPPY_PIPE_GAP_CENTER_MAX_DELTA_PX,
-  );
-  const maximumGapCenterYPx = Math.min(
+  return resolveSharedNextSpawnGapCenterY(
+    previousGapCenterYPx,
+    rng,
     resolveGapCenterUpperBoundYPx(worldHeightPx),
-    previousGapCenterYPx + FLAPPY_PIPE_GAP_CENTER_MAX_DELTA_PX,
-  );
-  return Math.max(
-    minimumGapCenterYPx,
-    Math.min(sampledGapCenterYPx, maximumGapCenterYPx),
   );
 }
 
@@ -107,7 +99,7 @@ export function resolveNextSpawnGapSize(
 ): number {
   return resolveSharedNextSpawnGapSize(
     previousSpawnGapPx,
-    difficultyProfile as SharedDifficultyProfile,
+    difficultyProfile,
     rng,
   );
 }
@@ -125,18 +117,6 @@ export function resolveNextSpawnIntervalFrames(
 ): number {
   return resolveSharedNextSpawnIntervalFrames(
     previousSpawnIntervalFrames,
-    difficultyProfile as SharedDifficultyProfile,
+    difficultyProfile,
   );
 }
-
-/**
- * Resolves current difficulty profile from pipes-passed progress.
- *
- * @param pipesPassed - Current pipes passed.
- * @returns Difficulty profile.
- */
-export function resolveDifficultyProfile(
-  pipesPassed: number,
-): BrowserDifficultyProfile {
-  return resolveAdaptiveDifficultyProfile(pipesPassed, 1);
-}

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

@@ -1,3 +1,11 @@
+/**
+ * HUD and runtime stats contracts for the Flappy Bird browser demo.
+ *
+ * The browser HUD is intentionally declarative: keys describe what should be
+ * shown, and helper utilities map those keys to DOM rows and live values. That
+ * keeps the status panel readable even as telemetry grows.
+ */
+
 /** Runtime stats table key union used across browser-entry helpers. */
 export type FlappyStatsKey =
   | 'currentHeader'
@@ -20,24 +28,44 @@ export type FlappyStatsKey =
   | 'status'
   | 'birds';
 
-/** Declarative row descriptor for the runtime stats table. */
+/**
+ * Declarative row descriptor for the runtime stats table.
+ *
+ * Each row is described as data first so the HUD can be assembled in a stable,
+ * testable order instead of being hand-written imperatively.
+ */
 export interface FlappyStatsRowDescriptor {
   key: FlappyStatsKey;
   label: string;
 }
 
-/** Runtime lookup map of stat keys to writable value cells. */
+/**
+ * Runtime lookup map of stat keys to writable value cells.
+ *
+ * This acts like a small DOM index so the update loop can mutate the correct
+ * cells directly without repeatedly querying the document.
+ */
 export type FlappyStatsTableCells = Partial<
   Record<FlappyStatsKey, HTMLTableCellElement>
 >;
 
-/** Color pair used for stats category key/value styling. */
+/**
+ * Color pair used for stats category key/value styling.
+ *
+ * The HUD uses paired colors so labels and values stay visually grouped while
+ * still separating categories such as current run, telemetry, and best-so-far.
+ */
 export interface FlappyStatsCategoryColors {
   keyColor: string;
   valueColor: string;
 }
 
-/** Input contract for declarative runtime stats table row builder. */
+/**
+ * Input contract for declarative runtime stats table row builder.
+ *
+ * The builder needs both the target table and a small policy surface that says
+ * whether instrumentation rows should appear and how rows should be colored.
+ */
 export interface CreateFlappyStatsTableRowsInput {
   statsTable: HTMLTableElement;
   enableRuntimeInstrumentation: boolean;

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

@@ -1,2 +1,13 @@
+/**
+ * Browser demo public entry for the Flappy Bird example.
+ *
+ * This boundary is the hand-off point between library consumers and the demo's
+ * browser runtime. Calling `start` boots the canvas UI, worker channel, HUD,
+ * and playback loop without exposing all of that internal orchestration as part
+ * of the public API.
+ *
+ * In other words, this file is intentionally tiny because it acts like a clean
+ * facade over a much larger interactive system.
+ */
 export { start } from './runtime/runtime';
 export type { FlappyBirdRunHandle } from './browser-entry.types';

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

@@ -1,3 +1,11 @@
+/**
+ * Aggregated public type surface for the Flappy Bird browser runtime.
+ *
+ * The browser demo spans several concerns at once: worker messaging, playback
+ * rendering, telemetry, viewport math, and network visualization. Re-exporting
+ * the public contracts from one place gives readers a compact map of that
+ * runtime without forcing them to know the internal folder layout first.
+ */
 export type * from './browser-entry.runtime.types';
 export type * from './browser-entry.stats.types';
 export type * from './browser-entry.worker.types';

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

@@ -1,5 +1,14 @@
 import type Network from '../../../../src/architecture/network';
 
+/**
+ * Network-visualization contracts for the Flappy Bird browser demo.
+ *
+ * One of the educational goals of the example is to let people watch evolved
+ * controllers as structures, not just as scores. These types describe the
+ * lightweight shapes used by the architecture panel so rendering logic can stay
+ * decoupled from the full internal network implementation.
+ */
+
 /** Draw callback contract for network architecture panel updates. */
 export interface NetworkVisualizationHandle {
   renderNetworkArchitecture: (
@@ -9,13 +18,22 @@ export interface NetworkVisualizationHandle {
   ) => void;
 }
 
-/** Connection or bias tier used for color mapping ramps. */
+/**
+ * Connection or bias tier used for color mapping ramps.
+ *
+ * Visualization buckets continuous weights into legible color bands so humans
+ * can scan sign and magnitude at a glance.
+ */
 export interface ColorTier {
   upperBound: number;
   color: string;
 }
 
-/** Legend row model for network visualization color legends. */
+/**
+ * Legend row model for network visualization color legends.
+ *
+ * Each row labels a numeric interval and the color used to render it.
+ */
 export interface ColorLegendRow {
   label: string;
   color: string;
@@ -23,7 +41,12 @@ export interface ColorLegendRow {
   maximumValue: number;
 }
 
-/** Precomputed legend panel layout used by visualization renderer. */
+/**
+ * Precomputed legend panel layout used by visualization renderer.
+ *
+ * Layout is resolved up front so the draw path can stay focused on painting,
+ * not recomputing geometry every frame.
+ */
 export interface NetworkLegendLayout {
   compactLegend: boolean;
   legendLeftPx: number;
@@ -36,7 +59,12 @@ export interface NetworkLegendLayout {
   legendSectionGapPx: number;
 }
 
-/** Lightweight connection shape used by network visualization drawing. */
+/**
+ * Lightweight connection shape used by network visualization drawing.
+ *
+ * The renderer only needs connectivity, weight, and enabled state, not the full
+ * training-time behavior of a connection object.
+ */
 export interface VisualNetworkConnectionLike {
   from?: { index?: number };
   to?: { index?: number };
@@ -44,7 +72,12 @@ export interface VisualNetworkConnectionLike {
   enabled?: boolean;
 }
 
-/** Lightweight node shape used by network visualization drawing. */
+/**
+ * Lightweight node shape used by network visualization drawing.
+ *
+ * This shape keeps the renderer independent from the concrete Network class
+ * while still exposing the semantic fields that matter visually.
+ */
 export interface VisualNetworkNodeLike {
   index: number;
   type: string;
@@ -52,14 +85,24 @@ export interface VisualNetworkNodeLike {
   layer?: number;
 }
 
-/** Positioned node instance used by network visualization drawing. */
+/**
+ * Positioned node instance used by network visualization drawing.
+ *
+ * Layout and rendering are split: first a node is assigned screen coordinates,
+ * then the renderer paints it.
+ */
 export interface PositionedNetworkNodeLike {
   node: VisualNetworkNodeLike;
   xPx: number;
   yPx: number;
 }
 
-/** Pixel dimensions used for network-node rectangle rendering. */
+/**
+ * Pixel dimensions used for network-node rectangle rendering.
+ *
+ * Keeping node box dimensions explicit makes legend and topology layout easier
+ * to tune without hidden drawing constants.
+ */
 export interface NetworkNodeDimensionsLike {
   widthPx: number;
   heightPx: number;