@reicek/neataptic-ts 0.1.21 → 0.1.23

package/test/examples/flappy_bird/browser-entry/playback/background/ground-grid/playback.background.ground-grid.batch.services.ts

@@ -0,0 +1,64 @@
+import type { PlaybackGroundGridSegmentBatch } from './playback.background.ground-grid.types';
+
+/**
+ * Draws one ordered collection of neon segment batches.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param batches - Ordered line-segment batches to render.
+ * @param lineColor - Core neon stroke color.
+ * @returns Nothing.
+ */
+export function drawGroundGridSegmentBatches(
+  context: CanvasRenderingContext2D,
+  batches: readonly PlaybackGroundGridSegmentBatch[],
+  lineColor: string,
+): void {
+  context.save();
+  context.strokeStyle = lineColor;
+
+  for (const batch of batches) {
+    drawGroundGridSegmentBatch(context, batch);
+  }
+
+  context.restore();
+}
+
+/**
+ * Draws one batch of neon line segments that share one render style.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param batch - Ordered line-segment batch that shares one render style.
+ * @returns Nothing.
+ */
+export function drawGroundGridSegmentBatch(
+  context: CanvasRenderingContext2D,
+  batch: PlaybackGroundGridSegmentBatch,
+): void {
+  context.globalAlpha = batch.alpha;
+  context.lineWidth = batch.thicknessPx;
+  strokePlaybackGroundGridBatch(context, batch);
+}
+
+/**
+ * Strokes one ground-grid batch using a cached path when the environment supports it.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param batch - Ordered line-segment batch that shares one render style.
+ * @returns Nothing.
+ */
+function strokePlaybackGroundGridBatch(
+  context: CanvasRenderingContext2D,
+  batch: PlaybackGroundGridSegmentBatch,
+): void {
+  if (batch.path) {
+    context.stroke(batch.path);
+    return;
+  }
+
+  context.beginPath();
+  for (const segment of batch.segments) {
+    context.moveTo(segment.startXPx, segment.startYPx);
+    context.lineTo(segment.endXPx, segment.endYPx);
+  }
+  context.stroke();
+}

package/test/examples/flappy_bird/browser-entry/playback/background/ground-grid/playback.background.ground-grid.cache.services.ts

