rn-gamekit 0.1.0 → 0.2.1

package/src/audio/errors.ts

@@ -0,0 +1,12 @@
+export class GameAudioError extends Error {
+  override name = 'GameAudioError';
+  constructor(message: string) {
+    super(message);
+  }
+}
+
+export function createAudioInstallationError(): GameAudioError {
+  return new GameAudioError(
+    'react-native-audio-api is not installed. Run `npx expo install react-native-audio-api react-native-worklets` and rebuild with `npx expo prebuild` (or `expo run:ios` / `expo run:android`). See https://docs.swmansion.com/react-native-audio-api/docs/fundamentals/getting-started',
+  );
+}

package/src/audio/index.ts

@@ -0,0 +1,9 @@
+export { createGameAudio } from './createGameAudio';
+export { GameAudioError } from './errors';
+export type {
+  AudioCategory,
+  AudioSoundRecord,
+  CreateGameAudioOptions,
+  GameAudio,
+  GameAudioPlayOptions,
+} from './types';

package/src/audio/resolver.ts

@@ -0,0 +1,74 @@
+/**
+ * Injectable resolver for the optional `react-native-audio-api` peer.
+ *
+ * Production code calls `loadAudioApi()` which does a dynamic `import()`.
+ * Tests inject a fake via `__setAudioApiLoader` to simulate a missing peer
+ * without relying on a production fallback object.
+ */
+export type LoadedAudioApi = {
+  AudioContext: new (options?: { sampleRate?: number }) => {
+    readonly state: 'running' | 'suspended' | 'closed';
+    readonly currentTime: number;
+    readonly destination: unknown;
+    readonly sampleRate: number;
+    decodeAudioData(input: number | string | ArrayBuffer): Promise<{ length: number; duration: number } & Record<string, unknown>>;
+    createBufferSource(): {
+      buffer: unknown | null;
+      loop: boolean;
+      connect(destination: unknown): void;
+      start(when?: number, offset?: number, duration?: number): void;
+      stop(when?: number): void;
+      addEventListener?(type: string, cb: () => void): void;
+    };
+    createGain(): unknown;
+    suspend(): Promise<void>;
+    resume(): Promise<void>;
+    close(): Promise<void>;
+  };
+  AudioManager: {
+    getDevicePreferredSampleRate(): number;
+    addSystemEventListener(
+      name: 'interruption' | 'volumeChange' | 'duck' | 'routeChange',
+      cb: (event: unknown) => void,
+    ): { remove(): void; subscriptionId?: string };
+    observeAudioInterruptions(param: unknown): void;
+  } | undefined;
+};
+
+let loader: (() => Promise<LoadedAudioApi>) | null = null;
+
+export function __setAudioApiLoader(fn: (() => Promise<LoadedAudioApi>) | null): void {
+  loader = fn;
+}
+
+export async function loadAudioApi(): Promise<LoadedAudioApi> {
+  if (loader) {
+    return loader();
+  }
+  // Dynamic import so `mock.module('react-native-audio-api', ...)` can intercept in tests
+  // and so importing `rn-gamekit/audio` does not eagerly load the native module.
+  const mod = (await import('react-native-audio-api')) as unknown as LoadedAudioApi & {
+    AudioContext?: LoadedAudioApi['AudioContext'];
+    default?: LoadedAudioApi;
+  };
+  // The package re-exports AudioContext via `src/api.ts` -> `export * from './core/AudioContext'`
+  // and also via `src/index.ts`. Handle both shapes.
+  const AudioContext =
+    (mod as unknown as { AudioContext?: LoadedAudioApi['AudioContext'] }).AudioContext ??
+    (mod as unknown as { default?: { AudioContext?: LoadedAudioApi['AudioContext'] } }).default?.AudioContext ??
+    (mod as unknown as LoadedAudioApi).AudioContext;
+  if (!AudioContext) {
+    throw new Error('AudioContext not found in react-native-audio-api — linking may have failed');
+  }
+  // GS-AUDIO-03: no synthesized no-op AudioManager. Interruption
+  // observation is an explicit optional capability: createGameAudio warns
+  // once and runs without it, so silence can never masquerade as support.
+  const AudioManager =
+    (mod as unknown as { default?: { AudioManager?: LoadedAudioApi['AudioManager'] } }).default?.AudioManager ??
+    (mod as unknown as { AudioManager?: LoadedAudioApi['AudioManager'] }).AudioManager ??
+    undefined;
+  return {
+    AudioContext: AudioContext as LoadedAudioApi['AudioContext'],
+    AudioManager: AudioManager as LoadedAudioApi['AudioManager'],
+  };
+}

