rn-gamekit 0.1.0

package/lib/module/react/sprites/spriteTransform.js

@@ -0,0 +1,135 @@
+"use strict";
+
+/** The resolved source rectangle for one frame selection. */
+
+/**
+ * Resolve the source rectangle for a static frame selection.
+ *
+ * RF4: an absent selection (the dynamic clip/elapsed mode before its first
+ * value) presents nothing instead of throwing. The static baseline uses the
+ * sheet's first frame so the anchor/scale correction has sane dimensions
+ * while the per-frame worklet resolves the real selection.
+ */
+export function resolveSpriteFrameRect(source, frame) {
+  if (source.descriptor.kind === 'image') {
+    const image = source;
+    return {
+      x: 0,
+      y: 0,
+      width: image.width,
+      height: image.height
+    };
+  }
+  const sheet = source;
+  if (frame === undefined) {
+    const firstAnimationName = Object.keys(sheet.descriptor.animations)[0];
+    const firstAnimation = firstAnimationName === undefined ? undefined : sheet.descriptor.animations[firstAnimationName];
+    const firstFrameName = firstAnimation?.frames[0];
+    const baseline = firstFrameName === undefined ? undefined : sheet.frames[firstFrameName];
+    return baseline ?? {
+      x: 0,
+      y: 0,
+      width: 0,
+      height: 0
+    };
+  }
+  const rect = sheet.frames[frame];
+  if (rect === undefined) {
+    throw new Error(`frame ${JSON.stringify(frame)} does not belong to this sprite sheet (loaded frames: ${Object.keys(sheet.frames).join(', ')})`);
+  }
+  return rect;
+}
+
+/**
+ * Sprite transform math (T7.6).
+ *
+ * Pure, worklet-compatible. A sprite's frame occupies
+ * `[0, 0, frameWidth, frameHeight]` in local space and the documented pivot
+ * order is:
+ *
+ *   M = T(x, y) · R(rotation) · T(anchor) · S(scaleX, scaleY) · T(-anchor)
+ *
+ * i.e. scale and explicit flips happen around the anchor, then the frame
+ * rotates around the anchor at the world position. The RSXform carries the
+ * rotation + position (its 2x2 cannot express flips or non-uniform scale);
+ * the wrapping Group applies the scale/flip part around the anchor.
+ */
+
+/** A sprite's presentation input; numbers or UI-runtime animated values. */
+
+/** The computed RSXform (rotation + position, pivot-compensated). */
+
+/** A Skia-compatible 3x3 transform element list. */
+
+function readNumber(value) {
+  'worklet';
+
+  return typeof value === 'number' ? value : value.value;
+}
+function readBoolean(value) {
+  'worklet';
+
+  return typeof value === 'boolean' ? value : value.value;
+}
+
+/**
+ * The RSXform for the atlas path: rotation + position with the pivot
+ * compensated (`tx = x - pivotX·cos + pivotY·sin`). Scale and flips are
+ * applied by the wrapping Group (`spriteGroupCorrection`).
+ */
+export function computeSpriteRsxform(input) {
+  'worklet';
+
+  const x = readNumber(input.x);
+  const y = readNumber(input.y);
+  const rotation = readNumber(input.rotation);
+  const pivotX = input.anchorX * input.frameWidth;
+  const pivotY = input.anchorY * input.frameHeight;
+  const cos = Math.cos(rotation);
+  const sin = Math.sin(rotation);
+  return {
+    scos: cos,
+    ssin: sin,
+    tx: x - pivotX * cos + pivotY * sin,
+    ty: y - pivotX * sin - pivotY * cos
+  };
+}
+
+/**
+ * The scale/flip part around the anchor as a Skia transform element list:
+ * `T(anchor) · S(scaleX, scaleY) · T(-anchor)` (the first element is the
+ * outermost).
+ */
+export function spriteGroupCorrection(input) {
+  'worklet';
+
+  const scale = readNumber(input.scale);
+  const flipX = readBoolean(input.flipX);
+  const flipY = readBoolean(input.flipY);
+  const pivotX = input.anchorX * input.frameWidth;
+  const pivotY = input.anchorY * input.frameHeight;
+  return [{
+    translateX: pivotX
+  }, {
+    translateY: pivotY
+  }, {
+    scaleX: flipX ? -scale : scale
+  }, {
+    scaleY: flipY ? -scale : scale
+  }, {
+    translateX: -pivotX
+  }, {
+    translateY: -pivotY
+  }];
+}
+
+/** World position of the anchor point (for debugging and overlays). */
+export function spriteAnchorWorld(input) {
+  'worklet';
+
+  return {
+    x: readNumber(input.x),
+    y: readNumber(input.y)
+  };
+}
+//# sourceMappingURL=spriteTransform.js.map