@@ -0,0 +1,207 @@
+import { FLAPPY_GROUND_GRID_FOG_HEIGHT_RATIO } from './playback.background.ground-grid.constants';
+import type {
+  PlaybackBackgroundGroundGridSceneContext,
+  PlaybackGroundGridHorizontalGeometry,
+  PlaybackGroundGridHorizontalGeometryFactory,
+  PlaybackGroundGridVerticalGeometry,
+  PlaybackGroundGridVerticalGeometryFactory,
+  PlaybackGroundGridVerticalSceneMetrics,
+  PlaybackGroundGridVerticalSceneMetricsFactory,
+} from './playback.background.ground-grid.types';
+
+let cachedViewportSizeKey: string | null = null;
+let cachedFogGradientsByCanvas = new WeakMap<
+  HTMLCanvasElement,
+  Map<string, CanvasGradient>
+>();
+
+const cachedHorizontalGeometryBySceneKey = new Map<
+  string,
+  PlaybackGroundGridHorizontalGeometry
+>();
+const cachedVerticalSceneMetricsBySceneKey = new Map<
+  string,
+  PlaybackGroundGridVerticalSceneMetrics
+>();
+const cachedVerticalGeometryByCycleKey = new Map<
+  string,
+  PlaybackGroundGridVerticalGeometry
+>();
+
+/**
+ * Ensures ground-grid caches only retain entries for the current viewport size.
+ *
+ * The ground grid is derived from viewport width and total scene height, so a
+ * page resize invalidates every cached geometry variant and fog gradient.
+ *
+ * @param sceneContext - Current lower-band scene geometry.
+ * @returns Stable viewport-size cache key for the current frame.
+ */
+export function ensureGroundGridViewportCacheValidity(
+  sceneContext: PlaybackBackgroundGroundGridSceneContext,
+): string {
+  const viewportSizeKey = resolveGroundGridViewportCacheKey(sceneContext);
+  if (cachedViewportSizeKey === viewportSizeKey) {
+    return viewportSizeKey;
+  }
+
+  cachedViewportSizeKey = viewportSizeKey;
+  cachedHorizontalGeometryBySceneKey.clear();
+  cachedVerticalSceneMetricsBySceneKey.clear();
+  cachedVerticalGeometryByCycleKey.clear();
+  cachedFogGradientsByCanvas = new WeakMap<
+    HTMLCanvasElement,
+    Map<string, CanvasGradient>
+  >();
+  return viewportSizeKey;
+}
+
+/**
+ * Resolves the viewport-size cache key used by the ground-grid caches.
+ *
+ * @param sceneContext - Current lower-band scene geometry.
+ * @returns Cache key that changes whenever the page size changes.
+ */
+export function resolveGroundGridViewportCacheKey(
+  sceneContext: PlaybackBackgroundGroundGridSceneContext,
+): string {
+  return `${sceneContext.visibleWorldWidthPx}x${sceneContext.lowerBandBottomYPx}`;
+}
+
+/**
+ * Resolves the stable local-scene cache key for ground-grid geometry.
+ *
+ * @param sceneContext - Current lower-band scene geometry.
+ * @returns Scene key suitable for static horizontal and vertical cache entries.
+ */
+export function resolveGroundGridSceneCacheKey(
+  sceneContext: PlaybackBackgroundGroundGridSceneContext,
+): string {
+  return [
+    sceneContext.visibleWorldWidthPx,
+    sceneContext.alignedHorizonYPx,
+    sceneContext.lowerBandTopYPx,
+    sceneContext.lowerBandHeightPx,
+    sceneContext.lowerBandBottomYPx,
+    sceneContext.vanishingPointXPx,
+    sceneContext.vanishingPointYPx,
+  ].join(':');
+}
+
+/**
+ * Resolves the cache key for one wrapped vertical-geometry cycle.
+ *
+ * @param sceneCacheKey - Stable scene key for the active viewport.
+ * @param wrappedOffsetPx - Wrapped offset within one lane cycle.
+ * @returns Cycle key used for vertical geometry reuse.
+ */
+export function resolveGroundGridVerticalCycleCacheKey(
+  sceneCacheKey: string,
+  wrappedOffsetPx: number,
+): string {
+  return `${sceneCacheKey}|offset:${wrappedOffsetPx}`;
+}
+
+/**
+ * Resolves cached horizontal geometry for one scene.
+ *
+ * @param sceneCacheKey - Stable scene key for the active viewport.
+ * @param factory - Lazy geometry builder used when the cache misses.
+ * @returns Cached horizontal geometry bundle for the scene.
+ */
+export function resolveCachedGroundGridHorizontalGeometry(
+  sceneCacheKey: string,
+  factory: PlaybackGroundGridHorizontalGeometryFactory,
+): PlaybackGroundGridHorizontalGeometry {
+  const cachedGeometry = cachedHorizontalGeometryBySceneKey.get(sceneCacheKey);
+  if (cachedGeometry) {
+    return cachedGeometry;
+  }
+
+  const resolvedGeometry = factory();
+  cachedHorizontalGeometryBySceneKey.set(sceneCacheKey, resolvedGeometry);
+  return resolvedGeometry;
+}
+
+/**
+ * Resolves cached scene metrics for one vertical-grid layout.
+ *
+ * @param sceneCacheKey - Stable scene key for the active viewport.
+ * @param factory - Lazy scene-metrics builder used when the cache misses.
+ * @returns Cached vertical scene metrics for the scene.
+ */
+export function resolveCachedGroundGridVerticalSceneMetrics(
+  sceneCacheKey: string,
+  factory: PlaybackGroundGridVerticalSceneMetricsFactory,
+): PlaybackGroundGridVerticalSceneMetrics {
+  const cachedSceneMetrics =
+    cachedVerticalSceneMetricsBySceneKey.get(sceneCacheKey);
+  if (cachedSceneMetrics) {
+    return cachedSceneMetrics;
+  }
+
+  const resolvedSceneMetrics = factory();
+  cachedVerticalSceneMetricsBySceneKey.set(sceneCacheKey, resolvedSceneMetrics);
+  return resolvedSceneMetrics;
+}
+
+/**
+ * Resolves cached vertical geometry for one scene and wrapped offset cycle.
+ *
+ * @param cycleCacheKey - Scene-and-offset cache key for the active frame.
+ * @param factory - Lazy geometry builder used when the cache misses.
+ * @returns Cached vertical geometry bundle for the cycle.
+ */
+export function resolveCachedGroundGridVerticalGeometry(
+  cycleCacheKey: string,
+  factory: PlaybackGroundGridVerticalGeometryFactory,
+): PlaybackGroundGridVerticalGeometry {
+  const cachedGeometry = cachedVerticalGeometryByCycleKey.get(cycleCacheKey);
+  if (cachedGeometry) {
+    return cachedGeometry;
+  }
+
+  const resolvedGeometry = factory();
+  cachedVerticalGeometryByCycleKey.set(cycleCacheKey, resolvedGeometry);
+  return resolvedGeometry;
+}
+
+/**
+ * Resolves a cached fog gradient for one canvas and local scene.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param sceneCacheKey - Stable scene key for the active viewport.
+ * @param sceneContext - Current lower-band scene geometry.
+ * @param fogColor - Theme-owned fog color token.
+ * @returns Cached fog gradient aligned to the lower-band scene.
+ */
+export function resolveCachedGroundGridFogGradient(
+  context: CanvasRenderingContext2D,
+  sceneCacheKey: string,
+  sceneContext: PlaybackBackgroundGroundGridSceneContext,
+  fogColor: string,
+): CanvasGradient {
+  const fogGradientKey = `${sceneCacheKey}|fog:${fogColor}`;
+  const canvas = context.canvas;
+  const cachedGradientsForCanvas =
+    cachedFogGradientsByCanvas.get(canvas) ?? new Map<string, CanvasGradient>();
+  const cachedGradient = cachedGradientsForCanvas.get(fogGradientKey);
+  if (cachedGradient) {
+    return cachedGradient;
+  }
+
+  const fogHeightPx =
+    sceneContext.lowerBandHeightPx * FLAPPY_GROUND_GRID_FOG_HEIGHT_RATIO;
+  const fogGradient = context.createLinearGradient(
+    0,
+    sceneContext.lowerBandTopYPx,
+    0,
+    sceneContext.lowerBandTopYPx + fogHeightPx,
+  );
+  fogGradient.addColorStop(0, fogColor);
+  fogGradient.addColorStop(1, 'rgba(0, 0, 0, 0)');
+
+  cachedGradientsForCanvas.set(fogGradientKey, fogGradient);
+  cachedFogGradientsByCanvas.set(canvas, cachedGradientsForCanvas);
+  return fogGradient;
+}

