rn-gamekit 0.1.0

package/src/core/session/deepFreeze.ts

@@ -0,0 +1,158 @@
+/**
+ * Trusted deep-freeze cache (T3).
+ *
+ * Each session owns one freezer. A subtree that has been completely frozen
+ * once is recorded in a `WeakSet` and never re-traversed: structurally
+ * shared snapshot subtrees (the common case: unchanged bricks, entities,
+ * or config objects reused by reference across ticks) are walked exactly
+ * once for the lifetime of the session.
+ *
+ * Correctness rules:
+ * - A node is promoted into the trusted set **only after** its whole
+ *   subtree finished freezing. A child getter that throws mid-traversal
+ *   leaves every ancestor untrusted, so a later snapshot re-walks it.
+ * - Cycle detection uses a separate per-traversal `visiting` set, never the
+ *   trusted set, so cycles freeze exactly once without infinite recursion.
+ * - `Object.isFrozen` is never used as a skip test: an externally
+ *   shallow-frozen object can contain mutable children and must still be
+ *   recursed into.
+ * - Freezing is never dev-only: the public API promise of deeply immutable
+ *   snapshots holds in every build.
+ */
+
+import type { DeepReadonly } from './types';
+
+/** Whether a string is a canonical array index (`0 <= i < 2^32 - 1`). */
+/** Decimal digit count of a non-negative integer (0 <= value < 1e11). */
+function digitLength(value: number): number {
+  'worklet';
+  if (value < 10) {
+    return 1;
+  }
+  if (value < 100) {
+    return 2;
+  }
+  if (value < 1_000) {
+    return 3;
+  }
+  if (value < 10_000) {
+    return 4;
+  }
+  if (value < 100_000) {
+    return 5;
+  }
+  if (value < 1_000_000) {
+    return 6;
+  }
+  if (value < 10_000_000) {
+    return 7;
+  }
+  if (value < 100_000_000) {
+    return 8;
+  }
+  if (value < 1_000_000_000) {
+    return 9;
+  }
+  return 10;
+}
+
+function isArrayIndexKey(key: string): boolean {
+  'worklet';
+  // A canonical array index is the exact decimal form of an integer in
+  // [0, 2^32 - 2]; numeric-looking strings such as '1e0', '01', or
+  // '4294967295' are ordinary properties, not indices. The check is
+  // allocation-free: a digit scan plus the leading-zero rule.
+  const length = key.length;
+  if (length === 0 || length > 10) {
+    return false;
+  }
+  if (length > 1 && key.charCodeAt(0) === 48 /* '0' */) {
+    return false;
+  }
+  let value = 0;
+  for (let index = 0; index < length; index += 1) {
+    const code = key.charCodeAt(index);
+    if (code < 48 /* '0' */ || code > 57 /* '9' */) {
+      return false;
+    }
+    value = value * 10 + (code - 48);
+  }
+  return value <= 0xffffffff - 1;
+}
+
+export interface DeepFreezer {
+  <T>(value: T): DeepReadonly<T>;
+}
+
+export function createDeepFreeze(): DeepFreezer {  const trusted = new WeakSet<object>();
+
+  return function deepFreeze<T>(value: T): DeepReadonly<T> {
+    if (typeof value !== 'object' || value === null) {
+      return value as DeepReadonly<T>;
+    }
+    const visiting = new WeakSet<object>();
+    const freeze = (node: unknown): void => {
+      if (typeof node !== 'object' || node === null) {
+        return;
+      }
+      if (trusted.has(node) || visiting.has(node)) {
+        return;
+      }
+      visiting.add(node);
+      if (Array.isArray(node)) {
+        // Index fast path: avoids materialising an index-key array per array.
+        for (let index = 0; index < node.length; index += 1) {
+          freeze(node[index]);
+        }
+        // F5: legal JavaScript arrays may also carry values on non-index
+        // string keys and symbol keys. Only own keys are reachable snapshot
+        // values, so the scan uses getOwnPropertyNames (own string keys,
+        // enumerable and non-enumerable, no inherited keys) plus
+        // getOwnPropertySymbols — `for-in` was rejected because it yields
+        // inherited enumerable keys and skips non-enumerable own keys. The
+        // name array allocation is the documented cost of full correctness;
+        // canonical indices and `length` are skipped with an arithmetic
+        // check, and every remaining own value is frozen before the array is
+        // promoted into the trusted set.
+        const names = Object.getOwnPropertyNames(node);
+        // getOwnPropertyNames yields canonical indices first, in ascending
+        // order, then 'length', then any extra string keys in insertion
+        // order — so a dense array's indices take one Number() compare each
+        // and only extras reach the canonical-form check.
+        let expectedIndex = 0;
+        for (let index = 0; index < names.length; index += 1) {
+          const name = names[index];
+          if (name === undefined || name === 'length') {
+            continue;
+          }
+          // Fast discriminator: a canonical ascending index must match the
+          // expected value AND carry its exact decimal length — '01', '1e0',
+          // or '4294967295' cannot pass the length guard and fall through
+          // to the canonical check.
+          if (Number(name) === expectedIndex && name.length === digitLength(expectedIndex)) {
+            expectedIndex += 1;
+            continue;
+          }
+          if (!isArrayIndexKey(name)) {
+            freeze((node as unknown as Record<PropertyKey, unknown>)[name]);
+          }
+        }
+        const symbols = Object.getOwnPropertySymbols(node);
+        for (let index = 0; index < symbols.length; index += 1) {
+          const symbol = symbols[index];
+          if (symbol !== undefined) {
+            freeze((node as unknown as Record<PropertyKey, unknown>)[symbol]);
+          }
+        }
+      } else {
+        for (const key of Reflect.ownKeys(node)) {
+          freeze((node as Record<PropertyKey, unknown>)[key]);
+        }
+      }
+      Object.freeze(node);
+      trusted.add(node);
+    };
+    freeze(value as object);
+    return value as DeepReadonly<T>;
+  };
+}