package/lib/module/react/sprites/spriteTransform.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["resolveSpriteFrameRect","source","frame","descriptor","kind","image","x","y","width","height","sheet","undefined","firstAnimationName","Object","keys","animations","firstAnimation","firstFrameName","frames","baseline","rect","Error","JSON","stringify","join","readNumber","value","readBoolean","computeSpriteRsxform","input","rotation","pivotX","anchorX","frameWidth","pivotY","anchorY","frameHeight","cos","Math","sin","scos","ssin","tx","ty","spriteGroupCorrection","scale","flipX","flipY","translateX","translateY","scaleX","scaleY","spriteAnchorWorld"],"sourceRoot":"../../../../src","sources":["react/sprites/spriteTransform.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/react/viewportBinding.js

@@ -0,0 +1,101 @@
+"use strict";
+
+import { resolveViewport2D } from "../viewport2d/index.js";
+
+/**
+ * Platform-neutral holder for the resolved viewport of a mounted game
+ * surface.
+ *
+ * It re-resolves whenever the surface size changes, notifies subscribers on
+ * each layout revision (so pointer input can cancel an active gesture on
+ * layout invalidation), and exposes the latest immutable resolved viewport to
+ * both the renderer and the input adapter. It never touches React, Skia, or
+ * platform dimensions.
+ */
+export class ViewportBinding {
+  #config;
+  #resolved;
+  #lastSurfaceSize;
+  #revision = 0;
+  #listeners = new Set();
+  constructor(config) {
+    this.#config = config;
+  }
+
+  /** The authored viewport configuration this binding resolves. */
+  get config() {
+    return this.#config;
+  }
+
+  /** The latest resolved viewport, or `undefined` while the layout is invalid. */
+  get resolved() {
+    return this.#resolved;
+  }
+
+  /** The latest native surface measurement, retained across viewport swaps. */
+  get surfaceSize() {
+    return this.#lastSurfaceSize;
+  }
+
+  /** Monotonic counter incremented on every layout revision. */
+  get revision() {
+    return this.#revision;
+  }
+
+  /**
+   * Resolve the configured viewport against a new surface size.
+   *
+   * No-op for unchanged sizes. Subscribers are notified only when the layout
+   * actually changes.
+   */
+  setSurfaceSize(size) {
+    if (this.#lastSurfaceSize !== undefined && this.#lastSurfaceSize.width === size.width && this.#lastSurfaceSize.height === size.height) {
+      return;
+    }
+    this.#lastSurfaceSize = Object.freeze({
+      width: size.width,
+      height: size.height
+    });
+    this.#resolved = resolveViewport2D(this.#config, size);
+    this.#revision += 1;
+    for (const listener of [...this.#listeners]) {
+      listener();
+    }
+  }
+
+  /** Observe layout revisions. Returns an idempotent unsubscribe. */
+  subscribe(listener) {
+    this.#listeners.add(listener);
+    let removed = false;
+    return () => {
+      if (removed) {
+        return;
+      }
+      removed = true;
+      this.#listeners.delete(listener);
+    };
+  }
+
+  /** Release subscribers. The binding becomes inert. */
+  dispose() {
+    this.#listeners.clear();
+  }
+}
+
+/**
+ * Return the existing binding when its authored viewport is unchanged, or
+ * create a replacement that immediately resolves against the already-mounted
+ * native surface. React Native does not guarantee another `onLayout` event
+ * when only the game/viewport changes and the View's dimensions stay equal.
+ */
+export function bindingForViewport(config, previous) {
+  if (previous?.config === config) {
+    return previous;
+  }
+  const replacement = new ViewportBinding(config);
+  if (previous?.surfaceSize !== undefined) {
+    replacement.setSurfaceSize(previous.surfaceSize);
+  }
+  return replacement;
+}
+//# sourceMappingURL=viewportBinding.js.map

