@reicek/neataptic-ts 0.1.21 → 0.1.22

package/test/examples/flappy_bird/browser-entry/playback/playback.starfield.service.ts

@@ -1,13 +1,14 @@
 import {
-  FLAPPY_STARFIELD_CYAN_FILL_STYLE,
-  FLAPPY_STARFIELD_FAR_SCROLL_RATIO,
-  FLAPPY_STARFIELD_MID_SCROLL_RATIO,
-  FLAPPY_STARFIELD_NEAR_SCROLL_RATIO,
+  FLAPPY_STARFIELD_LAYER_SPECS,
+  FLAPPY_STARFIELD_MIN_DIMENSION_PX,
   FLAPPY_STARFIELD_TILE_WIDTH_PX,
 } from '../../constants/constants';
 import { cachedStarfieldTilesByHeight } from './playback.constants';
-import { createSeededRandom } from './playback.starfield.utils';
-import type { StarTile } from './playback.types';
+import { createStarTileCanvas } from './playback.starfield.services';
+import type {
+  PlaybackStarfieldLayerSpec,
+  StarTile,
+} from './playback.starfield.types';
 
 /**
  * Resolves (and lazily creates) cached starfield tile layers for the viewport.
@@ -18,132 +19,48 @@ import type { StarTile } from './playback.types';
 export function resolveStarfieldTiles(
   visibleWorldHeightPx: number,
 ): readonly StarTile[] {
-  const tileHeightPx = Math.max(1, Math.round(visibleWorldHeightPx));
+  const tileHeightPx = Math.max(
+    FLAPPY_STARFIELD_MIN_DIMENSION_PX,
+    Math.round(visibleWorldHeightPx),
+  );
   const cachedTilesForHeight = cachedStarfieldTilesByHeight.get(tileHeightPx);
   if (cachedTilesForHeight) {
     return cachedTilesForHeight;
   }
 
-  const farTile: StarTile = {
-    image: createStarTileCanvas({
-      seed: 1_337,
-      tileWidthPx: FLAPPY_STARFIELD_TILE_WIDTH_PX,
-      tileHeightPx,
-      starCount: 35,
-      minSizePx: 1,
-      maxSizePx: 2,
-      minAlpha: 0.08,
-      maxAlpha: 0.22,
-      blurPx: 4,
-    }),
-    tileWidthPx: FLAPPY_STARFIELD_TILE_WIDTH_PX,
-    tileHeightPx,
-    scrollRatio: FLAPPY_STARFIELD_FAR_SCROLL_RATIO,
-  };
-  const midTile: StarTile = {
-    image: createStarTileCanvas({
-      seed: 2_777,
-      tileWidthPx: FLAPPY_STARFIELD_TILE_WIDTH_PX,
-      tileHeightPx,
-      starCount: 28,
-      minSizePx: 1,
-      maxSizePx: 3,
-      minAlpha: 0.1,
-      maxAlpha: 0.28,
-      blurPx: 6,
-    }),
-    tileWidthPx: FLAPPY_STARFIELD_TILE_WIDTH_PX,
-    tileHeightPx,
-    scrollRatio: FLAPPY_STARFIELD_MID_SCROLL_RATIO,
-  };
-  const nearTile: StarTile = {
+  const resolvedTiles = FLAPPY_STARFIELD_LAYER_SPECS.map((layerSpec) =>
+    createStarTile(layerSpec, tileHeightPx),
+  );
+  cachedStarfieldTilesByHeight.set(tileHeightPx, resolvedTiles);
+  return resolvedTiles;
+}
+
+/**
+ * Creates one cached tile layer from a declarative layer specification.
+ *
+ * @param layerSpec - Density and motion contract for a starfield layer.
+ * @param tileHeightPx - Height of the visible sky band in pixels.
+ * @returns Cached tile metadata for parallax drawing.
+ */
+function createStarTile(
+  layerSpec: PlaybackStarfieldLayerSpec,
+  tileHeightPx: number,
+): StarTile {
+  // Step 1: Pre-render one deterministic tile for the requested layer.
+  return {
     image: createStarTileCanvas({
-      seed: 4_242,
+      seed: layerSpec.seed,
       tileWidthPx: FLAPPY_STARFIELD_TILE_WIDTH_PX,
       tileHeightPx,
-      starCount: 23,
-      minSizePx: 2,
-      maxSizePx: 4,
-      minAlpha: 0.12,
-      maxAlpha: 0.34,
-      blurPx: 8,
+      starCount: layerSpec.starCount,
+      minSizePx: layerSpec.minSizePx,
+      maxSizePx: layerSpec.maxSizePx,
+      minAlpha: layerSpec.minAlpha,
+      maxAlpha: layerSpec.maxAlpha,
+      blurPx: layerSpec.blurPx,
     }),
     tileWidthPx: FLAPPY_STARFIELD_TILE_WIDTH_PX,
     tileHeightPx,
-    scrollRatio: FLAPPY_STARFIELD_NEAR_SCROLL_RATIO,
+    scrollRatio: layerSpec.scrollRatio,
   };
-
-  const resolvedTiles = [farTile, midTile, nearTile] as const;
-  cachedStarfieldTilesByHeight.set(tileHeightPx, resolvedTiles);
-  return resolvedTiles;
-}
-
-function createStarTileCanvas(options: {
-  seed: number;
-  tileWidthPx: number;
-  tileHeightPx: number;
-  starCount: number;
-  minSizePx: number;
-  maxSizePx: number;
-  minAlpha: number;
-  maxAlpha: number;
-  blurPx: number;
-}): CanvasImageSource {
-  const canvas = createCompatibleCanvas(
-    options.tileWidthPx,
-    options.tileHeightPx,
-  );
-  const tileContext = canvas.getContext('2d');
-  if (!tileContext) {
-    return canvas;
-  }
-
-  const seededRandom = createSeededRandom(options.seed);
-
-  tileContext.clearRect(0, 0, canvas.width, canvas.height);
-  tileContext.globalCompositeOperation = 'source-over';
-  tileContext.shadowColor = FLAPPY_STARFIELD_CYAN_FILL_STYLE;
-  tileContext.shadowBlur = options.blurPx;
-
-  for (let starIndex = 0; starIndex < options.starCount; starIndex += 1) {
-    const xPx = Math.floor(seededRandom() * options.tileWidthPx);
-    const yPx = Math.floor(seededRandom() * options.tileHeightPx);
-    const sizePx =
-      options.minSizePx +
-      Math.floor(seededRandom() * (options.maxSizePx - options.minSizePx + 1));
-    const alpha =
-      options.minAlpha + seededRandom() * (options.maxAlpha - options.minAlpha);
-
-    tileContext.globalAlpha = alpha;
-    tileContext.fillStyle = FLAPPY_STARFIELD_CYAN_FILL_STYLE;
-    tileContext.fillRect(xPx, yPx, sizePx, sizePx);
-  }
-
-  tileContext.shadowBlur = 0;
-  tileContext.shadowColor = 'transparent';
-  tileContext.globalAlpha = 1;
-  return canvas;
-}
-
-function createCompatibleCanvas(
-  widthPx: number,
-  heightPx: number,
-): HTMLCanvasElement | OffscreenCanvas {
-  const width = Math.max(1, Math.round(widthPx));
-  const height = Math.max(1, Math.round(heightPx));
-
-  if (typeof OffscreenCanvas !== 'undefined') {
-    return new OffscreenCanvas(width, height);
-  }
-
-  if (typeof document !== 'undefined') {
-    const canvas = document.createElement('canvas');
-    canvas.width = width;
-    canvas.height = height;
-    return canvas;
-  }
-
-  // Fallback: non-browser environments won't render, but should not crash.
-  const canvas = { width, height } as unknown as HTMLCanvasElement;
-  return canvas;
 }

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

