@reicek/neataptic-ts 0.1.21 → 0.1.22

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

@@ -0,0 +1,233 @@
+import {
+  FLAPPY_GROUND_GRID_APPROX_FRAME_DURATION_MS,
+  FLAPPY_GROUND_GRID_PULSE_ALPHA,
+  FLAPPY_GROUND_GRID_PULSE_GLOW_BLUR_PX,
+  FLAPPY_GROUND_GRID_PULSE_INTERVAL_MS,
+  FLAPPY_GROUND_GRID_PULSE_LIFETIME_MS,
+  FLAPPY_GROUND_GRID_PULSE_MAX_SIZE_PX,
+  FLAPPY_GROUND_GRID_PULSE_MIN_SIZE_PX,
+  FLAPPY_GROUND_GRID_UNSIGNED_NORMALIZATION_DIVISOR,
+  FLAPPY_GROUND_GRID_VERTICAL_PULSE_END_RATIO,
+  FLAPPY_GROUND_GRID_VERTICAL_PULSE_START_RATIO,
+} from './playback.background.ground-grid.constants';
+import {
+  interpolatePlaybackGroundGridPoint,
+  resolvePlaybackGroundGridDepthFromHorizonDistance,
+  resolvePlaybackGroundGridLineThickness,
+} from './playback.background.ground-grid.math.utils';
+import type {
+  PlaybackBackgroundGroundGridSceneContext,
+  PlaybackGroundGridPulse,
+  PlaybackGroundGridPulseInput,
+  PlaybackGroundGridPulseOrientation,
+  PlaybackGroundGridPulsePath,
+  PlaybackGroundGridPulseTrackThicknessInput,
+  PlaybackGroundGridPulseTravelRatioInput,
+} from './playback.background.ground-grid.types';
+
+/**
+ * Resolves one rare, deterministic pulse square for the current frame.
+ *
+ * @param input - Current frame timing and visible pulse path candidates.
+ * @returns Visible pulse square, or null when the current slot is inactive.
+ */
+export function resolvePlaybackGroundGridPulse(
+  input: PlaybackGroundGridPulseInput,
+): PlaybackGroundGridPulse | null {
+  const currentTimeMs =
+    input.frameIndex * FLAPPY_GROUND_GRID_APPROX_FRAME_DURATION_MS;
+  const pulseSlotIndex = Math.floor(
+    currentTimeMs / FLAPPY_GROUND_GRID_PULSE_INTERVAL_MS,
+  );
+  const pulseElapsedMs =
+    currentTimeMs - pulseSlotIndex * FLAPPY_GROUND_GRID_PULSE_INTERVAL_MS;
+  if (pulseElapsedMs > FLAPPY_GROUND_GRID_PULSE_LIFETIME_MS) {
+    return null;
+  }
+
+  const pulseOrientation =
+    resolvePlaybackGroundGridPulseOrientation(pulseSlotIndex);
+  const selectedPulsePath =
+    pulseOrientation === 'horizontal'
+      ? resolvePlaybackGroundGridHorizontalPulsePath(
+          input.horizontalPulsePaths,
+          pulseSlotIndex,
+        )
+      : resolvePlaybackGroundGridVerticalPulsePath(
+          input.verticalPulsePaths,
+          input.visibleVerticalPulsePaths,
+          pulseSlotIndex,
+        );
+  if (!selectedPulsePath) {
+    return null;
+  }
+
+  const directionIsForward =
+    resolvePlaybackGroundGridUnitHash(pulseSlotIndex, 29) >= 0.5;
+  const lifetimeProgressRatio =
+    pulseElapsedMs / FLAPPY_GROUND_GRID_PULSE_LIFETIME_MS;
+  const travelProgressRatio = resolvePlaybackGroundGridPulseTravelRatio({
+    directionIsForward,
+    lifetimeProgressRatio,
+    orientation: pulseOrientation,
+  });
+  const pulseCenter = interpolatePlaybackGroundGridPoint(
+    selectedPulsePath.startXPx,
+    selectedPulsePath.startYPx,
+    selectedPulsePath.endXPx,
+    selectedPulsePath.endYPx,
+    travelProgressRatio,
+  );
+  const pulseTrackThicknessPx = resolvePlaybackGroundGridPulseTrackThickness({
+    pulseCenterYPx: pulseCenter.yPx,
+    pulsePath: selectedPulsePath,
+    sceneContext: input.sceneContext,
+  });
+
+  return {
+    centerXPx: pulseCenter.xPx,
+    centerYPx: pulseCenter.yPx,
+    sizePx: Math.max(
+      FLAPPY_GROUND_GRID_PULSE_MIN_SIZE_PX,
+      Math.min(FLAPPY_GROUND_GRID_PULSE_MAX_SIZE_PX, pulseTrackThicknessPx),
+    ),
+    alpha: FLAPPY_GROUND_GRID_PULSE_ALPHA,
+    glowBlurPx: FLAPPY_GROUND_GRID_PULSE_GLOW_BLUR_PX,
+  };
+}
+
+/**
+ * Resolves pulse orientation for one deterministic pulse slot.
+ *
+ * @param pulseSlotIndex - Zero-based pulse slot index.
+ * @returns Horizontal or vertical pulse travel orientation.
+ */
+function resolvePlaybackGroundGridPulseOrientation(
+  pulseSlotIndex: number,
+): PlaybackGroundGridPulseOrientation {
+  return resolvePlaybackGroundGridUnitHash(pulseSlotIndex, 11) >= 0.5
+    ? 'horizontal'
+    : 'vertical';
+}
+
+/**
+ * Selects one thick-enough horizontal band for the current pulse slot.
+ *
+ * @param horizontalPulsePaths - Cached horizontal pulse paths eligible for travel.
+ * @param pulseSlotIndex - Zero-based pulse slot index.
+ * @returns Horizontal pulse path, or null when none are suitable.
+ */
+function resolvePlaybackGroundGridHorizontalPulsePath(
+  horizontalPulsePaths: readonly PlaybackGroundGridPulsePath[],
+  pulseSlotIndex: number,
+): PlaybackGroundGridPulsePath | null {
+  if (horizontalPulsePaths.length === 0) {
+    return null;
+  }
+
+  const selectedLineIndex = Math.min(
+    horizontalPulsePaths.length - 1,
+    Math.floor(
+      resolvePlaybackGroundGridUnitHash(pulseSlotIndex, 17) *
+        horizontalPulsePaths.length,
+    ),
+  );
+  return horizontalPulsePaths[selectedLineIndex];
+}
+
+/**
+ * Selects one sparse vertical pulse path for the current pulse slot.
+ *
+ * @param verticalPulsePaths - Full vertical ray paths.
+ * @param visibleVerticalPulsePaths - Visible subset preferred for on-screen pulses.
+ * @param pulseSlotIndex - Zero-based pulse slot index.
+ * @returns Vertical pulse path, or null when none are available.
+ */
+function resolvePlaybackGroundGridVerticalPulsePath(
+  verticalPulsePaths: readonly PlaybackGroundGridPulsePath[],
+  visibleVerticalPulsePaths: readonly PlaybackGroundGridPulsePath[],
+  pulseSlotIndex: number,
+): PlaybackGroundGridPulsePath | null {
+  if (verticalPulsePaths.length === 0) {
+    return null;
+  }
+
+  const candidatePulsePaths =
+    visibleVerticalPulsePaths.length > 0
+      ? visibleVerticalPulsePaths
+      : verticalPulsePaths;
+
+  const selectedPathIndex = Math.min(
+    candidatePulsePaths.length - 1,
+    Math.floor(
+      resolvePlaybackGroundGridUnitHash(pulseSlotIndex, 23) *
+        candidatePulsePaths.length,
+    ),
+  );
+  return candidatePulsePaths[selectedPathIndex];
+}
+
+/**
+ * Resolves the pulse travel ratio along its chosen line.
+ *
+ * @param input - Pulse timing direction and orientation.
+ * @returns Normalized 0..1 travel ratio along the chosen line.
+ */
+function resolvePlaybackGroundGridPulseTravelRatio(
+  input: PlaybackGroundGridPulseTravelRatioInput,
+): number {
+  const baseTravelProgressRatio = input.directionIsForward
+    ? input.lifetimeProgressRatio
+    : 1 - input.lifetimeProgressRatio;
+  if (input.orientation === 'horizontal') {
+    return baseTravelProgressRatio;
+  }
+
+  return (
+    FLAPPY_GROUND_GRID_VERTICAL_PULSE_START_RATIO +
+    (FLAPPY_GROUND_GRID_VERTICAL_PULSE_END_RATIO -
+      FLAPPY_GROUND_GRID_VERTICAL_PULSE_START_RATIO) *
+      baseTravelProgressRatio
+  );
+}
+
+/**
+ * Resolves the local track thickness at the pulse position.
+ *
+ * @param input - Pulse position, path, and scene geometry.
+ * @returns Thickness of the current line under the pulse.
+ */
+function resolvePlaybackGroundGridPulseTrackThickness(
+  input: PlaybackGroundGridPulseTrackThicknessInput,
+): number {
+  if (input.pulsePath.orientation === 'horizontal') {
+    return input.pulsePath.thicknessPx;
+  }
+
+  const maximumDistanceToHorizonPx = Math.max(
+    1,
+    input.sceneContext.lowerBandBottomYPx -
+      input.sceneContext.alignedHorizonYPx,
+  );
+  const depthRatio = resolvePlaybackGroundGridDepthFromHorizonDistance(
+    input.pulseCenterYPx - input.sceneContext.alignedHorizonYPx,
+    maximumDistanceToHorizonPx,
+  );
+  return resolvePlaybackGroundGridLineThickness(depthRatio);
+}
+
+/**
+ * Resolves a deterministic unit-interval hash from a slot index and salt.
+ *
+ * @param seed - Slot-local seed value.
+ * @param salt - Small integer salt used to pick a stable random stream.
+ * @returns Stable random value in the range 0..1.
+ */
+function resolvePlaybackGroundGridUnitHash(seed: number, salt: number): number {
+  let hashedValue = (seed + 1) ^ Math.imul(salt + 1, 374_761_393);
+  hashedValue = Math.imul(hashedValue ^ (hashedValue >>> 13), 1_274_126_177);
+  hashedValue ^= hashedValue >>> 16;
+  return (
+    (hashedValue >>> 0) / FLAPPY_GROUND_GRID_UNSIGNED_NORMALIZATION_DIVISOR
+  );
+}

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