package/lib/module/react/viewportBinding.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["resolveViewport2D","ViewportBinding","config","resolved","lastSurfaceSize","revision","listeners","Set","constructor","surfaceSize","setSurfaceSize","size","undefined","width","height","Object","freeze","listener","subscribe","add","removed","delete","dispose","clear","bindingForViewport","previous","replacement"],"sourceRoot":"../../../src","sources":["react/viewportBinding.ts"],"mappings":";;AAAA,SAASA,iBAAiB,QAAkE,wBAAe;;AAE3G;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,eAAe,CAAC;EAClB,CAACC,MAAM;EAChB,CAACC,QAAQ;EACT,CAACC,eAAe;EAChB,CAACC,QAAQ,GAAG,CAAC;EACb,CAACC,SAAS,GAAG,IAAIC,GAAG,CAAa,CAAC;EAElCC,WAAWA,CAACN,MAAgB,EAAE;IAC5B,IAAI,CAAC,CAACA,MAAM,GAAGA,MAAM;EACvB;;EAEA;EACA,IAAIA,MAAMA,CAAA,EAAa;IACrB,OAAO,IAAI,CAAC,CAACA,MAAM;EACrB;;EAEA;EACA,IAAIC,QAAQA,CAAA,EAAmC;IAC7C,OAAO,IAAI,CAAC,CAACA,QAAQ;EACvB;;EAEA;EACA,IAAIM,WAAWA,CAAA,EAA4B;IACzC,OAAO,IAAI,CAAC,CAACL,eAAe;EAC9B;;EAEA;EACA,IAAIC,QAAQA,CAAA,EAAW;IACrB,OAAO,IAAI,CAAC,CAACA,QAAQ;EACvB;;EAEA;AACF;AACA;AACA;AACA;AACA;EACEK,cAAcA,CAACC,IAAiB,EAAQ;IACtC,IACE,IAAI,CAAC,CAACP,eAAe,KAAKQ,SAAS,IACnC,IAAI,CAAC,CAACR,eAAe,CAACS,KAAK,KAAKF,IAAI,CAACE,KAAK,IAC1C,IAAI,CAAC,CAACT,eAAe,CAACU,MAAM,KAAKH,IAAI,CAACG,MAAM,EAC5C;MACA;IACF;IACA,IAAI,CAAC,CAACV,eAAe,GAAGW,MAAM,CAACC,MAAM,CAAC;MAAEH,KAAK,EAAEF,IAAI,CAACE,KAAK;MAAEC,MAAM,EAAEH,IAAI,CAACG;IAAO,CAAC,CAAC;IACjF,IAAI,CAAC,CAACX,QAAQ,GAAGH,iBAAiB,CAAC,IAAI,CAAC,CAACE,MAAM,EAAES,IAAI,CAAC;IACtD,IAAI,CAAC,CAACN,QAAQ,IAAI,CAAC;IACnB,KAAK,MAAMY,QAAQ,IAAI,CAAC,GAAG,IAAI,CAAC,CAACX,SAAS,CAAC,EAAE;MAC3CW,QAAQ,CAAC,CAAC;IACZ;EACF;;EAEA;EACAC,SAASA,CAACD,QAAoB,EAAc;IAC1C,IAAI,CAAC,CAACX,SAAS,CAACa,GAAG,CAACF,QAAQ,CAAC;IAC7B,IAAIG,OAAO,GAAG,KAAK;IACnB,OAAO,MAAM;MACX,IAAIA,OAAO,EAAE;QACX;MACF;MACAA,OAAO,GAAG,IAAI;MACd,IAAI,CAAC,CAACd,SAAS,CAACe,MAAM,CAACJ,QAAQ,CAAC;IAClC,CAAC;EACH;;EAEA;EACAK,OAAOA,CAAA,EAAS;IACd,IAAI,CAAC,CAAChB,SAAS,CAACiB,KAAK,CAAC,CAAC;EACzB;AACF;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,kBAAkBA,CAChCtB,MAAgB,EAChBuB,QAAgC,EACf;EACjB,IAAIA,QAAQ,EAAEvB,MAAM,KAAKA,MAAM,EAAE;IAC/B,OAAOuB,QAAQ;EACjB;EAEA,MAAMC,WAAW,GAAG,IAAIzB,eAAe,CAACC,MAAM,CAAC;EAC/C,IAAIuB,QAAQ,EAAEhB,WAAW,KAAKG,SAAS,EAAE;IACvCc,WAAW,CAAChB,cAAc,CAACe,QAAQ,CAAChB,WAAW,CAAC;EAClD;EACA,OAAOiB,WAAW;AACpB","ignoreList":[]}