@@ -0,0 +1,272 @@
+import {
+  FLAPPY_STARFIELD_CANVAS_CONTEXT_ID,
+  FLAPPY_STARFIELD_CYAN_FILL_STYLE,
+  FLAPPY_STARFIELD_COMPOSITE_SOURCE_OVER,
+  FLAPPY_STARFIELD_FULL_ALPHA,
+  FLAPPY_STARFIELD_INCLUSIVE_RANGE_OFFSET,
+  FLAPPY_STARFIELD_MIN_DIMENSION_PX,
+  FLAPPY_STARFIELD_NO_BLUR_PX,
+  FLAPPY_STARFIELD_ORIGIN_PX,
+  FLAPPY_STARFIELD_TRANSPARENT_SHADOW_COLOR,
+} from '../../constants/constants';
+import { createSeededRandom } from './playback.starfield.utils';
+import type {
+  CreateStarTileCanvasOptions,
+  StarfieldCanvasDimensions,
+  StarPlacement,
+} from './playback.starfield.types';
+
+/**
+ * Pre-renders a deterministic tile that can be reused across animation frames.
+ *
+ * @param options - Declarative drawing recipe for one parallax layer.
+ * @returns Canvas image source containing the rendered star strip.
+ */
+export function createStarTileCanvas(
+  options: CreateStarTileCanvasOptions,
+): CanvasImageSource {
+  // Step 1: Allocate a compatible canvas for the requested tile dimensions.
+  const canvas = createCompatibleCanvas(
+    options.tileWidthPx,
+    options.tileHeightPx,
+  );
+
+  // Step 2: Resolve a 2D context when the runtime can actually render.
+  const tileContext = resolveStarTileContext(canvas);
+  if (!tileContext) {
+    return canvas;
+  }
+
+  // Step 3: Initialize drawing state and render deterministic stars.
+  const seededRandom = createSeededRandom(options.seed);
+  initializeStarTileContext({
+    tileContext,
+    canvas,
+    blurPx: options.blurPx,
+  });
+  renderSeededStars({
+    tileContext,
+    seededRandom,
+    canvasOptions: options,
+  });
+
+  // Step 4: Restore neutral drawing state before handing the canvas back.
+  resetStarTileContext(tileContext);
+  return canvas;
+}
+
+/**
+ * Creates a browser-compatible canvas with clamped integer dimensions.
+ *
+ * @param widthPx - Requested tile width in pixels.
+ * @param heightPx - Requested tile height in pixels.
+ * @returns Offscreen canvas when supported, otherwise a DOM canvas fallback.
+ */
+function createCompatibleCanvas(
+  widthPx: number,
+  heightPx: number,
+): HTMLCanvasElement | OffscreenCanvas {
+  const canvasDimensions = normalizeCanvasDimensions(widthPx, heightPx);
+  const offscreenCanvas = createOffscreenCanvasIfSupported(canvasDimensions);
+  if (offscreenCanvas) {
+    return offscreenCanvas;
+  }
+
+  const documentCanvas = createDocumentCanvasIfSupported(canvasDimensions);
+  if (documentCanvas) {
+    return documentCanvas;
+  }
+
+  return createCanvasSizeFallback(canvasDimensions);
+}
+
+/**
+ * Resolves the rendering context used for star tile pre-rendering.
+ *
+ * @param canvas - Compatible canvas returned by the runtime-specific factory.
+ * @returns A 2D drawing context when rendering is supported.
+ */
+function resolveStarTileContext(
+  canvas: HTMLCanvasElement | OffscreenCanvas,
+): OffscreenCanvasRenderingContext2D | CanvasRenderingContext2D | null {
+  return canvas.getContext(FLAPPY_STARFIELD_CANVAS_CONTEXT_ID);
+}
+
+/**
+ * Clears the canvas and applies the glow settings shared by all rendered stars.
+ *
+ * @param options - Context initialization dependencies.
+ * @returns Nothing. The provided context is mutated in place.
+ */
+function initializeStarTileContext(options: {
+  tileContext: OffscreenCanvasRenderingContext2D | CanvasRenderingContext2D;
+  canvas: HTMLCanvasElement | OffscreenCanvas;
+  blurPx: number;
+}): void {
+  options.tileContext.clearRect(
+    FLAPPY_STARFIELD_ORIGIN_PX,
+    FLAPPY_STARFIELD_ORIGIN_PX,
+    options.canvas.width,
+    options.canvas.height,
+  );
+  options.tileContext.globalCompositeOperation =
+    FLAPPY_STARFIELD_COMPOSITE_SOURCE_OVER;
+  options.tileContext.shadowColor = FLAPPY_STARFIELD_CYAN_FILL_STYLE;
+  options.tileContext.shadowBlur = options.blurPx;
+}
+
+/**
+ * Draws all stars for one tile using a seeded random source.
+ *
+ * @param options - Drawing context, seed source, and tile recipe.
+ * @returns Nothing. The provided context is mutated in place.
+ */
+function renderSeededStars(options: {
+  tileContext: OffscreenCanvasRenderingContext2D | CanvasRenderingContext2D;
+  seededRandom: () => number;
+  canvasOptions: CreateStarTileCanvasOptions;
+}): void {
+  for (
+    let starIndex = 0;
+    starIndex < options.canvasOptions.starCount;
+    starIndex += 1
+  ) {
+    const starPlacement = resolveStarPlacement({
+      seededRandom: options.seededRandom,
+      tileWidthPx: options.canvasOptions.tileWidthPx,
+      tileHeightPx: options.canvasOptions.tileHeightPx,
+      minSizePx: options.canvasOptions.minSizePx,
+      maxSizePx: options.canvasOptions.maxSizePx,
+      minAlpha: options.canvasOptions.minAlpha,
+      maxAlpha: options.canvasOptions.maxAlpha,
+    });
+
+    options.tileContext.globalAlpha = starPlacement.alpha;
+    options.tileContext.fillStyle = FLAPPY_STARFIELD_CYAN_FILL_STYLE;
+    options.tileContext.fillRect(
+      starPlacement.xPx,
+      starPlacement.yPx,
+      starPlacement.sizePx,
+      starPlacement.sizePx,
+    );
+  }
+}
+
+/**
+ * Restores neutral drawing state so later canvas consumers start from defaults.
+ *
+ * @param tileContext - 2D context used to render the star tile.
+ * @returns Nothing. The provided context is mutated in place.
+ */
+function resetStarTileContext(
+  tileContext: OffscreenCanvasRenderingContext2D | CanvasRenderingContext2D,
+): void {
+  tileContext.shadowBlur = FLAPPY_STARFIELD_NO_BLUR_PX;
+  tileContext.shadowColor = FLAPPY_STARFIELD_TRANSPARENT_SHADOW_COLOR;
+  tileContext.globalAlpha = FLAPPY_STARFIELD_FULL_ALPHA;
+}
+
+/**
+ * Normalizes requested canvas dimensions into positive integer pixel sizes.
+ *
+ * @param widthPx - Requested width in pixels.
+ * @param heightPx - Requested height in pixels.
+ * @returns Clamped integer dimensions safe for canvas allocation.
+ */
+function normalizeCanvasDimensions(
+  widthPx: number,
+  heightPx: number,
+): StarfieldCanvasDimensions {
+  return {
+    width: Math.max(FLAPPY_STARFIELD_MIN_DIMENSION_PX, Math.round(widthPx)),
+    height: Math.max(FLAPPY_STARFIELD_MIN_DIMENSION_PX, Math.round(heightPx)),
+  };
+}
+
+/**
+ * Creates an offscreen canvas when the current runtime supports it.
+ *
+ * @param canvasDimensions - Already-normalized pixel dimensions.
+ * @returns Offscreen canvas instance or `null` when unavailable.
+ */
+function createOffscreenCanvasIfSupported(
+  canvasDimensions: StarfieldCanvasDimensions,
+): OffscreenCanvas | null {
+  if (typeof OffscreenCanvas !== 'undefined') {
+    return new OffscreenCanvas(canvasDimensions.width, canvasDimensions.height);
+  }
+
+  return null;
+}
+
+/**
+ * Creates a DOM canvas when document APIs are available.
+ *
+ * @param canvasDimensions - Already-normalized pixel dimensions.
+ * @returns DOM canvas instance or `null` when unavailable.
+ */
+function createDocumentCanvasIfSupported(
+  canvasDimensions: StarfieldCanvasDimensions,
+): HTMLCanvasElement | null {
+  if (typeof document !== 'undefined') {
+    const canvas = document.createElement('canvas');
+    canvas.width = canvasDimensions.width;
+    canvas.height = canvasDimensions.height;
+    return canvas;
+  }
+
+  return null;
+}
+
+/**
+ * Creates a size-only fallback so non-browser tests can skip rendering safely.
+ *
+ * @param canvasDimensions - Already-normalized pixel dimensions.
+ * @returns Minimal canvas-shaped object cast to the compatible return type.
+ */
+function createCanvasSizeFallback(
+  canvasDimensions: StarfieldCanvasDimensions,
+): HTMLCanvasElement {
+  const canvas = {
+    width: canvasDimensions.width,
+    height: canvasDimensions.height,
+  } as Partial<HTMLCanvasElement> as HTMLCanvasElement;
+  return canvas;
+}
+
+/**
+ * Resolves one deterministic star placement and appearance from the seeded RNG.
+ *
+ * @param options - Random source and star placement bounds.
+ * @returns Pixel location, square size, and alpha for one rendered star.
+ */
+function resolveStarPlacement(options: {
+  seededRandom: () => number;
+  tileWidthPx: number;
+  tileHeightPx: number;
+  minSizePx: number;
+  maxSizePx: number;
+  minAlpha: number;
+  maxAlpha: number;
+}): StarPlacement {
+  const xPx = Math.floor(options.seededRandom() * options.tileWidthPx);
+  const yPx = Math.floor(options.seededRandom() * options.tileHeightPx);
+  const sizePx =
+    options.minSizePx +
+    Math.floor(
+      options.seededRandom() *
+        (options.maxSizePx -
+          options.minSizePx +
+          FLAPPY_STARFIELD_INCLUSIVE_RANGE_OFFSET),
+    );
+  const alpha =
+    options.minAlpha +
+    options.seededRandom() * (options.maxAlpha - options.minAlpha);
+
+  return {
+    xPx,
+    yPx,
+    sizePx,
+    alpha,
+  };
+}

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