package/src/core/session/diagnostics.ts

@@ -0,0 +1,35 @@
+/**
+ * Internal performance diagnostics sink.
+ *
+ * The session calls these hooks only when a sink is supplied through the
+ * testing seam. Production sessions pass no sink and pay no timing reads,
+ * callbacks, or wrapper allocation on the disabled path (F4). This is
+ * intentionally NOT a public diagnostics API: its usefulness is being proven
+ * by the playground Performance Lab before any public contract.
+ */
+export interface SessionDiagnostics {
+  /** A presentation callback was delivered by the frame driver. */
+  onDisplayCallback(): void;
+  /** A display callback that ran zero simulation steps. */
+  onZeroStepCallback(): void;
+  /** A fixed simulation step ran. */
+  onFixedStep(): void;
+  /** A catch-up step (second or later in the same callback) ran. */
+  onCatchUpStep(): void;
+  /** Whole-step debt dropped after the catch-up cap, in steps. */
+  onDroppedDebt(steps: number): void;
+  /** Duration of one scene update, milliseconds. */
+  onUpdate(durationMs: number): void;
+  /** Duration of one input sample, milliseconds. */
+  onInputSample(durationMs: number): void;
+  /** Duration of one snapshot extraction, milliseconds. */
+  onSnapshot(durationMs: number): void;
+  /** Duration of one deep-freeze pass, milliseconds. */
+  onDeepFreeze(durationMs: number): void;
+  /** Duration of one publish (listener fan-out), milliseconds. */
+  onPublish(durationMs: number): void;
+  /** A render frame was published to listeners. */
+  onCommitNotification(): void;
+  /** Listener count at publish time. */
+  onListenerCount(count: number): void;
+}

package/src/core/session/types.ts