package/src/audio/types.ts

@@ -0,0 +1,47 @@
+export type AudioCategory = 'master' | 'music' | 'sfx' | 'ui';
+
+// Imported for documentation only; the runtime never requires the session.
+import type { GameLifecycleSource } from '../core/session/types';
+
+export type AudioSoundRecord = Record<string, number>;
+
+export interface CreateGameAudioOptions<T extends AudioSoundRecord> {
+  readonly sounds: T;
+}
+
+export interface GameAudioPlayOptions {
+  readonly category?: AudioCategory;
+  readonly volume?: number;
+  readonly loop?: boolean;
+  readonly concurrency?: {
+    readonly key?: string;
+    readonly limit?: number;
+    readonly overflow?: 'drop-new' | 'stop-oldest';
+  };
+}
+
+export interface GameAudio<T extends AudioSoundRecord = AudioSoundRecord> {
+  play<K extends keyof T & string>(id: K, options?: GameAudioPlayOptions): void;
+  playMusic<K extends keyof T & string>(id: K): Promise<void>;
+  stopMusic(): void;
+  pause(): void;
+  resume(): void;
+  setVolume(category: AudioCategory, volume: number): void;
+  getVolume(category: AudioCategory): number;
+  setMuted(muted: boolean): void;
+  isMuted(): boolean;
+  /**
+   * Session-driven pause (GS-AUDIO-04): follows the bound session status,
+   * independent of the manual pause()/resume() hold, app backgrounding,
+   * interruption, and mute — any reason suspends.
+   */
+  setPaused(paused: boolean): void;
+  /**
+   * Bind one session lifecycle source (GS-AUDIO-04, mirrors haptics):
+   * applies the current status immediately, follows transitions, and
+   * detaches any previously bound source. Returns an idempotent detach.
+   * All subscriptions disappear on disposal.
+   */
+  bindLifecycle(source: GameLifecycleSource): () => void;
+  dispose(): void;
+}

package/src/audio.ts

@@ -0,0 +1,13 @@
+/**
+ * Subpath entry for `rn-gamekit/audio`.
+ * Importing `rn-gamekit` or `rn-gamekit/react` must not load this module.
+ */
+export { createGameAudio } from './audio/createGameAudio';
+export { GameAudioError } from './audio/errors';
+export type {
+  AudioCategory,
+  AudioSoundRecord,
+  CreateGameAudioOptions,
+  GameAudio,
+  GameAudioPlayOptions,
+} from './audio/types';

package/src/camera2d/bounds.ts

