rn-gamekit 0.1.0 → 0.2.1

package/lib/module/sprites/sampleSpriteClip.js

@@ -6,25 +6,63 @@
  * 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.
+ *
+ * Single-contract rule (GS-ANIMATION-01): every renderer path resolves
+ * frames through these helpers — never duplicated arithmetic. Negative
+ * elapsed clamps uniformly (loops wrap, one-shots pin to frame zero);
+ * non-finite elapsed, empty clips, and non-positive durations fail clearly
+ * instead of masking invalid data as frame zero. Unknown clip names throw
+ * a plain `[ASSET_UNKNOWN_CLIP]` error: the UI-reachable call graph must
+ * stay free of error-class construction so failure branches execute on the
+ * UI runtime exactly as they do headlessly (GS-ANIMATION-02).
  */
 
+/** Reject elapsed values the sampler cannot define a frame for. */
+function assertFiniteElapsed(elapsedMs) {
+  'worklet';
+
+  if (typeof elapsedMs !== 'number' || !Number.isFinite(elapsedMs)) {
+    throw new Error(`sprite clip elapsed time must be a finite number of milliseconds, got ${String(elapsedMs)}`);
+  }
+}
+
+/** Reject clips with no selectable frame or no positive pace. */
+function assertSelectableClip(clip) {
+  'worklet';
+
+  const frameCount = clip.frames.length;
+  const duration = clip.frameDurationMs;
+  if (frameCount === 0) {
+    throw new Error('sprite clip must reference at least one frame');
+  }
+  if (typeof duration !== 'number' || !Number.isFinite(duration) || duration <= 0) {
+    throw new Error(`sprite clip frame duration must be a finite number greater than zero, got ${String(duration)}`);
+  }
+  return frameCount;
+}
+
 /**
  * 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.
+ * no zero-length boundary frame exists; negative elapsed wraps into range.
+ * One-shot clips clamp to `[0, frameCount - 1]`; completion is reported
+ * separately by the playback state.
  */
 export function sampleSpriteClipFrame(clip, elapsedMs) {
   'worklet';
 
-  const frameCount = clip.frames.length;
+  assertFiniteElapsed(elapsedMs);
+  const frameCount = assertSelectableClip(clip);
   const duration = clip.frameDurationMs;
   if (clip.mode === 'loop') {
     const index = Math.floor(elapsedMs / duration) % frameCount;
-    return index >= 0 ? index : index + frameCount;
+    return (index + frameCount) % frameCount;
   }
   const index = Math.floor(elapsedMs / duration);
+  if (index < 0) {
+    return 0;
+  }
   return index >= frameCount ? frameCount - 1 : index;
 }
 
@@ -37,8 +75,7 @@ export function sampleSpriteClipFrameName(clip, elapsedMs) {
 
   const frames = clip.frames;
   const index = sampleSpriteClipFrame(clip, elapsedMs);
-  const frame = frames[index];
-  return frame === undefined ? frames[0] ?? '' : frame;
+  return frames[index] ?? '';
 }
 
 /** Total clip duration in milliseconds (one-shot: its full timeline). */
@@ -47,4 +84,27 @@ export function spriteClipDurationMs(clip) {
 
   return clip.frames.length * clip.frameDurationMs;
 }
+
+/**
+ * Select the frame name for a clip + elapsed time (loop/once semantics).
+ *
+ * Reads the descriptor's animation table with the single sampler contract
+ * above. An absent clip table entry is an invalid clip — it throws instead
+ * of returning the clip string as if it were a frame name. Absent
+ * *selection* (no clip chosen yet) is distinct: callers keep that path and
+ * present nothing without calling this helper.
+ */
+export function spriteFrameNameForClip(animations, clip, elapsedMs) {
+  'worklet';
+
+  const animation = animations[clip];
+  if (animation === undefined) {
+    throw new Error(`[ASSET_UNKNOWN_CLIP] unknown animation clip ${JSON.stringify(clip)}`);
+  }
+  const name = sampleSpriteClipFrameName(animation, elapsedMs);
+  if (name === '') {
+    throw new Error(`[ASSET_EMPTY_CLIP] clip ${JSON.stringify(clip)} selects no frame`);
+  }
+  return name;
+}
 //# sourceMappingURL=sampleSpriteClip.js.map

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

