@reicek/neataptic-ts 0.1.21 → 0.1.22

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

@@ -0,0 +1,81 @@
+import {
+  resolvePlaybackGroundGridHorizontalGeometry,
+  resolvePlaybackGroundGridVerticalGeometry,
+} from './playback.background.ground-grid.geometry.utils';
+import { resolvePlaybackGroundGridPulse } from './playback.background.ground-grid.pulse.utils';
+import type {
+  PlaybackBackgroundGroundGridSceneContext,
+  PlaybackBackgroundGroundGridSourceScene,
+  PlaybackGroundGridGeometry,
+  PlaybackGroundGridHorizontalGeometry,
+  PlaybackGroundGridVerticalGeometry,
+} from './playback.background.ground-grid.types';
+
+export {
+  interpolatePlaybackGroundGridPoint,
+  resolvePlaybackGroundGridDepthCurve,
+  resolvePlaybackGroundGridDepthFromHorizonDistance,
+  resolvePlaybackGroundGridLineAlpha,
+  resolvePlaybackGroundGridLineBlur,
+  resolvePlaybackGroundGridLineThickness,
+} from './playback.background.ground-grid.math.utils';
+
+/**
+ * Resolves the shared scene context used by the ground-grid renderer.
+ *
+ * @param sceneContext - Lower-band geometry provided by the background module.
+ * @returns Narrow scene contract consumed by grid-specific helpers.
+ */
+export function resolvePlaybackGroundGridSceneContext(
+  sceneContext: PlaybackBackgroundGroundGridSourceScene,
+): PlaybackBackgroundGroundGridSceneContext {
+  return {
+    viewportOffsetXPx: sceneContext.viewportLeftXPx,
+    visibleWorldWidthPx: sceneContext.visibleWorldWidthPx,
+    alignedHorizonYPx: sceneContext.alignedHorizonYPx,
+    lowerBandTopYPx: sceneContext.lowerBandTopYPx,
+    lowerBandHeightPx: sceneContext.lowerBandHeightPx,
+    lowerBandBottomYPx: sceneContext.lowerBandBottomYPx,
+    vanishingPointXPx:
+      sceneContext.vanishingPointXPx - sceneContext.viewportLeftXPx,
+    vanishingPointYPx: sceneContext.vanishingPointYPx,
+  };
+}
+
+/**
+ * Builds the line geometry for the neon ground grid.
+ *
+ * @param sceneContext - Lower-band geometry for the current viewport.
+ * @param frameIndex - Current deterministic playback frame index.
+ * @param scrollBasePx - Shared world scroll used for parallax motion.
+ * @returns Horizontal depth bands and perspective rays for the current frame.
+ */
+export function resolvePlaybackGroundGridGeometry(
+  sceneContext: PlaybackBackgroundGroundGridSceneContext,
+  frameIndex: number,
+  scrollBasePx: number,
+): PlaybackGroundGridGeometry {
+  // Step 1: Resolve and cache the fixed horizontal depth bands for the lower plane.
+  const horizontalGeometry: PlaybackGroundGridHorizontalGeometry =
+    resolvePlaybackGroundGridHorizontalGeometry(sceneContext);
+
+  // Step 2: Resolve and cache the moving perspective rays within one wrapped cycle.
+  const verticalGeometry: PlaybackGroundGridVerticalGeometry =
+    resolvePlaybackGroundGridVerticalGeometry(sceneContext, scrollBasePx);
+
+  // Step 3: Resolve one visible pulse above the grid lines.
+  const pulse = resolvePlaybackGroundGridPulse({
+    frameIndex,
+    horizontalPulsePaths: horizontalGeometry.preferredHorizontalPulsePaths,
+    sceneContext,
+    verticalPulsePaths: verticalGeometry.verticalPulsePaths,
+    visibleVerticalPulsePaths: verticalGeometry.visibleVerticalPulsePaths,
+  });
+
+  // Step 4: Return the pure geometry bundle used by the canvas renderer.
+  return {
+    horizontalLineBatches: horizontalGeometry.horizontalLineBatches,
+    pulse,
+    verticalLineBatches: verticalGeometry.verticalLineBatches,
+  };
+}

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

