rn-gamekit 0.1.0

package/src/assets/defineAssets.ts

@@ -0,0 +1,62 @@
+/**
+ * Asset definition helpers (T7.2).
+ *
+ * `image(...)` and `spriteSheet(...)` build immutable descriptors;
+ * `defineAssets(...)` groups them into a deeply immutable typed manifest.
+ * Definition performs no I/O and allocates no native handle.
+ */
+import { createDeepFreeze } from '../core/session/deepFreeze';
+import { validateImageSource, validateManifest, validateSpriteSheet } from './validation';
+import type {
+  AssetGroupMap,
+  GameAssetManifest,
+  ImageDescriptor,
+  SpriteClip,
+  SpriteFrameRect,
+  SpriteSheetDescriptor,
+} from './types';
+
+/** Declare a single full-image asset from a static module handle. */
+export function image(source: number): ImageDescriptor {
+  validateImageSource(source);
+  return Object.freeze({ kind: 'image', source });
+}
+
+/**
+ * Declare a sprite-sheet asset: named source frames plus named animation
+ * clips. Frame and clip names are preserved as string literals; clip frame
+ * references are restricted to the declared frames.
+ */
+export function spriteSheet<
+  TFrames extends Record<string, SpriteFrameRect>,
+  TClips extends Record<string, SpriteClip<Extract<keyof TFrames, string>>>,
+>(
+  source: number,
+  spec: {
+    readonly frames: TFrames;
+    readonly animations: TClips;
+  },
+): SpriteSheetDescriptor<TFrames, TClips> {
+  validateSpriteSheet(source, spec);
+  const freezer = createDeepFreeze();
+  return freezer({
+    kind: 'sprite-sheet',
+    source,
+    frames: spec.frames,
+    animations: spec.animations,
+  }) as SpriteSheetDescriptor<TFrames, TClips>;
+}
+
+/**
+ * Declare the game's asset manifest: a deeply immutable, fully typed group
+ * map. Group, asset, frame, and clip names are preserved as string literals
+ * and every descriptor is branded with the manifest type so lookups stay
+ * typed. Allocates no native resources and performs no I/O.
+ */
+export function defineAssets<TGroups extends AssetGroupMap>(
+  groups: TGroups,
+): GameAssetManifest<TGroups> {
+  validateManifest(groups);
+  const freezer = createDeepFreeze();
+  return freezer(groups) as GameAssetManifest<TGroups>;
+}

package/src/assets/errors.ts

@@ -0,0 +1,64 @@
+/**
+ * Structured asset errors (T7.2).
+ *
+ * Every definition/loading failure carries a stable machine-readable code
+ * and the field path that caused it. Paths are documented in the public
+ * error reference; messages never embed machine-specific paths.
+ */
+
+/** Stable error codes for asset definition and loading. */
+export type GameAssetErrorCode =
+  | 'ASSET_INVALID_IDENTIFIER'
+  | 'ASSET_INVALID_SOURCE'
+  | 'ASSET_INVALID_FRAME_RECT'
+  | 'ASSET_EMPTY_CLIP'
+  | 'ASSET_UNKNOWN_FRAME'
+  | 'ASSET_UNKNOWN_CLIP'
+  | 'ASSET_INVALID_DURATION'
+  | 'ASSET_INVALID_MODE'
+  | 'ASSET_UNSUPPORTED_SOURCE'
+  | 'ASSET_UNKNOWN_GROUP'
+  | 'ASSET_UNKNOWN_ASSET'
+  | 'ASSET_RESOLVE_FAILED'
+  | 'ASSET_DECODE_FAILED'
+  | 'ASSET_FRAME_OUT_OF_BOUNDS'
+  | 'ASSET_ABORTED'
+  | 'ASSET_STORE_DISPOSED';
+
+/** A structured asset definition or loading failure. */
+export class GameAssetError extends Error {
+  /** Stable machine-readable code. */
+  readonly code: GameAssetErrorCode;
+  /** Field path within the manifest/descriptor that caused the failure. */
+  readonly path: readonly string[];
+
+  constructor(code: GameAssetErrorCode, path: readonly string[], message: string) {
+    super(`${code}${path.length > 0 ? ` at ${path.join('.')}` : ''}: ${message}`);
+    this.name = 'GameAssetError';
+    this.code = code;
+    this.path = path;
+  }
+}
+
+/** Throw when a definition-time identifier is invalid. */
+export function assertValidIdentifier(
+  path: readonly string[],
+  value: string,
+): void {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new GameAssetError(
+      'ASSET_INVALID_IDENTIFIER',
+      path,
+      'identifiers must be non-empty strings',
+    );
+  }
+  // '/' is the diagnostic-id separator (group/key); reserving it keeps
+  // diagnostic ids unambiguous.
+  if (value.includes('/')) {
+    throw new GameAssetError(
+      'ASSET_INVALID_IDENTIFIER',
+      path,
+      `identifier ${JSON.stringify(value)} contains the reserved separator '/'`,
+    );
+  }
+}