@@ -0,0 +1,69 @@
+/**
+ * Camera2D world-bounds clamping (T12.2).
+ *
+ * Keeps the visible camera region inside an authored world bound at the
+ * current zoom, using conservative enclosing-AABB containment for rotated
+ * views (frozen in T12.0): stable near boundaries, never jittering, and
+ * centering axes where the world is smaller than the view.
+ */
+import type { Aabb2D } from '../geometry/types';
+import { assertFiniteNumber, assertNonnegativeSize, GeometryError } from '../geometry/validation';
+import type { Camera2D } from './types';
+import { assertValidCamera2D, assertValidLogicalView } from './validation';
+import { rotatedHalfExtents2D } from './extents';
+
+/** Half-extents of the rotated visible rect, in world units. */
+export function cameraHalfExtents2D(camera: Camera2D, logicalView: Aabb2D): { x: number; y: number } {
+  return { ...rotatedHalfExtents2D(logicalView.width / 2 / camera.zoom, logicalView.height / 2 / camera.zoom, camera.rotationRadians) };
+}
+
+function clampCenter(center: number, halfExtent: number, axisMin: number, axisMax: number): number {
+  if (axisMax - axisMin < halfExtent * 2) {
+    return (axisMin + axisMax) / 2;
+  }
+  const min = axisMin + halfExtent;
+  const max = axisMax - halfExtent;
+  return center < min ? min : center > max ? max : center;
+}
+
+/**
+ * Clamp a camera so its visible region stays inside `worldBounds`.
+ *
+ * Conservative for rotated views: the enclosing AABB of the rotated
+ * visible rect is contained, so no part of the view leaves the world. An
+ * axis whose world is smaller than the view is centered rather than
+ * oscillating between impossible edges.
+ */
+export function clampCameraBounds2D(
+  camera: Camera2D,
+  worldBounds: Aabb2D,
+  logicalView: Aabb2D,
+): Camera2D {
+  assertValidCamera2D(camera);
+  assertValidLogicalView(logicalView);
+  if (
+    typeof worldBounds !== 'object' ||
+    worldBounds === null ||
+    Array.isArray(worldBounds)
+  ) {
+    throw new GeometryError(
+      'GEOMETRY_INVALID_NUMBER',
+      'worldBounds',
+      `expected a rect record, got ${worldBounds === null ? 'null' : typeof worldBounds}`,
+    );
+  }
+  assertFiniteNumber(worldBounds.x, 'worldBounds.x');
+  assertFiniteNumber(worldBounds.y, 'worldBounds.y');
+  assertNonnegativeSize(worldBounds.width, 'worldBounds.width');
+  assertNonnegativeSize(worldBounds.height, 'worldBounds.height');
+
+  const extents = cameraHalfExtents2D(camera, logicalView);
+  return Object.freeze({
+    center: Object.freeze({
+      x: clampCenter(camera.center.x, extents.x, worldBounds.x, worldBounds.x + worldBounds.width),
+      y: clampCenter(camera.center.y, extents.y, worldBounds.y, worldBounds.y + worldBounds.height),
+    }),
+    zoom: camera.zoom,
+    rotationRadians: camera.rotationRadians,
+  });
+}

package/src/camera2d/extents.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared rotated half-extent arithmetic (GS-CAMERA-03).
+ *
+ * The conservative enclosing half-extents of a rotated visible rect:
+ * `ex = |hx·cosθ| + |hy·sinθ|`, `ey = |hx·sinθ| + |hy·cosθ|`.
+ *
+ * Trusted scalars only: no validation, no errors, worklet-safe. Callers
+ * validate at their own boundary (headless paths with the camera
+ * validators) or consume already-validated values (UI paths that must
+ * never construct errors per frame). Padding, parallax, and centering
+ * stay per-system and explicit.
+ */
+export function rotatedHalfExtents2D(
+  halfWidth: number,
+  halfHeight: number,
+  rotationRadians: number,
+): { readonly x: number; readonly y: number } {
+  'worklet';
+  const cos = Math.abs(Math.cos(rotationRadians));
+  const sin = Math.abs(Math.sin(rotationRadians));
+  return {
+    x: halfWidth * cos + halfHeight * sin,
+    y: halfWidth * sin + halfHeight * cos,
+  };
+}

package/src/camera2d/follow.ts