@@ -0,0 +1,96 @@
+import type {
+  PlaybackBackgroundLayout,
+  PlaybackBackgroundLayoutFactory,
+} from './playback.background.types';
+
+let cachedViewportSizeKey: string | null = null;
+
+const cachedLayoutsByHeightPx = new Map<number, PlaybackBackgroundLayout>();
+const cachedTileCoverageCountsByTileWidthPx = new Map<number, number>();
+
+/**
+ * Ensures background caches only retain entries for the current viewport size.
+ *
+ * When the page size changes, cached geometry and coverage counts become
+ * obsolete because the background bands and tile coverage both depend on the
+ * current viewport dimensions.
+ *
+ * @param visibleWorldWidthPx - Current visible world width in pixels.
+ * @param visibleWorldHeightPx - Current visible world height in pixels.
+ * @returns Stable viewport-size cache key for the current frame.
+ */
+export function ensurePlaybackBackgroundViewportCacheValidity(
+  visibleWorldWidthPx: number,
+  visibleWorldHeightPx: number,
+): string {
+  const viewportSizeKey = resolvePlaybackBackgroundViewportCacheKey(
+    visibleWorldWidthPx,
+    visibleWorldHeightPx,
+  );
+
+  if (cachedViewportSizeKey === viewportSizeKey) {
+    return viewportSizeKey;
+  }
+
+  cachedViewportSizeKey = viewportSizeKey;
+  cachedLayoutsByHeightPx.clear();
+  cachedTileCoverageCountsByTileWidthPx.clear();
+  return viewportSizeKey;
+}
+
+/**
+ * Resolves the stable viewport-size cache key used by background caches.
+ *
+ * @param visibleWorldWidthPx - Current visible world width in pixels.
+ * @param visibleWorldHeightPx - Current visible world height in pixels.
+ * @returns Cache key that changes whenever the page size changes.
+ */
+export function resolvePlaybackBackgroundViewportCacheKey(
+  visibleWorldWidthPx: number,
+  visibleWorldHeightPx: number,
+): string {
+  return `${visibleWorldWidthPx}x${visibleWorldHeightPx}`;
+}
+
+/**
+ * Resolves cached background layout for the current viewport height.
+ *
+ * @param visibleWorldHeightPx - Current visible world height in pixels.
+ * @param factory - Lazy layout builder used when the cache misses.
+ * @returns Cached background layout for the current viewport size.
+ */
+export function resolveCachedPlaybackBackgroundLayout(
+  visibleWorldHeightPx: number,
+  factory: PlaybackBackgroundLayoutFactory,
+): PlaybackBackgroundLayout {
+  const cachedLayout = cachedLayoutsByHeightPx.get(visibleWorldHeightPx);
+  if (cachedLayout) {
+    return cachedLayout;
+  }
+
+  const resolvedLayout = factory();
+  cachedLayoutsByHeightPx.set(visibleWorldHeightPx, resolvedLayout);
+  return resolvedLayout;
+}
+
+/**
+ * Resolves cached tile coverage count for one tile width.
+ *
+ * @param tileWidthPx - Width of one repeated starfield tile in pixels.
+ * @param factory - Lazy coverage builder used when the cache misses.
+ * @returns Cached tile coverage count for the active viewport width.
+ */
+export function resolveCachedPlaybackTileCoverageCount(
+  tileWidthPx: number,
+  factory: () => number,
+): number {
+  const cachedCoverageCount =
+    cachedTileCoverageCountsByTileWidthPx.get(tileWidthPx);
+  if (cachedCoverageCount !== undefined) {
+    return cachedCoverageCount;
+  }
+
+  const resolvedCoverageCount = factory();
+  cachedTileCoverageCountsByTileWidthPx.set(tileWidthPx, resolvedCoverageCount);
+  return resolvedCoverageCount;
+}

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