package/test/examples/flappy_bird/browser-entry/playback/background/ground-grid/playback.background.ground-grid.constants.ts

@@ -0,0 +1,197 @@
+import { FLAPPY_NEON_PALETTE } from '../../../../constants/constants';
+import { FLAPPY_MAX_DIFFICULTY_PIPE_PITCH_PX } from '../../../../constants/constants.difficulty';
+import type { PlaybackBackgroundGroundGridStyle } from './playback.background.ground-grid.types';
+
+/**
+ * Number of horizontal depth bands used by the neon ground grid.
+ *
+ * More bands increase the sense of depth, but they also thicken the lower band
+ * visually and add more line work to each frame.
+ */
+export const FLAPPY_GROUND_GRID_HORIZONTAL_LINE_COUNT = 16;
+
+/**
+ * Target visible spacing between adjacent vertical rays at the pipe floor.
+ *
+ * The lower pipes visually attach to a projected floor band in the grid. The
+ * important invariant is phase repeat, not just raw gap width: each new pipe at
+ * max difficulty should land on the same relative grid position as the previous
+ * one. That requires matching the full pipe-to-pipe pitch, not only the open
+ * edge-to-edge gap between pipe bodies.
+ */
+export const FLAPPY_GROUND_GRID_TARGET_VERTICAL_LINE_SPACING_PX =
+  FLAPPY_MAX_DIFFICULTY_PIPE_PITCH_PX;
+
+/**
+ * Minimum visible perspective-ray count used on very narrow viewports.
+ *
+ * Even on a small canvas, the grid still needs at least a few rays to read as
+ * perspective instead of a flat block of horizontal stripes.
+ */
+export const FLAPPY_GROUND_GRID_MIN_VERTICAL_LINE_COUNT = 2;
+
+/**
+ * Extra off-screen perspective rays drawn for seamless wrap.
+ *
+ * Overflow rays prevent the parallax cycle from exposing empty gaps when the
+ * wrapped scroll offset lands near a lane boundary.
+ */
+export const FLAPPY_GROUND_GRID_VERTICAL_OVERFLOW_COUNT = 1;
+
+/**
+ * Target screen-space height for one vertical-ray style segment (pixels).
+ *
+ * Segmenting the rays lets the renderer vary alpha, thickness, and blur by
+ * depth rather than drawing each ray with one flat style.
+ */
+export const FLAPPY_GROUND_GRID_TARGET_VERTICAL_SEGMENT_HEIGHT_PX = 24;
+
+/**
+ * Approximate playback frame duration used for deterministic pulse timing.
+ *
+ * The pulse system is designed to feel stable at ordinary browser animation
+ * cadence without requiring access to wall-clock time in every helper.
+ */
+export const FLAPPY_GROUND_GRID_APPROX_FRAME_DURATION_MS = 1000 / 60;
+
+/**
+ * Interval between visible pulse events (milliseconds).
+ *
+ * A relatively slow cadence keeps the pulses as occasional accent lights rather
+ * than a constant distraction under the birds.
+ */
+export const FLAPPY_GROUND_GRID_PULSE_INTERVAL_MS = 6000;
+
+/**
+ * Lifetime of one pulse as it travels across its chosen line (milliseconds).
+ *
+ * The lifetime is slightly shorter than the full interval so one pulse fades
+ * out before the next slot becomes active.
+ */
+export const FLAPPY_GROUND_GRID_PULSE_LIFETIME_MS = 5900;
+
+/** Peak opacity used by visible pulse squares. */
+export const FLAPPY_GROUND_GRID_PULSE_ALPHA = 0.99;
+
+/** Smallest visible pulse square size (pixels). */
+export const FLAPPY_GROUND_GRID_PULSE_MIN_SIZE_PX = 1;
+
+/** Largest visible pulse square size (pixels). */
+export const FLAPPY_GROUND_GRID_PULSE_MAX_SIZE_PX = 6;
+
+/**
+ * Earliest progress ratio allowed for vertical pulse travel.
+ *
+ * Vertical pulses start a little away from the horizon so they are visible as
+ * distinct squares instead of immediately disappearing into compressed depth.
+ */
+export const FLAPPY_GROUND_GRID_VERTICAL_PULSE_START_RATIO = 0.14;
+
+/**
+ * Latest progress ratio allowed for vertical pulse travel.
+ *
+ * Ending early keeps the pulse out of the extreme foreground, where its square
+ * would become too large and visually heavy.
+ */
+export const FLAPPY_GROUND_GRID_VERTICAL_PULSE_END_RATIO = 0.62;
+
+/** Minimum horizontal line thickness eligible for pulse travel. */
+export const FLAPPY_GROUND_GRID_PULSE_MIN_ELIGIBLE_THICKNESS_PX = 1.5;
+
+/**
+ * Earliest eligible slice of horizontal lines used for visible pulse picks.
+ *
+ * This biases horizontal pulses toward the more legible near-midground instead
+ * of the compressed lines nearest the horizon.
+ */
+export const FLAPPY_GROUND_GRID_PULSE_PREFERRED_HORIZONTAL_START_RATIO = 0.4;
+
+/** Horizontal inset that keeps vertical pulse picks away from clipped edges. */
+export const FLAPPY_GROUND_GRID_PULSE_VISIBLE_VIEWPORT_INSET_PX = 24;
+
+/**
+ * Normalization divisor used for deterministic pulse hash generation.
+ *
+ * The pulse selection helpers convert unsigned integer hashes into stable
+ * floating-point picks in the unit interval.
+ */
+export const FLAPPY_GROUND_GRID_UNSIGNED_NORMALIZATION_DIVISOR = 0x1_0000_0000;
+
+/**
+ * Non-linear exponent used to compress depth lines toward the horizon.
+ *
+ * This is the main perspective stylization control: higher values bunch more of
+ * the depth bands near the horizon and leave broader spacing near the viewer.
+ */
+export const FLAPPY_GROUND_GRID_DEPTH_CURVE_EXPONENT = 2.35;
+
+/**
+ * Near-edge horizontal line offset used for the lower-pipe floor illusion.
+ *
+ * `1` targets the first usable grid band above the bottom edge rather than the
+ * terminal line that coincides with the lower-band boundary itself.
+ */
+export const FLAPPY_GROUND_GRID_PIPE_CONNECTION_LINE_OFFSET_FROM_BOTTOM = 1;
+
+/**
+ * Scroll ratio applied to the moving vertical perspective rays.
+ *
+ * Keeping the rays slower than gameplay motion makes the grid feel like a deep
+ * environmental layer rather than a surface glued to the pipes.
+ */
+export const FLAPPY_GROUND_GRID_SCROLL_RATIO = 0.16;
+
+/**
+ * Decimal precision used when quantizing the wrapped vertical-ray offset.
+ *
+ * Quantization stabilizes cache reuse by preventing tiny floating-point drift
+ * from generating effectively identical geometry variants.
+ */
+export const FLAPPY_GROUND_GRID_SCROLL_OFFSET_QUANTIZATION_DECIMALS = 3;
+
+/** Minimum alpha used by the farthest horizontal depth lines. */
+export const FLAPPY_GROUND_GRID_MIN_ALPHA = 0.12;
+
+/** Maximum alpha used by the nearest depth and perspective lines. */
+export const FLAPPY_GROUND_GRID_MAX_ALPHA = 0.58;
+
+/** Blur radius used by the farthest depth lines near the horizon. */
+export const FLAPPY_GROUND_GRID_MAX_BLUR_PX = 6;
+
+/** Blur radius used by the nearest depth lines at the bottom edge. */
+export const FLAPPY_GROUND_GRID_MIN_BLUR_PX = 0;
+
+/** Minimum stroke width used by far depth lines. */
+export const FLAPPY_GROUND_GRID_MIN_THICKNESS_PX = 1;
+
+/** Maximum stroke width used by near depth lines. */
+export const FLAPPY_GROUND_GRID_MAX_THICKNESS_PX = 3;
+
+/**
+ * Height ratio reserved for the subtle lower-band neon fog wash.
+ *
+ * The fog sits in the lower portion of the band so it enriches the foreground
+ * without muting the crisp horizon seam.
+ */
+export const FLAPPY_GROUND_GRID_FOG_HEIGHT_RATIO = 0.45;
+
+/**
+ * Peak opacity used by the lower-band neon fog wash.
+ *
+ * The fog should tint the band, not obscure the line geometry, so the opacity
+ * is intentionally modest.
+ */
+export const FLAPPY_GROUND_GRID_FOG_ALPHA = 0.24;
+
+/**
+ * Frozen neon style bundle reused by the playback ground-grid renderer.
+ *
+ * The values stay theme-owned but are materialized once so the renderer does
+ * not allocate a new style object during every frame.
+ */
+export const FLAPPY_BACKGROUND_GROUND_GRID_STYLE: PlaybackBackgroundGroundGridStyle =
+  Object.freeze({
+    lineColor: FLAPPY_NEON_PALETTE.groundGridLine,
+    fogColor: FLAPPY_NEON_PALETTE.groundGridFog,
+    pulseFillColor: FLAPPY_NEON_PALETTE.groundGridPulseFill,
+  });