@@ -0,0 +1,165 @@
+/**
+ * Camera2D follow behavior (T12.2).
+ *
+ * Deterministic, headless follow helpers for game update code. They never
+ * read a React ref, device clock, frame callback, or global singleton;
+ * games call them inside the scene update and store the returned camera in
+ * scene state.
+ */
+import type { Aabb2D, Point2D } from '../geometry/types';
+import { assertFiniteNumber, assertNonnegativeSize, GeometryError } from '../geometry/validation';
+import type { Camera2D, FollowCamera2DOptions2D } from './types';
+import { assertFinitePoint2D, assertValidCamera2D } from './validation';
+
+function assertNonnegativeDeadZone(deadZone: unknown): asserts deadZone is Aabb2D {
+  if (typeof deadZone !== 'object' || deadZone === null || Array.isArray(deadZone)) {
+    throw new GeometryError(
+      'GEOMETRY_INVALID_NUMBER',
+      'deadZone',
+      `expected a rect record, got ${deadZone === null ? 'null' : typeof deadZone}`,
+    );
+  }
+  const typed = deadZone as Aabb2D;
+  assertFiniteNumber(typed.x, 'deadZone.x');
+  assertFiniteNumber(typed.y, 'deadZone.y');
+  assertNonnegativeSize(typed.width, 'deadZone.width');
+  assertNonnegativeSize(typed.height, 'deadZone.height');
+}
+
+function assertFollowOptionsShape(options: unknown): asserts options is FollowCamera2DOptions2D {
+  if (typeof options !== 'object' || options === null || Array.isArray(options)) {
+    throw new GeometryError(
+      'GEOMETRY_INVALID_NUMBER',
+      'options',
+      `expected a follow options record, got ${options === null ? 'null' : typeof options}`,
+    );
+  }
+}
+
+function followFactor(halfLifeSeconds: number, deltaSeconds: number): number {
+  if (!Number.isFinite(deltaSeconds) || !(deltaSeconds > 0)) {
+    throw new GeometryError(
+      'GEOMETRY_INVALID_NUMBER',
+      'deltaSeconds',
+      `expected a finite positive step, got ${String(deltaSeconds)}`,
+    );
+  }
+  return 1 - Math.pow(0.5, deltaSeconds / halfLifeSeconds);
+}
+
+/**
+ * Compute the next camera for a follow target.
+ *
+ * - Without options: direct follow — the camera center becomes the target.
+ * - With a dead zone: the camera moves only when the target crosses the
+ *   zone edge, by exactly the amount needed to bring the target back to
+ *   the edge.
+ * - `perAxis` disables following on either axis.
+ * - `dampingHalfLifeSeconds` blends toward the desired center with a
+ *   half-life model; equivalent fixed-step schedules produce equivalent
+ *   results.
+ */
+export function followCamera2D(
+  camera: Camera2D,
+  target: Point2D,
+  options?: FollowCamera2DOptions2D,
+  deltaSeconds?: number,
+): Camera2D {
+  assertValidCamera2D(camera);
+  assertFinitePoint2D(target, 'target');
+
+  if (options !== undefined) {
+    assertFollowOptionsShape(options);
+  }
+  const perAxis = options?.perAxis;
+  if (perAxis !== undefined) {
+    // T12-SF3: the per-axis options must be a non-array record before any
+    // field is read.
+    if (typeof perAxis !== 'object' || perAxis === null || Array.isArray(perAxis)) {
+      throw new GeometryError(
+        'GEOMETRY_INVALID_NUMBER',
+        'perAxis',
+        `expected a per-axis record, got ${perAxis === null ? 'null' : typeof perAxis}`,
+      );
+    }
+    const x = (perAxis as { x?: unknown }).x;
+    const y = (perAxis as { y?: unknown }).y;
+    if (x !== undefined && typeof x !== 'boolean') {
+      throw new GeometryError('GEOMETRY_INVALID_NUMBER', 'perAxis.x', `expected a boolean, got ${String(x)}`);
+    }
+    if (y !== undefined && typeof y !== 'boolean') {
+      throw new GeometryError('GEOMETRY_INVALID_NUMBER', 'perAxis.y', `expected a boolean, got ${String(y)}`);
+    }
+  }
+  const perAxisX = options?.perAxis?.x ?? true;
+  const perAxisY = options?.perAxis?.y ?? true;
+  const deadZone = options?.deadZone;
+  if (deadZone !== undefined) {
+    assertNonnegativeDeadZone(deadZone);
+  }
+  const halfLife = options?.dampingHalfLifeSeconds;
+  if (halfLife !== undefined) {
+    assertFiniteNumber(halfLife, 'dampingHalfLifeSeconds');
+    if (!(halfLife > 0)) {
+      throw new GeometryError(
+        'GEOMETRY_INVALID_NUMBER',
+        'dampingHalfLifeSeconds',
+        `expected a finite positive half-life, got ${String(halfLife)}`,
+      );
+    }
+    if (deltaSeconds === undefined) {
+      throw new GeometryError(
+        'GEOMETRY_INVALID_NUMBER',
+        'deltaSeconds',
+        'damping requires an explicit fixed-step deltaSeconds',
+      );
+    }
+  }
+
+  const center = camera.center;
+  const desired = { x: center.x, y: center.y };
+  if (deadZone === undefined) {
+    desired.x = target.x;
+    desired.y = target.y;
+  } else {
+    const minX = center.x + deadZone.x;
+    const maxX = minX + deadZone.width;
+    const minY = center.y + deadZone.y;
+    const maxY = minY + deadZone.height;
+    if (target.x > maxX) {
+      desired.x = target.x - deadZone.width - deadZone.x;
+    } else if (target.x < minX) {
+      desired.x = target.x - deadZone.x;
+    }
+    if (target.y > maxY) {
+      desired.y = target.y - deadZone.height - deadZone.y;
+    } else if (target.y < minY) {
+      desired.y = target.y - deadZone.y;
+    }
+  }
+  if (!perAxisX) {
+    desired.x = center.x;
+  }
+  if (!perAxisY) {
+    desired.y = center.y;
+  }
+
+  let nextCenter: Point2D;
+  if (halfLife !== undefined && deltaSeconds !== undefined) {
+    const factor = followFactor(halfLife, deltaSeconds);
+    nextCenter = {
+      x: center.x + (desired.x - center.x) * factor,
+      y: center.y + (desired.y - center.y) * factor,
+    };
+  } else {
+    nextCenter = desired;
+  }
+
+  // T12-F6: every public helper returns a frozen value; the caller's
+  // camera is never aliased or mutated.
+  return Object.freeze({
+    center: Object.freeze({ x: nextCenter.x, y: nextCenter.y }),
+    zoom: camera.zoom,
+    rotationRadians: camera.rotationRadians,
+  });
+}

