rn-gamekit 0.1.0 → 0.2.1

package/src/react/tilemap/tilePresentation.ts

@@ -0,0 +1,491 @@
+import type { TileMap2D, TileSet2D } from '../../tilemap/types';
+import { rotatedHalfExtents2D } from '../../camera2d/extents';
+
+/**
+ * Tile presentation binding (T16-F3/F4).
+ *
+ * Pure module shared between the JS thread and UI-runtime worklets:
+ *
+ * - `buildFrameTable` runs ONCE on JS at bind time and produces a flat,
+ *   worklet-safe numeric lookup (`frameFlat[id*4..id*4+3]`) — no `Map`,
+ *   no objects, no per-frame lookups on the UI runtime.
+ * - `buildTileWindowSnapshot` runs on JS whenever the visible cell window
+ *   or source binding changes and produces a BOUNDED snapshot sized by the
+ *   viewport capacity, never by map dimensions.
+ * - `writeLayerVisibleBounds` / `fillTileSlots` are worklet-callable and
+ *   allocation-free: camera interpolation inside the transferred window
+ *   only reads scalars and pre-transferred arrays.
+ *
+ * Full map authority stays on the simulation side; the UI runtime never
+ * sees `layer.data`, the chunk index, or the map value itself.
+ */
+
+/** Flat numeric frame lookup: frameFlat[tileId*4] = x, [+1]=y, [+2]=w, [+3]=h. */
+export type TileFrameTable = readonly number[];
+
+/**
+ * Resolve every declared tile to sheet-frame rectangles ONCE at bind time.
+ *
+ * Throws a structured error when a referenced frame is missing from the
+ * bound sheet OR when its size differs from the map cell — v1 requires
+ * frame dimensions to equal cell dimensions (T16-F3).
+ */
+export function buildFrameTable(
+  tileset: TileSet2D,
+  frames: Readonly<Record<string, { x: number; y: number; width: number; height: number }>>,
+  cellWidth: number,
+  cellHeight: number,
+): TileFrameTable {
+  const maxId = tileset.names.length;
+  const flat: number[] = new Array((maxId + 1) * 4).fill(0);
+  for (let id = 1; id <= maxId; id++) {
+    const name = tileset.nameOfId[id]!;
+    const def = tileset.tiles[name]!;
+    const rect = frames[def.frame];
+    if (rect === undefined) {
+      throw new Error(
+        `[rn-gamekit/tilemap] frame "${def.frame}" for tile "${name}" is missing from the bound sheet`,
+      );
+    }
+    if (rect.width !== cellWidth || rect.height !== cellHeight) {
+      throw new Error(
+        `[rn-gamekit/tilemap] frame "${def.frame}" for tile "${name}" is ${rect.width}x${rect.height} but the map cell is ${cellWidth}x${cellHeight}; v1 requires frame dimensions to equal cell dimensions`,
+      );
+    }
+    flat[id * 4] = rect.x;
+    flat[id * 4 + 1] = rect.y;
+    flat[id * 4 + 2] = rect.width;
+    flat[id * 4 + 3] = rect.height;
+  }
+  return Object.freeze(flat);
+}
+
+/** Bounded visible-window snapshot transferred to the UI runtime. */
+export interface TileWindowSnapshot {
+  /** Window origin in cell coordinates. */
+  readonly x0: number;
+  readonly y0: number;
+  /** Window extent in cells (ids.length === w*h). */
+  readonly w: number;
+  readonly h: number;
+  /** Row-major tile ids for the window; 0 = empty. */
+  readonly ids: readonly number[];
+  /** Flat frame lookup shared by all windows of one binding. */
+  readonly frameFlat: readonly number[];
+  /**
+   * Binding generation that published this window (GS-TILE-01). Stamp
+   * applied by the binding when it publishes; snapshots built directly
+   * (tests, initial empty) carry no generation and never satisfy a bound
+   * update. A generation mismatch means a same-size replacement or a
+   * remount happened: the window is ignored, never displayed.
+   */
+  readonly gen?: number;
+}
+
+export const EMPTY_TILE_WINDOW: TileWindowSnapshot = Object.freeze({
+  x0: 0,
+  y0: 0,
+  w: 0,
+  h: 0,
+  ids: Object.freeze([]),
+  frameFlat: Object.freeze([]),
+});
+
+/**
+ * Build a bounded snapshot for the inclusive cell range [x0..x1]×[y0..y1].
+ * The range is clamped to the layer; the result size depends ONLY on the
+ * requested range (bounded by viewport capacity), never on map size.
+ */
+export function buildTileWindowSnapshot(
+  map: TileMap2D,
+  layerId: string,
+  x0: number, y0: number, x1: number, y1: number,
+  frameFlat: TileFrameTable,
+): TileWindowSnapshot {
+  const layer = map.layerById[layerId];
+  if (layer === undefined) return EMPTY_TILE_WINDOW;
+  const cx0 = Math.max(0, Math.min(x0, x1));
+  const cy0 = Math.max(0, Math.min(y0, y1));
+  const cx1 = Math.min(layer.width - 1, Math.max(x0, x1));
+  const cy1 = Math.min(layer.height - 1, Math.max(y0, y1));
+  if (cx0 > cx1 || cy0 > cy1) return EMPTY_TILE_WINDOW;
+  const w = cx1 - cx0 + 1;
+  const h = cy1 - cy0 + 1;
+  const ids: number[] = new Array(w * h).fill(0);
+  for (let cy = cy0; cy <= cy1; cy++) {
+    for (let cx = cx0; cx <= cx1; cx++) {
+      const id = layer.data[cy * layer.width + cx]!;
+      if (id !== 0) ids[(cy - cy0) * w + (cx - cx0)] = id;
+    }
+  }
+  return Object.freeze({
+    x0: cx0,
+    y0: cy0,
+    w,
+    h,
+    ids: Object.freeze(ids),
+    frameFlat,
+  });
+}
+
+/** Whether the snapshot fully covers the inclusive cell range. */
+export function windowCovers(
+  snap: TileWindowSnapshot,
+  x0: number, y0: number, x1: number, y1: number,
+): boolean {
+  'worklet';
+  if (snap.w === 0 || snap.h === 0) return false;
+  return snap.x0 <= x0 && snap.y0 <= y0 && snap.x0 + snap.w - 1 >= x1 && snap.y0 + snap.h - 1 >= y1;
+}
+
+// Minimal structural mirrors of the shared refs, keeping this pure module
+// free of Reanimated/RN imports while accepting real SharedValues.
+interface SharedLike<T> {
+  readonly value?: T;
+}
+export type SharedCameraRef = SharedLike<
+  { camera?: { center: { x: number; y: number }; zoom: number; rotationRadians: number } } | undefined
+>;
+export type SharedViewportRef = SharedLike<
+  { visibleLogicalBounds?: { x: number; y: number; width: number; height: number } } | undefined
+>;
+
+export interface LayerBounds {
+  minX: number;
+  minY: number;
+  maxX: number;
+  maxY: number;
+}
+
+/**
+ * Write the conservative world-space bounds visible through the PRESENTED
+ * camera into `out` (T16-F3, reworked per T16-RF2).
+ *
+ * - With a presented camera: the logical view rect is rotated/zoomed by the
+ *   camera, so its axis-aligned world bounds are the center plus rotated
+ *   half-extents; the GameLayer2D parallax model applies ONCE afterwards
+ *   (effective layer center C′ = L + (C − L)·p; zoom and rotation apply
+ *   fully at every factor). Padding is world units.
+ * - WITHOUT a presented camera, GameWorld2D's viewport-only path applies:
+ *   the bounds are `viewport.visibleLogicalBounds` expanded by the padding.
+ *
+ * Worklet-callable and allocation-free on the steady path: scalars only,
+ * results written into the caller-owned `out` scratch object. Returns false
+ * when no viewport bounds exist yet.
+ */
+export function writeLayerVisibleBounds(
+  camera: SharedCameraRef | null,
+  viewport: SharedViewportRef | null,
+  parallaxX: number,
+  parallaxY: number,
+  paddingWorld: number,
+): LayerBounds | null {
+  'worklet';
+  const view = viewport?.value?.visibleLogicalBounds;
+  if (view === undefined) return null;
+  const cam = camera?.value?.camera;
+  if (cam === undefined) {
+    // Viewport-only world: no zoom, no rotation, no parallax correction.
+    return {
+      minX: view.x - paddingWorld,
+      minY: view.y - paddingWorld,
+      maxX: view.x + view.width + paddingWorld,
+      maxY: view.y + view.height + paddingWorld,
+    };
+  }
+  const hx = view.width / (2 * cam.zoom);
+  const hy = view.height / (2 * cam.zoom);
+  const extent = rotatedHalfExtents2D(hx, hy, cam.rotationRadians);
+  const ex = extent.x + paddingWorld;
+  const ey = extent.y + paddingWorld;
+  // Parallax AFTER base bounds: shift the center contribution only.
+  let centerX = cam.center.x;
+  let centerY = cam.center.y;
+  if (parallaxX !== 1 || parallaxY !== 1) {
+    const logicalCx = view.x + view.width / 2;
+    const logicalCy = view.y + view.height / 2;
+    centerX = logicalCx + (centerX - logicalCx) * parallaxX;
+    centerY = logicalCy + (centerY - logicalCy) * parallaxY;
+  }
+  return {
+    minX: centerX - ex,
+    minY: centerY - ey,
+    maxX: centerX + ex,
+    maxY: centerY + ey,
+  };
+}
+
+/** Slot-buffer contract shared by the component and tests. */
+export interface TileSlotBuffers {
+  readonly rects: readonly (SlotRect | undefined)[];
+  readonly xforms: readonly (SlotXform | undefined)[];
+}
+export interface SlotRect {
+  setXYWH(x: number, y: number, w: number, h: number): void;
+}
+export interface SlotXform {
+  set(scos: number, ssin: number, tx: number, ty: number): void;
+}
+
+export interface FillParams {
+  readonly cw: number;
+  readonly ch: number;
+  readonly originX: number;
+  readonly originY: number;
+  readonly layerWidth: number;
+  readonly layerHeight: number;
+  readonly capacity: number;
+}
+
+/**
+ * Fill Atlas slot buffers from the transferred window for the currently
+ * visible cell span (worklet-callable, T16-F3/F4).
+ *
+ * - Cell range derives from `bounds` (already camera+parallax+padding).
+ * - Tiles place UNROTATED at their CELL TOP-LEFT: the RSXform translation
+ *   is the cell's world top-left corner.
+ * - Stale slots past the filled count are hidden atomically (zero-size).
+ * - Returns the filled slot count on success; returns -1 when the window
+ *   does not cover the visible span (caller should request a new window)
+ *   and -2 when the visible span exceeds the fixed capacity (caller must
+ *   hide the whole layer and never claim partial success) — T16-SF2.
+ */
+export function fillTileSlots(
+  snap: TileWindowSnapshot,
+  bounds: LayerBounds,
+  rects: readonly (SlotRect | undefined)[],
+  xforms: readonly (SlotXform | undefined)[],
+  params: FillParams,
+): number {
+  'worklet';
+  const { cw, ch, originX, originY, layerWidth, layerHeight, capacity } = params;
+  let cx0 = Math.floor((bounds.minX - originX) / cw);
+  let cy0 = Math.floor((bounds.minY - originY) / ch);
+  let cx1 = Math.floor((bounds.maxX - originX) / cw);
+  let cy1 = Math.floor((bounds.maxY - originY) / ch);
+  cx0 = Math.max(0, cx0);
+  cy0 = Math.max(0, cy0);
+  cx1 = Math.min(layerWidth - 1, cx1);
+  cy1 = Math.min(layerHeight - 1, cy1);
+  if (cx0 > cx1 || cy0 > cy1) {
+    hideRange(rects, 0, capacity);
+    return 0;
+  }
+  // Preflight the span against capacity so a rotated AABB never produces a
+  // partial visible region (T16-SF2). Every cell in the span could be
+  // occupied, so compare the worst-case span size to the fixed buffer.
+  const spanCells = (cx1 - cx0 + 1) * (cy1 - cy0 + 1);
+  if (spanCells > capacity) {
+    hideRange(rects, 0, capacity);
+    return -2;
+  }
+  if (!windowCovers(snap, cx0, cy0, cx1, cy1)) {
+    return -1;
+  }
+  let slot = 0;
+  for (let cy = cy0; cy <= cy1; cy++) {
+    for (let cx = cx0; cx <= cx1; cx++) {
+      const id = snap.ids[(cy - snap.y0) * snap.w + (cx - snap.x0)]!;
+      if (id === 0) continue;
+      if (slot >= capacity) {
+        hideRange(rects, 0, capacity);
+        return -2;
+      }
+      const rectSlot = rects[slot];
+      const xformSlot = xforms[slot];
+      if (rectSlot === undefined || xformSlot === undefined) continue;
+      rectSlot.setXYWH(
+        snap.frameFlat[id * 4]!,
+        snap.frameFlat[id * 4 + 1]!,
+        snap.frameFlat[id * 4 + 2]!,
+        snap.frameFlat[id * 4 + 3]!,
+      );
+      // Unrotated placement at the cell's world TOP-LEFT corner.
+      xformSlot.set(1, 0, originX + cx * cw, originY + cy * ch);
+      slot++;
+    }
+  }
+  // Hide remaining stale slots atomically.
+  for (let i = slot; i < capacity; i++) {
+    rects[i]?.setXYWH(0, 0, 0, 0);
+  }
+  return slot;
+}
+
+function hideRange(rects: readonly (SlotRect | undefined)[], from: number, to: number): void {
+  'worklet';
+  for (let i = from; i < to; i++) {
+    rects[i]?.setXYWH(0, 0, 0, 0);
+  }
+}
+
+/** Stable per-binding generation from object identity (GS-TILE-01). */
+const bindingGenerations = new WeakMap<object, number>();
+let nextBindingGeneration = 1;
+
+/**
+ * Mint (or recall) the generation for one binding identity object. The
+ * component creates a fresh identity per binding-affecting prop change, so
+ * each binding gets a distinct generation with no counters in React state.
+ */
+export function bindingGeneration(binding: object): number {
+  let gen = bindingGenerations.get(binding);
+  if (gen === undefined) {
+    gen = nextBindingGeneration;
+    nextBindingGeneration += 1;
+    bindingGenerations.set(binding, gen);
+  }
+  return gen;
+}
+
+/** Shared-value mirrors kept structural so headless fakes can drive updates. */
+export interface TileWindowShared {
+  value: TileWindowSnapshot;
+}
+export interface TileNumberShared {
+  value: number;
+}
+export interface TileBooleanShared {
+  value: boolean;
+}
+
+/**
+ * Inputs for one tile-layer UI update (GS-TILE-01).
+ *
+ * Everything the update may touch is listed here: scalars, shared values,
+ * buffers, and callbacks. Map, layer, and frame-table objects are
+ * deliberately absent — the UI closure provably cannot capture layer data
+ * because it is never passed (scalar layer dims travel in `layerWidth` /
+ * `layerHeight`). The binding `generation` gates every window and request.
+ */
+export interface TileLayerUIParams {
+  readonly camera: SharedCameraRef | null;
+  readonly viewport: SharedViewportRef | null;
+  readonly window: TileWindowShared;
+  /** Generation of the in-flight request, or -1 when none is pending. */
+  readonly pendingGen: TileNumberShared;
+  readonly warnedCapacity: TileBooleanShared;
+  readonly capacityWarnPending: TileBooleanShared;
+  readonly rects: { value: readonly (SlotRect | undefined)[] };
+  readonly xforms: { value: readonly (SlotXform | undefined)[] };
+  /**
+   * Publish a window for `gen` (JS side). Stale deliveries whose `gen`
+   * predates the publisher's binding are rejected before publishing; the
+   * update additionally refuses to display any window whose stamp differs
+   * from the live generation.
+   */
+  readonly requestWindow: (gen: number, x0: number, y0: number, x1: number, y1: number) => void;
+  /** Bridge crossing to the JS side (scheduleOnRN in production). */
+  readonly scheduleOnRN: (fn: () => void) => void;
+  readonly onBeyondCapacity: () => void;
+  readonly generation: number;
+  readonly capacity: number;
+  readonly originX: number;
+  readonly originY: number;
+  readonly cw: number;
+  readonly ch: number;
+  readonly layerWidth: number;
+  readonly layerHeight: number;
+  readonly padWorld: number;
+  readonly px: number;
+  readonly py: number;
+  readonly minZoom: number;
+}
+
+/**
+ * One tile-layer UI update: the body of the layer's derived value,
+ * extracted so binding identity, stale-request rejection, and capacity
+ * policy execute identically in tests and on the UI runtime (GS-TILE-01).
+ *
+ * Returns the filled slot count; -1 when a window was requested, -2 when
+ * the span exceeds capacity or zoom left the declared bounds, 0 when
+ * nothing is visible. A window whose generation stamp differs from the
+ * live binding is treated exactly like a missing window.
+ */
+export function updateTileLayerUI(params: TileLayerUIParams): number {
+  'worklet';
+  const {
+    camera,
+    viewport,
+    window,
+    pendingGen,
+    warnedCapacity,
+    capacityWarnPending,
+    rects,
+    xforms,
+    requestWindow,
+    scheduleOnRN,
+    onBeyondCapacity,
+    generation,
+    capacity,
+    originX,
+    originY,
+    cw,
+    ch,
+    layerWidth,
+    layerHeight,
+    padWorld,
+    px,
+    py,
+    minZoom,
+  } = params;
+  // Rejected camera state: zoomed out beyond the declared capacity.
+  const camZoom = camera?.value?.camera?.zoom;
+  if (camZoom !== undefined && camZoom < minZoom * (1 - 1e-3)) {
+    for (let i = 0; i < capacity; i++) {
+      rects.value[i]?.setXYWH(0, 0, 0, 0);
+    }
+    if (!warnedCapacity.value && !capacityWarnPending.value) {
+      capacityWarnPending.value = true;
+      scheduleOnRN(onBeyondCapacity);
+    }
+    return -2;
+  }
+  const bounds = writeLayerVisibleBounds(camera, viewport, px, py, padWorld);
+  if (bounds === null) {
+    return 0;
+  }
+  const cx0 = Math.max(0, Math.floor((bounds.minX - originX) / cw));
+  const cy0 = Math.max(0, Math.floor((bounds.minY - originY) / ch));
+  const cx1 = Math.min(layerWidth - 1, Math.floor((bounds.maxX - originX) / cw));
+  const cy1 = Math.min(layerHeight - 1, Math.floor((bounds.maxY - originY) / ch));
+  if (cx0 > cx1 || cy0 > cy1) {
+    // Off-map view: hide everything.
+    for (let i = 0; i < capacity; i++) {
+      rects.value[i]?.setXYWH(0, 0, 0, 0);
+    }
+    return 0;
+  }
+  const snap = window.value;
+  // GS-TILE-01: the generation stamp decides before coordinates do. A stale
+  // window (same-size replacement, remount, late delivery) takes the
+  // request path exactly like a missing window.
+  if (snap.gen !== generation) {
+    if (pendingGen.value !== generation) {
+      pendingGen.value = generation;
+      scheduleOnRN(() => requestWindow(generation, cx0, cy0, cx1, cy1));
+    }
+    return -1;
+  }
+  const filled = fillTileSlots(
+    snap,
+    bounds,
+    rects.value,
+    xforms.value,
+    { cw, ch, originX, originY, layerWidth, layerHeight, capacity },
+  );
+  if (filled === -1 && pendingGen.value !== generation) {
+    pendingGen.value = generation;
+    scheduleOnRN(() => requestWindow(generation, cx0, cy0, cx1, cy1));
+    return -1;
+  }
+  if (filled === -2) {
+    // Capacity insufficient even at a valid zoom (e.g. extreme rotation
+    // on a fully occupied span) — hide everything, never partial.
+    for (let i = 0; i < capacity; i++) {
+      rects.value[i]?.setXYWH(0, 0, 0, 0);
+    }
+    return -2;
+  }
+  return filled;
+}

