@reicek/neataptic-ts 0.1.21 → 0.1.23

package/test/examples/flappy_bird/constants/constants.birds.ts

@@ -8,6 +8,9 @@
 /** Maximum number of trail points retained per bird trail polyline. */
 export const FLAPPY_TRAIL_MAX_POINTS = 40;
 
+/** Maximum number of trail points retained for the champion-only short trail. */
+export const FLAPPY_CHAMPION_TRAIL_MAX_POINTS = 12;
+
 /** Stroke width used for per-bird trail line rendering. */
 export const FLAPPY_TRAIL_LINE_WIDTH_PX = 1.5;
 
@@ -17,30 +20,12 @@ export const FLAPPY_TRAIL_EDGE_FADE_DISTANCE_PX = 48;
 /** Opacity used for non-champion bird fills and trails. */
 export const FLAPPY_NON_CHAMPION_OPACITY = 0.1;
 
-/** Ratio of bird side length used for top-left shine square. */
-export const FLAPPY_BIRD_SHINE_SIZE_RATIO = 0.42;
-
-/** Ratio of bird side length used to inset shine from top-left corner. */
-export const FLAPPY_BIRD_SHINE_INSET_RATIO = 0.2;
-
-/** Fill style used for the bird shine highlight. */
-export const FLAPPY_BIRD_SHINE_FILL_STYLE = 'rgba(255, 255, 255, 0.7)';
-
-/** Fill style used for the champion bird shine highlight (xterm 196 red). */
-export const FLAPPY_BIRD_CHAMPION_SHINE_FILL_STYLE = 'rgba(255, 0, 0, 0.7)';
-
-/** Neon glow color used for the condensed white highlight shine. */
-export const FLAPPY_BIRD_WHITE_SHINE_GLOW_COLOR = '#ffffff';
-
-/** Neon glow color used for the champion shine highlight (xterm 196 red). */
-export const FLAPPY_BIRD_CHAMPION_SHINE_GLOW_COLOR = '#ff0000';
-
-/** Neon blur radius used for the condensed white highlight shine. */
-export const FLAPPY_BIRD_WHITE_SHINE_GLOW_BLUR_PX = 2;
-
 /** Base neon blur radius used for bird body glow. */
 export const FLAPPY_BIRD_BODY_GLOW_BLUR_PX = 10;
 
+/** Glow blur radius used for simplified non-champion bird bodies. */
+export const FLAPPY_NON_CHAMPION_BODY_GLOW_BLUR_PX = 0;
+
 /**
  * Opacity used for the extra Radiant-style aura around each bird.
  *
@@ -55,26 +40,19 @@ export const FLAPPY_BIRD_AURA_EXPAND_PX = 3;
 /** Blur multiplier used for the Radiant-style bird aura plate. */
 export const FLAPPY_BIRD_AURA_BLUR_MULTIPLIER = 2.6;
 
-/** Additional blur radius applied to the champion red body glow. */
-export const FLAPPY_BIRD_CHAMPION_EXTRA_GLOW_BLUR_PX = 7;
-
-/** Opacity used for the expanded champion red glow plate. */
-export const FLAPPY_BIRD_CHAMPION_RED_GLOW_ALPHA = 0.62;
-
-/** Pixel expansion used for the champion red glow plate. */
-export const FLAPPY_BIRD_CHAMPION_RED_GLOW_EXPAND_PX = 4;
+/**
+ * Additional blur radius applied to the champion red body glow.
+ *
+ * This keeps the champion body bloom aligned with the same neon blur
+ * intensity used by the pipe outline glow, so the leader reads with
+ * comparable visual weight.
+ */
+export const FLAPPY_BIRD_CHAMPION_EXTRA_GLOW_BLUR_PX =
+  Math.max(24, Math.round(FLAPPY_BIRD_BODY_GLOW_BLUR_PX * 3.2)) -
+  FLAPPY_BIRD_BODY_GLOW_BLUR_PX;
 
 /** Minimum horizontal segment length used by stepped trail rendering. */
 export const FLAPPY_TRAIL_MIN_HORIZONTAL_SEGMENT_PX = 2;
 
 /** Minimum vertical segment length used by stepped trail rendering. */
 export const FLAPPY_TRAIL_MIN_VERTICAL_SEGMENT_PX = 2;