package/src/camera2d/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Camera2D — the opt-in 2D camera system (Task 12).
+ *
+ * Pure, headless, native-free camera math shared by rendering and pointer
+ * input: immutable camera values, forward and inverse transforms, follow,
+ * bounds clamping, deterministic shake, presentation interpolation, and
+ * conservative visibility culling. The React integration
+ * (`defineGameCamera2D`, `GameView`, `GameWorld2D`, `GameLayer2D`) lives in
+ * `src/react/`.
+ */
+export { createCamera2D, getCameraVisibleBounds2D, logicalToWorld2D, worldToLogical2D, worldToSurface2D, surfaceToWorld2D } from './transform';
+export { interpolateCamera2D, interpolateCameraScalar2D, shortestRotationDelta2D } from './interpolation';
+export { followCamera2D } from './follow';
+export { clampCameraBounds2D, cameraHalfExtents2D } from './bounds';
+export { rotatedHalfExtents2D } from './extents';
+export { sampleCameraShake2D } from './shake';
+export {
+  filterCameraVisible2D,
+  intersectsCameraView2D,
+  paddedCameraBounds2D,
+  type CameraViewShape2D,
+} from './visibility';
+export type {
+  Camera2D,
+  CameraCut2D,
+  CameraFollowAxisOptions2D,
+  CameraShakeOptions2D,
+  FollowCamera2DOptions2D,
+} from './types';

package/src/camera2d/interpolation.ts