@@ -0,0 +1,62 @@
+/**
+ * Shared type contract for starfield tile rendering layers.
+ *
+ * A tile is pre-rendered and repeated horizontally to draw efficient
+ * parallax backgrounds during playback.
+ */
+export type StarTile = {
+  image: CanvasImageSource;
+  tileWidthPx: number;
+  tileHeightPx: number;
+  scrollRatio: number;
+};
+
+/**
+ * Declarative recipe for building one cached starfield parallax layer.
+ */
+export type PlaybackStarfieldLayerSpec = {
+  seed: number;
+  scrollRatio: number;
+  starCount: number;
+  minSizePx: number;
+  maxSizePx: number;
+  minAlpha: number;
+  maxAlpha: number;
+  blurPx: number;
+};
+
+/**
+ * Input contract for pre-rendering one deterministic starfield tile.
+ *
+ * The generated tile is cached and repeated horizontally during playback,
+ * so every field here affects both the visual look and the parallax cost.
+ */
+export type CreateStarTileCanvasOptions = {
+  seed: number;
+  tileWidthPx: number;
+  tileHeightPx: number;
+  starCount: number;
+  minSizePx: number;
+  maxSizePx: number;
+  minAlpha: number;
+  maxAlpha: number;
+  blurPx: number;
+};
+
+/**
+ * Normalized canvas dimensions used by browser and offscreen tile creation.
+ */
+export type StarfieldCanvasDimensions = {
+  width: number;
+  height: number;
+};
+
+/**
+ * Deterministic placement and appearance for one rendered star sprite.
+ */
+export type StarPlacement = {
+  xPx: number;
+  yPx: number;
+  sizePx: number;
+  alpha: number;
+};