@@ -0,0 +1,122 @@
+import type { InputMap, SceneMap } from '../../definition/types';
+import type { SceneSnapshot } from '../../scene/types';
+import type { Viewport } from '../../viewport2d/types';
+import type { InputController } from '../input/types';
+
+/** Recursively readonly view of renderer snapshot data. */
+export type DeepReadonly<T> = T extends (...arguments_: never[]) => unknown
+  ? T
+  : T extends readonly (infer TItem)[]
+    ? readonly DeepReadonly<TItem>[]
+    : T extends object
+      ? { readonly [TKey in keyof T]: DeepReadonly<T[TKey]> }
+      : T;
+
+/** Lifecycle states of a headless game session. */
+export type GameSessionStatus = 'idle' | 'running' | 'paused' | 'disposed';
+
+/** One renderer-neutral simulation commit produced by a game session. */
+export interface CommitFrameBase<TSnapshot> {
+  /** Snapshot immediately before the latest simulation update. */
+  readonly previous: DeepReadonly<TSnapshot>;
+  /** Snapshot produced by the latest simulation update. */
+  readonly current: DeepReadonly<TSnapshot>;
+  /** Number of completed global simulation updates. */
+  readonly tick: number;
+  /** Deterministic elapsed global simulation time in seconds. */
+  readonly elapsedSeconds: number;
+  /** Monotonic commit counter; increments on every simulation commit. */
+  readonly revision: number;
+  /** True when this commit is a transition hard cut (previous === current). */
+  readonly hardCut: boolean;
+  /** Fixed simulation step duration in milliseconds (UI alpha clock input). */
+  readonly stepMs: number;
+}
+
+/**
+ * A simulation commit discriminated by its scene name.
+ *
+ * Narrowing on `frame.scene` narrows both `previous` and `current` to the
+ * snapshot type of that scene. A transition commits a hard cut where both
+ * snapshots come from the new scene; frames never interpolate between two
+ * scene types.
+ */
+export type CommitFrame<TScenes extends SceneMap> = {
+  [TName in keyof TScenes]: CommitFrameBase<SceneSnapshot<TScenes[TName]>> & {
+    readonly scene: TName;
+  };
+}[keyof TScenes];
+
+/** A commit frame plus a presentation fraction computed on demand. */
+export type GameRenderFrame<TScenes extends SceneMap> = CommitFrame<TScenes> & {
+  /** Live fixed-step fraction at call time; renderers use the UI clock. */
+  readonly alpha: number;
+};
+
+/** An idempotently removable render-frame subscription. */
+export interface GameSubscription {
+  /** Stop future notifications. Safe to call repeatedly. */
+  remove(): void;
+}
+
+/** A closure-backed, headless running instance of one game definition. */
+export interface GameSession<TScenes extends SceneMap = SceneMap, TInput extends InputMap = InputMap> {
+  /** Current lifecycle status. */
+  readonly status: GameSessionStatus;
+  /** The active scene name, updated by transitions and restarts. */
+  readonly scene: keyof TScenes;
+  /** The authored viewport configuration of this game. */
+  readonly viewport: Viewport;
+  /** Semantic input controller constrained to declared action names. */
+  readonly input: InputController<Extract<keyof TInput, string>>;
+  /** Start an idle session or resume a paused session. */
+  start(): void;
+  /** Pause simulation and discard suspended wall time. */
+  pause(): void;
+  /**
+   * Transition to a declared scene.
+   *
+   * While running, the transition commits at the next fixed-step boundary.
+   * While idle or paused, it commits synchronously and publishes the new
+   * frame. Setting the current scene is an idempotent no-op.
+   */
+  setScene(name: keyof TScenes): void;
+  /** Recreate the active scene with fresh state. */
+  restartScene(): void;
+  /** Permanently stop the session and release the active scene. */
+  dispose(): void;
+  /**
+   * Read the latest immutable simulation commit with a live presentation
+   * fraction.
+   *
+   * Freshness contract: `alpha` is computed on demand from the session's
+   * accumulated timing fraction at call time and is only meaningful for
+   * headless inspection. Rendering uses the UI-owned alpha clock; the
+   * envelope fields never change between commits.
+   */
+  getRenderFrame(): GameRenderFrame<TScenes>;
+  /** Observe simulation commits at commit frequency (never per display frame). */
+  addCommitListener(listener: (frame: CommitFrame<TScenes>) => void): GameSubscription;
+}
+
+/** Error thrown when live work is requested from a disposed session. */
+export class GameSessionDisposedError extends Error {
+  override readonly name = 'GameSessionDisposedError';
+
+  constructor() {
+    super('This GameSession has been disposed');
+  }
+}
+
+/**
+ * Error thrown for lifecycle violations: conflicting transition requests,
+ * transition controllers used outside their update, unknown runtime scene
+ * names, and pending transition conflicts.
+ */
+export class GameSessionLifecycleError extends Error {
+  override readonly name = 'GameSessionLifecycleError';
+
+  constructor(message: string) {
+    super(message);
+  }
+}

package/src/definition/defineGame.ts