-
-/** Additional radius applied when drawing champion leader ring. */
-export const FLAPPY_LEADER_RING_RADIUS_OFFSET_PX = 2;
-
-/** Stroke width used when drawing champion leader ring. */
-export const FLAPPY_LEADER_RING_LINE_WIDTH_PX = 2;
-
-/** Neon blur radius used when drawing the champion outline stroke. */
-export const FLAPPY_LEADER_RING_GLOW_BLUR_PX = 10;

package/test/examples/flappy_bird/constants/constants.difficulty.ts

@@ -69,6 +69,27 @@ export const FLAPPY_PIPE_SPAWN_INTERVAL_MIN_FRAMES = Math.max(
   ),
 );
 
+/**
+ * Actual edge-to-edge spacing produced at peak adaptive difficulty.
+ *
+ * The recovery target above is a lower bound, but the runtime cadence is
+ * ultimately quantized by whole frames. This value is the real rendered pipe
+ * spacing once the minimum spawn interval has been rounded to an integer.
+ */
+export const FLAPPY_MAX_DIFFICULTY_EDGE_TO_EDGE_PIPE_SPACING_PX =
+  FLAPPY_PIPE_SPAWN_INTERVAL_MIN_FRAMES * FLAPPY_PIPE_SPEED_MAX_PX_PER_FRAME -
+  FLAPPY_PIPE_WIDTH_PX;
+
+/**
+ * Full pipe-to-pipe pitch produced at peak adaptive difficulty.
+ *
+ * This is the distance from one pipe's leading edge to the next pipe's leading
+ * edge at the hardest steady-state cadence. It is the periodicity the ground
+ * grid must match if each spawned pipe should land on the same grid phase.
+ */
+export const FLAPPY_MAX_DIFFICULTY_PIPE_PITCH_PX =
+  FLAPPY_PIPE_SPAWN_INTERVAL_MIN_FRAMES * FLAPPY_PIPE_SPEED_MAX_PX_PER_FRAME;
+
 /** Initial spawn-interval multiplier relative to the current hardest interval target. */
 export const FLAPPY_PIPE_SPAWN_INTERVAL_START_MULTIPLIER = 2.35;
 

package/test/examples/flappy_bird/constants/constants.network-view.ts

@@ -41,9 +41,15 @@ export const FLAPPY_NETWORK_GRAPH_RIGHT_PADDING_PX = 20;
 /** Graph-bottom padding for network visualization content. */
 export const FLAPPY_NETWORK_GRAPH_BOTTOM_PADDING_PX = 18;
 
+/** Minimum drawable graph dimension after padding is removed. */
+export const FLAPPY_NETWORK_MIN_DRAWABLE_SIZE_PX = 1;
+
 /** Gap between graph body and floating legend panel. */
 export const FLAPPY_NETWORK_LEGEND_GRAPH_GAP_PX = 10;
 
+/** Ratio used to decide whether the legend occupies the right half of the canvas. */
+export const FLAPPY_NETWORK_LEGEND_RIGHT_SIDE_THRESHOLD_RATIO = 0.5;
+
 /** Inner node-layout padding inside drawable network region. */
 export const FLAPPY_NETWORK_NODE_LAYOUT_PADDING_PX = 2;
 
@@ -161,6 +167,9 @@ export const FLAPPY_NETWORK_HEADER_FONT_SIZE_PX = 11;
 /** Extra pixel allowance above label baseline for minimum node-height readability. */
 export const FLAPPY_NETWORK_MIN_NODE_HEIGHT_LABEL_EXTRA_PX = 4;
 