package/lib/module/react.js

@@ -0,0 +1,13 @@
+"use strict";
+
+export { GameView } from "./react/GameView.js";
+export { createGameAssetStore } from "./react/assets/decodeSkiaImage.js";
+export { useGameAssets, stableGroupsKey } from "./react/assets/useGameAssets.js";
+export { GameWorld2D, viewportTransform } from "./react/sprites/GameWorld2D.js";
+export { Sprite, resolveSpriteFrameRect } from "./react/sprites/Sprite.js";
+export { GameSprite, spriteFrameNameForClip } from "./react/sprites/GameSprite.js";
+export { SpriteBatch } from "./react/sprites/SpriteBatch.js";
+export { computeSpriteRsxform, spriteAnchorWorld, spriteGroupCorrection } from "./react/sprites/spriteTransform.js";
+export { createGameAssetStoreCore } from "./react/assets/createGameAssetStore.js";
+export { GamePointerInput } from "./react/GamePointerInput.js";
+//# sourceMappingURL=react.js.map

package/lib/module/react.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["GameView","createGameAssetStore","useGameAssets","stableGroupsKey","GameWorld2D","viewportTransform","Sprite","resolveSpriteFrameRect","GameSprite","spriteFrameNameForClip","SpriteBatch","computeSpriteRsxform","spriteAnchorWorld","spriteGroupCorrection","createGameAssetStoreCore","GamePointerInput"],"sourceRoot":"../../src","sources":["react.ts"],"mappings":";;AAAA,SAASA,QAAQ,QAAQ,qBAAkB;AAC3C,SAASC,oBAAoB,QAAQ,mCAAgC;AACrE,SAASC,aAAa,EAAEC,eAAe,QAAQ,iCAA8B;AAE7E,SAASC,WAAW,EAAEC,iBAAiB,QAAQ,gCAA6B;AAC5E,SAASC,MAAM,EAAEC,sBAAsB,QAAQ,2BAAwB;AAEvE,SAASC,UAAU,EAAEC,sBAAsB,QAAQ,+BAA4B;AAM/E,SAASC,WAAW,QAAQ,gCAA6B;AAEzD,SACEC,oBAAoB,EACpBC,iBAAiB,EACjBC,qBAAqB,QAChB,oCAAiC;AAMxC,SAASC,wBAAwB,QAAQ,wCAAqC;AAS9E,SAASC,gBAAgB,QAAQ,6BAA0B","ignoreList":[]}

package/lib/module/scene/defineScene.js

@@ -0,0 +1,29 @@
+"use strict";
+
+/**
+ * Define a synchronous functional scene while inferring its state, snapshot,
+ * action, and transition types.
+ *
+ * @example
+ * ```ts
+ * const 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,
+ * });
+ * ```
+ */
+export function defineScene(definition) {
+  return {
+    kind: 'gamekit.scene',
+    ...definition
+  };
+}
+//# sourceMappingURL=defineScene.js.map

package/lib/module/scene/defineScene.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["defineScene","definition","kind"],"sourceRoot":"../../../src","sources":["scene/defineScene.ts"],"mappings":";;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASA,WAAWA,CAMzBC,UAGuE,EACK;EAC5E,OAAO;IACLC,IAAI,EAAE,eAAe;IACrB,GAAGD;EACL,CAAC;AACH","ignoreList":[]}