@@ -0,0 +1,94 @@
+import type { AssetGroupMap } from '../assets/types';
+import type { GameDefinition, InputMap, SceneMap } from './types';
+
+type SceneActions<TScene> = TScene extends { readonly __actionType?: infer TAction }
+  ? Exclude<TAction, undefined>
+  : never;
+
+type SceneTransitions<TScene> = TScene extends { readonly __transitionType?: infer TTransition }
+  ? Exclude<TTransition, undefined>
+  : never;
+
+type UndeclaredSceneActions<TScenes extends SceneMap, TInput extends InputMap> = Exclude<
+  SceneActions<TScenes[keyof TScenes]>,
+  Extract<keyof TInput, string>
+>;
+
+type UndeclaredSceneTransitions<TScenes extends SceneMap> = Exclude<
+  SceneTransitions<TScenes[keyof TScenes]>,
+  keyof TScenes
+>;
+
+type ValidateSceneActions<TScenes extends SceneMap, TInput extends InputMap> =
+  UndeclaredSceneActions<TScenes, TInput> extends never
+    ? unknown
+    : { readonly __undeclaredSceneActions: UndeclaredSceneActions<TScenes, TInput> };
+
+type ValidateSceneTransitions<TScenes extends SceneMap> =
+  UndeclaredSceneTransitions<TScenes> extends never
+    ? unknown
+    : { readonly __undeclaredSceneTransitions: UndeclaredSceneTransitions<TScenes> };
+
+/**
+ * Declare a game.
+ *
+ * `defineGame` is the entry point of the provisional GameKit API. It
+ * validates the definition at the type level — scene names are inferred so
+ * `initialScene` must be one of the keys of `scenes`, every scene action must
+ * exist in the game input map, and every declared transition target must be a
+ * declared scene — and preserves and returns the supplied definition.
+ *
+ * This function creates no runtime state: it does not start a scheduler,
+ * allocate a session, load assets, or register input. Pass the definition to
+ * `createGameSession` to create a live instance. The shape is provisional
+ * until reference games validate it.
+ *
+ * @example
+ * ```ts
+ * const game = defineGame({
+ *   viewport: {
+ *     logicalSize: { width: 390, height: 844 },
+ *     mode: 'fit',
+ *   },
+ *   assets: [],
+ *   input: { primary: { type: 'pointer' } },
+ *   scenes: {
+ *     ready: defineScene({
+ *       actions: ['primary'],
+ *       transitions: ['play'],
+ *       create: () => ({ ready: true }),
+ *       update: ({ state, input, transition }) => {
+ *         if (input.pointer('primary').pressed) {
+ *           transition.setScene('play');
+ *         }
+ *         return state;
+ *       },
+ *       snapshot: ({ state }) => state,
+ *     }),
+ *     play: defineScene({
+ *       actions: [],
+ *       create: () => ({ x: 0 }),
+ *       update: ({ state }) => ({ x: state.x + 1 }),
+ *       snapshot: ({ state }) => ({ x: state.x }),
+ *     }),
+ *   },
+ *   initialScene: 'ready',
+ * });
+ * ```
+ */
+export function defineGame<
+  const TScenes extends SceneMap,
+  const TInput extends InputMap = InputMap,
+  const TInitialScene extends keyof TScenes = keyof TScenes,
+  const TAssets extends AssetGroupMap = AssetGroupMap,
+>(
+  definition: GameDefinition<TScenes, TInput, TInitialScene, TAssets> &
+    ValidateSceneActions<TScenes, TInput> &
+    ValidateSceneTransitions<TScenes>,
+): GameDefinition<TScenes, TInput, TInitialScene, TAssets> {
+  // The viewport config is part of the public session surface; freeze it so a
+  // caller cannot mutate a live game's coordinate authority.
+  Object.freeze(definition.viewport.logicalSize);
+  Object.freeze(definition.viewport);
+  return definition;
+}

package/src/definition/types.ts