@@ -0,0 +1,62 @@
+import { FLAPPY_NEON_PALETTE } from '../../../constants/constants';
+import type { PlaybackHorizonStyle } from './playback.background.types';
+
+/**
+ * Background layout ratio reserved for the starfield sky band.
+ *
+ * The top band intentionally occupies most of the scene so the future ground
+ * layer can take over the lower strip without competing with the stars.
+ */
+export const FLAPPY_BACKGROUND_SKY_HEIGHT_RATIO = 2 / 3;
+
+/** Minimum safe viewport dimension used by background render math (pixels). */
+export const FLAPPY_BACKGROUND_MIN_VIEWPORT_DIMENSION_PX = 1;
+
+/** Index offset used to draw one extra tile before the visible left edge. */
+export const FLAPPY_BACKGROUND_TILE_ROW_START_INDEX = -1;
+
+/** Extra tile count rendered past the visible right edge for seamless wrap. */
+export const FLAPPY_BACKGROUND_TILE_ROW_BUFFER_COUNT = 1;
+
+/** Half-thickness multiplier used to center the horizon line on the split. */
+export const FLAPPY_BACKGROUND_HORIZON_HALF_THICKNESS_MULTIPLIER = 0.5;
+
+/** Divisor used to detect odd stroke widths for pixel snapping. */
+export const FLAPPY_BACKGROUND_ODD_STROKE_DIVISOR = 2;
+
+/** Pixel offset used to align odd-width strokes to the device pixel grid. */
+export const FLAPPY_BACKGROUND_ODD_STROKE_ALIGNMENT_OFFSET_PX = 0.5;
+
+/** Composite mode used for standard opaque drawing passes. */
+export const FLAPPY_BACKGROUND_COMPOSITE_SOURCE_OVER = 'source-over';
+
+/** Composite mode used when stacking glow-heavy starfield layers. */
+export const FLAPPY_BACKGROUND_COMPOSITE_LIGHTER = 'lighter';
+
+/** Transparent shadow color used to reset canvas glow state. */
+export const FLAPPY_BACKGROUND_TRANSPARENT_SHADOW_COLOR = 'transparent';
+
+/** Thickness of the neon horizon divider line (pixels). */
+export const FLAPPY_BACKGROUND_HORIZON_LINE_THICKNESS_PX = 4;
+
+/** Soft glow opacity applied during the horizon glow pass. */
+export const FLAPPY_BACKGROUND_HORIZON_GLOW_ALPHA = 0.92;
+
+/** Blur radius used to bloom the horizon divider glow (pixels). */
+export const FLAPPY_BACKGROUND_HORIZON_GLOW_BLUR_PX = 14;
+
+/**
+ * Frozen neon paint bundle reused by the playback horizon renderer.
+ *
+ * Keeping this style object in the constants module prevents repeated
+ * allocation during every background frame while still keeping the palette
+ * centrally theme-owned.
+ */
+export const FLAPPY_BACKGROUND_HORIZON_STYLE: PlaybackHorizonStyle =
+  Object.freeze({
+    lineColor: FLAPPY_NEON_PALETTE.horizonLine,
+    glowColor: FLAPPY_NEON_PALETTE.horizonGlow,
+    glowAlpha: FLAPPY_BACKGROUND_HORIZON_GLOW_ALPHA,
+    glowBlurPx: FLAPPY_BACKGROUND_HORIZON_GLOW_BLUR_PX,
+    lineThicknessPx: FLAPPY_BACKGROUND_HORIZON_LINE_THICKNESS_PX,
+  });

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