@@ -1 +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":[]}
+{"version":3,"names":["assertFiniteElapsed","elapsedMs","Number","isFinite","Error","String","assertSelectableClip","clip","frameCount","frames","length","duration","frameDurationMs","sampleSpriteClipFrame","mode","index","Math","floor","sampleSpriteClipFrameName","spriteClipDurationMs","spriteFrameNameForClip","animations","animation","undefined","JSON","stringify","name"],"sourceRoot":"../../../src","sources":["sprites/sampleSpriteClip.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/sprites/spriteAnimationState.js

@@ -10,6 +10,13 @@
  * elapsed game time always select the same presented frame (see
  * `sampleSpriteClip`).
  *
+ * Simulation-only execution (GS-ANIMATION-02): these state transitions run
+ * on fixed-step game time in the simulation, never on the UI runtime, so
+ * they carry no worklet directive — a directive here would promise UI
+ * execution the error branches (structured error classes) cannot keep.
+ * The UI-reachable frame-selection helpers live in `sampleSpriteClip` and
+ * `react/sprites/spriteSelection` with a UI-safe call graph.
+ *
  * 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
@@ -35,8 +42,6 @@ function assertFiniteDelta(deltaSeconds) {
 
 /** 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)}`);
@@ -45,14 +50,11 @@ function clipOf(descriptor, clip) {
 }
 
 /**
- * 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).
+ * Start playback of `clip` from its beginning. The clip name is constrained
+ * to the descriptor's animation keys, so a misspelled clip fails compilation;
+ * untyped callers still hit the runtime check below.
  */
 export function startSpriteAnimation(descriptor, clip) {
-  'worklet';
-
   clipOf(descriptor, clip);
   return {
     clip,
@@ -71,8 +73,6 @@ export function startSpriteAnimation(descriptor, clip) {
  * (modulo), so arbitrarily large deltas cost constant arithmetic.
  */
 export function advanceSpriteAnimation(descriptor, state, deltaSeconds) {
-  'worklet';
-
   assertFiniteDelta(deltaSeconds);
   if (state.paused || state.completed) {
     return state;
@@ -106,8 +106,6 @@ export function advanceSpriteAnimation(descriptor, state, deltaSeconds) {
  * name is typed against the descriptor's animation table.
  */
 export function playSpriteAnimation(descriptor, state, clip) {
-  'worklet';
-
   if (clip === state.clip) {
     return state;
   }
@@ -123,8 +121,6 @@ export function playSpriteAnimation(descriptor, state, clip) {
 
 /** Pause playback; `advance` becomes a no-op while paused. */
 export function pauseSpriteAnimation(state) {
-  'worklet';
-
   return state.paused ? state : {
     ...state,
     paused: true
@@ -133,8 +129,6 @@ export function pauseSpriteAnimation(state) {
 
 /** Resume playback from the paused position. */
 export function resumeSpriteAnimation(state) {
-  'worklet';
-
   return state.paused ? {
     ...state,
     paused: false
@@ -143,8 +137,6 @@ export function resumeSpriteAnimation(state) {
 
 /** Restart the current clip from its beginning. */
 export function resetSpriteAnimation(state) {
-  'worklet';
-
   return {
     ...state,
     elapsedMs: 0,
@@ -154,8 +146,6 @@ export function resetSpriteAnimation(state) {
 
 /** Set a finite positive speed multiplier. */
 export function setSpriteAnimationSpeed(state, speed) {
-  'worklet';
-
   assertFinitePositiveSpeed(speed);
   return state.speed === speed ? state : {
     ...state,

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

@@ -1 +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":[]}
+{"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/sprites.js

@@ -0,0 +1,11 @@
+"use strict";
+
+/**
+ * Subpath entry for `rn-gamekit/sprites`.
+ *
+ * Deterministic sprite-clip sampling and immutable playback-state helpers.
+ * React components (Sprite, GameSprite, SpriteBatch) remain in `rn-gamekit/react`.
+ */
+export { sampleSpriteClipFrame, sampleSpriteClipFrameName, spriteClipDurationMs, spriteFrameNameForClip } from "./sprites/sampleSpriteClip.js";
+export { advanceSpriteAnimation, pauseSpriteAnimation, playSpriteAnimation, resetSpriteAnimation, resumeSpriteAnimation, setSpriteAnimationSpeed, startSpriteAnimation } from "./sprites/spriteAnimationState.js";
+//# sourceMappingURL=sprites.js.map

package/lib/module/sprites.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["sampleSpriteClipFrame","sampleSpriteClipFrameName","spriteClipDurationMs","spriteFrameNameForClip","advanceSpriteAnimation","pauseSpriteAnimation","playSpriteAnimation","resetSpriteAnimation","resumeSpriteAnimation","setSpriteAnimationSpeed","startSpriteAnimation"],"sourceRoot":"../../src","sources":["sprites.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA,SACEA,qBAAqB,EACrBC,yBAAyB,EACzBC,oBAAoB,EACpBC,sBAAsB,QACjB,+BAA4B;AACnC,SACEC,sBAAsB,EACtBC,oBAAoB,EACpBC,mBAAmB,EACnBC,oBAAoB,EACpBC,qBAAqB,EACrBC,uBAAuB,EACvBC,oBAAoB,QACf,mCAAgC","ignoreList":[]}

package/lib/module/storage/adapters/asyncStorage.js

@@ -0,0 +1,57 @@
+"use strict";
+
+import { GameStorageError } from "../errors.js";
+let loader = null;
+export function __setAsyncStorageLoader(fn) {
+  loader = fn;
+}
+export function __getAsyncStorageLoader() {
+  return loader;
+}
+async function loadAsyncStorage() {
+  if (loader) return loader();
+  try {
+    const mod = await import('@react-native-async-storage/async-storage');
+    const resolved = mod.getItem !== undefined ? mod : mod.default?.getItem !== undefined ? mod.default : undefined;
+    if (!resolved) {
+      throw new Error('AsyncStorage module did not export getItem/setItem/removeItem');
+    }
+    return resolved;
+  } catch (cause) {
+    throw new GameStorageError('@react-native-async-storage/async-storage is not installed. Run `npx expo install @react-native-async-storage/async-storage` and rebuild with `npx expo prebuild` (or `expo run:ios` / `expo run:android`). See https://react-native-async-storage.github.io/async-storage/docs/install/', {
+      code: 'BACKEND_READ_FAILED',
+      cause
+    });
+  }
+}
+
+/**
+ * RN adapter backed by AsyncStorage.
+ *
+ * Importing `rn-gamekit/storage` does not eagerly import AsyncStorage —
+ * the dynamic import happens on the first read/write/remove.
+ */
+export function createGameStorageAdapter() {
+  let cached = null;
+  const get = async () => {
+    if (cached) return cached;
+    cached = await loadAsyncStorage();
+    return cached;
+  };
+  return {
+    async read(key) {
+      const storage = await get();
+      const value = await storage.getItem(key);
+      return value === null ? undefined : value;
+    },
+    async write(key, value) {
+      const storage = await get();
+      await storage.setItem(key, value);
+    },
+    async remove(key) {
+      const storage = await get();
+      await storage.removeItem(key);
+    }
+  };
+}
+//# sourceMappingURL=asyncStorage.js.map

package/lib/module/storage/adapters/asyncStorage.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["GameStorageError","loader","__setAsyncStorageLoader","fn","__getAsyncStorageLoader","loadAsyncStorage","mod","resolved","getItem","undefined","default","Error","cause","code","createGameStorageAdapter","cached","get","read","key","storage","value","write","setItem","remove","removeItem"],"sourceRoot":"../../../../src","sources":["storage/adapters/asyncStorage.ts"],"mappings":";;AACA,SAASA,gBAAgB,QAAQ,cAAW;AAS5C,IAAIC,MAAqB,GAAG,IAAI;AAEhC,OAAO,SAASC,uBAAuBA,CAACC,EAAiB,EAAQ;EAC/DF,MAAM,GAAGE,EAAE;AACb;AAEA,OAAO,SAASC,uBAAuBA,CAAA,EAAkB;EACvD,OAAOH,MAAM;AACf;AAEA,eAAeI,gBAAgBA,CAAA,EAAgC;EAC7D,IAAIJ,MAAM,EAAE,OAAOA,MAAM,CAAC,CAAC;EAC3B,IAAI;IACF,MAAMK,GAAG,GAAI,MAAM,MAAM,CAAC,2CAA2C,CAE/C;IACtB,MAAMC,QAAwC,GAC3CD,GAAG,CAAwBE,OAAO,KAAKC,SAAS,GAC5CH,GAAG,GACJA,GAAG,CAACI,OAAO,EAAEF,OAAO,KAAKC,SAAS,GAChCH,GAAG,CAACI,OAAO,GACXD,SAAS;IACjB,IAAI,CAACF,QAAQ,EAAE;MACb,MAAM,IAAII,KAAK,CAAC,+DAA+D,CAAC;IAClF;IACA,OAAOJ,QAAQ;EACjB,CAAC,CAAC,OAAOK,KAAK,EAAE;IACd,MAAM,IAAIZ,gBAAgB,CACxB,0RAA0R,EAC1R;MACEa,IAAI,EAAE,qBAAqB;MAC3BD;IACF,CACF,CAAC;EACH;AACF;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASE,wBAAwBA,CAAA,EAAuB;EAC7D,IAAIC,MAAiC,GAAG,IAAI;EAC5C,MAAMC,GAAG,GAAG,MAAAA,CAAA,KAAyC;IACnD,IAAID,MAAM,EAAE,OAAOA,MAAM;IACzBA,MAAM,GAAG,MAAMV,gBAAgB,CAAC,CAAC;IACjC,OAAOU,MAAM;EACf,CAAC;EAED,OAAO;IACL,MAAME,IAAIA,CAACC,GAAW,EAA+B;MACnD,MAAMC,OAAO,GAAG,MAAMH,GAAG,CAAC,CAAC;MAC3B,MAAMI,KAAK,GAAG,MAAMD,OAAO,CAACX,OAAO,CAACU,GAAG,CAAC;MACxC,OAAOE,KAAK,KAAK,IAAI,GAAGX,SAAS,GAAGW,KAAK;IAC3C,CAAC;IACD,MAAMC,KAAKA,CAACH,GAAW,EAAEE,KAAa,EAAiB;MACrD,MAAMD,OAAO,GAAG,MAAMH,GAAG,CAAC,CAAC;MAC3B,MAAMG,OAAO,CAACG,OAAO,CAACJ,GAAG,EAAEE,KAAK,CAAC;IACnC,CAAC;IACD,MAAMG,MAAMA,CAACL,GAAW,EAAiB;MACvC,MAAMC,OAAO,GAAG,MAAMH,GAAG,CAAC,CAAC;MAC3B,MAAMG,OAAO,CAACK,UAAU,CAACN,GAAG,CAAC;IAC/B;EACF,CAAC;AACH","ignoreList":[]}

package/lib/module/storage/adapters/memory.js

@@ -0,0 +1,50 @@
+"use strict";
+
+/**
+ * In-memory adapter for tests and apps that own storage elsewhere.
+ * Each instance owns its map.
+ */
+export function createMemoryStorageAdapter(initial) {
+  const map = new Map(initial ? Object.entries(initial) : []);
+  return {
+    async read(key) {
+      return map.get(key);
+    },
+    async write(key, value) {
+      map.set(key, value);
+    },
+    async remove(key) {
+      map.delete(key);
+    }
+  };
+}
+
+/**
+ * Programmable failure adapter for tests — wraps another adapter and injects failures.
+ */
+export function createFailingStorageAdapter(inner, opts = {}) {
+  const delay = async () => {
+    if (opts.delayMs) await new Promise(r => setTimeout(r, opts.delayMs));
+  };
+  return {
+    async read(key) {
+      await delay();
+      const err = opts.failRead?.(key) ?? null;
+      if (err) throw err;
+      return inner.read(key);
+    },
+    async write(key, value) {
+      await delay();
+      const err = opts.failWrite?.(key, value) ?? null;
+      if (err) throw err;
+      return inner.write(key, value);
+    },
+    async remove(key) {
+      await delay();
+      const err = opts.failRemove?.(key) ?? null;
+      if (err) throw err;
+      return inner.remove(key);
+    }
+  };
+}
+//# sourceMappingURL=memory.js.map

package/lib/module/storage/adapters/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["createMemoryStorageAdapter","initial","map","Map","Object","entries","read","key","get","write","value","set","remove","delete","createFailingStorageAdapter","inner","opts","delay","delayMs","Promise","r","setTimeout","err","failRead","failWrite","failRemove"],"sourceRoot":"../../../../src","sources":["storage/adapters/memory.ts"],"mappings":";;AAEA;AACA;AACA;AACA;AACA,OAAO,SAASA,0BAA0BA,CAACC,OAAgC,EAAsB;EAC/F,MAAMC,GAAG,GAAG,IAAIC,GAAG,CAAiBF,OAAO,GAAGG,MAAM,CAACC,OAAO,CAACJ,OAAO,CAAC,GAAG,EAAE,CAAC;EAE3E,OAAO;IACL,MAAMK,IAAIA,CAACC,GAAW,EAA+B;MACnD,OAAOL,GAAG,CAACM,GAAG,CAACD,GAAG,CAAC;IACrB,CAAC;IACD,MAAME,KAAKA,CAACF,GAAW,EAAEG,KAAa,EAAiB;MACrDR,GAAG,CAACS,GAAG,CAACJ,GAAG,EAAEG,KAAK,CAAC;IACrB,CAAC;IACD,MAAME,MAAMA,CAACL,GAAW,EAAiB;MACvCL,GAAG,CAACW,MAAM,CAACN,GAAG,CAAC;IACjB;EACF,CAAC;AACH;;AAEA;AACA;AACA;AACA,OAAO,SAASO,2BAA2BA,CACzCC,KAAyB,EACzBC,IAKC,GAAG,CAAC,CAAC,EACc;EACpB,MAAMC,KAAK,GAAG,MAAAA,CAAA,KAA2B;IACvC,IAAID,IAAI,CAACE,OAAO,EAAE,MAAM,IAAIC,OAAO,CAAEC,CAAC,IAAKC,UAAU,CAACD,CAAC,EAAEJ,IAAI,CAACE,OAAO,CAAC,CAAC;EACzE,CAAC;EACD,OAAO;IACL,MAAMZ,IAAIA,CAACC,GAAW,EAA+B;MACnD,MAAMU,KAAK,CAAC,CAAC;MACb,MAAMK,GAAG,GAAGN,IAAI,CAACO,QAAQ,GAAGhB,GAAG,CAAC,IAAI,IAAI;MACxC,IAAIe,GAAG,EAAE,MAAMA,GAAG;MAClB,OAAOP,KAAK,CAACT,IAAI,CAACC,GAAG,CAAC;IACxB,CAAC;IACD,MAAME,KAAKA,CAACF,GAAW,EAAEG,KAAa,EAAiB;MACrD,MAAMO,KAAK,CAAC,CAAC;MACb,MAAMK,GAAG,GAAGN,IAAI,CAACQ,SAAS,GAAGjB,GAAG,EAAEG,KAAK,CAAC,IAAI,IAAI;MAChD,IAAIY,GAAG,EAAE,MAAMA,GAAG;MAClB,OAAOP,KAAK,CAACN,KAAK,CAACF,GAAG,EAAEG,KAAK,CAAC;IAChC,CAAC;IACD,MAAME,MAAMA,CAACL,GAAW,EAAiB;MACvC,MAAMU,KAAK,CAAC,CAAC;MACb,MAAMK,GAAG,GAAGN,IAAI,CAACS,UAAU,GAAGlB,GAAG,CAAC,IAAI,IAAI;MAC1C,IAAIe,GAAG,EAAE,MAAMA,GAAG;MAClB,OAAOP,KAAK,CAACH,MAAM,CAACL,GAAG,CAAC;IAC1B;EACF,CAAC;AACH","ignoreList":[]}

package/lib/module/storage/errors.js

@@ -0,0 +1,34 @@
+"use strict";
+
+/**
+ * V1 storage errors — stable codes, operation, namespace/slot, schema context,
+ * exact path where relevant, and original cause.
+ */
+
+export class GameStorageError extends Error {
+  name = 'GameStorageError';
+  constructor(message, options) {
+    super(message);
+    this.code = options.code;
+    this.operation = options.operation;
+    this.namespace = options.namespace;
+    this.slot = options.slot;
+    this.schemaId = options.schemaId;
+    this.schemaVersion = options.schemaVersion;
+    this.path = options.path;
+    this.cause = options.cause;
+  }
+}
+export function storageError(message, code, opts = {}) {
+  return new GameStorageError(message, {
+    code,
+    operation: opts.operation,
+    namespace: opts.namespace,
+    slot: opts.slot,
+    schemaId: opts.schemaId,
+    schemaVersion: opts.schemaVersion,
+    path: opts.path,
+    cause: opts.cause
+  });
+}
+//# sourceMappingURL=errors.js.map

package/lib/module/storage/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["GameStorageError","Error","name","constructor","message","options","code","operation","namespace","slot","schemaId","schemaVersion","path","cause","storageError","opts"],"sourceRoot":"../../../src","sources":["storage/errors.ts"],"mappings":";;AAAA;AACA;AACA;AACA;;AAwBA,OAAO,MAAMA,gBAAgB,SAASC,KAAK,CAAC;EACxBC,IAAI,GAAG,kBAAkB;EAW3CC,WAAWA,CACTC,OAAe,EACfC,OASC,EACD;IACA,KAAK,CAACD,OAAO,CAAC;IACd,IAAI,CAACE,IAAI,GAAGD,OAAO,CAACC,IAAI;IACxB,IAAI,CAACC,SAAS,GAAGF,OAAO,CAACE,SAAS;IAClC,IAAI,CAACC,SAAS,GAAGH,OAAO,CAACG,SAAS;IAClC,IAAI,CAACC,IAAI,GAAGJ,OAAO,CAACI,IAAI;IACxB,IAAI,CAACC,QAAQ,GAAGL,OAAO,CAACK,QAAQ;IAChC,IAAI,CAACC,aAAa,GAAGN,OAAO,CAACM,aAAa;IAC1C,IAAI,CAACC,IAAI,GAAGP,OAAO,CAACO,IAAI;IACxB,IAAI,CAACC,KAAK,GAAGR,OAAO,CAACQ,KAAK;EAC5B;AACF;AAEA,OAAO,SAASC,YAAYA,CAC1BV,OAAe,EACfE,IAA0B,EAC1BS,IAQC,GAAG,CAAC,CAAC,EACY;EAClB,OAAO,IAAIf,gBAAgB,CAACI,OAAO,EAAE;IACnCE,IAAI;IACJC,SAAS,EAAEQ,IAAI,CAACR,SAAS;IACzBC,SAAS,EAAEO,IAAI,CAACP,SAAS;IACzBC,IAAI,EAAEM,IAAI,CAACN,IAAI;IACfC,QAAQ,EAAEK,IAAI,CAACL,QAAQ;IACvBC,aAAa,EAAEI,IAAI,CAACJ,aAAa;IACjCC,IAAI,EAAEG,IAAI,CAACH,IAAI;IACfC,KAAK,EAAEE,IAAI,CAACF;EACd,CAAC,CAAC;AACJ","ignoreList":[]}

package/lib/module/storage/index.js

@@ -0,0 +1,11 @@
+"use strict";
+
+export { GameStorageError } from "./errors.js";
+export { defineGameSave } from "./schema.js";
+export { createGameSaveStore } from "./store.js";
+export { createMemoryStorageAdapter } from "./adapters/memory.js";
+export { createGameStorageAdapter } from "./adapters/asyncStorage.js";
+export { __setAsyncStorageLoader, __getAsyncStorageLoader } from "./adapters/asyncStorage.js";
+export { STORAGE_LIMITS } from "./types.js";
+export { STORAGE_ENVELOPE_FORMAT } from "./serialization.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["GameStorageError","defineGameSave","createGameSaveStore","createMemoryStorageAdapter","createGameStorageAdapter","__setAsyncStorageLoader","__getAsyncStorageLoader","STORAGE_LIMITS","STORAGE_ENVELOPE_FORMAT"],"sourceRoot":"../../../src","sources":["storage/index.ts"],"mappings":";;AAAA,SAASA,gBAAgB,QAAQ,aAAU;AAE3C,SAASC,cAAc,QAAQ,aAAU;AACzC,SAASC,mBAAmB,QAAQ,YAAS;AAC7C,SAASC,0BAA0B,QAAQ,sBAAmB;AAC9D,SAASC,wBAAwB,QAAQ,4BAAyB;AAClE,SAASC,uBAAuB,EAAEC,uBAAuB,QAAQ,4BAAyB;AAU1F,SAASC,cAAc,QAAQ,YAAS;AACxC,SAASC,uBAAuB,QAAQ,oBAAiB","ignoreList":[]}

package/lib/module/storage/schema.js

@@ -0,0 +1,151 @@
+"use strict";
+
+import { GameStorageError, storageError } from "./errors.js";
+import { validateMigrations, validateSchemaId, validateVersion } from "./validation.js";
+import { cloneAndValidatePlainData } from "./serialization.js";
+
+/**
+ * Define a versioned game save schema.
+ *
+ * Id/version/migrations are validated immediately. `createDefault` and
+ * `validate` are stored as-is — they run later per load/save.
+ */
+export function defineGameSave(options) {
+  validateSchemaId(options.id);
+  validateVersion(options.version);
+  if (typeof options.createDefault !== 'function') {
+    throw new GameStorageError('createDefault must be a function', {
+      code: 'INVALID_SCHEMA_ID',
+      schemaId: options.id
+    });
+  }
+  if (typeof options.validate !== 'function') {
+    throw new GameStorageError('validate must be a function', {
+      code: 'VALIDATION_FAILED',
+      schemaId: options.id
+    });
+  }
+  const migrations = options.migrations ?? {};
+  validateMigrations(migrations, options.version);
+
+  // Freeze migrations shallowly — migration functions themselves remain.
+  const frozenMigrations = Object.freeze({
+    ...migrations
+  });
+  const schema = {
+    id: options.id,
+    version: options.version,
+    createDefault: options.createDefault,
+    validate: options.validate,
+    migrations: frozenMigrations
+  };
+  return Object.freeze(schema);
+}
+
+/** Clone/freeze via plain-data path for defaults that are plain; fallback to structured clone for custom validation. */
+function deepFreeze(value) {
+  if (value === null || typeof value !== 'object') return value;
+  // Use storage-style freeze: we already cloned, just deep freeze.
+  const seen = new WeakSet();
+  const freeze = node => {
+    if (node === null || typeof node !== 'object') return;
+    const o = node;
+    if (seen.has(o)) return;
+    seen.add(o);
+    if (Array.isArray(node)) {
+      for (const v of node) freeze(v);
+    } else {
+      for (const v of Object.values(node)) freeze(v);
+    }
+    Object.freeze(node);
+  };
+  freeze(value);
+  return value;
+}
+export function createDefaultData(schema) {
+  const raw = schema.createDefault();
+  // Validate through schema.validate to enforce domain rules and to
+  // ensure we return a newly owned, validated value. If validate does not
+  // clone, we still protect via plain-data clone.
+  try {
+    const validated = schema.validate(raw);
+    // Ensure plain-data safe and frozen
+    const cloned = cloneAndValidatePlainData(validated, 'createDefault() result');
+    return deepFreeze(cloned);
+  } catch (cause) {
+    if (cause instanceof GameStorageError) throw cause;
+    throw storageError(`createDefault() validation failed`, 'VALIDATION_FAILED', {
+      schemaId: schema.id,
+      schemaVersion: schema.version,
+      cause
+    });
+  }
+}
+export function validateCurrentData(schema, value, path = 'data') {
+  try {
+    const validated = schema.validate(value);
+    const cloned = cloneAndValidatePlainData(validated, path);
+    return deepFreeze(cloned);
+  } catch (cause) {
+    if (cause instanceof GameStorageError) throw cause;
+    // Preserve original validation error as cause; surface as VALIDATION_FAILED with path if available
+    const msg = cause instanceof Error ? cause.message : String(cause);
+    throw storageError(msg, 'VALIDATION_FAILED', {
+      schemaId: schema.id,
+      schemaVersion: schema.version,
+      path,
+      cause
+    });
+  }
+}
+export function migratePayload(schema, storedVersion, payload) {
+  let current = payload;
+  let version = storedVersion;
+  const target = schema.version;
+  if (version > target) {
+    throw storageError(`stored version ${version} is newer than schema version ${target}`, 'FUTURE_VERSION', {
+      schemaId: schema.id,
+      schemaVersion: target
+    });
+  }
+  if (version === target) return {
+    data: current,
+    fromVersion: version,
+    toVersion: target
+  };
+  // Sequential migrations version -> version+1
+  for (let v = version; v < target; v += 1) {
+    const fn = schema.migrations[v];
+    if (typeof fn !== 'function') {
+      throw storageError(`missing migration for version ${v} -> ${v + 1}`, 'MISSING_MIGRATION', {
+        schemaId: schema.id,
+        schemaVersion: target,
+        path: `migrations.${v}`
+      });
+    }
+    try {
+      // Engine-owned deeply frozen input — migration must be pure and cannot mutate it.
+      const frozenInput = deepFreeze(cloneAndValidatePlainData(current, `migrations.${v} input`));
+      const output = fn(frozenInput);
+      // Bounded-clone and freeze every migration output before the next step, so oversized/deep/unsupported intermediates are rejected at the step.
+      const clonedOutput = cloneAndValidatePlainData(output, `migrations.${v} output`);
+      deepFreeze(clonedOutput);
+      current = clonedOutput;
+      version = v + 1;
+    } catch (cause) {
+      if (cause instanceof GameStorageError) throw cause;
+      throw storageError(`migration ${v} -> ${v + 1} failed`, 'MIGRATION_FAILED', {
+        schemaId: schema.id,
+        schemaVersion: target,
+        path: `migrations.${v}`,
+        cause
+      });
+    }
+  }
+  return {
+    data: current,
+    fromVersion: storedVersion,
+    toVersion: target
+  };
+}
+//# sourceMappingURL=schema.js.map

package/lib/module/storage/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["GameStorageError","storageError","validateMigrations","validateSchemaId","validateVersion","cloneAndValidatePlainData","defineGameSave","options","id","version","createDefault","code","schemaId","validate","migrations","frozenMigrations","Object","freeze","schema","deepFreeze","value","seen","WeakSet","node","o","has","add","Array","isArray","v","values","createDefaultData","raw","validated","cloned","cause","schemaVersion","validateCurrentData","path","msg","Error","message","String","migratePayload","storedVersion","payload","current","target","data","fromVersion","toVersion","fn","frozenInput","output","clonedOutput"],"sourceRoot":"../../../src","sources":["storage/schema.ts"],"mappings":"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","ignoreList":[]}