package/test/examples/flappy_bird/browser-entry/playback/playback.starfield.utils.ts

@@ -1,3 +1,10 @@
+import {
+  FLAPPY_STARFIELD_UNSIGNED_NORMALIZATION_DIVISOR,
+  FLAPPY_STARFIELD_XORSHIFT_LEFT_SHIFT_FINAL,
+  FLAPPY_STARFIELD_XORSHIFT_LEFT_SHIFT_PRIMARY,
+  FLAPPY_STARFIELD_XORSHIFT_RIGHT_SHIFT,
+} from '../../constants/constants';
+
 /**
  * Creates a deterministic pseudo-random generator for starfield tile layouts.
  *
@@ -9,15 +16,15 @@ export function createSeededRandom(seed: number): () => number {
 
   return () => {
     // Step 1: Apply xorshift32 state transitions.
-    randomState ^= randomState << 13;
+    randomState ^= randomState << FLAPPY_STARFIELD_XORSHIFT_LEFT_SHIFT_PRIMARY;
     randomState >>>= 0;
-    randomState ^= randomState >> 17;
+    randomState ^= randomState >> FLAPPY_STARFIELD_XORSHIFT_RIGHT_SHIFT;
     randomState >>>= 0;
-    randomState ^= randomState << 5;
+    randomState ^= randomState << FLAPPY_STARFIELD_XORSHIFT_LEFT_SHIFT_FINAL;
     randomState >>>= 0;
 
     // Step 2: Normalize 32-bit unsigned state into [0, 1).
-    return randomState / 0x1_0000_0000;
+    return randomState / FLAPPY_STARFIELD_UNSIGNED_NORMALIZATION_DIVISOR;
   };
 }