+/** Minimum fit-based node height before width and label constraints are applied. */
+export const FLAPPY_NETWORK_MIN_NODE_FIT_HEIGHT_PX = 4;
+
 /**
  * Layer-fit divisor used when deriving max node height from dense layer stacks.
  *
@@ -215,3 +224,18 @@ export const FLAPPY_NETWORK_INPUT_GROUP_LABEL_FONT_WEIGHT = 700;
 
 /** Text color for vertical input-group labels on neon backgrounds. */
 export const FLAPPY_NETWORK_INPUT_GROUP_LABEL_TEXT_COLOR = '#000000';
+
+/** Placeholder label used when the network has no hidden layers. */
+export const FLAPPY_NETWORK_EMPTY_HIDDEN_LAYER_LABEL = '-';
+
+/** Prefix used when hidden-layer counts are inferred rather than declared. */
+export const FLAPPY_NETWORK_INFERRED_HIDDEN_LAYER_PREFIX = '~';
+
+/** Separator used between hidden-layer sizes inside architecture labels. */
+export const FLAPPY_NETWORK_HIDDEN_LAYER_SEPARATOR = ' - ';
+
+/** Separator used between architecture columns in the compact header label. */
+export const FLAPPY_NETWORK_ARCHITECTURE_COLUMN_SEPARATOR = ' | ';
+
+/** Line separator used by the two-line architecture label block. */
+export const FLAPPY_NETWORK_ARCHITECTURE_LINE_SEPARATOR = '\n';

package/test/examples/flappy_bird/constants/constants.network.ts

@@ -27,4 +27,4 @@ export const FLAPPY_NETWORK_OUTPUT_SIZE = 2;
  * Using at least two hidden layers improves representational flexibility for
  * precise vertical control near narrow, fast-changing pipe targets.
  */
-export const FLAPPY_NETWORK_HIDDEN_LAYER_SIZES = [8, 6, 4] as const;
+export const FLAPPY_NETWORK_HIDDEN_LAYER_SIZES = [10, 8, 6, 4] as const;

package/test/examples/flappy_bird/constants/constants.observation.ts

@@ -3,6 +3,10 @@
  *
  * These values are used by both browser playback and headless environment
  * simulation when building normalized feature vectors.
+ *
+ * Keeping normalization constants shared is important because even tiny drift in
+ * feature scaling would make trainer, worker, and browser policies "see"
+ * different worlds.
  */
 
 /**
@@ -10,5 +14,8 @@
  *
  * Prevents division by near-zero values when view-dependent scales are very
  * small, keeping feature values numerically stable.
+ *
+ * If you want a quick refresher on why feature scaling matters, the Wikipedia
+ * article on "feature scaling" is a useful background reference.
  */
 export const FLAPPY_NORMALIZATION_EPSILON = 0.001;

package/test/examples/flappy_bird/constants/constants.palette.ts

