rn-gamekit 0.1.0

package/src/react/sprites/SpriteBatch.tsx

@@ -0,0 +1,219 @@
+/**
+ * `SpriteBatch` — the Atlas-backed shared-texture batch (T7.7).
+ *
+ * Draws many instances of one decoded sprite-sheet image through Skia's
+ * `Atlas` with fixed-capacity, UI-owned buffers. The normal path owns all
+ * derived-value plumbing: `select` maps the committed snapshot to the item
+ * array and `write` is a UI-runtime setter that writes transforms in place —
+ * no per-frame allocation, no per-frame React, no author-written
+ * `useDerivedValue` side effects.
+ *
+ * Contract:
+ * - `capacity` is fixed for the mounted batch; active count is explicit.
+ * - Writes past capacity are rejected in development; inactive slots are
+ *   hidden (zero-size) and never remount topology.
+ * - Item order is the drawing order; the anchor is uniform per batch.
+ * - The batch never disposes the image (the asset lease owns it).
+ */
+import { useMemo } from 'react';
+import { Atlas, type SkImage } from '@shopify/react-native-skia';
+import { useDerivedValue, type SharedValue } from 'react-native-reanimated';
+import { useRectBuffer, useRSXformBuffer } from '@shopify/react-native-skia';
+
+import type { CommitFrame } from '../../core/session/types';
+import type { SceneSnapshot } from '../../scene/types';
+import type { SceneMap } from '../../definition/types';
+import type { LoadedImage, LoadedSpriteSheet } from '../../assets/types';
+import { computeSpriteRsxform } from './spriteTransform';
+import { batchUpdatePolicy } from './spriteBatchPolicy';
+
+/** The per-item write surface handed to the author's `write` mapper. */
+export interface SpriteBatchWrite {
+  /**
+   * Write one batch slot. `frame` names the sheet frame; `x`/`y` are world
+   * logical units; `rotation` is radians around the batch anchor; `scale`
+   * is uniform; `visible: false` hides the slot (zero-size rect). Writes
+   * past capacity fail in development.
+   */
+  readonly set: (
+    index: number,
+    frame: string,
+    x: number,
+    y: number,
+    rotation: number,
+    scale: number,
+    visible?: boolean,
+  ) => void;
+}
+
+export interface SpriteBatchProps<
+  TScenes extends SceneMap,
+  TSceneName extends Extract<keyof TScenes, string>,
+  TItem,
+> {
+  /** The scene whose snapshot `select` reads. */
+  readonly scene: TSceneName;
+  /** The renderer's latest commit. */
+  readonly commit: SharedValue<CommitFrame<TScenes>>;
+  /** The renderer's presentation alpha. */
+  readonly alpha: SharedValue<number>;
+  /** One decoded sheet shared by every instance. */
+  readonly source: LoadedImage | LoadedSpriteSheet;
+  /** Fixed slot capacity for the mounted batch. */
+  readonly capacity: number;
+  /** Map the committed snapshot to the item array. */
+  readonly select: (context: {
+    readonly current: SceneSnapshot<TScenes[TSceneName]>;
+    readonly alpha: number;
+  }) => readonly TItem[];
+  /** Write each item into its batch slot (UI runtime). */
+  readonly write: (write: SpriteBatchWrite, item: TItem, index: number) => void;
+  /** Uniform anchor in [0, 1] relative to the selected frame. */
+  readonly anchor?: { readonly x: number; readonly y: number };
+}
+
+function frameRectOf(
+  source: LoadedImage | LoadedSpriteSheet,
+  frame: string,
+): { x: number; y: number; width: number; height: number } | undefined {
+  'worklet';
+  if (source.descriptor.kind === 'image') {
+    const image = source as LoadedImage;
+    return { x: 0, y: 0, width: image.width, height: image.height };
+  }
+  return (source as LoadedSpriteSheet).frames[frame];
+}
+
+export function SpriteBatch<
+  TScenes extends SceneMap,
+  TSceneName extends Extract<keyof TScenes, string>,
+  TItem,
+>({
+  scene,
+  commit,
+  alpha,
+  source,
+  capacity,
+  select,
+  write,
+  anchor = { x: 0, y: 0 },
+}: SpriteBatchProps<TScenes, TSceneName, TItem>) {
+  const image = source.image as SkImage;
+  if (!Number.isInteger(capacity) || capacity <= 0) {
+    throw new Error(
+      `SpriteBatch capacity must be a positive integer, got ${String(capacity)}`,
+    );
+  }
+  const rects = useRectBuffer(capacity, (rect) => {
+    'worklet';
+    rect.setXYWH(0, 0, 0, 0);
+  });
+  const xforms = useRSXformBuffer(capacity, (xform) => {
+    'worklet';
+    xform.set(1, 0, 0, 0);
+  });
+
+  // R7: one stable write coordinator for the batch lifetime; the per-update
+  // worklet only calls it (no per-frame coordinator allocation).
+  const writeApi: SpriteBatchWrite = useMemo(
+    () => ({
+      set: (index, frame, x, y, rotation, scale, visible = true) => {
+        'worklet';
+        if (index < 0 || index >= capacity) {
+          throw new Error(
+            `SpriteBatch write index ${index} is outside the capacity ${capacity}`,
+          );
+        }
+        const rectSlot = rects.value[index];
+        const xformSlot = xforms.value[index];
+        if (rectSlot === undefined || xformSlot === undefined) {
+          return;
+        }
+        if (!visible) {
+          rectSlot.setXYWH(0, 0, 0, 0);
+          return;
+        }
+        const rect = frameRectOf(source, frame);
+        if (rect === undefined) {
+          throw new Error(
+            `frame ${JSON.stringify(frame)} does not belong to this sprite sheet`,
+          );
+        }
+        rectSlot.setXYWH(rect.x, rect.y, rect.width, rect.height);
+        const rsxform = computeSpriteRsxform({
+          x,
+          y,
+          rotation,
+          scale,
+          flipX: false,
+          flipY: false,
+          anchorX: anchor.x,
+          anchorY: anchor.y,
+          frameWidth: rect.width,
+          frameHeight: rect.height,
+        });
+        xformSlot.set(rsxform.scos, rsxform.ssin, rsxform.tx, rsxform.ty);
+      },
+    }),
+    // The buffers, source, and anchor are stable for the mounted batch.
+    [capacity, rects, xforms, source, anchor.x, anchor.y],
+  );
+
+  // The batch's own UI mapper: one derived value reads the committed
+  // snapshot, runs the author's select + write per item, and reports the
+  // active count. Buffers are mutated in place; no objects are allocated
+  // per item per frame beyond the item array the select returns.
+  const activeCount = useDerivedValue(() => {
+    'worklet';
+    const envelope = commit.value;
+    if (envelope.scene !== scene) {
+      // RF8: leaving the scene clears every previously active slot so no
+      // stale sprite from the old scene stays visible.
+      for (let index = 0; index < capacity; index += 1) {
+        const slot = rects.value[index];
+        if (slot !== undefined) {
+          slot.setXYWH(0, 0, 0, 0);
+        }
+      }
+      return 0;
+    }
+    const items = select({
+      current: envelope.current as never as SceneSnapshot<TScenes[TSceneName]>,
+      alpha: alpha.value,
+    });
+    const policy = batchUpdatePolicy(items.length, capacity, __DEV__);
+    if (policy.overflow) {
+      // RF8: production never crashes the UI runtime for ordinary data
+      // growth: hide the overflowing items.
+      for (let index = capacity; index < items.length; index += 1) {
+        const slot = rects.value[index];
+        if (slot !== undefined) {
+          slot.setXYWH(0, 0, 0, 0);
+        }
+      }
+    }
+    const count = policy.activeCount;
+    for (let index = 0; index < items.length; index += 1) {
+      const item = items[index];
+      if (item !== undefined) {
+        write(writeApi, item, index);
+      }
+    }
+    // Hide every inactive slot.
+    for (let index = count; index < capacity; index += 1) {
+      const slot = rects.value[index];
+      if (slot !== undefined) {
+        slot.setXYWH(0, 0, 0, 0);
+      }
+    }
+    return count;
+  }, [commit, alpha, scene, select, write, writeApi]);
+
+  void activeCount;
+
+  // The atlas renders the full buffer; the UI mapper keeps slots aligned.
+  const sampling = useMemo(() => 'nearest' as const, []);
+  return (
+    <Atlas image={image} sprites={rects} transforms={xforms} sampling={sampling as never} />
+  );
+}