@@ -0,0 +1,67 @@
+import type { AssetGroupMap, GameAssetManifest } from '../assets/types';
+import type { Viewport } from '../viewport2d/types';
+
+/** The button action supported by the runtime. */
+export interface ButtonInputAction {
+  /** Discriminant for a digital button action. */
+  readonly type: 'button';
+  /** Optional human-readable description for diagnostics and tooling. */
+  readonly description?: string;
+}
+
+/** A single primary pointer action driven by touch or a mouse pointer. */
+export interface PointerInputAction {
+  /** Discriminant for a pointer action. */
+  readonly type: 'pointer';
+  /** Optional human-readable description for diagnostics and tooling. */
+  readonly description?: string;
+}
+
+/** A named semantic input action. */
+export type InputAction = ButtonInputAction | PointerInputAction;
+
+/** The collection of semantic input actions declared by a game. */
+export type InputMap = Readonly<Record<string, InputAction>>;
+
+/**
+ * Structural marker shared by all definitions created with `defineScene`.
+ *
+ * It lets `defineGame` retain each scene's inferred state, snapshot, action,
+ * and transition types without erasing them into a universal world or
+ * renderer shape.
+ */
+export interface SceneDefinitionMarker {
+  /** Internal scene-definition discriminator. */
+  readonly kind: 'gamekit.scene';
+  /** @internal Type witness for actions consumed by this scene. */
+  readonly __actionType?: string;
+  /** @internal Type witness for transition targets declared by this scene. */
+  readonly __transitionType?: string;
+}
+
+/** The collection of functional scenes declared by a game. */
+export type SceneMap = Readonly<Record<string, SceneDefinitionMarker>>;
+
+/**
+ * A complete static game definition produced by `defineGame`.
+ *
+ * Creating a definition allocates no runtime state. Pass it to
+ * `createGameSession` when a live headless session is required.
+ */
+export interface GameDefinition<
+  TScenes extends SceneMap = SceneMap,
+  TInput extends InputMap = InputMap,
+  TInitialScene extends keyof TScenes = keyof TScenes,
+  TAssets extends AssetGroupMap = AssetGroupMap,
+> {
+  /** The viewport configuration of the game. */
+  readonly viewport: Viewport;
+  /** Typed asset manifest; optional for shape-only games. */
+  readonly assets?: GameAssetManifest<TAssets>;
+  /** Semantic input actions declared by the game. */
+  readonly input: TInput;
+  /** Functional scenes keyed by stable scene name. */
+  readonly scenes: TScenes;
+  /** The scene created first when a session starts. */
+  readonly initialScene: TInitialScene;
+}

package/src/geometry/types.ts

@@ -0,0 +1,7 @@
+/** A plain 2D point in logical/world or surface coordinate space. */
+export interface Point2D {
+  /** Horizontal coordinate. */
+  readonly x: number;
+  /** Vertical coordinate. */
+  readonly y: number;
+}

package/src/index.ts

@@ -0,0 +1,84 @@
+export { createGameSession } from './core/session/createGameSession';
+export { GameSessionDisposedError, GameSessionLifecycleError } from './core/session/types';
+export type {
+  ButtonState,
+  InputController,
+  InputFrame,
+  PointerState,
+} from './core/input/types';
+export type {
+  DeepReadonly,
+  CommitFrame,
+  GameRenderFrame,
+  GameSession,
+  GameSessionStatus,
+  GameSubscription,
+} from './core/session/types';
+export {
+  advanceSpriteAnimation,
+  pauseSpriteAnimation,
+  playSpriteAnimation,
+  resetSpriteAnimation,
+  resumeSpriteAnimation,
+  setSpriteAnimationSpeed,
+  startSpriteAnimation,
+} from './sprites/spriteAnimationState';
+export {
+  sampleSpriteClipFrame,
+  sampleSpriteClipFrameName,
+  spriteClipDurationMs,
+} from './sprites/sampleSpriteClip';
+export type { SpriteAnimationState, SpriteClipNames } from './sprites/spriteAnimationState';
+export { defineAssets, image, spriteSheet } from './assets/defineAssets';
+export { GameAssetError } from './assets/errors';
+export type {
+  AssetDescriptor,
+  AssetGroup,
+  AssetGroupMap,
+  AssetSourceHandle,
+  BrandedAssetDescriptor,
+  GameAssetLease,
+  GameAssetManifest,
+  ImageDescriptor,
+  LoadedAssets,
+  LoadedImage,
+  LoadedSpriteSheet,
+  ManifestOf,
+  SpriteAnimationMode,
+  SpriteClip,
+  SpriteFrameRect,
+  SpriteSheetDescriptor,
+} from './assets/types';
+export { defineGame } from './definition/defineGame';
+export type {
+  ButtonInputAction,
+  GameDefinition,
+  InputAction,
+  InputMap,
+  PointerInputAction,
+  SceneDefinitionMarker,
+  SceneMap,
+} from './definition/types';
+export type { Point2D } from './geometry/types';
+export { defineScene } from './scene/defineScene';
+export type {
+  SceneDefinition,
+  SceneSnapshot,
+  SceneSnapshotContext,
+  SceneTransitionController,
+  SceneUpdate,
+} from './scene/types';
+export {
+  containsSurfacePoint,
+  resolveViewport2D,
+  surfaceToWorld,
+  worldToSurface,
+} from './viewport2d';
+export type {
+  LogicalSize,
+  Rect,
+  ResolvedViewport2D,
+  SurfaceSize,
+  Viewport,
+  ViewportMode,
+} from './viewport2d';