package/test/examples/flappy_bird/browser-entry/playback/background/ground-grid/playback.background.ground-grid.geometry.batch.utils.ts

@@ -0,0 +1,114 @@
+import {
+  FLAPPY_GROUND_GRID_PULSE_MIN_ELIGIBLE_THICKNESS_PX,
+  FLAPPY_GROUND_GRID_PULSE_PREFERRED_HORIZONTAL_START_RATIO,
+} from './playback.background.ground-grid.constants';
+import type {
+  PlaybackGroundGridLineSegment,
+  PlaybackGroundGridPulsePath,
+  PlaybackGroundGridSegmentBatch,
+} from './playback.background.ground-grid.types';
+
+/**
+ * Groups line segments into ordered style batches for lower-overhead drawing.
+ *
+ * @param segments - Ordered line segments that should preserve draw grouping.
+ * @returns Ordered style batches that can be stroked with fewer state changes.
+ */
+export function groupPlaybackGroundGridSegmentsByStyle(
+  segments: readonly PlaybackGroundGridLineSegment[],
+): readonly PlaybackGroundGridSegmentBatch[] {
+  const groupedSegmentsByStyle = new Map<
+    string,
+    PlaybackGroundGridLineSegment[]
+  >();
+
+  for (const segment of segments) {
+    const styleKey = `${segment.alpha}:${segment.blurPx}:${segment.thicknessPx}`;
+    const existingGroup = groupedSegmentsByStyle.get(styleKey);
+    if (existingGroup) {
+      existingGroup.push(segment);
+      continue;
+    }
+
+    groupedSegmentsByStyle.set(styleKey, [segment]);
+  }
+
+  const segmentBatches: PlaybackGroundGridSegmentBatch[] = [];
+  for (const groupedSegments of groupedSegmentsByStyle.values()) {
+    const firstSegment = groupedSegments[0];
+    segmentBatches.push({
+      alpha: firstSegment.alpha,
+      blurPx: firstSegment.blurPx,
+      path: resolvePlaybackGroundGridBatchPath(groupedSegments),
+      thicknessPx: firstSegment.thicknessPx,
+      segments: groupedSegments,
+    });
+  }
+
+  return segmentBatches;
+}
+
+/**
+ * Prefers the nearer, thicker horizontal tracks when picking a pulse lane.
+ *
+ * @param horizontalLines - Visible horizontal grid bands.
+ * @returns Pulse-eligible horizontal paths biased toward the foreground.
+ */
+export function resolvePlaybackGroundGridPreferredHorizontalPulsePaths(
+  horizontalLines: readonly PlaybackGroundGridLineSegment[],
+): readonly PlaybackGroundGridPulsePath[] {
+  const eligibleHorizontalPulsePaths: PlaybackGroundGridPulsePath[] = [];
+
+  for (const horizontalLine of horizontalLines) {
+    if (
+      horizontalLine.thicknessPx <
+      FLAPPY_GROUND_GRID_PULSE_MIN_ELIGIBLE_THICKNESS_PX
+    ) {
+      continue;
+    }
+
+    eligibleHorizontalPulsePaths.push({
+      orientation: 'horizontal',
+      startXPx: horizontalLine.startXPx,
+      startYPx: horizontalLine.startYPx,
+      endXPx: horizontalLine.endXPx,
+      endYPx: horizontalLine.endYPx,
+      thicknessPx: horizontalLine.thicknessPx,
+    });
+  }
+
+  if (eligibleHorizontalPulsePaths.length === 0) {
+    return eligibleHorizontalPulsePaths;
+  }
+
+  const preferredStartIndex = Math.min(
+    eligibleHorizontalPulsePaths.length - 1,
+    Math.floor(
+      eligibleHorizontalPulsePaths.length *
+        FLAPPY_GROUND_GRID_PULSE_PREFERRED_HORIZONTAL_START_RATIO,
+    ),
+  );
+  return eligibleHorizontalPulsePaths.slice(preferredStartIndex);
+}
+
+/**
+ * Resolves one cached draw-ready path for a grouped segment batch.
+ *
+ * @param segments - Ordered line segments that belong to one style batch.
+ * @returns Cached Path2D when available, otherwise null.
+ */
+function resolvePlaybackGroundGridBatchPath(
+  segments: readonly PlaybackGroundGridLineSegment[],
+): Path2D | null {
+  if (typeof Path2D !== 'function') {
+    return null;
+  }
+
+  const batchPath = new Path2D();
+  for (const segment of segments) {
+    batchPath.moveTo(segment.startXPx, segment.startYPx);
+    batchPath.lineTo(segment.endXPx, segment.endYPx);
+  }
+
+  return batchPath;
+}