@@ -0,0 +1,244 @@
+import { FLAPPY_NEON_PALETTE } from '../../../constants/constants';
+import { resolveStarfieldTiles } from '../playback.starfield.service';
+import { positiveModulo } from '../playback.starfield.utils';
+import {
+  ensurePlaybackBackgroundViewportCacheValidity,
+  resolveCachedPlaybackBackgroundLayout,
+  resolveCachedPlaybackTileCoverageCount,
+} from './playback.background.cache.services';
+import {
+  FLAPPY_BACKGROUND_COMPOSITE_LIGHTER,
+  FLAPPY_BACKGROUND_COMPOSITE_SOURCE_OVER,
+  FLAPPY_BACKGROUND_TILE_ROW_BUFFER_COUNT,
+  FLAPPY_BACKGROUND_TILE_ROW_START_INDEX,
+  FLAPPY_BACKGROUND_TRANSPARENT_SHADOW_COLOR,
+} from './playback.background.constants';
+import type {
+  PlaybackBackgroundRequest,
+  PlaybackBackgroundSceneContext,
+  PlaybackHorizonLineRequest,
+} from './playback.background.types';
+import {
+  resolveAlignedHorizonYPx,
+  resolvePlaybackBackgroundLayout,
+  resolvePlaybackHorizonStyle,
+  resolveSafeBackgroundDimension,
+} from './playback.background.utils';
+
+/**
+ * Resolves the derived scene contract required by the background passes.
+ *
+ * @param request - Narrow render input required for background composition.
+ * @returns Immutable scene context shared by the private render helpers.
+ */
+export function resolvePlaybackBackgroundSceneContext(
+  request: PlaybackBackgroundRequest,
+): PlaybackBackgroundSceneContext {
+  // Step 1: Clamp viewport dimensions into render-safe pixel values.
+  const visibleWorldWidthPx = resolveSafeBackgroundDimension(
+    request.visibleWorldWidthPx,
+  );
+  const visibleWorldHeightPx = resolveSafeBackgroundDimension(
+    request.visibleWorldHeightPx,
+  );
+  ensurePlaybackBackgroundViewportCacheValidity(
+    visibleWorldWidthPx,
+    visibleWorldHeightPx,
+  );
+
+  // Step 2: Resolve the vertical sky-ground split and horizon style.
+  const backgroundLayout = resolveCachedPlaybackBackgroundLayout(
+    visibleWorldHeightPx,
+    () => resolvePlaybackBackgroundLayout(visibleWorldHeightPx),
+  );
+  const horizonStyle = resolvePlaybackHorizonStyle();
+  const alignedHorizonYPx = resolveAlignedHorizonYPx(
+    backgroundLayout.horizonYPx,
+    horizonStyle.lineThicknessPx,
+  );
+  const vanishingPointXPx = request.viewportLeftXPx + visibleWorldWidthPx * 0.5;
+  const vanishingPointYPx = visibleWorldHeightPx * 0.5;
+
+  // Step 3: Return a compact context object for the remaining passes.
+  return {
+    viewportLeftXPx: request.viewportLeftXPx,
+    visibleWorldWidthPx,
+    visibleWorldHeightPx,
+    skyHeightPx: backgroundLayout.skyHeightPx,
+    lowerBandTopYPx: backgroundLayout.lowerBandTopYPx,
+    lowerBandHeightPx: backgroundLayout.lowerBandHeightPx,
+    lowerBandBottomYPx: backgroundLayout.lowerBandBottomYPx,
+    alignedHorizonYPx,
+    vanishingPointXPx,
+    vanishingPointYPx,
+    horizonStyle,
+  };
+}
+
+/**
+ * Paints the base background fill for the currently visible viewport.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param sceneContext - Derived scene geometry and style contract.
+ * @returns Nothing.
+ */
+export function paintPlaybackBackgroundBase(
+  context: CanvasRenderingContext2D,
+  sceneContext: PlaybackBackgroundSceneContext,
+): void {
+  // Step 1: Reset canvas paint state to a predictable base pass.
+  context.globalAlpha = 1;
+  context.globalCompositeOperation = FLAPPY_BACKGROUND_COMPOSITE_SOURCE_OVER;
+  context.shadowBlur = 0;
+  context.shadowColor = FLAPPY_BACKGROUND_TRANSPARENT_SHADOW_COLOR;
+  context.fillStyle = FLAPPY_NEON_PALETTE.background;
+
+  // Step 2: Fill only the currently visible world-space viewport.
+  context.fillRect(
+    sceneContext.viewportLeftXPx,
+    0,
+    sceneContext.visibleWorldWidthPx,
+    sceneContext.visibleWorldHeightPx,
+  );
+}
+
+/**
+ * Draws the starfield parallax clipped to the upper sky band.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param sceneContext - Derived scene geometry and style contract.
+ * @param request - Narrow render input required for background composition.
+ * @returns Nothing.
+ */
+export function drawPlaybackBackgroundSky(
+  context: CanvasRenderingContext2D,
+  sceneContext: PlaybackBackgroundSceneContext,
+  request: PlaybackBackgroundRequest,
+): void {
+  // Step 1: Constrain star drawing to the sky band above the horizon.
+  context.save();
+  context.beginPath();
+  context.rect(
+    sceneContext.viewportLeftXPx,
+    0,
+    sceneContext.visibleWorldWidthPx,
+    sceneContext.skyHeightPx,
+  );
+  context.clip();
+  context.globalCompositeOperation = FLAPPY_BACKGROUND_COMPOSITE_LIGHTER;
+
+  // Step 2: Draw each cached starfield layer with its own parallax offset.
+  const starfieldTiles = resolveStarfieldTiles(sceneContext.skyHeightPx);
+  for (const starfieldTile of starfieldTiles) {
+    const scrollOffsetPx = request.scrollBasePx * starfieldTile.scrollRatio;
+    drawPlaybackTiledImageRow(
+      context,
+      sceneContext.viewportLeftXPx,
+      starfieldTile.image,
+      starfieldTile.tileWidthPx,
+      sceneContext.visibleWorldWidthPx,
+      scrollOffsetPx,
+    );
+  }
+
+  // Step 3: Restore the caller's unclipped canvas state.
+  context.restore();
+}
+
+/**
+ * Draws the glowing horizon divider across the visible viewport.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param sceneContext - Derived scene geometry and style contract.
+ * @returns Nothing.
+ */
+export function drawPlaybackBackgroundHorizon(
+  context: CanvasRenderingContext2D,
+  sceneContext: PlaybackBackgroundSceneContext,
+): void {
+  // Step 1: Delegate the divider rendering to the dedicated horizon helper.
+  drawPlaybackHorizonLine(context, {
+    viewportLeftXPx: sceneContext.viewportLeftXPx,
+    visibleWorldWidthPx: sceneContext.visibleWorldWidthPx,
+    alignedHorizonYPx: sceneContext.alignedHorizonYPx,
+    horizonStyle: sceneContext.horizonStyle,
+  });
+}
+
+/**
+ * Draws a horizontally tiled image strip across the visible width.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param startXPx - Leftmost visible world x-position for the tiled strip.
+ * @param tile - Pre-rendered tile image reused across the sky band.
+ * @param tileWidthPx - Width of one repeated tile in pixels.
+ * @param visibleWidthPx - Current visible width that must be fully covered.
+ * @param offsetPx - Parallax scroll offset used to wrap tile placement.
+ * @returns Nothing.
+ */
+function drawPlaybackTiledImageRow(
+  context: CanvasRenderingContext2D,
+  startXPx: number,
+  tile: CanvasImageSource,
+  tileWidthPx: number,
+  visibleWidthPx: number,
+  offsetPx: number,
+): void {
+  // Step 1: Normalize the scroll offset so tile placement stays bounded.
+  const normalizedOffsetPx = positiveModulo(offsetPx, tileWidthPx);
+  const maximumTileIndex = resolveCachedPlaybackTileCoverageCount(
+    tileWidthPx,
+    () =>
+      Math.ceil(visibleWidthPx / tileWidthPx) +
+      FLAPPY_BACKGROUND_TILE_ROW_BUFFER_COUNT,
+  );
+
+  // Step 2: Draw enough repeated tiles to cover the visible strip.
+  for (
+    let tileIndex = FLAPPY_BACKGROUND_TILE_ROW_START_INDEX;
+    tileIndex <= maximumTileIndex;
+    tileIndex += 1
+  ) {
+    const tileLeftPx = startXPx + tileIndex * tileWidthPx - normalizedOffsetPx;
+    context.drawImage(tile, tileLeftPx, 0);
+  }
+}
+
+/**
+ * Draws the glowing horizon divider using the provided neon style.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param request - Width, aligned y-position, and style for the divider.
+ * @returns Nothing.
+ */
+function drawPlaybackHorizonLine(
+  context: CanvasRenderingContext2D,
+  request: PlaybackHorizonLineRequest,
+): void {
+  // Step 1: Draw the outer glow pass to establish the neon bloom.
+  context.globalCompositeOperation = FLAPPY_BACKGROUND_COMPOSITE_SOURCE_OVER;
+  context.strokeStyle = request.horizonStyle.lineColor;
+  context.lineWidth = request.horizonStyle.lineThicknessPx;
+  context.shadowColor = request.horizonStyle.glowColor;
+  context.shadowBlur = request.horizonStyle.glowBlurPx;
+  context.globalAlpha = request.horizonStyle.glowAlpha;
+  context.beginPath();
+  context.moveTo(request.viewportLeftXPx, request.alignedHorizonYPx);
+  context.lineTo(
+    request.viewportLeftXPx + request.visibleWorldWidthPx,
+    request.alignedHorizonYPx,
+  );
+  context.stroke();
+
+  // Step 2: Restore a crisp core line after the glow pass.
+  context.shadowBlur = 0;
+  context.shadowColor = FLAPPY_BACKGROUND_TRANSPARENT_SHADOW_COLOR;
+  context.globalAlpha = 1;
+  context.beginPath();
+  context.moveTo(request.viewportLeftXPx, request.alignedHorizonYPx);
+  context.lineTo(
+    request.viewportLeftXPx + request.visibleWorldWidthPx,
+    request.alignedHorizonYPx,
+  );
+  context.stroke();
+}

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