@@ -0,0 +1,211 @@
+import {
+  FLAPPY_GROUND_GRID_FOG_ALPHA,
+  FLAPPY_GROUND_GRID_FOG_HEIGHT_RATIO,
+  FLAPPY_GROUND_GRID_PULSE_GLOW_ALPHA_RATIO,
+  FLAPPY_GROUND_GRID_PULSE_GLOW_SIZE_MULTIPLIER,
+} from './playback.background.ground-grid.constants';
+import {
+  FLAPPY_BACKGROUND_COMPOSITE_LIGHTER,
+  FLAPPY_BACKGROUND_COMPOSITE_SOURCE_OVER,
+} from '../playback.background.constants';
+import {
+  resolveCachedGroundGridFogGradient,
+  resolveGroundGridSceneCacheKey,
+} from './playback.background.ground-grid.cache.services';
+import type {
+  PlaybackBackgroundGroundGridResolvedScene,
+  PlaybackGroundGridGeometry,
+  PlaybackGroundGridPulse,
+  PlaybackGroundGridSegmentBatch,
+} from './playback.background.ground-grid.types';
+
+/**
+ * Draws the resolved neon ground grid inside the lower background band.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param resolvedScene - Geometry and style for the current viewport.
+ * @param geometry - Precomputed horizontal and vertical line segments.
+ * @returns Nothing.
+ */
+export function drawPlaybackGroundGrid(
+  context: CanvasRenderingContext2D,
+  resolvedScene: PlaybackBackgroundGroundGridResolvedScene,
+  geometry: PlaybackGroundGridGeometry,
+): void {
+  context.save();
+  context.translate(resolvedScene.sceneContext.viewportOffsetXPx, 0);
+  context.globalCompositeOperation = FLAPPY_BACKGROUND_COMPOSITE_SOURCE_OVER;
+  context.beginPath();
+  context.rect(
+    0,
+    resolvedScene.sceneContext.lowerBandTopYPx,
+    resolvedScene.sceneContext.visibleWorldWidthPx,
+    resolvedScene.sceneContext.lowerBandHeightPx,
+  );
+  context.clip();
+
+  drawGroundGridFog(context, resolvedScene);
+  drawGroundGridSegmentBatches(
+    context,
+    geometry.verticalLineBatches,
+    resolvedScene.style.lineColor,
+    resolvedScene.style.glowColor,
+  );
+  drawGroundGridSegmentBatches(
+    context,
+    geometry.horizontalLineBatches,
+    resolvedScene.style.lineColor,
+    resolvedScene.style.glowColor,
+  );
+  drawGroundGridPulse(
+    context,
+    geometry.pulse,
+    resolvedScene.style.pulseFillColor,
+    resolvedScene.style.pulseGlowColor,
+  );
+  context.restore();
+}
+
+/**
+ * Draws the lower-band atmospheric wash behind the neon line work.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param resolvedScene - Geometry and style for the current viewport.
+ * @returns Nothing.
+ */
+export function drawGroundGridFog(
+  context: CanvasRenderingContext2D,
+  resolvedScene: PlaybackBackgroundGroundGridResolvedScene,
+): void {
+  const fogHeightPx =
+    resolvedScene.sceneContext.lowerBandHeightPx *
+    FLAPPY_GROUND_GRID_FOG_HEIGHT_RATIO;
+  const sceneCacheKey = resolveGroundGridSceneCacheKey(
+    resolvedScene.sceneContext,
+  );
+  const fogGradient = resolveCachedGroundGridFogGradient(
+    context,
+    sceneCacheKey,
+    resolvedScene.sceneContext,
+    resolvedScene.style.fogColor,
+  );
+
+  context.save();
+  context.globalAlpha = FLAPPY_GROUND_GRID_FOG_ALPHA;
+  context.fillStyle = fogGradient;
+  context.fillRect(
+    0,
+    resolvedScene.sceneContext.lowerBandTopYPx,
+    resolvedScene.sceneContext.visibleWorldWidthPx,
+    fogHeightPx,
+  );
+  context.restore();
+}
+
+/**
+ * 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.
+ * @param glowColor - Outer glow color used for bloom.
+ * @returns Nothing.
+ */
+export function drawGroundGridSegmentBatches(
+  context: CanvasRenderingContext2D,
+  batches: readonly PlaybackGroundGridSegmentBatch[],
+  lineColor: string,
+  glowColor: string,
+): void {
+  context.save();
+  context.strokeStyle = lineColor;
+  context.shadowColor = glowColor;
+
+  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.shadowBlur = batch.blurPx;
+  context.globalAlpha = batch.alpha;
+  context.lineWidth = batch.thicknessPx;
+  context.beginPath();
+
+  for (const segment of batch.segments) {
+    context.moveTo(segment.startXPx, segment.startYPx);
+    context.lineTo(segment.endXPx, segment.endYPx);
+  }
+
+  context.stroke();
+
+  context.shadowBlur = 0;
+  context.globalAlpha = Math.min(1, batch.alpha + 0.18);
+  context.beginPath();
+
+  for (const segment of batch.segments) {
+    context.moveTo(segment.startXPx, segment.startYPx);
+    context.lineTo(segment.endXPx, segment.endYPx);
+  }
+
+  context.stroke();
+}
+
+/**
+ * Draws one pulse square above the grid lines and below gameplay entities.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param pulse - Visible pulse square for the current frame.
+ * @param fillColor - Core neon fill color.
+ * @param glowColor - Outer glow color used behind the pulse.
+ * @returns Nothing.
+ */
+export function drawGroundGridPulse(
+  context: CanvasRenderingContext2D,
+  pulse: PlaybackGroundGridPulse | null,
+  fillColor: string,
+  glowColor: string,
+): void {
+  if (!pulse) {
+    return;
+  }
+
+  const halfSizePx = pulse.sizePx * 0.5;
+  const glowSizePx =
+    pulse.sizePx * FLAPPY_GROUND_GRID_PULSE_GLOW_SIZE_MULTIPLIER;
+  const glowHalfSizePx = glowSizePx * 0.5;
+
+  context.save();
+  context.globalCompositeOperation = FLAPPY_BACKGROUND_COMPOSITE_LIGHTER;
+  context.fillStyle = fillColor;
+  context.shadowColor = glowColor;
+  context.shadowBlur = pulse.glowBlurPx;
+  context.globalAlpha = pulse.alpha * FLAPPY_GROUND_GRID_PULSE_GLOW_ALPHA_RATIO;
+  context.fillRect(
+    pulse.centerXPx - glowHalfSizePx,
+    pulse.centerYPx - glowHalfSizePx,
+    glowSizePx,
+    glowSizePx,
+  );
+
+  context.globalAlpha = pulse.alpha;
+  context.fillRect(
+    pulse.centerXPx - halfSizePx,
+    pulse.centerYPx - halfSizePx,
+    pulse.sizePx,
+    pulse.sizePx,
+  );
+  context.restore();
+}

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