package/test/examples/flappy_bird/browser-entry/playback/background/ground-grid/playback.background.ground-grid.geometry.layout.utils.test.ts

@@ -0,0 +1,96 @@
+import {
+  FLAPPY_MAX_DIFFICULTY_PIPE_PITCH_PX,
+  FLAPPY_PIPE_SPEED_MAX_PX_PER_FRAME,
+  FLAPPY_PIPE_SPAWN_INTERVAL_MIN_FRAMES,
+} from '../../../../constants/constants.difficulty';
+import {
+  buildPlaybackGroundGridVerticalSceneMetrics,
+  resolvePlaybackGroundGridVerticalCycleContext,
+} from './playback.background.ground-grid.geometry.layout.utils';
+import { resolvePlaybackGroundGridPipeConnectionProfile } from './playback.background.ground-grid.math.utils';
+import type { PlaybackBackgroundGroundGridSceneContext } from './playback.background.ground-grid.types';
+
+describe('buildPlaybackGroundGridVerticalSceneMetrics', () => {
+  it('matches pipe-floor lane spacing to the actual max-difficulty pipe pitch', () => {
+    const sceneContext = createSceneContext();
+    const verticalSceneMetrics =
+      buildPlaybackGroundGridVerticalSceneMetrics(sceneContext);
+    const pipeConnectionProfile =
+      resolvePlaybackGroundGridPipeConnectionProfile(
+        sceneContext.lowerBandBottomYPx,
+      );
+    const retainedWidthRatioAtPipeConnection =
+      (sceneContext.vanishingPointYPx - pipeConnectionProfile.pipeFloorYPx) /
+      (sceneContext.vanishingPointYPx - sceneContext.lowerBandBottomYPx);
+    const projectedLaneSpacingPx =
+      verticalSceneMetrics.safeLaneSpacingPx *
+      retainedWidthRatioAtPipeConnection;
+
+    expect(projectedLaneSpacingPx).toBeCloseTo(
+      FLAPPY_MAX_DIFFICULTY_PIPE_PITCH_PX,
+      6,
+    );
+  });
+
+  it('repeats the same grid phase after one max-difficulty spawn interval', () => {
+    const sceneContext = createSceneContext();
+    const verticalSceneMetrics =
+      buildPlaybackGroundGridVerticalSceneMetrics(sceneContext);
+    const pipeConnectionProfile =
+      resolvePlaybackGroundGridPipeConnectionProfile(
+        sceneContext.lowerBandBottomYPx,
+      );
+    const retainedWidthRatioAtPipeConnection =
+      (sceneContext.vanishingPointYPx - pipeConnectionProfile.pipeFloorYPx) /
+      (sceneContext.vanishingPointYPx - sceneContext.lowerBandBottomYPx);
+    const projectedLaneSpacingPx =
+      verticalSceneMetrics.safeLaneSpacingPx *
+      retainedWidthRatioAtPipeConnection;
+    const projectedTravelPerSpawnPx =
+      FLAPPY_PIPE_SPEED_MAX_PX_PER_FRAME *
+      FLAPPY_PIPE_SPAWN_INTERVAL_MIN_FRAMES;
+
+    expect(projectedTravelPerSpawnPx % projectedLaneSpacingPx).toBeCloseTo(
+      0,
+      6,
+    );
+  });
+
+  it('retains enough rays to cover the full visible horizon span', () => {
+    const sceneContext = createSceneContext();
+    const verticalSceneMetrics =
+      buildPlaybackGroundGridVerticalSceneMetrics(sceneContext);
+    const coveredAnchorSpanPx =
+      (verticalSceneMetrics.totalVisibleLaneCount - 1) *
+      verticalSceneMetrics.safeLaneSpacingPx;
+
+    expect(coveredAnchorSpanPx).toBeGreaterThanOrEqual(
+      verticalSceneMetrics.visibleAnchorBounds.anchorSpanPx,
+    );
+  });
+});
+
+describe('resolvePlaybackGroundGridVerticalCycleContext', () => {
+  it('preserves the lane spacing that the viewport metrics resolved', () => {
+    const verticalCycleContext = resolvePlaybackGroundGridVerticalCycleContext(
+      120,
+      512,
+      960,
+    );
+
+    expect(verticalCycleContext.safeLaneSpacingPx).toBe(120);
+  });
+});
+
+function createSceneContext(): PlaybackBackgroundGroundGridSceneContext {
+  return {
+    viewportOffsetXPx: 0,
+    visibleWorldWidthPx: 288,
+    alignedHorizonYPx: 339,
+    lowerBandTopYPx: 341,
+    lowerBandHeightPx: 171,
+    lowerBandBottomYPx: 512,
+    vanishingPointXPx: 144,
+    vanishingPointYPx: 256,
+  };
+}