package/src/react/useGameSession.ts

@@ -0,0 +1,90 @@
+import { useEffect, useState } from 'react';
+import { createGameSession } from '../core/session/createGameSession';
+import type { GameSession } from '../core/session/types';
+import type { GameDefinition, InputMap, SceneMap } from '../definition/types';
+
+type SessionCreator<TScenes extends SceneMap, TInput extends InputMap> = (
+  definition: GameDefinition<TScenes, TInput>,
+) => GameSession<TScenes, TInput>;
+
+interface OwnedSession<TScenes extends SceneMap, TInput extends InputMap> {
+  /** The definition this session was created from, compared by identity. */
+  readonly definition: GameDefinition<TScenes, TInput>;
+  /** The live session owned by this hook instance. */
+  readonly session: GameSession<TScenes, TInput>;
+}
+
+/**
+ * Create and own a `GameSession` for a `GameDefinition`, with React
+ * ownership.
+ *
+ * The hook creates an idle session during the commit phase, publishes it,
+ * and disposes it exactly once when it is replaced or the owner unmounts.
+ * React Strict Mode's development setup/cleanup rehearsal is safe: every
+ * rehearsal session is disposed exactly once and a disposed session is never
+ * published.
+ *
+ * Ownership rules:
+ *
+ * - The return value is `undefined` until React commits a live session for
+ *   the current definition: the initial render, and the boundary while a
+ *   definition replacement is being created. Render a deliberate fallback
+ *   instead of hiding it.
+ * - The same definition object returns the same session across re-renders.
+ *   A different definition object unpublishes the old session, disposes it,
+ *   and publishes a fresh one. Disposed sessions are never revived, so
+ *   declaring definitions at module scope keeps identity stable.
+ * - The hook owns terminal disposal. Do not call `session.dispose()` on a
+ *   hook-owned session.
+ * - The hook does not start the session. Pass it to `GameView`, which binds,
+ *   starts, pauses on unmount/backgrounding, and never terminally disposes a
+ *   borrowed session.
+ * - For an asset-backed game, mount the component that calls this hook only
+ *   after `useGameAssets()` reports `ready`; this hook does not load assets.
+ *
+ * Use `createGameSession()` with explicit `try/finally` disposal for headless
+ * tests, non-React programs, and custom surface controllers that need to own
+ * sessions imperatively.
+ */
+export function useGameSession<TScenes extends SceneMap, TInput extends InputMap>(
+  definition: GameDefinition<TScenes, TInput>,
+): GameSession<TScenes, TInput> | undefined {
+  return useOwnedGameSession(definition, createGameSession);
+}
+
+/**
+ * @internal
+ *
+ * The injectable-creator seam behind `useGameSession`, exported from this
+ * module only (never from the `rn-gamekit/react` barrel). Tests supply a
+ * deterministic creator (for example `createGameSessionWithDriver` with a
+ * `ManualFrameDriver`, since node has no `requestAnimationFrame`) and must
+ * pass a stable factory identity across renders.
+ */
+export function useOwnedGameSession<TScenes extends SceneMap, TInput extends InputMap>(
+  definition: GameDefinition<TScenes, TInput>,
+  create: SessionCreator<TScenes, TInput>,
+): GameSession<TScenes, TInput> | undefined {
+  const [owned, setOwned] = useState<OwnedSession<TScenes, TInput> | undefined>(undefined);
+
+  // Render-phase selector: publish a session only while its definition is
+  // the current prop and its status is not disposed. A replacement render
+  // therefore unpublishes the old session before any effect runs, and
+  // `undefined` is the only other value.
+  const session =
+    owned !== undefined &&
+    owned.definition === definition &&
+    owned.session.status !== 'disposed'
+      ? owned.session
+      : undefined;
+
+  useEffect(() => {
+    const next = create(definition);
+    setOwned({ definition, session: next });
+    return () => {
+      next.dispose();
+    };
+  }, [definition, create]);
+
+  return session;
+}