@@ -0,0 +1,53 @@
+import { renderPlaybackBackgroundGroundGrid } from './ground-grid/playback.background.ground-grid';
+import {
+  drawPlaybackBackgroundHorizon,
+  drawPlaybackBackgroundSky,
+  paintPlaybackBackgroundBase,
+  resolvePlaybackBackgroundSceneContext,
+} from './playback.background.services';
+import type { PlaybackBackgroundRequest } from './playback.background.types';
+
+/**
+ * Draws the layered playback background.
+ *
+ * The composition keeps the top two-thirds for the neon starfield, fills the
+ * lower band with a TRON-like perspective ground grid, and separates both
+ * regions with a glowing horizon divider.
+ *
+ * @param context - Canvas 2D drawing context.
+ * @param request - Narrow render input required for background composition.
+ * @returns Nothing.
+ *
+ * @example
+ * ```ts
+ * renderPlaybackBackground(context, {
+ *   viewportLeftXPx: cameraLeftPx,
+ *   visibleWorldWidthPx: 288,
+ *   visibleWorldHeightPx: 512,
+ *   frameIndex,
+ *   scrollBasePx: frameIndex * pipeSpeedPxPerFrame,
+ * });
+ * ```
+ */
+export function renderPlaybackBackground(
+  context: CanvasRenderingContext2D,
+  request: PlaybackBackgroundRequest,
+): void {
+  // Step 1: Resolve the scene contracts needed by the background passes.
+  const backgroundSceneContext = resolvePlaybackBackgroundSceneContext(request);
+
+  // Step 2: Paint the shared base fill behind all background layers.
+  paintPlaybackBackgroundBase(context, backgroundSceneContext);
+
+  // Step 3: Render the sky-only starfield inside the horizon clip band.
+  drawPlaybackBackgroundSky(context, backgroundSceneContext, request);
+
+  // Step 4: Render the lower-band neon grid beneath the horizon seam.
+  renderPlaybackBackgroundGroundGrid(context, backgroundSceneContext, {
+    frameIndex: request.frameIndex,
+    scrollBasePx: request.scrollBasePx,
+  });
+
+  // Step 5: Draw the horizon divider above the sky and ground layers.
+  drawPlaybackBackgroundHorizon(context, backgroundSceneContext);
+}

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