package/lib/module/scene/types.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=types.js.map

package/lib/module/scene/types.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sourceRoot":"../../../src","sources":["scene/types.ts"],"mappings":"","ignoreList":[]}

package/lib/module/sprites/sampleSpriteClip.js

@@ -0,0 +1,50 @@
+"use strict";
+
+/**
+ * Deterministic clip frame sampling (T7.3).
+ *
+ * Pure, allocation-free, worklet-compatible frame selection. The same clip
+ * metadata and elapsed time always select the same frame, so equivalent
+ * game time produces identical presentation at 30/60/90/120 Hz.
+ */
+
+/**
+ * Select the frame index for `elapsedMs` of playback.
+ *
+ * Loop clips wrap with modulo — the boundary frame is never duplicated and
+ * no zero-length boundary frame exists. One-shot clips clamp to their final
+ * frame; completion is reported separately.
+ */
+export function sampleSpriteClipFrame(clip, elapsedMs) {
+  'worklet';
+
+  const frameCount = clip.frames.length;
+  const duration = clip.frameDurationMs;
+  if (clip.mode === 'loop') {
+    const index = Math.floor(elapsedMs / duration) % frameCount;
+    return index >= 0 ? index : index + frameCount;
+  }
+  const index = Math.floor(elapsedMs / duration);
+  return index >= frameCount ? frameCount - 1 : index;
+}
+
+/**
+ * The frame NAME selected for `elapsedMs` of playback (the ordered frame
+ * references of the clip).
+ */
+export function sampleSpriteClipFrameName(clip, elapsedMs) {
+  'worklet';
+
+  const frames = clip.frames;
+  const index = sampleSpriteClipFrame(clip, elapsedMs);
+  const frame = frames[index];
+  return frame === undefined ? frames[0] ?? '' : frame;
+}
+
+/** Total clip duration in milliseconds (one-shot: its full timeline). */
+export function spriteClipDurationMs(clip) {
+  'worklet';
+
+  return clip.frames.length * clip.frameDurationMs;
+}
+//# sourceMappingURL=sampleSpriteClip.js.map

package/lib/module/sprites/sampleSpriteClip.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["sampleSpriteClipFrame","clip","elapsedMs","frameCount","frames","length","duration","frameDurationMs","mode","index","Math","floor","sampleSpriteClipFrameName","frame","undefined","spriteClipDurationMs"],"sourceRoot":"../../../src","sources":["sprites/sampleSpriteClip.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASA,qBAAqBA,CACnCC,IAAgB,EAChBC,SAAiB,EACT;EACR,SAAS;;EACT,MAAMC,UAAU,GAAGF,IAAI,CAACG,MAAM,CAACC,MAAM;EACrC,MAAMC,QAAQ,GAAGL,IAAI,CAACM,eAAe;EACrC,IAAIN,IAAI,CAACO,IAAI,KAAK,MAAM,EAAE;IACxB,MAAMC,KAAK,GAAGC,IAAI,CAACC,KAAK,CAACT,SAAS,GAAGI,QAAQ,CAAC,GAAGH,UAAU;IAC3D,OAAOM,KAAK,IAAI,CAAC,GAAGA,KAAK,GAAGA,KAAK,GAAGN,UAAU;EAChD;EACA,MAAMM,KAAK,GAAGC,IAAI,CAACC,KAAK,CAACT,SAAS,GAAGI,QAAQ,CAAC;EAC9C,OAAOG,KAAK,IAAIN,UAAU,GAAGA,UAAU,GAAG,CAAC,GAAGM,KAAK;AACrD;;AAEA;AACA;AACA;AACA;AACA,OAAO,SAASG,yBAAyBA,CACvCX,IAAgB,EAChBC,SAAiB,EACT;EACR,SAAS;;EACT,MAAME,MAAM,GAAGH,IAAI,CAACG,MAAM;EAC1B,MAAMK,KAAK,GAAGT,qBAAqB,CAACC,IAAI,EAAEC,SAAS,CAAC;EACpD,MAAMW,KAAK,GAAGT,MAAM,CAACK,KAAK,CAAC;EAC3B,OAAOI,KAAK,KAAKC,SAAS,GAAGV,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,GAAGS,KAAK;AACtD;;AAEA;AACA,OAAO,SAASE,oBAAoBA,CAACd,IAAgB,EAAU;EAC7D,SAAS;;EACT,OAAOA,IAAI,CAACG,MAAM,CAACC,MAAM,GAAGJ,IAAI,CAACM,eAAe;AAClD","ignoreList":[]}

