rn-gamekit 0.1.0

package/lib/module/core/session/deepFreeze.js

@@ -0,0 +1,155 @@
+"use strict";
+
+/**
+ * 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.
+ */
+
+/** 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) {
+  '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) {
+  '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 function createDeepFreeze() {
+  const trusted = new WeakSet();
+  return function deepFreeze(value) {
+    if (typeof value !== 'object' || value === null) {
+      return value;
+    }
+    const visiting = new WeakSet();
+    const freeze = node => {
+      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[name]);
+          }
+        }
+        const symbols = Object.getOwnPropertySymbols(node);
+        for (let index = 0; index < symbols.length; index += 1) {
+          const symbol = symbols[index];
+          if (symbol !== undefined) {
+            freeze(node[symbol]);
+          }
+        }
+      } else {
+        for (const key of Reflect.ownKeys(node)) {
+          freeze(node[key]);
+        }
+      }
+      Object.freeze(node);
+      trusted.add(node);
+    };
+    freeze(value);
+    return value;
+  };
+}
+//# sourceMappingURL=deepFreeze.js.map

package/lib/module/core/session/deepFreeze.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["digitLength","value","isArrayIndexKey","key","length","charCodeAt","index","code","createDeepFreeze","trusted","WeakSet","deepFreeze","visiting","freeze","node","has","add","Array","isArray","names","Object","getOwnPropertyNames","expectedIndex","name","undefined","Number","symbols","getOwnPropertySymbols","symbol","Reflect","ownKeys"],"sourceRoot":"../../../../src","sources":["core/session/deepFreeze.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/core/session/diagnostics.js

@@ -0,0 +1,2 @@
+"use strict";
+//# sourceMappingURL=diagnostics.js.map

package/lib/module/core/session/diagnostics.js.map

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

package/lib/module/core/session/types.js

@@ -0,0 +1,43 @@
+"use strict";
+
+/** Recursively readonly view of renderer snapshot data. */
+
+/** Lifecycle states of a headless game session. */
+
+/** One renderer-neutral simulation commit produced by a game session. */
+
+/**
+ * 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.
+ */
+
+/** A commit frame plus a presentation fraction computed on demand. */
+
+/** An idempotently removable render-frame subscription. */
+
+/** A closure-backed, headless running instance of one game definition. */
+
+/** Error thrown when live work is requested from a disposed session. */
+export class GameSessionDisposedError extends Error {
+  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 {
+  name = 'GameSessionLifecycleError';
+  constructor(message) {
+    super(message);
+  }
+}
+//# sourceMappingURL=types.js.map

package/lib/module/core/session/types.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["GameSessionDisposedError","Error","name","constructor","GameSessionLifecycleError","message"],"sourceRoot":"../../../../src","sources":["core/session/types.ts"],"mappings":";;AAKA;;AASA;;AAGA;;AAkBA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAOA;;AAMA;;AAMA;;AAwCA;AACA,OAAO,MAAMA,wBAAwB,SAASC,KAAK,CAAC;EAChCC,IAAI,GAAG,0BAA0B;EAEnDC,WAAWA,CAAA,EAAG;IACZ,KAAK,CAAC,oCAAoC,CAAC;EAC7C;AACF;;AAEA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,yBAAyB,SAASH,KAAK,CAAC;EACjCC,IAAI,GAAG,2BAA2B;EAEpDC,WAAWA,CAACE,OAAe,EAAE;IAC3B,KAAK,CAACA,OAAO,CAAC;EAChB;AACF","ignoreList":[]}

package/lib/module/definition/defineGame.js

@@ -0,0 +1,57 @@
+"use strict";
+
+/**
+ * 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(definition) {
+  // 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;
+}
+//# sourceMappingURL=defineGame.js.map

package/lib/module/definition/defineGame.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["defineGame","definition","Object","freeze","viewport","logicalSize"],"sourceRoot":"../../../src","sources":["definition/defineGame.ts"],"mappings":";;AA+BA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASA,UAAUA,CAMxBC,UAEmC,EACsB;EACzD;EACA;EACAC,MAAM,CAACC,MAAM,CAACF,UAAU,CAACG,QAAQ,CAACC,WAAW,CAAC;EAC9CH,MAAM,CAACC,MAAM,CAACF,UAAU,CAACG,QAAQ,CAAC;EAClC,OAAOH,UAAU;AACnB","ignoreList":[]}

package/lib/module/definition/types.js

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

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

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

package/lib/module/geometry/types.js

@@ -0,0 +1,2 @@
+"use strict";
+//# sourceMappingURL=types.js.map

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

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

package/lib/module/index.js

@@ -0,0 +1,12 @@
+"use strict";
+
+export { createGameSession } from "./core/session/createGameSession.js";
+export { GameSessionDisposedError, GameSessionLifecycleError } from "./core/session/types.js";
+export { advanceSpriteAnimation, pauseSpriteAnimation, playSpriteAnimation, resetSpriteAnimation, resumeSpriteAnimation, setSpriteAnimationSpeed, startSpriteAnimation } from "./sprites/spriteAnimationState.js";
+export { sampleSpriteClipFrame, sampleSpriteClipFrameName, spriteClipDurationMs } from "./sprites/sampleSpriteClip.js";
+export { defineAssets, image, spriteSheet } from "./assets/defineAssets.js";
+export { GameAssetError } from "./assets/errors.js";
+export { defineGame } from "./definition/defineGame.js";
+export { defineScene } from "./scene/defineScene.js";
+export { containsSurfacePoint, resolveViewport2D, surfaceToWorld, worldToSurface } from "./viewport2d/index.js";
+//# sourceMappingURL=index.js.map

package/lib/module/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["createGameSession","GameSessionDisposedError","GameSessionLifecycleError","advanceSpriteAnimation","pauseSpriteAnimation","playSpriteAnimation","resetSpriteAnimation","resumeSpriteAnimation","setSpriteAnimationSpeed","startSpriteAnimation","sampleSpriteClipFrame","sampleSpriteClipFrameName","spriteClipDurationMs","defineAssets","image","spriteSheet","GameAssetError","defineGame","defineScene","containsSurfacePoint","resolveViewport2D","surfaceToWorld","worldToSurface"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;AAAA,SAASA,iBAAiB,QAAQ,qCAAkC;AACpE,SAASC,wBAAwB,EAAEC,yBAAyB,QAAQ,yBAAsB;AAe1F,SACEC,sBAAsB,EACtBC,oBAAoB,EACpBC,mBAAmB,EACnBC,oBAAoB,EACpBC,qBAAqB,EACrBC,uBAAuB,EACvBC,oBAAoB,QACf,mCAAgC;AACvC,SACEC,qBAAqB,EACrBC,yBAAyB,EACzBC,oBAAoB,QACf,+BAA4B;AAEnC,SAASC,YAAY,EAAEC,KAAK,EAAEC,WAAW,QAAQ,0BAAuB;AACxE,SAASC,cAAc,QAAQ,oBAAiB;AAmBhD,SAASC,UAAU,QAAQ,4BAAyB;AAWpD,SAASC,WAAW,QAAQ,wBAAqB;AAQjD,SACEC,oBAAoB,EACpBC,iBAAiB,EACjBC,cAAc,EACdC,cAAc,QACT,uBAAc","ignoreList":[]}

package/lib/module/package.json

@@ -0,0 +1 @@
+{"type":"module"}