rn-gamekit 0.1.0 → 0.2.1

package/src/scene/defineScene.ts

@@ -1,9 +1,27 @@
+import type { GameEventDescriptor, InferGameEventMap } from '../events/types';
 import type { SceneDefinition } from './types';
 
 /**
  * Define a synchronous functional scene while inferring its state, snapshot,
  * action, and transition types.
  *
+ * To get typed event emission in a standalone scene, pass the same
+ * `events` object that will be passed to `defineGame({ events })`:
+ *
+ * ```ts
+ * const events = defineGameEvents({ 'brick-hit': gameEvent<{ id: string }>() });
+ * const play = defineScene({
+ *   actions: ['primary'],
+ *   emits: ['brick-hit'],
+ *   events,
+ *   update: ({ events }) => {
+ *     events.emit('brick-hit', { id: '1' }); // typed, wrong payload fails
+ *   },
+ *   // ...
+ * });
+ * const game = defineGame({ events, scenes: { play }, initialScene: 'play' });
+ * ```
+ *
  * @example
  * ```ts
  * const ready = defineScene({
@@ -25,14 +43,38 @@ export function defineScene<
   TState,
   TSnapshot,
   const TTransitions extends readonly string[] = [],
+  const TEmits extends readonly (keyof InferGameEventMap<TEventDefs> & string)[] = [],
+  const TEventDefs extends Record<string, GameEventDescriptor<unknown>> = Record<string, never>,
 >(
   definition: Omit<
-    SceneDefinition<TState, TSnapshot, TActions[number], TTransitions[number]>,
-    'kind' | '__actionType' | '__transitionType' | '__snapshotType' | 'actions' | 'transitions'
-  > & { readonly actions: TActions; readonly transitions?: TTransitions },
-): SceneDefinition<TState, TSnapshot, TActions[number], TTransitions[number]> {
+    SceneDefinition<
+      TState,
+      TSnapshot,
+      TActions[number],
+      TTransitions[number],
+      TEmits[number],
+      TEventDefs
+    >,
+    | 'kind'
+    | '__actionType'
+    | '__transitionType'
+    | '__snapshotType'
+    | '__emitType'
+    | '__eventMapType'
+    | '__eventDefsType'
+    | 'actions'
+    | 'transitions'
+    | 'emits'
+    | 'events'
+  > & {
+    readonly actions: TActions;
+    readonly transitions?: TTransitions;
+    readonly emits?: TEmits;
+    readonly events?: TEventDefs;
+  },
+): SceneDefinition<TState, TSnapshot, TActions[number], TTransitions[number], TEmits[number], TEventDefs> {
   return {
     kind: 'gamekit.scene',
     ...definition,
-  };
+  } as SceneDefinition<TState, TSnapshot, TActions[number], TTransitions[number], TEmits[number], TEventDefs>;
 }

package/src/scene/types.ts

@@ -1,4 +1,9 @@
 import type { InputFrame } from '../core/input/types';
+import type {
+  GameEventDescriptor,
+  GameEventEmitter,
+  InferGameEventMap,
+} from '../events/types';
 
 /**
  * Update-scoped scene transition controls.
@@ -20,13 +25,21 @@ export interface SceneTransitionController<TTransitionName extends string> {
 }
 
 /** Values supplied to a scene for one deterministic simulation tick. */