package/src/assets/types.ts

@@ -0,0 +1,164 @@
+/**
+ * Asset descriptor and manifest types (T7.2).
+ *
+ * The manifest is the static, deeply immutable declaration of a game's local
+ * assets. Group, asset, frame, and clip names are preserved as string
+ * literals; retrieval goes through typed descriptor references, never
+ * duplicated strings. Sources are static module handles (`number` from
+ * `require(...)`) only — string/URL sources are rejected at the type
+ * boundary and deliberately have no runtime branch.
+ */
+
+/** Static React Native module handle returned by `require(...)`. */
+export type AssetSourceHandle = number;
+
+/** A single full-image asset. */
+export interface ImageDescriptor {
+  /** Discriminant. */
+  readonly kind: 'image';
+  /** Static module handle. */
+  readonly source: AssetSourceHandle;
+}
+
+/** A named rectangle inside a sprite sheet, in source pixels. */
+export interface SpriteFrameRect {
+  /** Left edge in source pixels; non-negative finite number. */
+  readonly x: number;
+  /** Top edge in source pixels; non-negative finite number. */
+  readonly y: number;
+  /** Width in source pixels; greater than zero. */
+  readonly width: number;
+  /** Height in source pixels; greater than zero. */
+  readonly height: number;
+}
+
+/** Clip playback mode: looping or one-shot. */
+export type SpriteAnimationMode = 'loop' | 'once';
+
+/**
+ * A named animation clip over a sprite sheet's frames.
+ *
+ * Frame references are restricted to the sheet's declared frame names and
+ * durations are uniform per clip in this version (per-frame durations are
+ * deferred so precedence cannot be misunderstood).
+ */
+export interface SpriteClip<TFrameName extends string = string> {
+  /** Ordered frame references; at least one, all declared on the sheet. */
+  readonly frames: readonly TFrameName[];
+  /** Uniform per-frame duration in milliseconds; finite and greater than zero. */
+  readonly frameDurationMs: number;
+  /** Discriminated playback mode. */
+  readonly mode: SpriteAnimationMode;
+}
+
+/** A sprite-sheet asset: named frames plus named animation clips. */
+export interface SpriteSheetDescriptor<
+  TFrames extends Record<string, SpriteFrameRect> = Record<string, SpriteFrameRect>,
+  TClips extends Record<string, SpriteClip<Extract<keyof TFrames, string>>> = Record<
+    string,
+    SpriteClip<Extract<keyof TFrames, string>>
+  >,
+> {
+  /** Discriminant. */
+  readonly kind: 'sprite-sheet';
+  /** Static module handle. */
+  readonly source: AssetSourceHandle;
+  /** Named source rectangles. */
+  readonly frames: TFrames;
+  /** Named animation clips restricted to the declared frames. */
+  readonly animations: TClips;
+}
+
+/** Union of all asset descriptors. */
+export type AssetDescriptor = ImageDescriptor | SpriteSheetDescriptor;
+
+/** A group of named asset descriptors. */
+export type AssetGroup = Readonly<Record<string, AssetDescriptor>>;
+
+/** The author-facing group map accepted by `defineAssets`. */
+export type AssetGroupMap = Readonly<Record<string, AssetGroup>>;
+
+/**
+ * Type-level manifest brand. Every descriptor of a manifest carries a
+ * phantom reference to its originating manifest type, so a loaded store can
+ * reject descriptors from any other manifest at compile time.
+ */
+declare const manifestBrand: unique symbol;
+
+export type BrandedAssetDescriptor<
+  TManifest,
+  TDescriptor extends AssetDescriptor,
+> = { readonly [manifestBrand]?: TManifest } & TDescriptor;
+
+/**
+ * The deeply immutable manifest produced by `defineAssets`.
+ *
+ * Groups and assets keep their literal names; every descriptor is branded
+ * with the manifest type so lookups stay typed.
+ */
+export type GameAssetManifest<TGroups extends AssetGroupMap = AssetGroupMap> = {
+  readonly [TGroup in keyof TGroups]: {
+    readonly [TAsset in keyof TGroups[TGroup]]: BrandedAssetDescriptor<
+      GameAssetManifest<TGroups>,
+      TGroups[TGroup][TAsset]
+    >;
+  };
+};
+
+/** The manifest type of a descriptor's originating manifest. */
+export type ManifestOf<TDescriptor> =
+  TDescriptor extends { readonly [manifestBrand]?: infer TManifest } ? TManifest : never;
+
+/** Loaded-asset lookup keyed by typed descriptor reference.
+ *
+ * v1 semantics (R9): lookup is descriptor-REFERENCE membership — the exact
+ * descriptor object declared by the manifest. The compile-time brand is
+ * structural, so identically shaped manifests are not nominally distinct;
+ * the runtime reference check is the guarantee, and the type layer still
+ * rejects duplicated string keys and descriptors from differently shaped
+ * manifests.
+ */
+export interface LoadedAssets<TManifest> {
+  /** The manifest this store was created from. */
+  readonly manifest: TManifest;
+  /** Retrieve a loaded asset by its typed descriptor reference. */
+  readonly get: <TDescriptor extends AssetDescriptor>(
+    descriptor: BrandedAssetDescriptor<TManifest, TDescriptor>,
+  ) => TDescriptor extends { readonly kind: 'sprite-sheet' }
+    ? LoadedSpriteSheet
+    : LoadedImage;
+}
+
+/** A ready full-image resource. */
+export interface LoadedImage {
+  /** Logical descriptor this resource was loaded for. */
+  readonly descriptor: ImageDescriptor;
+  /** Decoded source width in pixels. */
+  readonly width: number;
+  /** Decoded source height in pixels. */
+  readonly height: number;
+  /** The decoded image handle (Skia's SkImage satisfies this structurally). */
+  readonly image: unknown;
+}
+
+/** A ready sprite-sheet resource with validated frame rectangles. */
+export interface LoadedSpriteSheet {
+  /** Logical descriptor this resource was loaded for. */
+  readonly descriptor: SpriteSheetDescriptor;
+  /** Validated frames in source pixels (offsets against the decoded image). */
+  readonly frames: Readonly<Record<string, SpriteFrameRect>>;
+  /** Decoded source width in pixels. */
+  readonly width: number;
+  /** Decoded source height in pixels. */
+  readonly height: number;
+  /** The decoded image handle (Skia's SkImage satisfies this structurally). */
+  readonly image: unknown;
+}
+
+/** A ready, typed, caller-owned lease over loaded asset groups. */
+export interface GameAssetLease<TManifest> {
+  /** Typed lookup; rejects descriptors from other manifests. */
+  readonly assets: LoadedAssets<TManifest>;
+  /** Release this lease; idempotent; the final release disposes the image. */
+  readonly dispose: () => void;
+}