@@ -11,8 +11,8 @@ export const FLAPPY_NEON_PALETTE = {
   pipeFill: '#00ff66',
   pipeEdgeOuter: '#2dff78',
   pipeEdgeInner: '#bfffd4',
-  championBird: '#ff0000',
-  nonChampionBird: '#ffe94d',
+  championBird: '#ff4a8d',
+  nonChampionBird: '#00e5ff',
   leaderRing: '#ffffff',
   trail: '#875fff',
   currentRunText: '#00ff66',
@@ -22,6 +22,13 @@ export const FLAPPY_NEON_PALETTE = {
   hudAccent: '#ff9a2e',
   hudPanelBackground: '#000000',
   hudPanelBorder: '#0fb5ff',
+  horizonLine: '#0a8ea0',
+  horizonGlow: 'rgba(10, 142, 160, 0.95)',
+  groundGridLine: '#0a8ea0',
+  groundGridGlow: 'rgba(10, 142, 160, 0.9)',
+  groundGridFog: 'rgba(10, 142, 160, 0.55)',
+  groundGridPulseFill: '#fff14a',
+  groundGridPulseGlow: 'rgba(255, 241, 74, 0.92)',
 } as const;
 
 /** Neon bird palette for per-agent render color assignment. */

package/test/examples/flappy_bird/constants/constants.physics.ts

@@ -3,6 +3,9 @@
  *
  * Values in this module shape how quickly the bird falls, how strongly a flap
  * responds, and how often a policy can react inside each visible frame.
+ *
+ * Small changes here have outsized behavioral impact because they reshape the
+ * control problem the policy is trying to solve.
  */
 
 /**
@@ -33,6 +36,9 @@ export const FLAPPY_MAX_FALL_SPEED_PX_PER_FRAME = 7;
  *
  * Values > 1 give agents finer temporal control in tight scenarios by allowing
  * multiple react-and-integrate passes before the frame counter advances.
+ *
+ * This is one of the main levers that keeps high-speed play numerically stable
+ * without forcing the visible frame rate to explode.
  */
 export const FLAPPY_CONTROL_SUBSTEPS_PER_FRAME = 4;
 
@@ -41,5 +47,8 @@ export const FLAPPY_CONTROL_SUBSTEPS_PER_FRAME = 4;
  *
  * A smaller value means the policy is expected to correct more frequently
  * (effectively "jumping more often"), which supports narrower endgame gaps.
+ *
+ * The value is used analytically when estimating whether a late recovery is
+ * still plausible, not as the direct execution cadence of the simulation loop.
  */
 export const FLAPPY_TARGET_FLAP_INTERVAL_FRAMES = 2;

package/test/examples/flappy_bird/constants/constants.pipe-render.ts

@@ -30,6 +30,9 @@ export const FLAPPY_PIPE_OUTLINE_GLOW_ALPHA = 0.68;
 /** Stroke width used for the soft pipe glow stroke pass (pixels). */
 export const FLAPPY_PIPE_OUTLINE_GLOW_STROKE_WIDTH_PX = 8;
 
+/** Inset used for the pipe entrance rim line measured from the gap-facing edge. */
+export const FLAPPY_PIPE_ENTRY_RIM_INSET_PX = 10;
+
 /**
  * Cyan neon glow used for pipe outline shadow.
  *

package/test/examples/flappy_bird/constants/constants.pipes.ts

@@ -5,6 +5,11 @@ import { FLAPPY_WORLD_HEIGHT_PX } from './constants.world';
  *
  * These values describe the canonical pipe body size, opening geometry, visual
  * outline offsets, and default leftward movement cadence.
+ *
+ * Educational note:
+ * Pipe constants do double duty: some values describe actual gameplay geometry,
+ * while others are chosen so the visible pipe outline and the collision envelope
+ * feel aligned to a human viewer.
  */
 
 /** Pipe width (pixels). */
@@ -40,13 +45,27 @@ export const FLAPPY_PIPE_COLLISION_ENTRANCE_EXPAND_PX = Math.round(
     FLAPPY_PIPE_OUTLINE_STROKE_WIDTH_PX * 0.5,
 );
 
-/** Vertical opening size of each pipe gap (pixels). */
+/**
+ * Vertical opening size of each pipe gap (pixels).
+ *
+ * This is the nominal baseline gap before adaptive difficulty narrows it.
+ */
 export const FLAPPY_PIPE_GAP_PX = 150;
 
-/** Pipe horizontal speed (pixels/frame). */
+/**
+ * Pipe horizontal speed (pixels/frame).
+ *
+ * Higher values shrink reaction time, which makes the same gap geometry much
+ * harder even before the adaptive curriculum starts tightening gaps.
+ */
 export const FLAPPY_PIPE_SPEED_PX_PER_FRAME = 5;
 
-/** Frames between spawning new pipes. */
+/**
+ * Frames between spawning new pipes.
+ *
+ * Together with pipe speed, this controls horizontal pacing and how much time a
+ * policy has to recover between obstacles.
+ */
 export const FLAPPY_PIPE_SPAWN_INTERVAL_FRAMES = 50;
 
 /** Minimum allowed gap center height (pixels). */

package/test/examples/flappy_bird/constants/constants.runtime.ts

@@ -5,6 +5,10 @@ import { FLAPPY_NORMALIZATION_EPSILON as SHARED_FLAPPY_NORMALIZATION_EPSILON } f
  *
  * These values control startup defaults, emulation cadence, and common
  * placeholder/status values rendered by the UI.
+ *
+ * This module is less about game physics and more about operator experience:
+ * what the browser shows while loading, how frequently HUD numbers refresh, and
+ * which defaults the demo uses when bootstrapping the worker.
  */
 
 /** Default host container id for the browser demo mount point. */
@@ -13,16 +17,36 @@ export const DEFAULT_CONTAINER_ID = 'flappy-bird-output';
 /** Emulation speed multiplier for browser playback (1.5 => 50% faster). */
 export const FLAPPY_EMULATION_SPEED_MULTIPLIER = 1.5;
 
-/** Update HUD counters every N simulation frames to reduce DOM churn. */
+/**
+ * Update HUD counters every N simulation frames to reduce DOM churn.
+ *
+ * The value trades freshness for stability. Updating every frame would make the
+ * numbers twitchier and force more frequent DOM work on the main thread.
+ */
 export const FLAPPY_HUD_UPDATE_INTERVAL_FRAMES = 10;
 
-/** Default population size for browser playback worker initialization. */
+/**
+ * Default population size for browser playback worker initialization.
+ *
+ * The browser default is intentionally smaller than the long-running trainer so
+ * the interactive demo remains responsive.
+ */
 export const FLAPPY_BROWSER_POPULATION_SIZE = 10;
 
-/** Default elitism count for browser playback worker initialization. */
+/**
+ * Default elitism count for browser playback worker initialization.
+ *
+ * Keeping elitism small in the browser demo emphasizes visible variety over raw
+ * training efficiency.
+ */
 export const FLAPPY_BROWSER_ELITISM_COUNT = 1;
 
-/** Deterministic default RNG seed shared by browser runtime and trainer flows. */
+/**
+ * Deterministic default RNG seed shared by browser runtime and trainer flows.
+ *
+ * Reusing one canonical seed makes debugging and README examples more
+ * repeatable.
+ */
 export const FLAPPY_DEFAULT_RNG_SEED = 0x1234abcd;
 
 /** Normalized decision threshold used for scalar output flap policies. */

package/test/examples/flappy_bird/constants/constants.starfield.ts

@@ -10,6 +10,42 @@ import { FLAPPY_WORLD_HEIGHT_PX } from './constants.world';
 /** Width of one repeated starfield tile (pixels). */
 export const FLAPPY_STARFIELD_TILE_WIDTH_PX = 512;
 
+/** Minimum positive dimension allowed for generated starfield canvases. */
+export const FLAPPY_STARFIELD_MIN_DIMENSION_PX = 1;
+
+/** Zero pixel origin used for starfield canvas clears and draws. */
+export const FLAPPY_STARFIELD_ORIGIN_PX = 0;
+
+/** Canvas rendering context identifier used for starfield tile generation. */
+export const FLAPPY_STARFIELD_CANVAS_CONTEXT_ID = '2d';
+
+/** Composite mode used for normal starfield canvas drawing passes. */
+export const FLAPPY_STARFIELD_COMPOSITE_SOURCE_OVER = 'source-over';
+
+/** Transparent shadow reset value used after glow drawing. */
+export const FLAPPY_STARFIELD_TRANSPARENT_SHADOW_COLOR = 'transparent';
+
+/** Default fully opaque alpha restored after tile generation. */
+export const FLAPPY_STARFIELD_FULL_ALPHA = 1;
+
+/** Blur reset value used after the star glow pass. */
+export const FLAPPY_STARFIELD_NO_BLUR_PX = 0;
+
+/** Inclusive range offset used when converting size bounds into random spans. */
+export const FLAPPY_STARFIELD_INCLUSIVE_RANGE_OFFSET = 1;
+
+/** Divisor that normalizes unsigned 32-bit RNG state into the unit interval. */
+export const FLAPPY_STARFIELD_UNSIGNED_NORMALIZATION_DIVISOR = 0x1_0000_0000;
+
+/** Primary left-shift used by the xorshift32 random transition. */
+export const FLAPPY_STARFIELD_XORSHIFT_LEFT_SHIFT_PRIMARY = 13;
+
+/** Middle right-shift used by the xorshift32 random transition. */
+export const FLAPPY_STARFIELD_XORSHIFT_RIGHT_SHIFT = 17;
+
+/** Final left-shift used by the xorshift32 random transition. */
+export const FLAPPY_STARFIELD_XORSHIFT_LEFT_SHIFT_FINAL = 5;
+
 /** Height of one repeated starfield tile (pixels). */
 export const FLAPPY_STARFIELD_TILE_HEIGHT_PX = FLAPPY_WORLD_HEIGHT_PX;
 
@@ -17,10 +53,49 @@ export const FLAPPY_STARFIELD_TILE_HEIGHT_PX = FLAPPY_WORLD_HEIGHT_PX;
 export const FLAPPY_STARFIELD_CYAN_FILL_STYLE = 'rgba(95, 255, 255, 1)';
 
 /** Horizontal scroll ratio for the farthest parallax layer. */
-export const FLAPPY_STARFIELD_FAR_SCROLL_RATIO = 0.08;
+export const FLAPPY_STARFIELD_FAR_SCROLL_RATIO = 0.03;
 
 /** Horizontal scroll ratio for the middle parallax layer. */
-export const FLAPPY_STARFIELD_MID_SCROLL_RATIO = 0.12;
+export const FLAPPY_STARFIELD_MID_SCROLL_RATIO = 0.04;
 
 /** Horizontal scroll ratio for the nearest parallax layer. */
-export const FLAPPY_STARFIELD_NEAR_SCROLL_RATIO = 0.18;
+export const FLAPPY_STARFIELD_NEAR_SCROLL_RATIO = 0.05;
+
+/**
+ * Declarative layer specs for the default starfield parallax bands.
+ *
+ * Keeping the layer recipe in data form makes it easier to swap the lower
+ * segment to a different parallax family without changing the tile builder.
+ */
+export const FLAPPY_STARFIELD_LAYER_SPECS = [
+  {
+    seed: 1_337,
+    scrollRatio: FLAPPY_STARFIELD_FAR_SCROLL_RATIO,
+    starCount: 35,
+    minSizePx: 1,
+    maxSizePx: 2,
+    minAlpha: 0.08,
+    maxAlpha: 0.22,
+    blurPx: 4,
+  },
+  {
+    seed: 2_777,
+    scrollRatio: FLAPPY_STARFIELD_MID_SCROLL_RATIO,
+    starCount: 28,
+    minSizePx: 1,
+    maxSizePx: 3,
+    minAlpha: 0.1,
+    maxAlpha: 0.28,
+    blurPx: 6,
+  },
+  {
+    seed: 4_242,
+    scrollRatio: FLAPPY_STARFIELD_NEAR_SCROLL_RATIO,
+    starCount: 23,
+    minSizePx: 2,
+    maxSizePx: 4,
+    minAlpha: 0.12,
+    maxAlpha: 0.34,
+    blurPx: 8,
+  },
+] as const;

package/test/examples/flappy_bird/constants/constants.ts

@@ -4,6 +4,11 @@
  * Constants are now organized into small, category-focused modules
  * (`constants.*.ts`). This file remains as a compatibility export surface so
  * existing imports continue to work while callers migrate gradually.
+ *
+ * Educational note:
+ * Treat this file as the folder map, not the best place to learn individual
+ * values. The category modules below are where the real documentation lives:
+ * physics, pipes, observation, runtime, rendering, network layout, and so on.
  */
 
 export * from './constants.world';
@@ -41,6 +46,7 @@ export * from './constants.stats';
 export * from './constants.network-view';
 export * from './constants.birds';
 export {
+  FLAPPY_PIPE_ENTRY_RIM_INSET_PX,
   FLAPPY_PIPE_OUTLINE_GLOW_ALPHA,
   FLAPPY_PIPE_OUTLINE_GLOW_STROKE_WIDTH_PX,
   FLAPPY_PIPE_OUTLINE_CYAN_GLOW_COLOR,

package/test/examples/flappy_bird/environment/README.md

@@ -0,0 +1,182 @@
+# environment
+
+## environment/environment.types.ts
+
+### FlappyBird
+
+Bird kinematic state for one simulation frame.
+
+The environment keeps only the minimum physics state needed to advance the
+episode: vertical position and vertical velocity.
+
+### FlappyDifficultyScale
+
+Difficulty scale used by the curriculum scheduler.
+
+- `0` means easiest profile (wide gaps, slower pipes).
+- `1` means fully adaptive profile based on passed pipes.
+
+Values between `0` and `1` interpolate between those extremes, which lets the
+trainer or environment caller dial curriculum strength continuously.
+
+### FlappyGameState
+
+Full simulation state for one Flappy episode.
+
+Educational note:
+This is the canonical single-episode world state used by evaluation and some
+trainer-facing helpers. It is intentionally compact so stepping the world is
+deterministic and easy to inspect.
+
+### FlappyObservationFeatures
+
+Structured observation features used to build the neural-network input vector.
+
+Re-exported from shared simulation utilities so trainer and browser paths
+stay synchronized as the observation schema evolves.
+
+### FlappyPipe
+
+Pipe obstacle definition.
+
+Pipes move from right to left. The bird scores once per pipe when the pipe
+completely crosses the bird x-position.
+
+This is the environment-owned pipe state, distinct from the packed snapshot
+transport shapes used by the browser worker.
+
+## environment/environment.constants.ts
+
+### FLAPPY_ENVIRONMENT_DEFAULT_CONTROL_SUBSTEPS_PER_FRAME
+
+### FLAPPY_ENVIRONMENT_DEFAULT_DIFFICULTY_SCALE
+
+### FLAPPY_ENVIRONMENT_MAX_FRAMES_PER_EPISODE
+
+## environment/environment.step.service.ts
+
+### stepFlappyState
+
+`(state: import("test/examples/flappy_bird/environment/environment.types").FlappyGameState, rng: import("test/examples/flappy_bird/rng").FlappyRng, flap: boolean, difficultyScale: number) => void`
+
+Advance the simulation by one frame.
+
+This is the simplest stepping surface: one logical frame and one flap choice.
+More advanced callers can use the control-substep variant below.
+
+Parameters:
+- `state` - - Mutable state object to update in-place.
+- `rng` - - Random source used to spawn pipes.
+- `flap` - - If true, applies an upward velocity impulse.
+- `difficultyScale` - - Curriculum difficulty scale in [0, 1].
+
+Returns: Nothing.
+
+### stepFlappyStateWithControlSubsteps
+
+`(state: import("test/examples/flappy_bird/environment/environment.types").FlappyGameState, rng: import("test/examples/flappy_bird/rng").FlappyRng, shouldFlapForSubstep: () => boolean, difficultyScale: number, controlSubstepsPerFrame: number) => void`
+
+Advance one logical frame using multiple control/physics substeps.
+
+This allows policies to react multiple times before `frameIndex` advances,
+improving responsiveness in high-difficulty scenarios.
+
+Educational note:
+Splitting a logical frame into smaller control steps is a simple numerical
+stability trick. It reduces the chance that fast pipes or large velocity
+updates make the environment feel artificially coarse.
+
+For background reading, the Wikipedia article on "numerical integration"
+provides the general idea behind updating continuous motion in small steps.
+
+Parameters:
+- `state` - - Mutable state object to update in-place.
+- `rng` - - Random source used to spawn pipes.
+- `shouldFlapForSubstep` - - Callback deciding flap action per substep.
+- `difficultyScale` - - Curriculum difficulty scale in [0, 1].
+- `controlSubstepsPerFrame` - - Number of substeps to run this frame.
+
+Returns: Nothing.
+
+## environment/environment.state.service.ts
+
+### createInitialFlappyState
+
+`(rng: import("test/examples/flappy_bird/rng").FlappyRng) => import("test/examples/flappy_bird/environment/environment.types").FlappyGameState`
+
+Create a fresh Flappy Bird episode state.
+
+Educational note:
+A new episode starts with one initial pipe already materialized so the first
+observation is meaningful immediately. That avoids a cold-start phase where a
+policy would receive mostly empty-space inputs.
+
+Parameters:
+- `rng` - - Random source used to generate initial pipe configuration.
+
+Returns: Initial state for one deterministic rollout.
+
+## environment/environment.collision.utils.ts
+
+### updateCollisionAndProgressState
+
+`(state: import("test/examples/flappy_bird/environment/environment.types").FlappyGameState) => void`
+
+Apply out-of-bounds, pipe-collision, and pass-credit rules for one substep.
+
+Educational note:
+Collision resolution and progress credit live together because both depend on
+the same bird-vs-pipe geometry for the current substep. Keeping them in one
+place helps the environment avoid inconsistent "passed but also collided"
+edge cases.
+
+Parameters:
+- `state` - - Mutable simulation state to update in-place.
+
+Returns: Nothing.
+
+## environment/environment.observation.utils.ts
+
+### getFlappyObservation
+
+`(state: import("test/examples/flappy_bird/environment/environment.types").FlappyGameState, difficultyScale: number) => number[]`
+
+Generate the network observation vector for the current state.
+
+Educational note:
+This helper is the environment-facing bridge into the shared observation
+system. It keeps the environment API simple while ensuring evaluation,
+training, and browser playback all derive their policy inputs from the same
+feature definitions.
+
+Observation (12 numbers):
+ 1) bird y position normalized to [0, 1]
+ 2) bird vertical velocity normalized to [-1, 1]
+ 3) distance to next pipe normalized to [0, 1]
+ 4) delta (bird y - gap center y) normalized to [-1, 1]
+ 5) next pipe gap top normalized to [0, 1]
+ 6) next pipe gap bottom normalized to [0, 1]
+ 7) distance to second pipe normalized to [0, 1]
+ 8) delta to second gap center normalized to [-1, 1]
+ 9) time-to-next-pipe closeness normalized to [0, 1]
+10) signed clearance relative to next gap normalized to [-1, 1]
+11) required vertical velocity toward next gap center normalized to [-1, 1]
+12) gap-center transition (next to second) normalized to [-1, 1]
+
+Parameters:
+- `state` - - Current state.
+- `difficultyScale` - - Curriculum difficulty scale in [0, 1].
+
+Returns: Input vector for the neural network.
+
+### getFlappyObservationFeatures
+
+`(state: import("test/examples/flappy_bird/environment/environment.types").FlappyGameState, difficultyScale: number) => import("test/examples/flappy_bird/simulation-shared/simulation-shared.types").SharedObservationFeatures`
+
+Resolve structured observation features for policy input and reward shaping.
+
+Parameters:
+- `state` - - Current state.
+- `difficultyScale` - - Curriculum difficulty scale in [0, 1].
+
+Returns: Named feature object.

package/test/examples/flappy_bird/environment/environment.collision.utils.ts

@@ -11,7 +11,14 @@ import type { FlappyGameState } from './environment.types';
 /**
  * Apply out-of-bounds, pipe-collision, and pass-credit rules for one substep.
  *
+ * Educational note:
+ * Collision resolution and progress credit live together because both depend on
+ * the same bird-vs-pipe geometry for the current substep. Keeping them in one
+ * place helps the environment avoid inconsistent "passed but also collided"
+ * edge cases.
+ *
  * @param state - Mutable simulation state to update in-place.
+ * @returns Nothing.
  */
 export function updateCollisionAndProgressState(state: FlappyGameState): void {
   // Step 1: Resolve world-bound collisions.