package/src/react/useGameSessionStatus.ts

@@ -0,0 +1,53 @@
+import { useCallback, useSyncExternalStore } from 'react';
+import type { GameSession, GameSessionStatus } from '../core/session/types';
+import type { InputMap, SceneMap } from '../definition/types';
+
+/** Stable no-op cleanup for the absent/disposed session branch. */
+const unsubscribeNothing = (): void => {};
+
+/**
+ * Observe a session's lifecycle status from React.
+ *
+ * Returns the current `session.status` on the render that observes a
+ * session, and re-renders once per actual lifecycle transition. `undefined`
+ * means no session is currently available — the same meaning Task 9's
+ * `useGameSession()` gives its pre-commit value, so both hooks compose
+ * unconditionally:
+ *
+ * ```ts
+ * const session = useGameSession(game);
+ * const status = useGameSessionStatus(session);
+ * ```
+ *
+ * The hook subscribes through `addStatusListener` and never polls; it owns
+ * no session and never disposes one. Replacing the session argument detaches
+ * the old subscription before the replacement's status is reported, and
+ * idempotent lifecycle commands do not cause redundant re-renders.
+ */
+export function useGameSessionStatus<
+  TScenes extends SceneMap,
+  TInput extends InputMap,
+>(session: GameSession<TScenes, TInput> | undefined): GameSessionStatus | undefined {
+  // The callbacks are memoized on the session identity only, so unrelated
+  // parent renders never tear down and recreate the subscription; a session
+  // prop change produces new identities and React detaches the old session
+  // before attaching the replacement.
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      // Never subscribe to a disposed session: its terminal notification is
+      // already delivered, and addStatusListener follows the disposed-error
+      // policy for new subscribers.
+      if (session === undefined || session.status === 'disposed') {
+        return unsubscribeNothing;
+      }
+      const subscription = session.addStatusListener(onStoreChange);
+      return () => {
+        subscription.remove();
+      };
+    },
+    [session],
+  );
+  const getSnapshot = useCallback(() => session?.status, [session]);
+
+  return useSyncExternalStore(subscribe, getSnapshot);
+}