package/src/assets/validation.ts

@@ -0,0 +1,158 @@
+/**
+ * Manifest validation (T7.2).
+ *
+ * Everything knowable before decoding is validated here with stable error
+ * codes and field paths. Rectangles are additionally validated against the
+ * decoded image dimensions after load (T7.4).
+ */
+import { GameAssetError, assertValidIdentifier } from './errors';
+import type {
+  AssetGroupMap,
+  SpriteClip,
+  SpriteFrameRect,
+  SpriteSheetDescriptor,
+} from './types';
+
+/** Validate one frame rectangle. */
+export function validateFrameRect(
+  path: readonly string[],
+  name: string,
+  rect: SpriteFrameRect,
+): void {
+  assertValidIdentifier(path, name);
+  const { x, y, width, height } = rect;
+  const values = [x, y, width, height] as const;
+  for (const value of values) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+      throw new GameAssetError(
+        'ASSET_INVALID_FRAME_RECT',
+        path,
+        `frame ${JSON.stringify(name)} coordinates must be finite numbers`,
+      );
+    }
+  }
+  if (x < 0 || y < 0) {
+    throw new GameAssetError(
+      'ASSET_INVALID_FRAME_RECT',
+      path,
+      `frame ${JSON.stringify(name)} x/y must be non-negative`,
+    );
+  }
+  if (width <= 0 || height <= 0) {
+    throw new GameAssetError(
+      'ASSET_INVALID_FRAME_RECT',
+      path,
+      `frame ${JSON.stringify(name)} width/height must be greater than zero`,
+    );
+  }
+}
+
+/** Validate one animation clip against the sheet's declared frames. */
+export function validateClip(
+  path: readonly string[],
+  name: string,
+  clip: SpriteClip,
+  frames: Readonly<Record<string, SpriteFrameRect>>,
+): void {
+  assertValidIdentifier(path, name);
+  if (typeof clip.frames !== 'object' || clip.frames.length === 0) {
+    throw new GameAssetError(
+      'ASSET_EMPTY_CLIP',
+      path,
+      `clip ${JSON.stringify(name)} must reference at least one frame`,
+    );
+  }
+  for (const frame of clip.frames) {
+    if (typeof frame !== 'string' || !(frame in frames)) {
+      throw new GameAssetError(
+        'ASSET_UNKNOWN_FRAME',
+        [...path, 'frames'],
+        `clip ${JSON.stringify(name)} references unknown frame ${JSON.stringify(frame)}`,
+      );
+    }
+  }
+  const duration = clip.frameDurationMs;
+  if (typeof duration !== 'number' || !Number.isFinite(duration) || duration <= 0) {
+    throw new GameAssetError(
+      'ASSET_INVALID_DURATION',
+      [...path, 'frameDurationMs'],
+      `clip ${JSON.stringify(name)} duration must be finite and greater than zero`,
+    );
+  }
+  if (clip.mode !== 'loop' && clip.mode !== 'once') {
+    throw new GameAssetError(
+      'ASSET_INVALID_MODE',
+      [...path, 'mode'],
+      `clip ${JSON.stringify(name)} mode must be 'loop' or 'once'`,
+    );
+  }
+}
+
+/** Validate a full sprite-sheet descriptor. */
+export function validateSpriteSheet(
+  source: unknown,
+  spec: { readonly frames: Readonly<Record<string, SpriteFrameRect>>; readonly animations: Readonly<Record<string, SpriteClip>> },
+): void {
+  if (typeof source !== 'number' || !Number.isInteger(source) || source < 0) {
+    throw new GameAssetError(
+      'ASSET_INVALID_SOURCE',
+      [],
+      'sprite-sheet source must be a static module handle (number)',
+    );
+  }
+  for (const [name, rect] of Object.entries(spec.frames)) {
+    validateFrameRect(['frames', name], name, rect);
+  }
+  for (const [name, clip] of Object.entries(spec.animations)) {
+    validateClip(['animations', name], name, clip, spec.frames);
+  }
+}
+
+/** Validate an image descriptor's source. */
+export function validateImageSource(source: unknown): void {
+  if (typeof source !== 'number' || !Number.isInteger(source) || source < 0) {
+    throw new GameAssetError(
+      'ASSET_INVALID_SOURCE',
+      [],
+      'image source must be a static module handle (number)',
+    );
+  }
+}
+
+/** Validate a full asset manifest. */
+export function validateManifest(manifest: AssetGroupMap): void {
+  for (const [group, assets] of Object.entries(manifest)) {
+    const groupPath = [group];
+    assertValidIdentifier([], group);
+    if (typeof assets !== 'object' || assets === null) {
+      throw new GameAssetError(
+        'ASSET_INVALID_IDENTIFIER',
+        groupPath,
+        `group ${JSON.stringify(group)} must be an object of named assets`,
+      );
+    }
+    for (const [name, descriptor] of Object.entries(assets)) {
+      const path = [...groupPath, name];
+      assertValidIdentifier(groupPath, name);
+      if (descriptor === null || typeof descriptor !== 'object') {
+        throw new GameAssetError(
+          'ASSET_INVALID_IDENTIFIER',
+          path,
+          `asset ${JSON.stringify(name)} must be a descriptor`,
+        );
+      }
+      if ((descriptor as { readonly kind?: unknown }).kind === 'image') {
+        validateImageSource((descriptor as { readonly source?: unknown }).source);
+      } else if ((descriptor as { readonly kind?: unknown }).kind === 'sprite-sheet') {
+        const sheet = descriptor as unknown as SpriteSheetDescriptor;
+        validateSpriteSheet(sheet.source, sheet);
+      } else {
+        throw new GameAssetError(
+          'ASSET_INVALID_IDENTIFIER',
+          path,
+          `asset ${JSON.stringify(name)} has unknown descriptor kind`,
+        );
+      }
+    }
+  }
+}