@@ -0,0 +1,48 @@
+import { drawPlaybackGroundGrid } from './playback.background.ground-grid.services';
+import { FLAPPY_BACKGROUND_GROUND_GRID_STYLE } from './playback.background.ground-grid.constants';
+import type {
+  PlaybackBackgroundGroundGridRequest,
+  PlaybackBackgroundGroundGridResolvedScene,
+  PlaybackBackgroundGroundGridSourceScene,
+} from './playback.background.ground-grid.types';
+import {
+  resolvePlaybackGroundGridGeometry,
+  resolvePlaybackGroundGridSceneContext,
+} from './playback.background.ground-grid.utils';
+
+/**
+ * Draws the neon lower-band ground grid beneath the horizon.
+ *
+ * The grid is intentionally stylized rather than physically realistic: fixed
+ * horizontal depth bands compress toward the horizon, while moving perspective
+ * rays slide sideways but still converge to the centered vanishing point.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param sourceScene - Shared lower-band geometry from the background module.
+ * @param request - Shared parallax scroll input for the current frame.
+ * @returns Nothing.
+ */
+export function renderPlaybackBackgroundGroundGrid(
+  context: CanvasRenderingContext2D,
+  sourceScene: PlaybackBackgroundGroundGridSourceScene,
+  request: PlaybackBackgroundGroundGridRequest,
+): void {
+  // Step 1: Adapt the shared background scene into the narrow grid contract.
+  const sceneContext = resolvePlaybackGroundGridSceneContext(sourceScene);
+
+  // Step 2: Resolve theme-owned styling for the lower-band grid.
+  const resolvedScene: PlaybackBackgroundGroundGridResolvedScene = {
+    sceneContext,
+    style: FLAPPY_BACKGROUND_GROUND_GRID_STYLE,
+  };
+
+  // Step 3: Build all grid geometry before touching the canvas state.
+  const geometry = resolvePlaybackGroundGridGeometry(
+    sceneContext,
+    request.frameIndex,
+    request.scrollBasePx,
+  );
+
+  // Step 4: Draw the resolved lower-band neon grid.
+  drawPlaybackGroundGrid(context, resolvedScene, geometry);
+}

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