package/lib/module/sprites/spriteAnimationState.js

@@ -0,0 +1,165 @@
+"use strict";
+
+/**
+ * Deterministic sprite animation playback state (T7.3).
+ *
+ * Animation state is plain serializable data advanced from fixed-step game
+ * time: `clip`, elapsed time, pause flag, speed, and completion. Changing,
+ * pausing, restarting, or completing a clip returns a NEW state object; it
+ * never mutates scene state or emits a side effect. The same input and
+ * elapsed game time always select the same presented frame (see
+ * `sampleSpriteClip`).
+ *
+ * Separation of concerns: gameplay-significant animation state lives in the
+ * scene snapshot and advances from fixed-step game time; a renderer-only
+ * loop may interpolate presentation from the latest committed state plus
+ * the interpolation alpha, but must never emit gameplay events from a
+ * presentation-only frame.
+ */
+import { GameAssetError } from "../assets/errors.js";
+import { spriteClipDurationMs } from "./sampleSpriteClip.js";
+
+/** Immutable, serializable animation playback state. */
+
+function assertFinitePositiveSpeed(speed) {
+  if (typeof speed !== 'number' || !Number.isFinite(speed) || speed <= 0) {
+    throw new Error('sprite animation speed must be a finite number greater than zero');
+  }
+}
+function assertFiniteDelta(deltaSeconds) {
+  if (typeof deltaSeconds !== 'number' || !Number.isFinite(deltaSeconds)) {
+    throw new Error('sprite animation delta must be a finite number of seconds');
+  }
+}
+/** The clip names of a sprite-sheet descriptor (works through the manifest brand). */
+
+/** Runtime clip lookup; throws a structured error for unknown clips. */
+function clipOf(descriptor, clip) {
+  'worklet';
+
+  const animation = descriptor.animations[clip];
+  if (animation === undefined) {
+    throw new GameAssetError('ASSET_UNKNOWN_CLIP', ['animations', clip], `unknown animation clip ${JSON.stringify(clip)}`);
+  }
+  return animation;
+}
+
+/**
+ * Start playback of `clip` from its beginning. The clip name is preserved
+ * as a string literal in the returned state; unknown clips are rejected at
+ * runtime (the manifest descriptor keeps the sheet-level frame and clip
+ * names literal via the spriteSheet contract).
+ */
+export function startSpriteAnimation(descriptor, clip) {
+  'worklet';
+
+  clipOf(descriptor, clip);
+  return {
+    clip,
+    elapsedMs: 0,
+    paused: false,
+    speed: 1,
+    completed: false
+  };
+}
+
+/**
+ * Advance playback by `deltaSeconds` of fixed-step game time.
+ *
+ * Finite negative deltas clamp elapsed time to zero; NaN/infinity fail
+ * clearly. Loop clips keep their elapsed time bounded within one timeline
+ * (modulo), so arbitrarily large deltas cost constant arithmetic.
+ */
+export function advanceSpriteAnimation(descriptor, state, deltaSeconds) {
+  'worklet';
+
+  assertFiniteDelta(deltaSeconds);
+  if (state.paused || state.completed) {
+    return state;
+  }
+  const clip = clipOf(descriptor, state.clip);
+  const totalMs = spriteClipDurationMs(clip);
+  const next = state.elapsedMs + deltaSeconds * 1000 * state.speed;
+  if (clip.mode === 'once') {
+    if (next >= totalMs) {
+      return {
+        ...state,
+        elapsedMs: totalMs,
+        completed: true
+      };
+    }
+    return {
+      ...state,
+      elapsedMs: next < 0 ? 0 : next
+    };
+  }
+  // Loop: bounded elapsed within one timeline; negative clamps to zero.
+  const wrapped = next < 0 ? 0 : next % totalMs;
+  return {
+    ...state,
+    elapsedMs: wrapped
+  };
+}
+
+/**
+ * Switch playback to `clip`, restarting it from the beginning. The clip
+ * name is typed against the descriptor's animation table.
+ */
+export function playSpriteAnimation(descriptor, state, clip) {
+  'worklet';
+
+  if (clip === state.clip) {
+    return state;
+  }
+  clipOf(descriptor, clip);
+  return {
+    clip,
+    elapsedMs: 0,
+    paused: state.paused,
+    speed: state.speed,
+    completed: false
+  };
+}
+
+/** Pause playback; `advance` becomes a no-op while paused. */
+export function pauseSpriteAnimation(state) {
+  'worklet';
+
+  return state.paused ? state : {
+    ...state,
+    paused: true
+  };
+}
+
+/** Resume playback from the paused position. */
+export function resumeSpriteAnimation(state) {
+  'worklet';
+
+  return state.paused ? {
+    ...state,
+    paused: false
+  } : state;
+}
+
+/** Restart the current clip from its beginning. */
+export function resetSpriteAnimation(state) {
+  'worklet';
+
+  return {
+    ...state,
+    elapsedMs: 0,
+    completed: false
+  };
+}
+
+/** Set a finite positive speed multiplier. */
+export function setSpriteAnimationSpeed(state, speed) {
+  'worklet';
+
+  assertFinitePositiveSpeed(speed);
+  return state.speed === speed ? state : {
+    ...state,
+    speed
+  };
+}
+//# sourceMappingURL=spriteAnimationState.js.map