package/src/core/frameDriver.ts

@@ -0,0 +1,31 @@
+/** Opaque handle returned by an animation-frame driver. */
+export type FrameHandle = number;
+
+/** Minimal presentation clock used by the fixed-step runtime. */
+export interface FrameDriver {
+  /** Request the next presentation callback. */
+  requestFrame(callback: (timestampMs: number) => void): FrameHandle;
+  /** Cancel a previously requested callback. */
+  cancelFrame(handle: FrameHandle): void;
+}
+
+interface AnimationFrameHost {
+  requestAnimationFrame(callback: (timestampMs: number) => void): number;
+  cancelAnimationFrame(handle: number): void;
+}
+
+/** Create the platform animation-frame driver used by live sessions. */
+export function createAnimationFrameDriver(): FrameDriver {
+  const host = globalThis as unknown as Partial<AnimationFrameHost>;
+  const requestAnimationFrame = host.requestAnimationFrame;
+  const cancelAnimationFrame = host.cancelAnimationFrame;
+
+  if (!requestAnimationFrame || !cancelAnimationFrame) {
+    throw new Error('GameSession requires requestAnimationFrame on this platform');
+  }
+
+  return {
+    requestFrame: (callback) => requestAnimationFrame(callback),
+    cancelFrame: (handle) => cancelAnimationFrame(handle),
+  };
+}