package/src/react/sprites/spriteBatchPolicy.ts

@@ -0,0 +1,21 @@
+/** Pure SpriteBatch update policy (RF8): the overflow decision and the
+ * active count. Development reports a structured error; production clamps
+ * and hides the overflow so the UI runtime never crashes for ordinary data
+ * growth. Runs inside the batch's update worklet, so it carries the worklet
+ * directive. */
+export function batchUpdatePolicy(
+  itemsCount: number,
+  capacity: number,
+  dev: boolean,
+): { readonly overflow: boolean; readonly activeCount: number } {
+  'worklet';
+  if (itemsCount <= capacity) {
+    return { overflow: false, activeCount: itemsCount };
+  }
+  if (dev) {
+    throw new Error(
+      `SpriteBatch overflow: ${itemsCount} items selected with capacity ${capacity}`,
+    );
+  }
+  return { overflow: true, activeCount: capacity };
+}

package/src/react/sprites/spriteTransform.ts

@@ -0,0 +1,163 @@
+import type { LoadedImage, LoadedSpriteSheet } from '../../assets/types';
+
+/** The resolved source rectangle for one frame selection. */
+export interface SpriteFrameRect {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+/**
+ * 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: LoadedImage | LoadedSpriteSheet,
+  frame: string | undefined,
+): SpriteFrameRect {
+  if (source.descriptor.kind === 'image') {
+    const image = source as LoadedImage;
+    return { x: 0, y: 0, width: image.width, height: image.height };
+  }
+  const sheet = source as LoadedSpriteSheet;
+  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.
+ */
+import type { SharedValue } from 'react-native-reanimated';
+
+/** A sprite's presentation input; numbers or UI-runtime animated values. */
+export interface SpriteTransformInput {
+  /** World position in logical units. */
+  readonly x: number | SharedValue<number>;
+  readonly y: number | SharedValue<number>;
+  /** Rotation in radians around the anchor. */
+  readonly rotation: number | SharedValue<number>;
+  /** Uniform scale around the anchor. */
+  readonly scale: number | SharedValue<number>;
+  /** Explicit flips preserve the anchor. */
+  readonly flipX: boolean | SharedValue<boolean>;
+  readonly flipY: boolean | SharedValue<boolean>;
+  /** Normalized anchor in [0, 1] relative to the selected frame. */
+  readonly anchorX: number;
+  readonly anchorY: number;
+  /** Selected frame size in source pixels (logical units for placement). */
+  readonly frameWidth: number;
+  readonly frameHeight: number;
+}
+
+/** The computed RSXform (rotation + position, pivot-compensated). */
+export interface SpriteRsxform {
+  readonly scos: number;
+  readonly ssin: number;
+  readonly tx: number;
+  readonly ty: number;
+}
+
+/** A Skia-compatible 3x3 transform element list. */
+export type SkiaTransformElement =
+  | { readonly translateX: number }
+  | { readonly translateY: number }
+  | { readonly scaleX: number }
+  | { readonly scaleY: number };
+
+function readNumber(value: number | SharedValue<number>): number {
+  'worklet';
+  return typeof value === 'number' ? value : value.value;
+}
+
+function readBoolean(value: boolean | SharedValue<boolean>): boolean {
+  '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: SpriteTransformInput): SpriteRsxform {
+  '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: SpriteTransformInput): readonly SkiaTransformElement[] {
+  '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: SpriteTransformInput): {
+  readonly x: number;
+  readonly y: number;
+} {
+  'worklet';
+  return {
+    x: readNumber(input.x),
+    y: readNumber(input.y),
+  };
+}

package/src/react/viewportBinding.ts

@@ -0,0 +1,104 @@
+import { resolveViewport2D, type ResolvedViewport2D, type SurfaceSize, type Viewport } from '../viewport2d';
+
+/**
+ * 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 {
+  readonly #config: Viewport;
+  #resolved: ResolvedViewport2D | undefined;
+  #lastSurfaceSize: SurfaceSize | undefined;
+  #revision = 0;
+  #listeners = new Set<() => void>();
+
+  constructor(config: Viewport) {
+    this.#config = config;
+  }
+
+  /** The authored viewport configuration this binding resolves. */
+  get config(): Viewport {
+    return this.#config;
+  }
+
+  /** The latest resolved viewport, or `undefined` while the layout is invalid. */
+  get resolved(): ResolvedViewport2D | undefined {
+    return this.#resolved;
+  }
+
+  /** The latest native surface measurement, retained across viewport swaps. */
+  get surfaceSize(): SurfaceSize | undefined {
+    return this.#lastSurfaceSize;
+  }
+
+  /** Monotonic counter incremented on every layout revision. */
+  get revision(): number {
+    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: SurfaceSize): void {
+    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: () => void): () => void {
+    this.#listeners.add(listener);
+    let removed = false;
+    return () => {
+      if (removed) {
+        return;
+      }
+      removed = true;
+      this.#listeners.delete(listener);
+    };
+  }
+
+  /** Release subscribers. The binding becomes inert. */
+  dispose(): void {
+    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: Viewport,
+  previous: ViewportBinding | null,
+): ViewportBinding {
+  if (previous?.config === config) {
+    return previous;
+  }
+
+  const replacement = new ViewportBinding(config);
+  if (previous?.surfaceSize !== undefined) {
+    replacement.setSurfaceSize(previous.surfaceSize);
+  }
+  return replacement;
+}

package/src/react.ts

@@ -0,0 +1,37 @@
+export { GameView } from './react/GameView';
+export { createGameAssetStore } from './react/assets/decodeSkiaImage';
+export { useGameAssets, stableGroupsKey } from './react/assets/useGameAssets';
+export type { GameAssetsState } from './react/assets/useGameAssets';
+export { GameWorld2D, viewportTransform } from './react/sprites/GameWorld2D';
+export { Sprite, resolveSpriteFrameRect } from './react/sprites/Sprite';
+export type { SpriteAnimatable, SpriteAnimatableBoolean, SpriteProps } from './react/sprites/Sprite';
+export { GameSprite, spriteFrameNameForClip } from './react/sprites/GameSprite';
+export type {
+  GameSpriteProps,
+  GameSpriteSelectContext,
+  GameSpriteSelection,
+} from './react/sprites/GameSprite';
+export { SpriteBatch } from './react/sprites/SpriteBatch';
+export type { SpriteBatchProps, SpriteBatchWrite } from './react/sprites/SpriteBatch';
+export {
+  computeSpriteRsxform,
+  spriteAnchorWorld,
+  spriteGroupCorrection,
+} from './react/sprites/spriteTransform';
+export type {
+  SkiaTransformElement,
+  SpriteRsxform,
+  SpriteTransformInput,
+} from './react/sprites/spriteTransform';
+export { createGameAssetStoreCore } from './react/assets/createGameAssetStore';
+export type {
+  AcquireOptions,
+  AssetPipelines,
+  GameAssetStore,
+  NativeImageHandle,
+} from './react/assets/createGameAssetStore';
+
+export type { GameRendererProps, GameViewProps } from './react/GameView';
+export { GamePointerInput } from './react/GamePointerInput';
+export type { GamePointerInputProps } from './react/GamePointerInput';
+export type { GamePointerInstrumentation, GameViewInstrumentation } from './react/instrumentation';

package/src/scene/defineScene.ts

@@ -0,0 +1,38 @@
+import type { SceneDefinition } from './types';
+
+/**
+ * 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<
+  const TActions extends readonly string[],
+  TState,
+  TSnapshot,
+  const TTransitions extends readonly string[] = [],
+>(
+  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]> {
+  return {
+    kind: 'gamekit.scene',
+    ...definition,
+  };
+}

package/src/scene/types.ts

@@ -0,0 +1,79 @@
+import type { InputFrame } from '../core/input/types';
+
+/**
+ * Update-scoped scene transition controls.
+ *
+ * The controller is valid only for the duration of the `update` call that
+ * received it. Retaining it and calling either method afterwards throws a
+ * lifecycle error. Conflicting requests within one update fail clearly.
+ */
+export interface SceneTransitionController<TTransitionName extends string> {
+  /**
+   * Request a transition to a declared target scene.
+   *
+   * Requests to the current scene are idempotent no-ops. The transition
+   * commits after the current update completes successfully.
+   */
+  setScene(name: TTransitionName): void;
+  /** Recreate the current scene with fresh state. */
+  restartScene(): void;
+}
+
+/** Values supplied to a scene for one deterministic simulation tick. */
+export interface SceneUpdate<TState, TActionName extends string, TTransitionName extends 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>;
+  /** One-based global simulation tick number. */
+  readonly tick: number;
+  /** One-based tick number within the current scene instance. */
+  readonly sceneTick: number;
+  /** Constant fixed-step duration in seconds. */
+  readonly deltaSeconds: number;
+  /** Deterministic global simulation time after this tick. */
+  readonly elapsedSeconds: number;
+  /** Deterministic time within the current scene instance. */
+  readonly sceneElapsedSeconds: number;
+}
+
+/** Values supplied when extracting a renderer-specific snapshot. */
+export interface SceneSnapshotContext<TState> {
+  /** Current authoritative scene state. */
+  readonly state: Readonly<TState>;
+}
+
+/** A synchronous functional scene used by the runtime. */
+export interface SceneDefinition<
+  TState,
+  TSnapshot,
+  TActionName extends string = never,
+  TTransitionName extends string = never,
+> {
+  /** Internal scene-definition discriminator. */
+  readonly kind: 'gamekit.scene';
+  /** @internal Covariant type witness used to infer presentation snapshots. */
+  readonly __snapshotType?: TSnapshot;
+  /** @internal Type witness used to validate scene actions against the game. */
+  readonly __actionType?: TActionName;
+  /** @internal Type witness used to validate scene transition targets. */
+  readonly __transitionType?: TTransitionName;
+  /** Semantic input actions this scene may read. */
+  readonly actions: readonly TActionName[];
+  /** Declared scene names this scene may transition to. */
+  readonly transitions?: readonly TTransitionName[];
+  /** 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 snapshot: (context: SceneSnapshotContext<TState>) => TSnapshot;
+  /** Release scene-owned resources exactly once. */
+  readonly dispose?: (state: Readonly<TState>) => void;
+}
+
+/** Infer the presentation snapshot produced by a scene definition. */
+export type SceneSnapshot<TScene> =
+  TScene extends { readonly __snapshotType?: infer TSnapshot } ? TSnapshot : never;