package/src/react/viewportBinding.ts

@@ -76,7 +76,11 @@ export class ViewportBinding {
     };
   }
 
-  /** Release subscribers. The binding becomes inert. */
+  /**
+   * Release current subscribers (GS-VIEWPORT-01). This is not a lifecycle
+   * gate: late subscriptions still register and setSurfaceSize still
+   * resolves. Discard the binding after disposal instead of reusing it.
+   */
   dispose(): void {
     this.#listeners.clear();
   }

package/src/react.ts

@@ -1,8 +1,15 @@
 export { GameView } from './react/GameView';
+export { useGameSession } from './react/useGameSession';
+export { useGameSessionStatus } from './react/useGameSessionStatus';
+export { createGameLifecycleSource, GameLifecycleProvider, useGameLifecycleSource } from './react/lifecycleSource';
+export type { GameLifecycleSource } from './core/session/types';
 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 { GameWorld2D, viewportTransform, cameraViewportTransform2D, layerParallaxTransform2D } from './react/sprites/GameWorld2D';
+export { GameLayer2D } from './react/camera2d/GameLayer2D';
+export { defineGameCamera2D } from './react/camera2d/defineGameCamera2D';
+export type { GameCamera2DDefinition } from './react/camera2d/defineGameCamera2D';
 export { Sprite, resolveSpriteFrameRect } from './react/sprites/Sprite';
 export type { SpriteAnimatable, SpriteAnimatableBoolean, SpriteProps } from './react/sprites/Sprite';
 export { GameSprite, spriteFrameNameForClip } from './react/sprites/GameSprite';
@@ -34,4 +41,14 @@ export type {
 export type { GameRendererProps, GameViewProps } from './react/GameView';
 export { GamePointerInput } from './react/GamePointerInput';
 export type { GamePointerInputProps } from './react/GamePointerInput';
+export { GameButtonPad, GameButton } from './react/GameButtonPad';
+export type { GameButtonPadProps, GameButtonProps, ButtonActionName } from './react/GameButtonPad';
 export type { GamePointerInstrumentation, GameViewInstrumentation } from './react/instrumentation';
+export { ParticleView } from './react/particles/ParticleView';
+export type { ParticleViewProps } from './react/particles/ParticleView';
+export { useParticlePresentation } from './react/particles/useParticlePresentation';
+export type { ParticlePresentation } from './react/particles/useParticlePresentation';
+export { particleSpriteXform, assertUniformParticleSpriteRatio } from './react/particles/spriteXForm';
+export { cameraVisibleWorldBounds, visibleInBounds, PARTICLE_CULL_PADDING } from './react/particles/culling';
+export { TileMapLayer2D } from './react/tilemap/TileMapLayer2D';
+export type { TileMapLayer2DProps } from './react/tilemap/TileMapLayer2D';