@@ -0,0 +1,113 @@
+/**
+ * Camera2D presentation interpolation (T12.2, T12.3).
+ *
+ * The public `interpolateCamera2D` validates its inputs and returns a
+ * frozen camera. The internal `interpolateCameraScalar2D` is the trusted
+ * display-frequency projector: its COMPLETE call graph is workletized (no
+ * validation, no structured error construction, the shortest-arc math is
+ * inline), so the UI runtime can call it from the camera presentation
+ * worklet without crossing runtimes (T12-F2). Callers validate selector
+ * output at the JS commit boundary before publishing shared values.
+ */
+import { assertFiniteNumber, GeometryError } from '../geometry/validation';
+import type { Camera2D, CameraCut2D } from './types';
+import { assertCameraShape } from './validation';
+
+function assertCutShape(cut: unknown, field: string): asserts cut is CameraCut2D {
+  if (typeof cut !== 'object' || cut === null || Array.isArray(cut)) {
+    throw new GeometryError(
+      'GEOMETRY_INVALID_NUMBER',
+      field,
+      `expected a camera cut record, got ${cut === null ? 'null' : typeof cut}`,
+    );
+  }
+  assertFiniteNumber((cut as CameraCut2D).cutId, `${field}.cutId`);
+  const camera = (cut as CameraCut2D).camera;
+  assertCameraShape(camera, `${field}.camera`);
+  const cameraField = `${field}.camera`;
+  assertFiniteNumber(camera.center.x, `${cameraField}.center.x`);
+  assertFiniteNumber(camera.center.y, `${cameraField}.center.y`);
+  assertFiniteNumber(camera.zoom, `${cameraField}.zoom`);
+  if (!(camera.zoom > 0)) {
+    throw new GeometryError(
+      'GEOMETRY_INVALID_NUMBER',
+      `${cameraField}.zoom`,
+      `expected a finite zoom greater than zero, got ${String(camera.zoom)}`,
+    );
+  }
+  assertFiniteNumber(camera.rotationRadians, `${cameraField}.rotationRadians`);
+}
+
+/**
+ * Trusted scalar projector (worklet-safe): interpolates center and zoom
+ * linearly and rotation across the shortest angular arc. A changed `cutId`
+ * (or an absent previous cut) snaps to the current camera. No validation,
+ * no allocation of structured errors.
+ */
+export function interpolateCameraScalar2D(
+  previous: CameraCut2D | undefined,
+  current: CameraCut2D,
+  alpha: number,
+): Camera2D {
+  'worklet';
+  if (previous === undefined || previous.cutId !== current.cutId) {
+    return current.camera;
+  }
+  const from = previous.camera;
+  const to = current.camera;
+  let delta = (to.rotationRadians - from.rotationRadians) % (Math.PI * 2);
+  if (delta > Math.PI) {
+    delta -= Math.PI * 2;
+  } else if (delta < -Math.PI) {
+    delta += Math.PI * 2;
+  }
+  return {
+    center: {
+      x: from.center.x + (to.center.x - from.center.x) * alpha,
+      y: from.center.y + (to.center.y - from.center.y) * alpha,
+    },
+    zoom: from.zoom + (to.zoom - from.zoom) * alpha,
+    rotationRadians: from.rotationRadians + delta * alpha,
+  };
+}
+
+/** The shortest signed angular difference from `from` to `to`. */
+export function shortestRotationDelta2D(from: number, to: number): number {
+  let delta = (to - from) % (Math.PI * 2);
+  if (delta > Math.PI) {
+    delta -= Math.PI * 2;
+  } else if (delta < -Math.PI) {
+    delta += Math.PI * 2;
+  }
+  return delta;
+}
+
+/**
+ * Public interpolated camera: validates every input, clamps the alpha
+ * policy (reject outside `[0, 1]`), and returns a frozen value. Delegates
+ * to the trusted scalar projector.
+ */
+export function interpolateCamera2D(
+  previous: CameraCut2D | undefined,
+  current: CameraCut2D,
+  alpha: number,
+): Camera2D {
+  assertCutShape(current, 'current');
+  if (previous !== undefined) {
+    assertCutShape(previous, 'previous');
+  }
+  assertFiniteNumber(alpha, 'alpha');
+  if (alpha < 0 || alpha > 1) {
+    throw new GeometryError(
+      'GEOMETRY_INVALID_NUMBER',
+      'alpha',
+      `expected alpha in [0, 1], got ${String(alpha)}`,
+    );
+  }
+  const interpolated = interpolateCameraScalar2D(previous, current, alpha);
+  return Object.freeze({
+    center: Object.freeze({ x: interpolated.center.x, y: interpolated.center.y }),
+    zoom: interpolated.zoom,
+    rotationRadians: interpolated.rotationRadians,
+  });
+}

