rn-gamekit 0.1.0 → 0.2.0

package/lib/module/react/tilemap/tilePresentation.js

@@ -0,0 +1,374 @@
+"use strict";
+
+import { rotatedHalfExtents2D } from "../../camera2d/extents.js";
+
+/**
+ * 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. */
+
+/**
+ * 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, frames, cellWidth, cellHeight) {
+  const maxId = tileset.names.length;
+  const flat = 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 const EMPTY_TILE_WINDOW = 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, layerId, x0, y0, x1, y1, frameFlat) {
+  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 = 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, x0, y0, x1, y1) {
+  '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.
+
+/**
+ * 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, viewport, parallaxX, parallaxY, paddingWorld) {
+  '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. */
+
+/**
+ * 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, bounds, rects, xforms, params) {
+  '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, from, to) {
+  '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();
+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) {
+  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. */
+
+/**
+ * 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.
+ */
+
+/**
+ * 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) {
+  '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;
+}
+//# sourceMappingURL=tilePresentation.js.map

package/lib/module/react/tilemap/tilePresentation.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["rotatedHalfExtents2D","buildFrameTable","tileset","frames","cellWidth","cellHeight","maxId","names","length","flat","Array","fill","id","name","nameOfId","def","tiles","rect","frame","undefined","Error","width","height","x","y","Object","freeze","EMPTY_TILE_WINDOW","x0","y0","w","h","ids","frameFlat","buildTileWindowSnapshot","map","layerId","x1","y1","layer","layerById","cx0","Math","max","min","cy0","cx1","cy1","cy","cx","data","windowCovers","snap","writeLayerVisibleBounds","camera","viewport","parallaxX","parallaxY","paddingWorld","view","value","visibleLogicalBounds","cam","minX","minY","maxX","maxY","hx","zoom","hy","extent","rotationRadians","ex","ey","centerX","center","centerY","logicalCx","logicalCy","fillTileSlots","bounds","rects","xforms","params","cw","ch","originX","originY","layerWidth","layerHeight","capacity","floor","hideRange","spanCells","slot","rectSlot","xformSlot","setXYWH","set","i","from","to","bindingGenerations","WeakMap","nextBindingGeneration","bindingGeneration","binding","gen","get","updateTileLayerUI","window","pendingGen","warnedCapacity","capacityWarnPending","requestWindow","scheduleOnRN","onBeyondCapacity","generation","padWorld","px","py","minZoom","camZoom","filled"],"sourceRoot":"../../../../src","sources":["react/tilemap/tilePresentation.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/react/useGameSession.js

@@ -0,0 +1,70 @@
+"use strict";
+
+import { useEffect, useState } from 'react';
+import { createGameSession } from "../core/session/createGameSession.js";
+/**
+ * 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(definition) {
+  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(definition, create) {
+  const [owned, setOwned] = useState(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;
+}
+//# sourceMappingURL=useGameSession.js.map

package/lib/module/react/useGameSession.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["useEffect","useState","createGameSession","useGameSession","definition","useOwnedGameSession","create","owned","setOwned","undefined","session","status","next","dispose"],"sourceRoot":"../../../src","sources":["react/useGameSession.ts"],"mappings":";;AAAA,SAASA,SAAS,EAAEC,QAAQ,QAAQ,OAAO;AAC3C,SAASC,iBAAiB,QAAQ,sCAAmC;AAerE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,cAAcA,CAC5BC,UAA2C,EACD;EAC1C,OAAOC,mBAAmB,CAACD,UAAU,EAAEF,iBAAiB,CAAC;AAC3D;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASG,mBAAmBA,CACjCD,UAA2C,EAC3CE,MAAuC,EACG;EAC1C,MAAM,CAACC,KAAK,EAAEC,QAAQ,CAAC,GAAGP,QAAQ,CAA4CQ,SAAS,CAAC;;EAExF;EACA;EACA;EACA;EACA,MAAMC,OAAO,GACXH,KAAK,KAAKE,SAAS,IACnBF,KAAK,CAACH,UAAU,KAAKA,UAAU,IAC/BG,KAAK,CAACG,OAAO,CAACC,MAAM,KAAK,UAAU,GAC/BJ,KAAK,CAACG,OAAO,GACbD,SAAS;EAEfT,SAAS,CAAC,MAAM;IACd,MAAMY,IAAI,GAAGN,MAAM,CAACF,UAAU,CAAC;IAC/BI,QAAQ,CAAC;MAAEJ,UAAU;MAAEM,OAAO,EAAEE;IAAK,CAAC,CAAC;IACvC,OAAO,MAAM;MACXA,IAAI,CAACC,OAAO,CAAC,CAAC;IAChB,CAAC;EACH,CAAC,EAAE,CAACT,UAAU,EAAEE,MAAM,CAAC,CAAC;EAExB,OAAOI,OAAO;AAChB","ignoreList":[]}

package/lib/module/react/useGameSessionStatus.js

@@ -0,0 +1,46 @@
+"use strict";
+
+import { useCallback, useSyncExternalStore } from 'react';
+/** Stable no-op cleanup for the absent/disposed session branch. */
+const unsubscribeNothing = () => {};
+
+/**
+ * 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(session) {
+  // 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 => {
+    // 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);
+}
+//# sourceMappingURL=useGameSessionStatus.js.map

package/lib/module/react/useGameSessionStatus.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["useCallback","useSyncExternalStore","unsubscribeNothing","useGameSessionStatus","session","subscribe","onStoreChange","undefined","status","subscription","addStatusListener","remove","getSnapshot"],"sourceRoot":"../../../src","sources":["react/useGameSessionStatus.ts"],"mappings":";;AAAA,SAASA,WAAW,EAAEC,oBAAoB,QAAQ,OAAO;AAIzD;AACA,MAAMC,kBAAkB,GAAGA,CAAA,KAAY,CAAC,CAAC;;AAEzC;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,oBAAoBA,CAGlCC,OAAiD,EAAiC;EAClF;EACA;EACA;EACA;EACA,MAAMC,SAAS,GAAGL,WAAW,CAC1BM,aAAyB,IAAK;IAC7B;IACA;IACA;IACA,IAAIF,OAAO,KAAKG,SAAS,IAAIH,OAAO,CAACI,MAAM,KAAK,UAAU,EAAE;MAC1D,OAAON,kBAAkB;IAC3B;IACA,MAAMO,YAAY,GAAGL,OAAO,CAACM,iBAAiB,CAACJ,aAAa,CAAC;IAC7D,OAAO,MAAM;MACXG,YAAY,CAACE,MAAM,CAAC,CAAC;IACvB,CAAC;EACH,CAAC,EACD,CAACP,OAAO,CACV,CAAC;EACD,MAAMQ,WAAW,GAAGZ,WAAW,CAAC,MAAMI,OAAO,EAAEI,MAAM,EAAE,CAACJ,OAAO,CAAC,CAAC;EAEjE,OAAOH,oBAAoB,CAACI,SAAS,EAAEO,WAAW,CAAC;AACrD","ignoreList":[]}

package/lib/module/react/viewportBinding.js

@@ -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() {
     this.#listeners.clear();
   }

package/lib/module/react/viewportBinding.js.map

@@ -1 +1 @@
-{"version":3,"names":["resolveViewport2D","ViewportBinding","config","resolved","lastSurfaceSize","revision","listeners","Set","constructor","surfaceSize","setSurfaceSize","size","undefined","width","height","Object","freeze","listener","subscribe","add","removed","delete","dispose","clear","bindingForViewport","previous","replacement"],"sourceRoot":"../../../src","sources":["react/viewportBinding.ts"],"mappings":";;AAAA,SAASA,iBAAiB,QAAkE,wBAAe;;AAE3G;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,eAAe,CAAC;EAClB,CAACC,MAAM;EAChB,CAACC,QAAQ;EACT,CAACC,eAAe;EAChB,CAACC,QAAQ,GAAG,CAAC;EACb,CAACC,SAAS,GAAG,IAAIC,GAAG,CAAa,CAAC;EAElCC,WAAWA,CAACN,MAAgB,EAAE;IAC5B,IAAI,CAAC,CAACA,MAAM,GAAGA,MAAM;EACvB;;EAEA;EACA,IAAIA,MAAMA,CAAA,EAAa;IACrB,OAAO,IAAI,CAAC,CAACA,MAAM;EACrB;;EAEA;EACA,IAAIC,QAAQA,CAAA,EAAmC;IAC7C,OAAO,IAAI,CAAC,CAACA,QAAQ;EACvB;;EAEA;EACA,IAAIM,WAAWA,CAAA,EAA4B;IACzC,OAAO,IAAI,CAAC,CAACL,eAAe;EAC9B;;EAEA;EACA,IAAIC,QAAQA,CAAA,EAAW;IACrB,OAAO,IAAI,CAAC,CAACA,QAAQ;EACvB;;EAEA;AACF;AACA;AACA;AACA;AACA;EACEK,cAAcA,CAACC,IAAiB,EAAQ;IACtC,IACE,IAAI,CAAC,CAACP,eAAe,KAAKQ,SAAS,IACnC,IAAI,CAAC,CAACR,eAAe,CAACS,KAAK,KAAKF,IAAI,CAACE,KAAK,IAC1C,IAAI,CAAC,CAACT,eAAe,CAACU,MAAM,KAAKH,IAAI,CAACG,MAAM,EAC5C;MACA;IACF;IACA,IAAI,CAAC,CAACV,eAAe,GAAGW,MAAM,CAACC,MAAM,CAAC;MAAEH,KAAK,EAAEF,IAAI,CAACE,KAAK;MAAEC,MAAM,EAAEH,IAAI,CAACG;IAAO,CAAC,CAAC;IACjF,IAAI,CAAC,CAACX,QAAQ,GAAGH,iBAAiB,CAAC,IAAI,CAAC,CAACE,MAAM,EAAES,IAAI,CAAC;IACtD,IAAI,CAAC,CAACN,QAAQ,IAAI,CAAC;IACnB,KAAK,MAAMY,QAAQ,IAAI,CAAC,GAAG,IAAI,CAAC,CAACX,SAAS,CAAC,EAAE;MAC3CW,QAAQ,CAAC,CAAC;IACZ;EACF;;EAEA;EACAC,SAASA,CAACD,QAAoB,EAAc;IAC1C,IAAI,CAAC,CAACX,SAAS,CAACa,GAAG,CAACF,QAAQ,CAAC;IAC7B,IAAIG,OAAO,GAAG,KAAK;IACnB,OAAO,MAAM;MACX,IAAIA,OAAO,EAAE;QACX;MACF;MACAA,OAAO,GAAG,IAAI;MACd,IAAI,CAAC,CAACd,SAAS,CAACe,MAAM,CAACJ,QAAQ,CAAC;IAClC,CAAC;EACH;;EAEA;EACAK,OAAOA,CAAA,EAAS;IACd,IAAI,CAAC,CAAChB,SAAS,CAACiB,KAAK,CAAC,CAAC;EACzB;AACF;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,kBAAkBA,CAChCtB,MAAgB,EAChBuB,QAAgC,EACf;EACjB,IAAIA,QAAQ,EAAEvB,MAAM,KAAKA,MAAM,EAAE;IAC/B,OAAOuB,QAAQ;EACjB;EAEA,MAAMC,WAAW,GAAG,IAAIzB,eAAe,CAACC,MAAM,CAAC;EAC/C,IAAIuB,QAAQ,EAAEhB,WAAW,KAAKG,SAAS,EAAE;IACvCc,WAAW,CAAChB,cAAc,CAACe,QAAQ,CAAChB,WAAW,CAAC;EAClD;EACA,OAAOiB,WAAW;AACpB","ignoreList":[]}
+{"version":3,"names":["resolveViewport2D","ViewportBinding","config","resolved","lastSurfaceSize","revision","listeners","Set","constructor","surfaceSize","setSurfaceSize","size","undefined","width","height","Object","freeze","listener","subscribe","add","removed","delete","dispose","clear","bindingForViewport","previous","replacement"],"sourceRoot":"../../../src","sources":["react/viewportBinding.ts"],"mappings":";;AAAA,SAASA,iBAAiB,QAAkE,wBAAe;;AAE3G;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,eAAe,CAAC;EAClB,CAACC,MAAM;EAChB,CAACC,QAAQ;EACT,CAACC,eAAe;EAChB,CAACC,QAAQ,GAAG,CAAC;EACb,CAACC,SAAS,GAAG,IAAIC,GAAG,CAAa,CAAC;EAElCC,WAAWA,CAACN,MAAgB,EAAE;IAC5B,IAAI,CAAC,CAACA,MAAM,GAAGA,MAAM;EACvB;;EAEA;EACA,IAAIA,MAAMA,CAAA,EAAa;IACrB,OAAO,IAAI,CAAC,CAACA,MAAM;EACrB;;EAEA;EACA,IAAIC,QAAQA,CAAA,EAAmC;IAC7C,OAAO,IAAI,CAAC,CAACA,QAAQ;EACvB;;EAEA;EACA,IAAIM,WAAWA,CAAA,EAA4B;IACzC,OAAO,IAAI,CAAC,CAACL,eAAe;EAC9B;;EAEA;EACA,IAAIC,QAAQA,CAAA,EAAW;IACrB,OAAO,IAAI,CAAC,CAACA,QAAQ;EACvB;;EAEA;AACF;AACA;AACA;AACA;AACA;EACEK,cAAcA,CAACC,IAAiB,EAAQ;IACtC,IACE,IAAI,CAAC,CAACP,eAAe,KAAKQ,SAAS,IACnC,IAAI,CAAC,CAACR,eAAe,CAACS,KAAK,KAAKF,IAAI,CAACE,KAAK,IAC1C,IAAI,CAAC,CAACT,eAAe,CAACU,MAAM,KAAKH,IAAI,CAACG,MAAM,EAC5C;MACA;IACF;IACA,IAAI,CAAC,CAACV,eAAe,GAAGW,MAAM,CAACC,MAAM,CAAC;MAAEH,KAAK,EAAEF,IAAI,CAACE,KAAK;MAAEC,MAAM,EAAEH,IAAI,CAACG;IAAO,CAAC,CAAC;IACjF,IAAI,CAAC,CAACX,QAAQ,GAAGH,iBAAiB,CAAC,IAAI,CAAC,CAACE,MAAM,EAAES,IAAI,CAAC;IACtD,IAAI,CAAC,CAACN,QAAQ,IAAI,CAAC;IACnB,KAAK,MAAMY,QAAQ,IAAI,CAAC,GAAG,IAAI,CAAC,CAACX,SAAS,CAAC,EAAE;MAC3CW,QAAQ,CAAC,CAAC;IACZ;EACF;;EAEA;EACAC,SAASA,CAACD,QAAoB,EAAc;IAC1C,IAAI,CAAC,CAACX,SAAS,CAACa,GAAG,CAACF,QAAQ,CAAC;IAC7B,IAAIG,OAAO,GAAG,KAAK;IACnB,OAAO,MAAM;MACX,IAAIA,OAAO,EAAE;QACX;MACF;MACAA,OAAO,GAAG,IAAI;MACd,IAAI,CAAC,CAACd,SAAS,CAACe,MAAM,CAACJ,QAAQ,CAAC;IAClC,CAAC;EACH;;EAEA;AACF;AACA;AACA;AACA;EACEK,OAAOA,CAAA,EAAS;IACd,IAAI,CAAC,CAAChB,SAAS,CAACiB,KAAK,CAAC,CAAC;EACzB;AACF;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,kBAAkBA,CAChCtB,MAAgB,EAChBuB,QAAgC,EACf;EACjB,IAAIA,QAAQ,EAAEvB,MAAM,KAAKA,MAAM,EAAE;IAC/B,OAAOuB,QAAQ;EACjB;EAEA,MAAMC,WAAW,GAAG,IAAIzB,eAAe,CAACC,MAAM,CAAC;EAC/C,IAAIuB,QAAQ,EAAEhB,WAAW,KAAKG,SAAS,EAAE;IACvCc,WAAW,CAAChB,cAAc,CAACe,QAAQ,CAAChB,WAAW,CAAC;EAClD;EACA,OAAOiB,WAAW;AACpB","ignoreList":[]}

package/lib/module/react.js

@@ -1,13 +1,24 @@
 "use strict";
 
 export { GameView } from "./react/GameView.js";
+export { useGameSession } from "./react/useGameSession.js";
+export { useGameSessionStatus } from "./react/useGameSessionStatus.js";
+export { createGameLifecycleSource, GameLifecycleProvider, useGameLifecycleSource } from "./react/lifecycleSource.js";
 export { createGameAssetStore } from "./react/assets/decodeSkiaImage.js";
 export { useGameAssets, stableGroupsKey } from "./react/assets/useGameAssets.js";
-export { GameWorld2D, viewportTransform } from "./react/sprites/GameWorld2D.js";
+export { GameWorld2D, viewportTransform, cameraViewportTransform2D, layerParallaxTransform2D } from "./react/sprites/GameWorld2D.js";
+export { GameLayer2D } from "./react/camera2d/GameLayer2D.js";
+export { defineGameCamera2D } from "./react/camera2d/defineGameCamera2D.js";
 export { Sprite, resolveSpriteFrameRect } from "./react/sprites/Sprite.js";
 export { GameSprite, spriteFrameNameForClip } from "./react/sprites/GameSprite.js";
 export { SpriteBatch } from "./react/sprites/SpriteBatch.js";
 export { computeSpriteRsxform, spriteAnchorWorld, spriteGroupCorrection } from "./react/sprites/spriteTransform.js";
 export { createGameAssetStoreCore } from "./react/assets/createGameAssetStore.js";
 export { GamePointerInput } from "./react/GamePointerInput.js";
+export { GameButtonPad, GameButton } from "./react/GameButtonPad.js";
+export { ParticleView } from "./react/particles/ParticleView.js";
+export { useParticlePresentation } from "./react/particles/useParticlePresentation.js";
+export { particleSpriteXform, assertUniformParticleSpriteRatio } from "./react/particles/spriteXForm.js";
+export { cameraVisibleWorldBounds, visibleInBounds, PARTICLE_CULL_PADDING } from "./react/particles/culling.js";
+export { TileMapLayer2D } from "./react/tilemap/TileMapLayer2D.js";
 //# sourceMappingURL=react.js.map

package/lib/module/react.js.map

@@ -1 +1 @@
-{"version":3,"names":["GameView","createGameAssetStore","useGameAssets","stableGroupsKey","GameWorld2D","viewportTransform","Sprite","resolveSpriteFrameRect","GameSprite","spriteFrameNameForClip","SpriteBatch","computeSpriteRsxform","spriteAnchorWorld","spriteGroupCorrection","createGameAssetStoreCore","GamePointerInput"],"sourceRoot":"../../src","sources":["react.ts"],"mappings":";;AAAA,SAASA,QAAQ,QAAQ,qBAAkB;AAC3C,SAASC,oBAAoB,QAAQ,mCAAgC;AACrE,SAASC,aAAa,EAAEC,eAAe,QAAQ,iCAA8B;AAE7E,SAASC,WAAW,EAAEC,iBAAiB,QAAQ,gCAA6B;AAC5E,SAASC,MAAM,EAAEC,sBAAsB,QAAQ,2BAAwB;AAEvE,SAASC,UAAU,EAAEC,sBAAsB,QAAQ,+BAA4B;AAM/E,SAASC,WAAW,QAAQ,gCAA6B;AAEzD,SACEC,oBAAoB,EACpBC,iBAAiB,EACjBC,qBAAqB,QAChB,oCAAiC;AAMxC,SAASC,wBAAwB,QAAQ,wCAAqC;AAS9E,SAASC,gBAAgB,QAAQ,6BAA0B","ignoreList":[]}
+{"version":3,"names":["GameView","useGameSession","useGameSessionStatus","createGameLifecycleSource","GameLifecycleProvider","useGameLifecycleSource","createGameAssetStore","useGameAssets","stableGroupsKey","GameWorld2D","viewportTransform","cameraViewportTransform2D","layerParallaxTransform2D","GameLayer2D","defineGameCamera2D","Sprite","resolveSpriteFrameRect","GameSprite","spriteFrameNameForClip","SpriteBatch","computeSpriteRsxform","spriteAnchorWorld","spriteGroupCorrection","createGameAssetStoreCore","GamePointerInput","GameButtonPad","GameButton","ParticleView","useParticlePresentation","particleSpriteXform","assertUniformParticleSpriteRatio","cameraVisibleWorldBounds","visibleInBounds","PARTICLE_CULL_PADDING","TileMapLayer2D"],"sourceRoot":"../../src","sources":["react.ts"],"mappings":";;AAAA,SAASA,QAAQ,QAAQ,qBAAkB;AAC3C,SAASC,cAAc,QAAQ,2BAAwB;AACvD,SAASC,oBAAoB,QAAQ,iCAA8B;AACnE,SAASC,yBAAyB,EAAEC,qBAAqB,EAAEC,sBAAsB,QAAQ,4BAAyB;AAElH,SAASC,oBAAoB,QAAQ,mCAAgC;AACrE,SAASC,aAAa,EAAEC,eAAe,QAAQ,iCAA8B;AAE7E,SAASC,WAAW,EAAEC,iBAAiB,EAAEC,yBAAyB,EAAEC,wBAAwB,QAAQ,gCAA6B;AACjI,SAASC,WAAW,QAAQ,iCAA8B;AAC1D,SAASC,kBAAkB,QAAQ,wCAAqC;AAExE,SAASC,MAAM,EAAEC,sBAAsB,QAAQ,2BAAwB;AAEvE,SAASC,UAAU,EAAEC,sBAAsB,QAAQ,+BAA4B;AAM/E,SAASC,WAAW,QAAQ,gCAA6B;AAEzD,SACEC,oBAAoB,EACpBC,iBAAiB,EACjBC,qBAAqB,QAChB,oCAAiC;AAMxC,SAASC,wBAAwB,QAAQ,wCAAqC;AAS9E,SAASC,gBAAgB,QAAQ,6BAA0B;AAE3D,SAASC,aAAa,EAAEC,UAAU,QAAQ,0BAAuB;AAGjE,SAASC,YAAY,QAAQ,mCAAgC;AAE7D,SAASC,uBAAuB,QAAQ,8CAA2C;AAEnF,SAASC,mBAAmB,EAAEC,gCAAgC,QAAQ,kCAA+B;AACrG,SAASC,wBAAwB,EAAEC,eAAe,EAAEC,qBAAqB,QAAQ,8BAA2B;AAC5G,SAASC,cAAc,QAAQ,mCAAgC","ignoreList":[]}

package/lib/module/scene/defineScene.js

@@ -4,6 +4,23 @@
  * 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({

package/lib/module/scene/defineScene.js.map

@@ -1 +1 @@
-{"version":3,"names":["defineScene","definition","kind"],"sourceRoot":"../../../src","sources":["scene/defineScene.ts"],"mappings":";;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASA,WAAWA,CAMzBC,UAGuE,EACK;EAC5E,OAAO;IACLC,IAAI,EAAE,eAAe;IACrB,GAAGD;EACL,CAAC;AACH","ignoreList":[]}
+{"version":3,"names":["defineScene","definition","kind"],"sourceRoot":"../../../src","sources":["scene/defineScene.ts"],"mappings":";;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASA,WAAWA,CAQzBC,UAyBC,EACuG;EACxG,OAAO;IACLC,IAAI,EAAE,eAAe;IACrB,GAAGD;EACL,CAAC;AACH","ignoreList":[]}