@@ -0,0 +1,212 @@
+import type { PlaybackBackgroundSceneContext } from '../playback.background.types';
+
+/**
+ * Narrow request required to render the playback ground grid.
+ */
+export type PlaybackBackgroundGroundGridRequest = {
+  frameIndex: number;
+  scrollBasePx: number;
+};
+
+/**
+ * Lazy builder used when one horizontal geometry cache entry is missing.
+ */
+export type PlaybackGroundGridHorizontalGeometryFactory =
+  () => PlaybackGroundGridHorizontalGeometry;
+
+/**
+ * Lazy builder used when one vertical geometry cache entry is missing.
+ */
+export type PlaybackGroundGridVerticalGeometryFactory =
+  () => PlaybackGroundGridVerticalGeometry;
+
+/**
+ * Immutable scene context resolved for one lower-band ground-grid pass.
+ */
+export type PlaybackBackgroundGroundGridSceneContext = {
+  viewportOffsetXPx: number;
+  visibleWorldWidthPx: number;
+  alignedHorizonYPx: number;
+  lowerBandTopYPx: number;
+  lowerBandHeightPx: number;
+  lowerBandBottomYPx: number;
+  vanishingPointXPx: number;
+  vanishingPointYPx: number;
+};
+
+/**
+ * Theme-owned style contract for the neon ground grid.
+ */
+export type PlaybackBackgroundGroundGridStyle = {
+  lineColor: string;
+  glowColor: string;
+  fogColor: string;
+  pulseFillColor: string;
+  pulseGlowColor: string;
+};
+
+/** Travel orientation used by lightweight pulse overlays. */
+export type PlaybackGroundGridPulseOrientation = 'horizontal' | 'vertical';
+
+/**
+ * Geometry and style package resolved before drawing the ground grid.
+ */
+export type PlaybackBackgroundGroundGridResolvedScene = {
+  sceneContext: PlaybackBackgroundGroundGridSceneContext;
+  style: PlaybackBackgroundGroundGridStyle;
+};
+
+/**
+ * Declarative line segment model used by the ground-grid renderer.
+ */
+export type PlaybackGroundGridLineSegment = {
+  startXPx: number;
+  startYPx: number;
+  endXPx: number;
+  endYPx: number;
+  alpha: number;
+  blurPx: number;
+  thicknessPx: number;
+};
+
+/** Ordered batch of line segments that share one render style. */
+export type PlaybackGroundGridSegmentBatch = {
+  alpha: number;
+  blurPx: number;
+  thicknessPx: number;
+  segments: readonly PlaybackGroundGridLineSegment[];
+};
+
+/**
+ * Internal helper contract used while generating vertical-ray sub-segments.
+ */
+export type PlaybackGroundGridVerticalRayInput = PlaybackGroundGridPulsePath & {
+  lineDepthRatio: number;
+  maximumDistanceToHorizonPx: number;
+  sceneContext: PlaybackBackgroundGroundGridSceneContext;
+  verticalSegmentCount: number;
+};
+
+/** Simplified path used by one visible pulse event. */
+export type PlaybackGroundGridPulsePath = {
+  orientation: PlaybackGroundGridPulseOrientation;
+  startXPx: number;
+  startYPx: number;
+  endXPx: number;
+  endYPx: number;
+  thicknessPx: number;
+};
+
+/** One visible pulse square rendered above the grid lines. */
+export type PlaybackGroundGridPulse = {
+  centerXPx: number;
+  centerYPx: number;
+  sizePx: number;
+  alpha: number;
+  glowBlurPx: number;
+};
+
+/**
+ * Pure geometry bundle generated before canvas drawing begins.
+ */
+export type PlaybackGroundGridGeometry = {
+  horizontalLineBatches: readonly PlaybackGroundGridSegmentBatch[];
+  pulse: PlaybackGroundGridPulse | null;
+  verticalLineBatches: readonly PlaybackGroundGridSegmentBatch[];
+};
+
+/**
+ * Cached horizontal geometry bundle reused across matching scene sizes.
+ */
+export type PlaybackGroundGridHorizontalGeometry = {
+  horizontalLineBatches: readonly PlaybackGroundGridSegmentBatch[];
+  horizontalLines: readonly PlaybackGroundGridLineSegment[];
+  preferredHorizontalPulsePaths: readonly PlaybackGroundGridPulsePath[];
+};
+
+/**
+ * Cached vertical geometry bundle reused across one wrapped scroll cycle.
+ */
+export type PlaybackGroundGridVerticalGeometry = {
+  verticalLineBatches: readonly PlaybackGroundGridSegmentBatch[];
+  verticalPulsePaths: readonly PlaybackGroundGridPulsePath[];
+  visibleVerticalPulsePaths: readonly PlaybackGroundGridPulsePath[];
+};
+
+/**
+ * Visible horizon bounds projected onto the bottom anchor line.
+ */
+export type PlaybackGroundGridAnchorBounds = {
+  leftAnchorXPx: number;
+  rightAnchorXPx: number;
+  anchorSpanPx: number;
+};
+
+/**
+ * Input used when projecting a visible horizon span onto anchor space.
+ */
+export type PlaybackGroundGridAnchorBoundsInput = {
+  horizonLeftXPx: number;
+  horizonRightXPx: number;
+  sceneContext: PlaybackBackgroundGroundGridSceneContext;
+};
+
+/**
+ * Input used when projecting one horizon x-position onto the floor anchor line.
+ */
+export type PlaybackGroundGridAnchorProjectionInput = {
+  horizonXPx: number;
+  sceneContext: PlaybackBackgroundGroundGridSceneContext;
+};
+
+/**
+ * Wrapped vertical-cycle state derived from scroll for one frame.
+ */
+export type PlaybackGroundGridVerticalCycleContext = {
+  quantizedWrappedOffsetPx: number;
+  safeLaneSpacingPx: number;
+};
+
+/**
+ * Input contract used while resolving one deterministic pulse event.
+ */
+export type PlaybackGroundGridPulseInput = {
+  frameIndex: number;
+  horizontalPulsePaths: readonly PlaybackGroundGridPulsePath[];
+  sceneContext: PlaybackBackgroundGroundGridSceneContext;
+  visibleVerticalPulsePaths: readonly PlaybackGroundGridPulsePath[];
+  verticalPulsePaths: readonly PlaybackGroundGridPulsePath[];
+};
+
+/**
+ * Direction and timing state used when resolving pulse travel progress.
+ */
+export type PlaybackGroundGridPulseTravelRatioInput = {
+  directionIsForward: boolean;
+  lifetimeProgressRatio: number;
+  orientation: PlaybackGroundGridPulseOrientation;
+};
+
+/**
+ * Input used when adapting a pulse position into a local track thickness.
+ */
+export type PlaybackGroundGridPulseTrackThicknessInput = {
+  pulseCenterYPx: number;
+  pulsePath: PlaybackGroundGridPulsePath;
+  sceneContext: PlaybackBackgroundGroundGridSceneContext;
+};
+
+/**
+ * Helper alias used when adapting the shared background scene context.
+ */
+export type PlaybackBackgroundGroundGridSourceScene = Pick<
+  PlaybackBackgroundSceneContext,
+  | 'viewportLeftXPx'
+  | 'visibleWorldWidthPx'
+  | 'alignedHorizonYPx'
+  | 'lowerBandTopYPx'
+  | 'lowerBandHeightPx'
+  | 'lowerBandBottomYPx'
+  | 'vanishingPointXPx'
+  | 'vanishingPointYPx'
+>;