package/lib/module/sprites/spriteAnimationState.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["GameAssetError","spriteClipDurationMs","assertFinitePositiveSpeed","speed","Number","isFinite","Error","assertFiniteDelta","deltaSeconds","clipOf","descriptor","clip","animation","animations","undefined","JSON","stringify","startSpriteAnimation","elapsedMs","paused","completed","advanceSpriteAnimation","state","totalMs","next","mode","wrapped","playSpriteAnimation","pauseSpriteAnimation","resumeSpriteAnimation","resetSpriteAnimation","setSpriteAnimationSpeed"],"sourceRoot":"../../../src","sources":["sprites/spriteAnimationState.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/testing.js

@@ -0,0 +1,57 @@
+"use strict";
+
+import { createGameSessionWithDriver } from "./core/session/createGameSession.js";
+import { createAnimationFrameDriver } from "./core/frameDriver.js";
+export { createAnimationFrameDriver, createGameSessionWithDriver };
+/**
+ * Deterministic animation-frame driver for headless tests.
+ *
+ * Frames are fired manually with explicit timestamps, so games can be driven
+ * with a fixed step and exact wall-clock schedules in Node without a
+ * simulator.
+ */
+export class ManualFrameDriver {
+  #callbacks = new Map();
+  #allCallbacks = new Map();
+  #nextHandle = 1;
+
+  /** Number of currently scheduled callbacks. */
+  get pendingCount() {
+    return this.#callbacks.size;
+  }
+  requestFrame(callback) {
+    const handle = this.#nextHandle;
+    this.#nextHandle += 1;
+    this.#callbacks.set(handle, callback);
+    this.#allCallbacks.set(handle, callback);
+    return handle;
+  }
+  cancelFrame(handle) {
+    this.#callbacks.delete(handle);
+  }
+
+  /** Fire the next pending callback with the given timestamp. */
+  fireNext(timestampMs) {
+    const next = this.#callbacks.entries().next();
+    if (next.done) {
+      throw new Error('No frame is pending');
+    }
+    const [handle, callback] = next.value;
+    this.#callbacks.delete(handle);
+    callback(timestampMs);
+    return handle;
+  }
+
+  /**
+   * Fire a specific handle even if it was already fired, simulating a stale
+   * callback racing with a lifecycle change.
+   */
+  fireCancelled(handle, timestampMs) {
+    const callback = this.#allCallbacks.get(handle);
+    if (!callback) {
+      throw new Error(`Unknown frame handle: ${handle}`);
+    }
+    callback(timestampMs);
+  }
+}
+//# sourceMappingURL=testing.js.map

package/lib/module/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["createGameSessionWithDriver","createAnimationFrameDriver","ManualFrameDriver","callbacks","Map","allCallbacks","nextHandle","pendingCount","size","requestFrame","callback","handle","set","cancelFrame","delete","fireNext","timestampMs","next","entries","done","Error","value","fireCancelled","get"],"sourceRoot":"../../src","sources":["testing.ts"],"mappings":";;AAAA,SAASA,2BAA2B,QAAQ,qCAAkC;AAC9E,SAASC,0BAA0B,QAAQ,uBAAoB;AAI/D,SAASA,0BAA0B,EAAED,2BAA2B;AAGhE;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAME,iBAAiB,CAAwB;EAC3C,CAACC,SAAS,GAAG,IAAIC,GAAG,CAAwC,CAAC;EAC7D,CAACC,YAAY,GAAG,IAAID,GAAG,CAAwC,CAAC;EACzE,CAACE,UAAU,GAAG,CAAC;;EAEf;EACA,IAAIC,YAAYA,CAAA,EAAW;IACzB,OAAO,IAAI,CAAC,CAACJ,SAAS,CAACK,IAAI;EAC7B;EAEAC,YAAYA,CAACC,QAAuC,EAAe;IACjE,MAAMC,MAAM,GAAG,IAAI,CAAC,CAACL,UAAU;IAC/B,IAAI,CAAC,CAACA,UAAU,IAAI,CAAC;IACrB,IAAI,CAAC,CAACH,SAAS,CAACS,GAAG,CAACD,MAAM,EAAED,QAAQ,CAAC;IACrC,IAAI,CAAC,CAACL,YAAY,CAACO,GAAG,CAACD,MAAM,EAAED,QAAQ,CAAC;IACxC,OAAOC,MAAM;EACf;EAEAE,WAAWA,CAACF,MAAmB,EAAQ;IACrC,IAAI,CAAC,CAACR,SAAS,CAACW,MAAM,CAACH,MAAM,CAAC;EAChC;;EAEA;EACAI,QAAQA,CAACC,WAAmB,EAAe;IACzC,MAAMC,IAAI,GAAG,IAAI,CAAC,CAACd,SAAS,CAACe,OAAO,CAAC,CAAC,CAACD,IAAI,CAAC,CAAC;IAC7C,IAAIA,IAAI,CAACE,IAAI,EAAE;MACb,MAAM,IAAIC,KAAK,CAAC,qBAAqB,CAAC;IACxC;IACA,MAAM,CAACT,MAAM,EAAED,QAAQ,CAAC,GAAGO,IAAI,CAACI,KAAK;IACrC,IAAI,CAAC,CAAClB,SAAS,CAACW,MAAM,CAACH,MAAM,CAAC;IAC9BD,QAAQ,CAACM,WAAW,CAAC;IACrB,OAAOL,MAAM;EACf;;EAEA;AACF;AACA;AACA;EACEW,aAAaA,CAACX,MAAmB,EAAEK,WAAmB,EAAQ;IAC5D,MAAMN,QAAQ,GAAG,IAAI,CAAC,CAACL,YAAY,CAACkB,GAAG,CAACZ,MAAM,CAAC;IAC/C,IAAI,CAACD,QAAQ,EAAE;MACb,MAAM,IAAIU,KAAK,CAAC,yBAAyBT,MAAM,EAAE,CAAC;IACpD;IACAD,QAAQ,CAACM,WAAW,CAAC;EACvB;AACF","ignoreList":[]}

package/lib/module/viewport2d/index.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export { containsSurfacePoint, resolveViewport2D, surfaceToWorld, worldToSurface } from "./math.js";
+//# sourceMappingURL=index.js.map

package/lib/module/viewport2d/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["containsSurfacePoint","resolveViewport2D","surfaceToWorld","worldToSurface"],"sourceRoot":"../../../src","sources":["viewport2d/index.ts"],"mappings":";;AACA,SACEA,oBAAoB,EACpBC,iBAAiB,EACjBC,cAAc,EACdC,cAAc,QACT,WAAQ","ignoreList":[]}