-export interface SceneUpdate<TState, TActionName extends string, TTransitionName extends string> {
+export interface SceneUpdate<
+  TState,
+  TActionName extends string,
+  TTransitionName extends string,
+  TEventDefs extends Record<string, GameEventDescriptor<unknown>> = Record<string, never>,
+  TEmits extends keyof InferGameEventMap<TEventDefs> & string = keyof InferGameEventMap<TEventDefs> & string,
+> {
   /** The authoritative state produced by the previous tick. */
   readonly state: Readonly<TState>;
   /** One immutable semantic input snapshot for this tick. */
   readonly input: InputFrame<TActionName>;
   /** Update-scoped transition controls restricted to declared targets. */
   readonly transition: SceneTransitionController<TTransitionName>;
+  /** Update-scoped emitter for declared game events (T13). Invalid after the update returns or throws. */
+  readonly events: GameEventEmitter<Pick<InferGameEventMap<TEventDefs>, TEmits>>;
   /** One-based global simulation tick number. */
   readonly tick: number;
   /** One-based tick number within the current scene instance. */
@@ -51,6 +64,8 @@ export interface SceneDefinition<
   TSnapshot,
   TActionName extends string = never,
   TTransitionName extends string = never,
+  TEmits extends string = never,
+  TEventDefs extends Record<string, GameEventDescriptor<unknown>> = Record<string, never>,
 > {
   /** Internal scene-definition discriminator. */
   readonly kind: 'gamekit.scene';
@@ -60,15 +75,34 @@ export interface SceneDefinition<
   readonly __actionType?: TActionName;
   /** @internal Type witness used to validate scene transition targets. */
   readonly __transitionType?: TTransitionName;
+  /** @internal Type witness for emitted event names. */
+  readonly __emitType?: TEmits;
+  /** @internal Type witness for the game event map. */
+  readonly __eventMapType?: InferGameEventMap<TEventDefs>;
+  /** @internal Type witness for the branded event definitions identity. */
+  readonly __eventDefsType?: TEventDefs;
   /** Semantic input actions this scene may read. */
   readonly actions: readonly TActionName[];
   /** Declared scene names this scene may transition to. */
   readonly transitions?: readonly TTransitionName[];
+  /** Declared event names this scene may emit (subset of the game's event map). */
+  readonly emits?: readonly TEmits[];
+  /** The branded event definitions this scene is bound to (for standalone type safety). */
+  readonly events?: TEventDefs;
   /** Create the scene's initial authoritative state. */
   readonly create: () => TState;
   /** Produce the next state for one fixed simulation tick. */
-  readonly update: (frame: SceneUpdate<TState, TActionName, TTransitionName>) => TState;
-  /** Extract a compact renderer-specific snapshot from current state. */
+  readonly update: (
+    frame: SceneUpdate<TState, TActionName, TTransitionName, TEventDefs, TEmits>,
+  ) => TState;
+  /**
+   * Extract a compact renderer-specific snapshot from current state.
+   *
+   * The snapshot domain is plain records, arrays, and scalars; anything
+   * else fails with a `SnapshotDomainError` carrying the key path before
+   * publication. Returning a state reference transfers it into immutable
+   * snapshot ownership — it is frozen in place.
+   */
   readonly snapshot: (context: SceneSnapshotContext<TState>) => TSnapshot;
   /** Release scene-owned resources exactly once. */
   readonly dispose?: (state: Readonly<TState>) => void;

package/src/sprites/sampleSpriteClip.ts

@@ -4,28 +4,65 @@
  * 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).
  */
 import type { SpriteClip } from '../assets/types';
 
+/** Reject elapsed values the sampler cannot define a frame for. */
+function assertFiniteElapsed(elapsedMs: number): void {
+  '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: SpriteClip): number {
+  '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: SpriteClip,
-  elapsedMs: number,
-): number {
+export function sampleSpriteClipFrame(clip: SpriteClip, elapsedMs: number): number {
   '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;
 }
 
@@ -33,15 +70,11 @@ export function sampleSpriteClipFrame(
  * The frame NAME selected for `elapsedMs` of playback (the ordered frame
  * references of the clip).
  */
-export function sampleSpriteClipFrameName(
-  clip: SpriteClip,
-  elapsedMs: number,
-): string {
+export function sampleSpriteClipFrameName(clip: SpriteClip, elapsedMs: number): string {
   'worklet';
   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). */
@@ -49,3 +82,38 @@ export function spriteClipDurationMs(clip: SpriteClip): number {
   'worklet';
   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: Readonly<
+    Record<
+      string,
+      {
+        readonly frames: readonly string[];
+        readonly frameDurationMs: number;
+        readonly mode: 'loop' | 'once';
+      }
+    >
+  >,
+  clip: string,
+  elapsedMs: number,
+): string {
+  '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;
+}

package/src/sprites/spriteAnimationState.ts

@@ -8,6 +8,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
@@ -54,7 +61,6 @@ function clipOf(
   descriptor: SpriteSheetDescriptor,
   clip: string,
 ): SpriteSheetDescriptor['animations'][string] {
-  'worklet';
   const animation = descriptor.animations[clip];
   if (animation === undefined) {
     throw new GameAssetError(
@@ -67,16 +73,14 @@ function clipOf(
 }
 
 /**
- * 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<TClipName extends string>(
-  descriptor: SpriteSheetDescriptor,
-  clip: TClipName,
-): SpriteAnimationState<TClipName> {
-  'worklet';
+export function startSpriteAnimation<TDescriptor extends SpriteSheetDescriptor>(
+  descriptor: TDescriptor,
+  clip: SpriteClipNames<TDescriptor>,
+): SpriteAnimationState<SpriteClipNames<TDescriptor>> {
   clipOf(descriptor, clip);
   return {
     clip,
@@ -94,12 +98,14 @@ export function startSpriteAnimation<TClipName extends string>(
  * clearly. Loop clips keep their elapsed time bounded within one timeline
  * (modulo), so arbitrarily large deltas cost constant arithmetic.
  */
-export function advanceSpriteAnimation<TClipName extends string>(
-  descriptor: SpriteSheetDescriptor,
-  state: SpriteAnimationState<TClipName>,
+export function advanceSpriteAnimation<
+  TDescriptor extends SpriteSheetDescriptor,
+  TClip extends SpriteClipNames<TDescriptor>,
+>(
+  descriptor: TDescriptor,
+  state: SpriteAnimationState<TClip>,
   deltaSeconds: number,
-): SpriteAnimationState<TClipName> {
-  'worklet';
+): SpriteAnimationState<TClip> {
   assertFiniteDelta(deltaSeconds);
   if (state.paused || state.completed) {
     return state;
@@ -122,12 +128,14 @@ export function advanceSpriteAnimation<TClipName extends string>(
  * Switch playback to `clip`, restarting it from the beginning. The clip
  * name is typed against the descriptor's animation table.
  */
-export function playSpriteAnimation<TClipName extends string>(
-  descriptor: SpriteSheetDescriptor,
-  state: SpriteAnimationState<TClipName>,
-  clip: TClipName,
-): SpriteAnimationState<TClipName> {
-  'worklet';
+export function playSpriteAnimation<
+  TDescriptor extends SpriteSheetDescriptor,
+  TClip extends SpriteClipNames<TDescriptor>,
+>(
+  descriptor: TDescriptor,
+  state: SpriteAnimationState<TClip>,
+  clip: SpriteClipNames<TDescriptor>,
+): SpriteAnimationState<SpriteClipNames<TDescriptor>> {
   if (clip === state.clip) {
     return state;
   }
@@ -145,7 +153,6 @@ export function playSpriteAnimation<TClipName extends string>(
 export function pauseSpriteAnimation<TClipName extends string>(
   state: SpriteAnimationState<TClipName>,
 ): SpriteAnimationState<TClipName> {
-  'worklet';
   return state.paused ? state : { ...state, paused: true };
 }
 
@@ -153,7 +160,6 @@ export function pauseSpriteAnimation<TClipName extends string>(
 export function resumeSpriteAnimation<TClipName extends string>(
   state: SpriteAnimationState<TClipName>,
 ): SpriteAnimationState<TClipName> {
-  'worklet';
   return state.paused ? { ...state, paused: false } : state;
 }
 
@@ -161,7 +167,6 @@ export function resumeSpriteAnimation<TClipName extends string>(
 export function resetSpriteAnimation<TClipName extends string>(
   state: SpriteAnimationState<TClipName>,
 ): SpriteAnimationState<TClipName> {
-  'worklet';
   return { ...state, elapsedMs: 0, completed: false };
 }
 
@@ -170,7 +175,6 @@ export function setSpriteAnimationSpeed<TClipName extends string>(
   state: SpriteAnimationState<TClipName>,
   speed: number,
 ): SpriteAnimationState<TClipName> {
-  'worklet';
   assertFinitePositiveSpeed(speed);
   return state.speed === speed ? state : { ...state, speed };
 }

package/src/sprites.ts

@@ -0,0 +1,22 @@
+/**
+ * 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';
+export {
+  advanceSpriteAnimation,
+  pauseSpriteAnimation,
+  playSpriteAnimation,
+  resetSpriteAnimation,
+  resumeSpriteAnimation,
+  setSpriteAnimationSpeed,
+  startSpriteAnimation,
+} from './sprites/spriteAnimationState';
+export type { SpriteAnimationState, SpriteClipNames } from './sprites/spriteAnimationState';

package/src/storage/adapters/asyncStorage.ts

@@ -0,0 +1,77 @@
+import type { GameStorageAdapter } from '../types';
+import { GameStorageError } from '../errors';
+
+export type LoadedAsyncStorage = {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+  removeItem(key: string): Promise<void>;
+};
+
+type Loader = () => Promise<LoadedAsyncStorage>;
+let loader: Loader | null = null;
+
+export function __setAsyncStorageLoader(fn: Loader | null): void {
+  loader = fn;
+}
+
+export function __getAsyncStorageLoader(): Loader | null {
+  return loader;
+}
+
+async function loadAsyncStorage(): Promise<LoadedAsyncStorage> {
+  if (loader) return loader();
+  try {
+    const mod = (await import('@react-native-async-storage/async-storage')) as unknown as {
+      default?: LoadedAsyncStorage;
+    } & LoadedAsyncStorage;
+    const resolved: LoadedAsyncStorage | undefined =
+      (mod as LoadedAsyncStorage).getItem !== undefined
+        ? (mod as LoadedAsyncStorage)
+        : 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(): GameStorageAdapter {
+  let cached: LoadedAsyncStorage | null = null;
+  const get = async (): Promise<LoadedAsyncStorage> => {
+    if (cached) return cached;
+    cached = await loadAsyncStorage();
+    return cached;
+  };
+
+  return {
+    async read(key: string): Promise<string | undefined> {
+      const storage = await get();
+      const value = await storage.getItem(key);
+      return value === null ? undefined : value;
+    },
+    async write(key: string, value: string): Promise<void> {
+      const storage = await get();
+      await storage.setItem(key, value);
+    },
+    async remove(key: string): Promise<void> {
+      const storage = await get();
+      await storage.removeItem(key);
+    },
+  };
+}

package/src/storage/adapters/memory.ts

@@ -0,0 +1,58 @@
+import type { GameStorageAdapter } from '../types';
+
+/**
+ * In-memory adapter for tests and apps that own storage elsewhere.
+ * Each instance owns its map.
+ */
+export function createMemoryStorageAdapter(initial?: Record<string, string>): GameStorageAdapter {
+  const map = new Map<string, string>(initial ? Object.entries(initial) : []);
+
+  return {
+    async read(key: string): Promise<string | undefined> {
+      return map.get(key);
+    },
+    async write(key: string, value: string): Promise<void> {
+      map.set(key, value);
+    },
+    async remove(key: string): Promise<void> {
+      map.delete(key);
+    },
+  };
+}
+
+/**
+ * Programmable failure adapter for tests — wraps another adapter and injects failures.
+ */
+export function createFailingStorageAdapter(
+  inner: GameStorageAdapter,
+  opts: {
+    failRead?: (key: string) => Error | null;
+    failWrite?: (key: string, value: string) => Error | null;
+    failRemove?: (key: string) => Error | null;
+    delayMs?: number;
+  } = {},
+): GameStorageAdapter {
+  const delay = async (): Promise<void> => {
+    if (opts.delayMs) await new Promise((r) => setTimeout(r, opts.delayMs));
+  };
+  return {
+    async read(key: string): Promise<string | undefined> {
+      await delay();
+      const err = opts.failRead?.(key) ?? null;
+      if (err) throw err;
+      return inner.read(key);
+    },
+    async write(key: string, value: string): Promise<void> {
+      await delay();
+      const err = opts.failWrite?.(key, value) ?? null;
+      if (err) throw err;
+      return inner.write(key, value);
+    },
+    async remove(key: string): Promise<void> {
+      await delay();
+      const err = opts.failRemove?.(key) ?? null;
+      if (err) throw err;
+      return inner.remove(key);
+    },
+  };
+}

package/src/storage/errors.ts

@@ -0,0 +1,88 @@
+/**
+ * V1 storage errors — stable codes, operation, namespace/slot, schema context,
+ * exact path where relevant, and original cause.
+ */
+export type GameStorageErrorCode =
+  | 'INVALID_NAMESPACE'
+  | 'INVALID_SLOT'
+  | 'INVALID_SCHEMA_ID'
+  | 'INVALID_SCHEMA_VERSION'
+  | 'INVALID_MIGRATION'
+  | 'UNSUPPORTED_VALUE'
+  | 'SERIALIZATION_FAILED'
+  | 'SIZE_EXCEEDED'
+  | 'DEPTH_EXCEEDED'
+  | 'BACKEND_READ_FAILED'
+  | 'BACKEND_WRITE_FAILED'
+  | 'BACKEND_REMOVE_FAILED'
+  | 'CORRUPT_ENVELOPE'
+  | 'SCHEMA_ID_MISMATCH'
+  | 'FUTURE_VERSION'
+  | 'MISSING_MIGRATION'
+  | 'MIGRATION_FAILED'
+  | 'VALIDATION_FAILED'
+  | 'DISPOSED';
+
+export type GameStorageOperation = 'load' | 'save' | 'remove' | 'delete' | 'flush' | 'dispose' | 'validate' | 'migrate' | 'serialize' | 'parse';
+
+export class GameStorageError extends Error {
+  override readonly name = 'GameStorageError';
+
+  readonly code: GameStorageErrorCode;
+  readonly operation: GameStorageOperation | undefined;
+  readonly namespace: string | undefined;
+  readonly slot: string | undefined;
+  readonly schemaId: string | undefined;
+  readonly schemaVersion: number | undefined;
+  readonly path: string | undefined;
+  override readonly cause: unknown | undefined;
+
+  constructor(
+    message: string,
+    options: {
+      code: GameStorageErrorCode;
+      operation?: GameStorageOperation | undefined;
+      namespace?: string | undefined;
+      slot?: string | undefined;
+      schemaId?: string | undefined;
+      schemaVersion?: number | undefined;
+      path?: string | undefined;
+      cause?: unknown | undefined;
+    },
+  ) {
+    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: string,
+  code: GameStorageErrorCode,
+  opts: {
+    operation?: GameStorageOperation | undefined;
+    namespace?: string | undefined;
+    slot?: string | undefined;
+    schemaId?: string | undefined;
+    schemaVersion?: number | undefined;
+    path?: string | undefined;
+    cause?: unknown | undefined;
+  } = {},
+): GameStorageError {
+  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,
+  });
+}

package/src/storage/index.ts

@@ -0,0 +1,18 @@
+export { GameStorageError } from './errors';
+export type { GameStorageErrorCode, GameStorageOperation } from './errors';
+export { defineGameSave } from './schema';
+export { createGameSaveStore } from './store';
+export { createMemoryStorageAdapter } from './adapters/memory';
+export { createGameStorageAdapter } from './adapters/asyncStorage';
+export { __setAsyncStorageLoader, __getAsyncStorageLoader } from './adapters/asyncStorage';
+export type {
+  GameSaveSchema,
+  GameStorageAdapter,
+  StoredGameEnvelope,
+  GameSaveLoadResult,
+  GameSaveLoadStatus,
+  CreateGameSaveStoreOptions,
+  GameSaveStore,
+} from './types';
+export { STORAGE_LIMITS } from './types';
+export { STORAGE_ENVELOPE_FORMAT } from './serialization';