@@ -0,0 +1,68 @@
+/**
+ * Minimal render input required to draw the playback background.
+ *
+ * Keeping this contract narrow prevents the background renderer from reaching
+ * into unrelated playback state such as birds, pipes, or trail caches.
+ */
+export type PlaybackBackgroundRequest = {
+  viewportLeftXPx: number;
+  visibleWorldWidthPx: number;
+  visibleWorldHeightPx: number;
+  frameIndex: number;
+  scrollBasePx: number;
+};
+
+/**
+ * Derived scene contract shared by the playback background render passes.
+ */
+export type PlaybackBackgroundSceneContext = {
+  viewportLeftXPx: number;
+  visibleWorldWidthPx: number;
+  visibleWorldHeightPx: number;
+  skyHeightPx: number;
+  lowerBandTopYPx: number;
+  lowerBandHeightPx: number;
+  lowerBandBottomYPx: number;
+  alignedHorizonYPx: number;
+  vanishingPointXPx: number;
+  vanishingPointYPx: number;
+  horizonStyle: PlaybackHorizonStyle;
+};
+
+/**
+ * Resolved vertical scene split used by playback background composition.
+ */
+export type PlaybackBackgroundLayout = {
+  skyHeightPx: number;
+  lowerBandTopYPx: number;
+  lowerBandHeightPx: number;
+  lowerBandBottomYPx: number;
+  horizonYPx: number;
+  horizonThicknessPx: number;
+};
+
+/**
+ * Zero-argument builder used to lazily construct one cached background layout.
+ */
+export type PlaybackBackgroundLayoutFactory = () => PlaybackBackgroundLayout;
+
+/**
+ * Neon styling contract for the horizon divider line.
+ */
+export type PlaybackHorizonStyle = {
+  lineColor: string;
+  glowColor: string;
+  glowAlpha: number;
+  glowBlurPx: number;
+  lineThicknessPx: number;
+};
+
+/**
+ * Draw request for the horizon divider line.
+ */
+export type PlaybackHorizonLineRequest = {
+  viewportLeftXPx: number;
+  visibleWorldWidthPx: number;
+  alignedHorizonYPx: number;
+  horizonStyle: PlaybackHorizonStyle;
+};