package/src/camera2d/shake.ts

@@ -0,0 +1,90 @@
+/**
+ * Camera2D deterministic shake (T12.2).
+ *
+ * Shake is reproducible from explicit state: a seed, elapsed simulation
+ * time, duration, and amplitude. No `Math.random()` anywhere. The sampler
+ * returns the unmodified base camera at and after the duration, and never
+ * mutates its input. Presentation applies the offset to the presented
+ * camera, so pointer inversion (which uses the same presented camera)
+ * keeps visible targets touchable.
+ */
+import type { Camera2D, CameraShakeOptions2D } from './types';
+import { assertValidCamera2D } from './validation';
+import { assertFiniteNumber, assertNonnegativeSize, GeometryError } from '../geometry/validation';
+
+function assertValidShakeOptions(options: CameraShakeOptions2D): void {
+  if (typeof options !== 'object' || options === null || Array.isArray(options)) {
+    throw new GeometryError(
+      'GEOMETRY_INVALID_NUMBER',
+      'options',
+      `expected a shake options record, got ${options === null ? 'null' : typeof options}`,
+    );
+  }
+  assertFiniteNumber(options.seed, 'seed');
+  assertFiniteNumber(options.elapsedSeconds, 'elapsedSeconds');
+  if (!(options.elapsedSeconds >= 0)) {
+    throw new GeometryError(
+      'GEOMETRY_INVALID_NUMBER',
+      'elapsedSeconds',
+      `expected a nonnegative elapsed time, got ${String(options.elapsedSeconds)}`,
+    );
+  }
+  assertFiniteNumber(options.durationSeconds, 'durationSeconds');
+  if (!(options.durationSeconds > 0)) {
+    throw new GeometryError(
+      'GEOMETRY_INVALID_NUMBER',
+      'durationSeconds',
+      `expected a positive duration, got ${String(options.durationSeconds)}`,
+    );
+  }
+  assertNonnegativeSize(options.amplitude, 'amplitude');
+  if (options.frequency !== undefined) {
+    assertFiniteNumber(options.frequency, 'frequency');
+  }
+}
+
+/** Deterministic per-axis phase from the seed (never a wall-clock read). */
+function phaseOf(seed: number, axis: number): number {
+  const raw = Math.sin(seed * 12.9898 + axis * 78.233) * 43758.5453;
+  const fraction = raw - Math.floor(raw);
+  return fraction * Math.PI * 2;
+}
+
+/**
+ * Sample the presented camera offset for a shake.
+ *
+ * The offset decays linearly to zero over `durationSeconds`; at and after
+ * the duration the base camera is returned unchanged. Equal options
+ * produce equal results.
+ */
+export function sampleCameraShake2D(
+  base: Camera2D,
+  options: CameraShakeOptions2D,
+): Camera2D {
+  assertValidCamera2D(base);
+  assertValidShakeOptions(options);
+
+  const { seed, elapsedSeconds, durationSeconds, amplitude, frequency = Math.PI * 2 } = options;
+  if (elapsedSeconds >= durationSeconds || amplitude === 0) {
+    // T12-F6: even the endpoint returns a frozen copy — never the caller's
+    // base object by identity.
+    return Object.freeze({
+      center: Object.freeze({ x: base.center.x, y: base.center.y }),
+      zoom: base.zoom,
+      rotationRadians: base.rotationRadians,
+    });
+  }
+  const envelope = 1 - elapsedSeconds / durationSeconds;
+  const offset = {
+    x: Math.sin(elapsedSeconds * frequency + phaseOf(seed, 1)) * amplitude * envelope,
+    y: Math.sin(elapsedSeconds * frequency + phaseOf(seed, 2)) * amplitude * envelope,
+  };
+  return Object.freeze({
+    center: Object.freeze({
+      x: base.center.x + offset.x,
+      y: base.center.y + offset.y,
+    }),
+    zoom: base.zoom,
+    rotationRadians: base.rotationRadians,
+  });
+}