@jgengine/shell 0.38.0 → 0.38.2

package/CHANGELOG.md

@@ -26,6 +26,53 @@ At publish, rename this heading to the new version and mirror the entries into
 `packages/core/src/meta/changelog.ts` (the typed `CHANGELOG` export).
 -->
 
+## 0.38.2
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.38.2`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.35.2`; `@jgengine/github` is `0.25.2`.
+
+### Added
+
+- `requestSceneCapture` and `requestSceneThumbnail` (`@jgengine/shell/render/sceneCapture`) ask the live scene for a frame or a save-card thumbnail. A request waits for `SceneCaptureBinding` to mount, waits for the canvas to paint, retries a blank read and resolves with the image or a stated failure (`no-binding`, `no-frame`, `undecodable`), so a game stops polling for the binding and waiting frames before a save screenshot.
+- `registerSceneCapture` (`@jgengine/shell/render/sceneCapture`) lets a host that owns its own canvas hand the capture path a reader.
+- `createDownedState` (`@jgengine/core/combat/downed`) exposes `restore(next)`, the counterpart to `snapshot()`, so a saved bleed-out resumes with the same remaining seconds, revive progress, phase and banner timer instead of being rebuilt around a guessed countdown.
+
+### Changed
+
+- Pin Games to the 0.38.1 adoption
+- `GameMenu`'s `style` and `detailStyle` accept `--jg-*` custom properties (`GameMenuStyle`), so a game passes `{ "--jg-menu-surface-radius": "12px" }` without a cast.
+- `GameMenu` sets `pointer-events: auto` on its own root while its painted backdrop stays `none`, so a menu inside a HUD wrapper that passes clicks through to the scene no longer has dead buttons.
+- `check-stateful-ratchet` skips a factory carrying `// stateless: <reason>`, the named case for a catalog whose only closure state is an index of its own config. `createBuildSocketCatalog` declares it instead of being baselined.
+
+### Fixed
+
+- `bun run shoot` refuses a scene shot whose page has no 3D canvas, and scores rendered geometry inside the canvas region before writing the file. `bun run shoot <game> --view <name>` defaults to `--mode ui`, which renders the game's HUD preview over a CSS backdrop and creates no canvas; the whole-frame flat test was skipped without a region and the backdrop's full-screen paint withheld the viewport verdict, so a HUD-only frame was written with exit 0.
+- `countStaticBatchDraws` (`@jgengine/shell/world/staticObjectBatches`) counts the draws the static batches submit, so a variant level with no instance in a cell and a cell the camera culled are no longer reported as draws. `submitInstanceCount` (`@jgengine/shell/render/submittedDraws`) is the one place the batch, scatter, proxy and authored-primitive paths set an instance count and its visibility, and three issues a draw only when both say there is something to draw.
+- `createCastRunner.state()` carries the cast's `moveTolerance`, `moveDeadzone` and `movedTotal`, and `restore(next)` resumes it. A cast saved mid-fight used to come back with a fresh movement budget, so the caster could walk further than the ability allowed.
+- `createDecayMeterSet.serialize()` / `restore(next)` carry each meter's value, base rate and `setRateModifier` multiplier. A save used to drop a tuned rate, so a cold biome's faster warmth drain reset to the config rate on load.
+- `createAreaEffectField.restore(state)`, `createSelectionBookmarks.restore(snapshot)` and `createPlotPermissions.restore(snapshot)` are the state-in counterparts to their existing `serialize()` / `snapshot()`; restoring into a live field releases the members the saved state does not carry.
+- `check-stateful-ratchet` names the round-trip gap separately and caps it: a `snapshot()` with no `restore()`/`reset()` fails as `round-trip` debt, `--write` refuses to raise that ceiling, and a group paid below its ceiling must lower it. `createDownedState` was baselined when the ratchet shipped and never revisited; the restores in this release take the baseline from 113 entries to 93 and the `round-trip` ceiling from 8 to 2.
+
+## 0.38.1
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.38.1`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.35.1`; `@jgengine/github` is `0.25.1`.
+- Nothing to migrate. `variantLevels()` was renamed to `ModelVariantConfig.shadows` before any release shipped it, so no published version ever exported it and no consumer can be holding one. A level that wants to stop paying the near level's shadow cost writes `{ url, shadows: "none" }`; leaving `shadows` out keeps the model's own answer.
+
+### Added
+
+- `ModelVariantConfig.shadows` (`@jgengine/core/world/modelLod`): a model variant level declares its own shadow participation as a plain field, `"inherit" | "cast" | "receive" | "both" | "none"`. `"inherit"`, the default, keeps the model's own `shadows`, so every existing model draws as before; a far level set to `"none"` leaves the shadow pass while still drawing its mesh.
+- `ModelShadowMode` (`@jgengine/core/world/modelLod`) names the four-value shadow vocabulary, and `ModelConfig.shadows` uses it.
+- `variantLevelModel` (`@jgengine/shell/render/singleVariantLod`) is the one place that resolves what a level draws and how it shadows; the single prop, batched prop and scatter paths all ask it, so a level's asset and its shadow answer cannot disagree.
+
+### Fixed
+
+- `SaveSlotsPane` cards are one box each: equal tracks, `grid-auto-rows: 1fr`, a card edge that reads over a bright scene, and a name that ellipsises instead of widening the card. A save with a long name and one with none produce the same card box.
+- `GameMenu` puts the primary verbs on their own scrim, so their labels stay legible over whatever the live scene is showing instead of relying on a text shadow.
+- The theme emits three menu tokens the slot card and the verb surface read: `--jg-menu-card-height` (`clamp(244px, 27vh, 300px)`), `--jg-menu-card-thumb` (`clamp(88px, 14vh, 160px)`) and `--jg-menu-surface-radius` (`8px`). A game overrides them in its own `HudTheme` instead of patching the menu components.
+
 ## 0.38.0
 
 ### Migrate

package/dist/render/SceneModels.js

@@ -17,7 +17,7 @@ import { useFootIk } from "./useFootIk.js";
 import { resolveRigNode } from "./rigNode.js";
 import { PartMotionRig } from "./PartMotion.js";
 import { syncSpriteFrame } from "./spriteRender.js";
-import { singleVariantLevel, singleVariantModel } from "./singleVariantLod.js";
+import { singleVariantLevel, variantLevelModel } from "./singleVariantLod.js";
 import { applyMaterialOverride } from "../materialOverride.js";
 import { applyPaintTextureToMaterials, cacheStandardMaterials, cloneModelScene, createPaintCanvas, disposeModelScene, ownModelMaterial, disposePaintCanvas, syncPaintCanvas, } from "./modelRender.js";
 export function EntitySprite({ sprite }) {
@@ -123,7 +123,7 @@ export function SingleVariantModel({ model, instanceId, measure, }) {
         if (next !== level)
             setLevel(next);
     });
-    const drawn = useMemo(() => singleVariantModel(model, level), [model, level]);
+    const drawn = useMemo(() => variantLevelModel(model, level), [model, level]);
     // The near level owns the measured bounds and collision mesh, like the batched path: a decimated
     // asset must not redefine what the catalog entry collides as.
     return _jsx(EntityModel, { model: drawn, instanceId: instanceId, measure: level === 0 ? measure : undefined });

package/dist/render/levelPass.d.ts

@@ -0,0 +1,69 @@
+import type * as THREE from "three";
+import type { SceneObject } from "@jgengine/core/scene/objectStore";
+import type { ModelVariantLodConfig, ModelVariantSelector } from "@jgengine/core/world/modelLod";
+import type { SystemProbe } from "@jgengine/core/devtools/types";
+/**
+ * Metres of camera travel a path tolerates before it re-runs its level pass when it cannot tell how
+ * close an instance sits to a switch edge. The scatter path passes this as its margin; a path that
+ * knows the switch distances passes their real margin instead.
+ * @internal
+ */
+export declare const LEVEL_PASS_MIN_CAMERA_MOVE = 0.5;
+/** Count one frame a level pass was offered. @internal */
+export declare function noteLevelPassFrame(): void;
+/** Count one level pass that ran or was skipped. @internal */
+export declare function noteLevelPass(ran: boolean): void;
+/** Clear the level pass counters. For tests and between capture runs. @internal */
+export declare function resetLevelPassStats(): void;
+/**
+ * The level-pass system probe: how many per-instance variant level passes ran, how many the
+ * camera-unchanged skip removed, and the per-frame average. `debug_snapshot().systems` names the CPU
+ * cost a still or distant camera no longer pays instead of leaving it to a profile.
+ * @internal
+ */
+export declare function levelPassProbe(): SystemProbe;
+/**
+ * True when the camera has moved far enough that some instance's level could differ from the last
+ * pass. Moving the camera by `d` changes every instance distance by at most `d`, so a pass whose
+ * smallest margin to a switch edge was `margin` cannot change until the camera moves that far. A
+ * margin of `0` (an instance sitting on its edge) always runs.
+ * @internal
+ */
+export declare function levelPassNeeded(last: THREE.Vector3, camera: THREE.Vector3, margin: number): boolean;
+/** Holds the last pass's camera position and its distance to the nearest switch edge. @internal */
+export interface LevelPassGate {
+    /** True when this frame's pass could change an answer, or when no pass has run yet. */
+    needsPass(camera: THREE.Vector3): boolean;
+    /** Record a pass that ran: its camera position and the smallest margin it measured. */
+    record(camera: THREE.Vector3, margin: number): void;
+    /** Forget the last pass, so the next frame runs one. */
+    invalidate(): void;
+}
+/** A skip gate for one batch's level pass. @internal */
+export declare function createLevelPassGate(): LevelPassGate;
+/**
+ * A model's switch edges as the level pass measures against them: one finite boundary per level
+ * below the last, and the hysteresis an instance must clear before it crosses one.
+ * @internal
+ */
+export interface VariantSwitch {
+    readonly boundaries: readonly number[];
+    readonly hysteresis: number;
+}
+/** Read a model's variant config as {@link VariantSwitch}. @internal */
+export declare function variantSwitchOf(variants: ModelVariantLodConfig): VariantSwitch;
+/**
+ * Metres from one instance's distance to the nearest distance at which its level would change: the
+ * level's own boundary plus the hysteresis going out, the level below's boundary minus it coming
+ * back. Zero means the instance sits on its edge.
+ * @internal
+ */
+export declare function levelEdgeMargin(distance: number, level: number, variantSwitch: VariantSwitch): number;
+/**
+ * One batch's per-instance level pass: asks the shared {@link ModelVariantSelector} for every live
+ * instance's level at its camera distance, writes the answers into `into`, and returns the smallest
+ * margin any instance had to its switch edge so the caller can skip the next pass that cannot change
+ * an answer.
+ * @internal
+ */
+export declare function assignVariantLevels(selector: ModelVariantSelector, variantSwitch: VariantSwitch, objects: readonly SceneObject[], live: (id: string) => SceneObject | null, camera: THREE.Vector3, into: Map<string, number>, probe: THREE.Vector3): number;

package/dist/render/levelPass.js

@@ -0,0 +1,129 @@
+import { DEFAULT_VARIANT_HYSTERESIS } from "@jgengine/core/world/modelLod";
+/**
+ * Metres of camera travel a path tolerates before it re-runs its level pass when it cannot tell how
+ * close an instance sits to a switch edge. The scatter path passes this as its margin; a path that
+ * knows the switch distances passes their real margin instead.
+ * @internal
+ */
+export const LEVEL_PASS_MIN_CAMERA_MOVE = 0.5;
+let passes = 0;
+let skips = 0;
+let frames = 0;
+/** Count one frame a level pass was offered. @internal */
+export function noteLevelPassFrame() {
+    frames += 1;
+}
+/** Count one level pass that ran or was skipped. @internal */
+export function noteLevelPass(ran) {
+    if (ran)
+        passes += 1;
+    else
+        skips += 1;
+}
+/** Clear the level pass counters. For tests and between capture runs. @internal */
+export function resetLevelPassStats() {
+    passes = 0;
+    skips = 0;
+    frames = 0;
+}
+function readLevelPass() {
+    const perFrame = frames === 0 ? 0 : Math.round((passes / frames) * 100) / 100;
+    return {
+        counters: { levelPasses: passes, levelPassSkips: skips, levelPassFrames: frames, levelPassesPerFrame: perFrame },
+        line: `${passes} level passes / ${frames} frames (${perFrame}/frame) � ${skips} skipped`,
+    };
+}
+/**
+ * The level-pass system probe: how many per-instance variant level passes ran, how many the
+ * camera-unchanged skip removed, and the per-frame average. `debug_snapshot().systems` names the CPU
+ * cost a still or distant camera no longer pays instead of leaving it to a profile.
+ * @internal
+ */
+export function levelPassProbe() {
+    return {
+        counters: () => readLevelPass().counters,
+        state: () => readLevelPass().line,
+    };
+}
+/**
+ * True when the camera has moved far enough that some instance's level could differ from the last
+ * pass. Moving the camera by `d` changes every instance distance by at most `d`, so a pass whose
+ * smallest margin to a switch edge was `margin` cannot change until the camera moves that far. A
+ * margin of `0` (an instance sitting on its edge) always runs.
+ * @internal
+ */
+export function levelPassNeeded(last, camera, margin) {
+    return camera.distanceToSquared(last) >= margin * margin;
+}
+/** A skip gate for one batch's level pass. @internal */
+export function createLevelPassGate() {
+    let x = 0;
+    let y = 0;
+    let z = 0;
+    let margin = 0;
+    let recorded = false;
+    return {
+        needsPass(camera) {
+            if (!recorded)
+                return true;
+            const dx = camera.x - x;
+            const dy = camera.y - y;
+            const dz = camera.z - z;
+            return dx * dx + dy * dy + dz * dz >= margin * margin;
+        },
+        record(camera, next) {
+            x = camera.x;
+            y = camera.y;
+            z = camera.z;
+            margin = next;
+            recorded = true;
+        },
+        invalidate() {
+            recorded = false;
+        },
+    };
+}
+/** Read a model's variant config as {@link VariantSwitch}. @internal */
+export function variantSwitchOf(variants) {
+    const boundaries = [];
+    for (let index = 0; index < variants.levels.length - 1; index += 1) {
+        boundaries.push(variants.levels[index].maxDistance);
+    }
+    return { boundaries, hysteresis: Math.max(0, variants.hysteresis ?? DEFAULT_VARIANT_HYSTERESIS) };
+}
+/**
+ * Metres from one instance's distance to the nearest distance at which its level would change: the
+ * level's own boundary plus the hysteresis going out, the level below's boundary minus it coming
+ * back. Zero means the instance sits on its edge.
+ * @internal
+ */
+export function levelEdgeMargin(distance, level, variantSwitch) {
+    const { boundaries, hysteresis } = variantSwitch;
+    let margin = Number.POSITIVE_INFINITY;
+    if (level < boundaries.length)
+        margin = Math.abs(distance - (boundaries[level] + hysteresis));
+    if (level > 0)
+        margin = Math.min(margin, Math.abs(distance - (boundaries[level - 1] - hysteresis)));
+    return margin;
+}
+/**
+ * One batch's per-instance level pass: asks the shared {@link ModelVariantSelector} for every live
+ * instance's level at its camera distance, writes the answers into `into`, and returns the smallest
+ * margin any instance had to its switch edge so the caller can skip the next pass that cannot change
+ * an answer.
+ * @internal
+ */
+export function assignVariantLevels(selector, variantSwitch, objects, live, camera, into, probe) {
+    let margin = Number.POSITIVE_INFINITY;
+    for (const object of objects) {
+        const current = live(object.instanceId) ?? object;
+        probe.set(current.position[0] ?? 0, current.position[1] ?? 0, current.position[2] ?? 0);
+        const distance = camera.distanceTo(probe);
+        const level = selector.level(object.instanceId, distance);
+        into.set(object.instanceId, level);
+        const edge = levelEdgeMargin(distance, level, variantSwitch);
+        if (edge < margin)
+            margin = edge;
+    }
+    return margin;
+}

package/dist/render/sceneCapture.d.ts

@@ -1,3 +1,5 @@
+export { registerSceneCapture, requestSceneCapture, requestSceneThumbnail, } from "./sceneCaptureRequest.js";
+export type { SceneCapture, SceneCaptureFailure, SceneCaptureRequestOptions, SceneCaptureResult, SceneThumbnailResult, } from "./sceneCaptureRequest.js";
 /** The bit of a WebGL renderer scene capture needs — its backing `<canvas>`. */
 export interface CaptureRenderer {
     domElement: {
@@ -16,12 +18,15 @@ export declare function captureCanvas(gl: CaptureRenderer): string | null;
 export declare function downloadImage(dataUrl: string, filename?: string): void;
 /**
  * In-`<Canvas>` binder that hands the scene-capture function out to HUD code
- * living outside the reconciler (a photo-mode Capture button). Mount it inside
- * the game's `WorldOverlay`; call `bind` receives a `() => string | null` that
- * grabs the current frame. Renders nothing.
+ * living outside the reconciler (a photo-mode Capture button, a save slot's
+ * thumbnail). Mount it inside the game's `WorldOverlay`; the reader is
+ * registered for `requestSceneCapture`/`requestSceneThumbnail`, which wait for
+ * this mount and the first painted frame. `bind` is for code that wants the
+ * function directly and can be left out when a game only requests captures.
+ * Renders nothing.
  *
- * @capability scene-capture-binding expose the in-Canvas scene-capture function to outside-Canvas HUD (photo mode)
+ * @capability scene-capture-binding expose the in-Canvas scene-capture function to outside-Canvas HUD (photo mode, save thumbnails)
  */
-export declare function SceneCaptureBinding({ bind }: {
-    bind: (capture: () => string | null) => void;
+export declare function SceneCaptureBinding({ bind }?: {
+    bind?: (capture: () => string | null) => void;
 }): null;

package/dist/render/sceneCapture.js

@@ -1,5 +1,7 @@
 import { useThree } from "@react-three/fiber";
 import { useEffect } from "react";
+import { registerSceneCapture } from "./sceneCaptureRequest.js";
+export { registerSceneCapture, requestSceneCapture, requestSceneThumbnail, } from "./sceneCaptureRequest.js";
 /**
  * Read the current frame to a PNG data URL. Requires the R3F `<Canvas>` to have
  * been created with `gl={{ preserveDrawingBuffer: true }}` (the shell's game
@@ -27,17 +29,25 @@ export function downloadImage(dataUrl, filename = "screenshot.png") {
 }
 /**
  * In-`<Canvas>` binder that hands the scene-capture function out to HUD code
- * living outside the reconciler (a photo-mode Capture button). Mount it inside
- * the game's `WorldOverlay`; call `bind` receives a `() => string | null` that
- * grabs the current frame. Renders nothing.
+ * living outside the reconciler (a photo-mode Capture button, a save slot's
+ * thumbnail). Mount it inside the game's `WorldOverlay`; the reader is
+ * registered for `requestSceneCapture`/`requestSceneThumbnail`, which wait for
+ * this mount and the first painted frame. `bind` is for code that wants the
+ * function directly and can be left out when a game only requests captures.
+ * Renders nothing.
  *
- * @capability scene-capture-binding expose the in-Canvas scene-capture function to outside-Canvas HUD (photo mode)
+ * @capability scene-capture-binding expose the in-Canvas scene-capture function to outside-Canvas HUD (photo mode, save thumbnails)
  */
-export function SceneCaptureBinding({ bind }) {
+export function SceneCaptureBinding({ bind } = {}) {
     const gl = useThree((state) => state.gl);
     useEffect(() => {
-        bind(() => captureCanvas(gl));
-        return () => bind(() => null);
+        const capture = () => captureCanvas(gl);
+        const unbind = registerSceneCapture(capture);
+        bind?.(capture);
+        return () => {
+            unbind();
+            bind?.(() => null);
+        };
     }, [gl, bind]);
     return null;
 }

package/dist/render/sceneCaptureRequest.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Asking the live scene for a frame without owning the canvas. A game mounts the
+ * {@link import("./sceneCapture.js").SceneCaptureBinding} once and then requests a thumbnail when it
+ * saves. The request survives the two ways a hand-written capture goes blank — the binding mounting
+ * after the save screen rendered, and reading the canvas before its first painted frame — so no game
+ * polls for the binding or waits frames of its own.
+ */
+import { type SaveThumbnailOptions } from "@jgengine/react/saveThumbnail";
+/** Reads the current scene frame as an image data URL, or null when the frame cannot be read. */
+export type SceneCapture = () => string | null;
+/** Why a capture request produced no image. */
+export type SceneCaptureFailure = "no-binding" | "no-frame" | "undecodable";
+/** A captured frame, or the stated reason there is none. */
+export type SceneCaptureResult = {
+    ok: true;
+    capture: string;
+} | {
+    ok: false;
+    reason: SceneCaptureFailure;
+};
+/** A save-card thumbnail, or the stated reason there is none. */
+export type SceneThumbnailResult = {
+    ok: true;
+    thumbnail: string;
+} | {
+    ok: false;
+    reason: SceneCaptureFailure;
+};
+/** How a capture request waits and retries. */
+export interface SceneCaptureRequestOptions {
+    /**
+     * How long to wait for a capture binding to mount, in milliseconds. Default 5000. A game that
+     * never mounts the binding gets `"no-binding"` instead of a request that never settles.
+     */
+    bindingTimeoutMs?: number;
+    /**
+     * Painted frames to wait after the binding appears before reading, so the read lands after the
+     * canvas has drawn at least once. Default 2, which is one paint.
+     */
+    settleFrames?: number;
+    /** Reads attempted on later frames before reporting `"no-frame"`. Default 3. */
+    attempts?: number;
+}
+/**
+ * Hand the capture path a reader for the live frame, or `null` to retire it. The returned function
+ * unbinds only that reader, so a canvas that remounts cannot be unbound by its predecessor.
+ */
+export declare function registerSceneCapture(capture: SceneCapture | null): () => void;
+/**
+ * Request the current scene frame. Resolves once a binding exists and the canvas has painted, or
+ * with the reason no frame could be read; it never polls and never rejects.
+ *
+ * @capability request-scene-capture request the live scene frame, waiting for a late binding and the first painted frame
+ */
+export declare function requestSceneCapture(options?: SceneCaptureRequestOptions): Promise<SceneCaptureResult>;
+/**
+ * Request a save-card thumbnail from the live scene: the shared capture request, then
+ * `shrinkCapture`. Pass what the slot card stores; omit everything for a 320x180 JPEG.
+ *
+ * @capability request-scene-thumbnail request a save-card thumbnail from the live scene, or a stated failure
+ */
+export declare function requestSceneThumbnail(options?: SceneCaptureRequestOptions & SaveThumbnailOptions): Promise<SceneThumbnailResult>;

package/dist/render/sceneCaptureRequest.js

@@ -0,0 +1,112 @@
+/**
+ * Asking the live scene for a frame without owning the canvas. A game mounts the
+ * {@link import("./sceneCapture.js").SceneCaptureBinding} once and then requests a thumbnail when it
+ * saves. The request survives the two ways a hand-written capture goes blank — the binding mounting
+ * after the save screen rendered, and reading the canvas before its first painted frame — so no game
+ * polls for the binding or waits frames of its own.
+ */
+import { shrinkCapture } from "@jgengine/react/saveThumbnail";
+/** The registered reader, and the requests waiting for one to appear. */
+let bound = null;
+const waiting = new Set();
+/**
+ * Hand the capture path a reader for the live frame, or `null` to retire it. The returned function
+ * unbinds only that reader, so a canvas that remounts cannot be unbound by its predecessor.
+ */
+export function registerSceneCapture(capture) {
+    bound = capture;
+    if (capture !== null) {
+        for (const resolve of [...waiting]) {
+            waiting.delete(resolve);
+            resolve(capture);
+        }
+    }
+    return () => {
+        if (bound === capture)
+            bound = null;
+    };
+}
+function settleFrames(count) {
+    if (typeof requestAnimationFrame !== "function")
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        let remaining = count;
+        const step = () => {
+            remaining -= 1;
+            if (remaining <= 0)
+                resolve();
+            else
+                requestAnimationFrame(step);
+        };
+        requestAnimationFrame(step);
+    });
+}
+function waitForBinding(timeoutMs) {
+    if (bound !== null)
+        return Promise.resolve(bound);
+    return new Promise((resolve) => {
+        let settled = false;
+        let timer;
+        const settle = (capture) => {
+            if (settled)
+                return;
+            settled = true;
+            waiting.delete(onReady);
+            if (timer !== undefined)
+                clearTimeout(timer);
+            resolve(capture);
+        };
+        const onReady = (capture) => settle(capture);
+        waiting.add(onReady);
+        timer = setTimeout(() => settle(null), timeoutMs);
+    });
+}
+function read(capture) {
+    try {
+        const image = capture();
+        return typeof image === "string" && image.startsWith("data:image") ? image : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Request the current scene frame. Resolves once a binding exists and the canvas has painted, or
+ * with the reason no frame could be read; it never polls and never rejects.
+ *
+ * @capability request-scene-capture request the live scene frame, waiting for a late binding and the first painted frame
+ */
+export async function requestSceneCapture(options = {}) {
+    const capture = await waitForBinding(options.bindingTimeoutMs ?? 5000);
+    if (capture === null)
+        return { ok: false, reason: "no-binding" };
+    await settleFrames(options.settleFrames ?? 2);
+    const attempts = options.attempts ?? 3;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        const image = read(capture);
+        if (image !== null)
+            return { ok: true, capture: image };
+        if (attempt < attempts - 1)
+            await settleFrames(1);
+    }
+    return { ok: false, reason: "no-frame" };
+}
+/**
+ * Request a save-card thumbnail from the live scene: the shared capture request, then
+ * `shrinkCapture`. Pass what the slot card stores; omit everything for a 320x180 JPEG.
+ *
+ * @capability request-scene-thumbnail request a save-card thumbnail from the live scene, or a stated failure
+ */
+export async function requestSceneThumbnail(options = {}) {
+    const source = await requestSceneCapture(options);
+    if (!source.ok)
+        return source;
+    let thumbnail = null;
+    try {
+        thumbnail = await shrinkCapture(source.capture, options);
+    }
+    catch {
+        thumbnail = null;
+    }
+    return thumbnail === null ? { ok: false, reason: "undecodable" } : { ok: true, thumbnail };
+}

package/dist/render/singleVariantLod.d.ts

@@ -2,12 +2,19 @@ import type * as THREE from "three";
 import type { ModelConfig } from "@jgengine/core/game/playableGame";
 import type { ModelVariantSelector } from "@jgengine/core/world/modelLod";
 /**
- * The model an isolated prop draws at one variant level: that level's asset and no nested variants, so
- * a prop rendered on its own switches assets the way a batched instance does. Out-of-range levels clamp
- * to the nearest one, and a model without variants is returned untouched.
+ * Shadow participation the model draws with at one level: the level's own choice when it made one,
+ * otherwise the model's `shadows` untouched.
  * @internal
  */
-export declare function singleVariantModel(model: ModelConfig, level: number): ModelConfig;
+export declare function variantLevelShadows(model: ModelConfig, level: number): ModelConfig["shadows"];
+/**
+ * The model any path draws at one variant level: that level's asset, its shadow participation, and no
+ * nested variants, so a prop rendered on its own, a batched instance and a scatter cell all switch
+ * the same way. Out-of-range levels clamp to the nearest one, and a model without variants is
+ * returned untouched.
+ * @internal
+ */
+export declare function variantLevelModel(model: ModelConfig, level: number): ModelConfig;
 /**
  * Metres from the camera's world position to a placement, written through the caller's scratch vectors
  * so a frame allocates nothing.

package/dist/render/singleVariantLod.js

@@ -1,15 +1,36 @@
+function levelOf(model, level) {
+    const levels = model.variants?.levels;
+    if (levels === undefined)
+        return undefined;
+    return levels[Math.min(levels.length - 1, Math.max(0, level))];
+}
 /**
- * The model an isolated prop draws at one variant level: that level's asset and no nested variants, so
- * a prop rendered on its own switches assets the way a batched instance does. Out-of-range levels clamp
- * to the nearest one, and a model without variants is returned untouched.
+ * Shadow participation the model draws with at one level: the level's own choice when it made one,
+ * otherwise the model's `shadows` untouched.
  * @internal
  */
-export function singleVariantModel(model, level) {
-    const levels = model.variants?.levels;
-    if (levels === undefined)
+export function variantLevelShadows(model, level) {
+    const chosen = levelOf(model, level)?.shadows;
+    return chosen === undefined || chosen === "inherit" ? model.shadows : chosen;
+}
+/**
+ * The model any path draws at one variant level: that level's asset, its shadow participation, and no
+ * nested variants, so a prop rendered on its own, a batched instance and a scatter cell all switch
+ * the same way. Out-of-range levels clamp to the nearest one, and a model without variants is
+ * returned untouched.
+ * @internal
+ */
+export function variantLevelModel(model, level) {
+    const chosen = levelOf(model, level);
+    if (chosen === undefined)
         return model;
-    const chosen = levels[Math.min(levels.length - 1, Math.max(0, level))];
-    return { ...model, url: chosen.url, variants: undefined };
+    const shadows = variantLevelShadows(model, level);
+    return {
+        ...model,
+        url: chosen.url,
+        variants: undefined,
+        ...(shadows === undefined ? {} : { shadows }),
+    };
 }
 /**
  * Metres from the camera's world position to a placement, written through the caller's scratch vectors

package/dist/render/staticShapeInstances.js

@@ -3,6 +3,7 @@ import { Suspense, useLayoutEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
 import { AuthoredSurfaceMaterial, authoredSurfaceKey } from "./authoredSurfaceMaterial.js";
 import { ModelFallbackBoundary } from "./SceneModels.js";
+import { submitInstanceCount } from "./submittedDraws.js";
 import { useDisposable } from "./useDisposable.js";
 /** Plan compatible material/shape/shadow groups without changing authored transforms. @internal */
 export function groupStaticShapeInstances(instances) {
@@ -36,7 +37,7 @@ export function writeStaticShapeInstances(mesh, instances) {
         transform.updateMatrix();
         mesh.setMatrixAt(index, transform.matrix);
     });
-    mesh.count = instances.length;
+    submitInstanceCount(mesh, instances.length);
     if (mesh.geometry.boundingBox === null)
         mesh.geometry.computeBoundingBox();
     const heightSurface = instances[0]?.surface;

package/dist/render/submittedDraws.d.ts

@@ -0,0 +1,13 @@
+import type * as THREE from "three";
+/**
+ * What one instanced draw submits this frame. Three skips a draw whose instance count is zero and
+ * skips an invisible node, so the count and the visibility are one answer: every path that claims a
+ * subset of a batch's placements — a variant level, a species, a proxy, an authored primitive group —
+ * states it here, and one that holds nothing submits nothing.
+ * @internal
+ */
+export declare function submitInstanceCount(mesh: THREE.InstancedMesh, count: number): void;
+/** Whether three issues a draw for this node this frame: instanced, visible, and holding an instance. @internal */
+export declare function submitsDraw(node: THREE.Object3D): boolean;
+/** Instanced draws a subtree submits this frame, optionally only the nodes an owner tagged. @internal */
+export declare function countSubmittedDraws(root: THREE.Object3D, tag?: string): number;

package/dist/render/submittedDraws.js

@@ -0,0 +1,27 @@
+/**
+ * What one instanced draw submits this frame. Three skips a draw whose instance count is zero and
+ * skips an invisible node, so the count and the visibility are one answer: every path that claims a
+ * subset of a batch's placements — a variant level, a species, a proxy, an authored primitive group —
+ * states it here, and one that holds nothing submits nothing.
+ * @internal
+ */
+export function submitInstanceCount(mesh, count) {
+    mesh.count = count;
+    mesh.visible = count > 0;
+}
+/** Whether three issues a draw for this node this frame: instanced, visible, and holding an instance. @internal */
+export function submitsDraw(node) {
+    const mesh = node;
+    return mesh.isInstancedMesh === true && node.visible && mesh.count > 0;
+}
+/** Instanced draws a subtree submits this frame, optionally only the nodes an owner tagged. @internal */
+export function countSubmittedDraws(root, tag) {
+    let draws = 0;
+    root.traverse((node) => {
+        if (tag !== undefined && node.userData[tag] !== true)
+            return;
+        if (submitsDraw(node))
+            draws += 1;
+    });
+    return draws;
+}

package/dist/scatter/InstancedScatter.js

@@ -8,6 +8,9 @@ import { chunkScatterInstances } from "@jgengine/core/world/scatterRegion";
 import { beginFallbackSeam, reportFallbackSeam } from "@jgengine/core/devtools/fallbackSeams";
 import { createModelVariantSelector } from "@jgengine/core/world/modelLod";
 import { CAMERA_POST_FRAME_PRIORITY } from "../camera/cameraRigs.js";
+import { submitInstanceCount } from "../render/submittedDraws.js";
+import { LEVEL_PASS_MIN_CAMERA_MOVE, levelPassNeeded } from "../render/levelPass.js";
+import { variantLevelModel } from "../render/singleVariantLod.js";
 import { buildScatterProxy } from "./scatterProxies.js";
 import { buildScatterModelSources, disposeScatterModelSources } from "./scatterModels.js";
 import { writeScatterVariantLevel } from "./scatterVariants.js";
@@ -53,7 +56,7 @@ function ScatterBatchMesh({ batch, geometry }) {
             return;
         for (let i = 0; i < batch.matrices.length; i += 1)
             mesh.setMatrixAt(i, batch.matrices[i]);
-        mesh.count = batch.matrices.length;
+        submitInstanceCount(mesh, batch.matrices.length);
         mesh.instanceMatrix.needsUpdate = true;
         mesh.computeBoundingSphere();
     }, [batch]);
@@ -71,7 +74,7 @@ function ScatterModelSourceInstances({ source, matrices }) {
             composed.multiplyMatrices(matrices[i], source.localMatrix);
             mesh.setMatrixAt(i, composed);
         }
-        mesh.count = matrices.length;
+        submitInstanceCount(mesh, matrices.length);
         mesh.instanceMatrix.needsUpdate = true;
         mesh.computeBoundingSphere();
     }, [matrices, source]);
@@ -94,8 +97,7 @@ function ScatterVariantSourceInstances({ source, batch, level, selector }) {
         if (mesh === null)
             return;
         const count = writeScatterVariantLevel(level, selector, from, batch.instances, batch.matrices, source.localMatrix, slots);
-        mesh.count = count;
-        mesh.visible = count > 0;
+        submitInstanceCount(mesh, count);
         mesh.instanceMatrix.needsUpdate = true;
         if (count > 0)
             mesh.computeBoundingSphere();
@@ -107,7 +109,7 @@ function ScatterVariantSourceInstances({ source, batch, level, selector }) {
     }, [camera, writeLevel, cameraPosition]);
     useFrame((state) => {
         state.camera.getWorldPosition(cameraPosition);
-        if (cameraPosition.distanceToSquared(lastCamera.current) < 0.25)
+        if (!levelPassNeeded(lastCamera.current, cameraPosition, LEVEL_PASS_MIN_CAMERA_MOVE))
             return;
         lastCamera.current.copy(cameraPosition);
         writeLevel(cameraPosition);
@@ -120,9 +122,8 @@ function ScatterVariantLevel({ model, url, level, selector, batches }) {
         loader.setMeshoptDecoder(MeshoptDecoder);
     });
     const { sources, root } = useMemo(() => {
-        const levelModel = { ...model, url, variants: undefined };
-        return buildScatterModelSources(gltf.scene, levelModel);
-    }, [gltf, model, url]);
+        return buildScatterModelSources(gltf.scene, variantLevelModel(model, level));
+    }, [gltf, model, level]);
     useEffect(() => () => disposeScatterModelSources(root), [root]);
     return (_jsx(_Fragment, { children: sources.map((source, sourceIndex) => batches.map((batch) => (_jsx(ScatterVariantSourceInstances, { source: source, batch: batch, level: level, selector: selector }, `${batch.key}:${sourceIndex}`)))) }));
 }

package/dist/world/StaticObjectModels.d.ts

@@ -1,7 +1,6 @@
 import { type ReactNode } from "react";
 import * as THREE from "three";
 import type { SceneObject } from "@jgengine/core/scene/objectStore";
-import { type ModelVariantSelector } from "@jgengine/core/world/modelLod";
 import { type StaticObjectBatch } from "./staticObjectBatches.js";
 /**
  * Report what static object batching is doing to `debug_snapshot().systems`: the grouped batches, the
@@ -16,10 +15,10 @@ export declare function useStaticObjectBatchProbe(scene: THREE.Object3D, stats:
     singles: number;
 }): void;
 /** Members of one level drawn through the individual renderer, for a level whose asset cannot be instanced. @internal */
-export declare function LevelSingles({ objects, level, selector, single }: {
+export declare function LevelSingles({ objects, level, assignment, single }: {
     objects: readonly SceneObject[];
     level: number;
-    selector: ModelVariantSelector;
+    assignment: ReadonlyMap<string, number>;
     single: (object: SceneObject) => ReactNode;
 }): import("react").JSX.Element;
 /**

package/dist/world/StaticObjectModels.js

@@ -7,6 +7,8 @@ import { devtools } from "@jgengine/core/devtools/devtools";
 import { useGameContext } from "@jgengine/react/provider";
 import { sharedGltfLoader } from "../render/modelLoad.js";
 import { IsolatedModelPart } from "../render/SceneModels.js";
+import { variantLevelModel } from "../render/singleVariantLod.js";
+import { assignVariantLevels, createLevelPassGate, levelPassProbe, noteLevelPass, noteLevelPassFrame, variantSwitchOf } from "../render/levelPass.js";
 import { freezeStaticTransforms } from "../render/staticTransforms.js";
 import { measureLocalBounds, reportMeasuredBounds } from "../render/measureBounds.js";
 import { measureLocalCollisionTriangles, reportMeasuredCollisionMesh } from "../render/measureCollisionMesh.js";
@@ -31,6 +33,7 @@ export function useStaticObjectBatchProbe(scene, stats) {
             return `${ref.current.batches} batches · ${draws} draws · ${drawn}/${ref.current.instances} instances drawn`;
         },
     }), [scene]);
+    useEffect(() => devtools.probes.registerSystem("render/levelPass", levelPassProbe()), []);
 }
 /** Live members of one batch after the per-frame compatibility gate removed any that changed at runtime. */
 function useBatchMembers(batch) {
@@ -45,13 +48,11 @@ function useBatchMembers(batch) {
     const objects = useMemo(() => batch.objects.filter((object) => !excluded.includes(object.instanceId)), [batch, excluded]);
     return { objects, excluded };
 }
-function ObjectSource({ source, objects, batch, selector, level }) {
+function ObjectSource({ source, objects, batch, assignment, level }) {
     const ctx = useGameContext();
     const visibility = useRenderVisibility();
     const ref = useRef(null);
     const scratch = useMemo(() => new THREE.Object3D(), []);
-    const cameraPosition = useRef(new THREE.Vector3());
-    const probe = useMemo(() => new THREE.Vector3(), []);
     const attach = useCallback((mesh) => {
         ref.current = mesh;
         if (mesh !== null)
@@ -61,21 +62,18 @@ function ObjectSource({ source, objects, batch, selector, level }) {
         const mesh = ref.current;
         return () => { mesh?.dispose(); };
     }, [objects.length, source]);
-    useFrame((state) => {
+    useFrame(() => {
         if (ref.current === null)
             return;
-        let accept;
-        if (selector !== undefined && level !== undefined) {
-            const camera = cameraPosition.current;
-            state.camera.getWorldPosition(camera);
-            accept = (live) => selector.level(live.instanceId, camera.distanceTo(probe.set(live.position[0], live.position[1], live.position[2]))) === level;
-        }
+        const accept = assignment !== undefined && level !== undefined
+            ? (live) => assignment.get(live.instanceId) === level
+            : undefined;
         syncStaticObjectSource(ref.current, source, objects, (id) => {
             const object = ctx.scene.object.get(id);
             return object !== null && object.catalogId === batch.objects[0].catalogId &&
                 isCompatibleStaticObject(object, batch.model, ctx.scene.object.catalog(id)) ? object : null;
         }, visibility.current, scratch, accept);
-    }, CAMERA_POST_FRAME_PRIORITY + 0.1);
+    }, CAMERA_POST_FRAME_PRIORITY + 0.2);
     return _jsx("instancedMesh", { ref: attach, args: [source.geometry, source.material, objects.length], userData: { [STATIC_BATCH_MESH_KEY]: true }, castShadow: source.castShadow, receiveShadow: source.receiveShadow, dispose: null });
 }
 function LoadedStaticObjects({ batch, single }) {
@@ -111,7 +109,7 @@ function LoadedStaticObjects({ batch, single }) {
     return _jsxs(_Fragment, { children: [harvested.sources.map((source, index) => objects.length === 0 ? null : _jsx(ObjectSource, { source: source, objects: objects, batch: batch }, index)), excluded.map((id) => { const live = ctx.scene.object.get(id); return live === null ? null : single(live); })] });
 }
 /** One detail level's GLB, harvested into instanced draws that only claim the instances the selector put on this level. */
-function VariantLevel({ url, model, batch, objects, level, selector, measure, single }) {
+function VariantLevel({ url, model, batch, objects, level, assignment, measure, single }) {
     const ctx = useGameContext();
     const gltf = useLoader(sharedGltfLoader, url);
     const supported = useMemo(() => canInstanceStaticScene(gltf.scene, gltf.animations), [gltf]);
@@ -139,28 +137,24 @@ function VariantLevel({ url, model, batch, objects, level, selector, measure, si
             reportMeasuredCollisionMesh(ctx, "object", key, triangles);
     }, [ctx, harvested, batch, measure]);
     if (harvested === null)
-        return _jsx(LevelSingles, { objects: objects, level: level, selector: selector, single: single });
-    return _jsx(_Fragment, { children: harvested.sources.map((source, index) => _jsx(ObjectSource, { source: source, objects: objects, batch: batch, selector: selector, level: level }, index)) });
+        return _jsx(LevelSingles, { objects: objects, level: level, assignment: assignment, single: single });
+    return _jsx(_Fragment, { children: harvested.sources.map((source, index) => _jsx(ObjectSource, { source: source, objects: objects, batch: batch, assignment: assignment, level: level }, index)) });
 }
 /** Members of one level drawn through the individual renderer, for a level whose asset cannot be instanced. @internal */
-export function LevelSingles({ objects, level, selector, single }) {
+export function LevelSingles({ objects, level, assignment, single }) {
     const ctx = useGameContext();
     const visibility = useRenderVisibility();
-    const camera = useMemo(() => new THREE.Vector3(), []);
-    const probe = useMemo(() => new THREE.Vector3(), []);
     const [members, setMembers] = useState(objects);
-    useFrame((state) => {
-        state.camera.getWorldPosition(camera);
+    useFrame(() => {
         const next = objects.flatMap((object) => {
             const live = ctx.scene.object.get(object.instanceId);
             if (live === null || !visibility.current(live.instanceId))
                 return [];
-            probe.set(live.position[0], live.position[1], live.position[2]);
-            return selector.level(live.instanceId, camera.distanceTo(probe)) === level ? [live] : [];
+            return assignment.get(live.instanceId) === level ? [live] : [];
         });
         if (next.length !== members.length || next.some((member, index) => member !== members[index]))
             setMembers(next);
-    });
+    }, CAMERA_POST_FRAME_PRIORITY + 0.2);
     return _jsx(_Fragment, { children: members.map(single) });
 }
 /**
@@ -174,7 +168,34 @@ export function VariantStaticObjects({ batch, single }) {
     const { objects, excluded } = useBatchMembers(batch);
     const levels = batch.model.variants.levels;
     const selector = useMemo(() => createModelVariantSelector(batch.model.variants), [batch.model]);
-    return _jsxs(_Fragment, { children: [levels.map((level, index) => (_jsx(VariantLevel, { url: level.url, model: { ...batch.model, url: level.url, variants: undefined }, batch: batch, objects: objects, level: index, selector: selector, measure: index === 0, single: single }, `${level.url}:${index}`))), excluded.map((id) => { const live = ctx.scene.object.get(id); return live === null ? null : single(live); })] });
+    const variantSwitch = useMemo(() => variantSwitchOf(batch.model.variants), [batch.model]);
+    const gate = useMemo(() => createLevelPassGate(), []);
+    const assignment = useMemo(() => new Map(), []);
+    const camera = useMemo(() => new THREE.Vector3(), []);
+    const probe = useMemo(() => new THREE.Vector3(), []);
+    const members = useRef(objects);
+    const revision = useRef(-1);
+    const activeSelector = useRef(selector);
+    useFrame((state) => {
+        noteLevelPassFrame();
+        state.camera.getWorldPosition(camera);
+        const membership = members.current !== objects;
+        const model = activeSelector.current !== selector;
+        const moved = revision.current !== ctx.scene.object.version();
+        if (!membership && !model && !moved && !gate.needsPass(camera)) {
+            noteLevelPass(false);
+            return;
+        }
+        if (membership || model)
+            assignment.clear();
+        const margin = assignVariantLevels(selector, variantSwitch, objects, ctx.scene.object.get, camera, assignment, probe);
+        gate.record(camera, margin);
+        members.current = objects;
+        activeSelector.current = selector;
+        revision.current = ctx.scene.object.version();
+        noteLevelPass(true);
+    }, CAMERA_POST_FRAME_PRIORITY + 0.1);
+    return _jsxs(_Fragment, { children: [levels.map((level, index) => (_jsx(VariantLevel, { url: level.url, model: variantLevelModel(batch.model, index), batch: batch, objects: objects, level: index, assignment: assignment, measure: index === 0, single: single }, `${level.url}:${index}`))), excluded.map((id) => { const live = ctx.scene.object.get(id); return live === null ? null : single(live); })] });
 }
 /** Render compatible authored or `scenery` props as shared model draws, preserving unsupported models. @internal */
 export function StaticObjectModels({ batch, single }) {

package/dist/world/staticObjectBatches.d.ts

@@ -55,9 +55,11 @@ export interface StaticBatchCounts {
     drawn: number;
 }
 /**
- * Sum the tagged draws in the live scene. `drawn` counts each instance once even though one instance
- * appears in every material source's draw, so it is the number of instances the renderer was asked to
- * draw this frame — a world-wide batch whose instances leave the view drops it without unmounting.
+ * Sum the tagged draws the batches actually submit. `drawn` counts each instance once even though one
+ * instance appears in every material source's draw, so it is the number of instances the renderer was
+ * asked to draw this frame — a world-wide batch whose instances leave the view drops it without
+ * unmounting. A variant level with no instance in a cell, or a cell the camera culled, submits nothing
+ * and is not a draw.
  * @internal
  */
 export declare function countStaticBatchDraws(scene: THREE.Object3D): StaticBatchCounts;

package/dist/world/staticObjectBatches.js

@@ -1,5 +1,6 @@
 import * as THREE from "three";
 import { POINTER_OBJECT_INSTANCES_KEY } from "../pointer/pointerService.js";
+import { submitInstanceCount, submitsDraw } from "../render/submittedDraws.js";
 /** The same compatibility gate is used when live placements change after grouping. @internal */
 export function canBatchStaticObject(candidate) {
     const { object, model, catalog } = candidate;
@@ -99,16 +100,18 @@ export function groupStaticObjects(candidates, previous, cell = STATIC_BATCH_CEL
 /** Marks the instanced draws a static object batch owns so the batching probe can count them. @internal */
 export const STATIC_BATCH_MESH_KEY = "jgStaticObjectBatch";
 /**
- * Sum the tagged draws in the live scene. `drawn` counts each instance once even though one instance
- * appears in every material source's draw, so it is the number of instances the renderer was asked to
- * draw this frame — a world-wide batch whose instances leave the view drops it without unmounting.
+ * Sum the tagged draws the batches actually submit. `drawn` counts each instance once even though one
+ * instance appears in every material source's draw, so it is the number of instances the renderer was
+ * asked to draw this frame — a world-wide batch whose instances leave the view drops it without
+ * unmounting. A variant level with no instance in a cell, or a cell the camera culled, submits nothing
+ * and is not a draw.
  * @internal
  */
 export function countStaticBatchDraws(scene) {
     let draws = 0;
     const drawn = new Set();
     scene.traverse((node) => {
-        if (node.userData[STATIC_BATCH_MESH_KEY] !== true)
+        if (node.userData[STATIC_BATCH_MESH_KEY] !== true || !submitsDraw(node))
             return;
         draws += 1;
         const ids = node.userData[POINTER_OBJECT_INSTANCES_KEY];
@@ -192,8 +195,7 @@ export function syncStaticObjectSource(mesh, source, objects, get, visible, scra
     ids.length = count;
     poses.length = count;
     changed ||= mesh.count !== count;
-    mesh.count = count;
-    mesh.visible = count > 0;
+    submitInstanceCount(mesh, count);
     if (changed) {
         mesh.instanceMatrix.needsUpdate = true;
         mesh.computeBoundingSphere();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/shell",
-  "version": "0.38.0",
+  "version": "0.38.2",
   "description": "Game player shell for JGengine: React Three Fiber canvas, orbit camera, input tracking, HUD mounting, GameUiPreview, and a demo game. Consumers supply a GameRegistry.",
   "license": "Apache-2.0",
   "type": "module",
@@ -39,9 +39,9 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.38.0",
-    "@jgengine/react": "^0.38.0",
-    "@jgengine/ws": "^0.38.0"
+    "@jgengine/core": "^0.38.2",
+    "@jgengine/react": "^0.38.2",
+    "@jgengine/ws": "^0.38.2"
   },
   "peerDependencies": {
     "@react-three/drei": "^10.0.0",

package/skills/jgengine/api.md

@@ -6,7 +6,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.38.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.38.2" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -285,7 +285,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.38.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.38.2" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 

package/skills/jgengine-ui/api.md

@@ -795,6 +795,7 @@
 - `GameMenuSoundConfig` (interface): interface GameMenuSoundConfig — How {@link createGameMenuSound} is tuned.
 - `GameMenuSoundKind` (type): type GameMenuSoundKind = "move" | "confirm" | "back" — The short, quiet click a menu makes when the selection moves or is confirmed. Generated with an oscillator instead of shipped as an audio file, so a game gets menu feedback without authoring a sound and the whole thing unmounts with the screen.
 - `GameMenuSoundState` (interface): interface GameMenuSoundState — The sound player's readable state: on/off, gain, and whether audio is actually running.
+- `GameMenuStyle` (type): type GameMenuStyle = CSSProperties & Record<`--${string}`, string | number> — Inline style for a menu surface that also accepts `--jg-*` theme tokens, so a game sets a token with `{ "--jg-menu-radius": "12px" }` instead of casting the object to `CSSProperties`.
 - `GameMenuVariant` (type): type GameMenuVariant = "title" | "pause" — How a {@link GameMenu} is used. `pause` is the same system at a smaller scale.
 - `GamePauseMenu` (function): function GamePauseMenu(props: Omit<GameMenuProps, "variant"> & { onResume?: () => void }): ReactNode — A pause menu built from {@link GameMenu}: the same surface and navigation at a smaller scale, so a game composes one menu system rather than a second one. Escape (or B/Start) resumes.
 - `GamePreviewComponent` (type): type GamePreviewComponent = ComponentType<GamePreviewProps> — ⚠ undocumented
@@ -1483,6 +1484,7 @@
 - `GameMenuItem` (interface): interface GameMenuItem — A game's front-end menu: a full-bleed surface over a living background, a logo, primary verbs on the left that animate as the selection moves, and a detail pane on the right that changes with the highlighted verb. It is the block a main menu, a pause menu and their sub-screens are built from, so a game composes one menu system instead of a stack of modal panels.
 - `GameMenuLogo` (interface): interface GameMenuLogo — The logo slot. Give it `image` for art, or `text` for a styled wordmark.
 - `GameMenuProps` (interface): interface GameMenuProps — Props for {@link GameMenu}.
+- `GameMenuStyle` (type): type GameMenuStyle = CSSProperties & Record<`--${string}`, string | number> — Inline style for a menu surface that also accepts `--jg-*` theme tokens, so a game sets a token with `{ "--jg-menu-radius": "12px" }` instead of casting the object to `CSSProperties`.
 - `GameMenuVariant` (type): type GameMenuVariant = "title" | "pause" — How a {@link GameMenu} is used. `pause` is the same system at a smaller scale.
 - `GamePauseMenu` (function): function GamePauseMenu(props: Omit<GameMenuProps, "variant"> & { onResume?: () => void }): ReactNode — A pause menu built from {@link GameMenu}: the same surface and navigation at a smaller scale, so a game composes one menu system rather than a second one. Escape (or B/Start) resumes.
 - `useViewportScrollLock` (function): function useViewportScrollLock(active: boolean): void — Lock the page scroll while `active`, so a fixed full-bleed surface is exactly the viewport and the document behind it never gains a scrollbar. Nested and repeated locks are counted, and the previous inline styles are restored when the last one releases.
@@ -2115,6 +2117,10 @@
 - `TalentTree` (function): function TalentTree<TStat extends string = string>({ view: viewProp, nodes, tree, onLearn, icon, label, branchLabel, title = "Talents", variation = "themed", nodeSize = 54, columnGap = 30, tierGap = 46, showPoints = true, className, style, }: TalentTreeProps<TStat>): ReactNode — Drop-in talent / skill-tree widget over the existing progression model (`@jgengine/core/game/talents` + its `talentTreeView` selector). The game passes its node definitions and a live `createTalentTree` instance; the widget lays nodes out by branch column and prerequisite-depth tier, draws SVG prerequisite edges, styles each node learned/available/locked/maxed, shows an icon + rank badge, and calls `onLearn(nodeId)` when the player clicks a node that is currently allocatable. All layout, edge-drawing, and eligibility come from the model/selector — the widget never re-derives topology. Unskinned and HudTheme-token driven; node ids/branches are opaque game data the game supplies icons and labels for.
 - `TalentTreeProps` (interface): interface TalentTreeProps<TStat extends string = string> — Props for {@link TalentTree}.
 
+## @jgengine/react/testFixtures
+
+- `MENU_THEME_STYLE` (const): const MENU_THEME_STYLE: GameMenuStyle — Menu theme tokens passed through the `style` prop with no cast. This file is type-checked and kept out of the build, so the compiler proves the prop accepts `--jg-*` custom properties on every typecheck while nothing ships from here.
+
 ## @jgengine/react/tileLayerPreview
 
 - `TileLayerPreview` (function): function TileLayerPreview({ className }: { className?: string }): React.JSX.Element — Deterministic canvas-backed tile-layer fixture for textured tile presentation evidence.
@@ -3078,9 +3084,28 @@
 ## @jgengine/shell/render/sceneCapture
 
 - `CaptureRenderer` (interface): interface CaptureRenderer — The bit of a WebGL renderer scene capture needs — its backing `<canvas>`.
-- `SceneCaptureBinding` (function): function SceneCaptureBinding({ bind }: { bind: (capture: () => string | null) => void }): null — In-`<Canvas>` binder that hands the scene-capture function out to HUD code living outside the reconciler (a photo-mode Capture button). Mount it inside the game's `WorldOverlay`; call `bind` receives a `() => string | null` that grabs the current frame. Renders nothing.
+- `SceneCapture` (type): type SceneCapture = () => string | null — Reads the current scene frame as an image data URL, or null when the frame cannot be read.
+- `SceneCaptureBinding` (function): function SceneCaptureBinding({ bind }: { bind?: (capture: () => string | null) => void } = {}): null — In-`<Canvas>` binder that hands the scene-capture function out to HUD code living outside the reconciler (a photo-mode Capture button, a save slot's thumbnail). Mount it inside the game's `WorldOverlay`; the reader is registered for `requestSceneCapture`/`requestSceneThumbnail`, which wait for this mount and the first painted frame. `bind` is for code that wants the function directly and can be left out when a game only requests captures. Renders nothing.
+- `SceneCaptureFailure` (type): type SceneCaptureFailure = "no-binding" | "no-frame" | "undecodable" — Why a capture request produced no image.
+- `SceneCaptureRequestOptions` (interface): interface SceneCaptureRequestOptions — How a capture request waits and retries.
+- `SceneCaptureResult` (type): type SceneCaptureResult = | { ok: true; capture: string } | { ok: false; reason: SceneCaptureFailure } — A captured frame, or the stated reason there is none.
+- `SceneThumbnailResult` (type): type SceneThumbnailResult = | { ok: true; thumbnail: string } | { ok: false; reason: SceneCaptureFailure } — A save-card thumbnail, or the stated reason there is none.
 - `captureCanvas` (function): function captureCanvas(gl: CaptureRenderer): string | null — Read the current frame to a PNG data URL. Requires the R3F `<Canvas>` to have been created with `gl={{ preserveDrawingBuffer: true }}` (the shell's game canvas already is); returns null if the backing canvas can't be read.
 - `downloadImage` (function): function downloadImage(dataUrl: string, filename = "screenshot.png"): void — Trigger a browser download of an image data URL (the photo-mode "save" action).
+- `registerSceneCapture` (function): function registerSceneCapture(capture: SceneCapture | null): () => void — Hand the capture path a reader for the live frame, or `null` to retire it. The returned function unbinds only that reader, so a canvas that remounts cannot be unbound by its predecessor.
+- `requestSceneCapture` (function): function requestSceneCapture(options: SceneCaptureRequestOptions = {}): Promise<SceneCaptureResult> — Request the current scene frame. Resolves once a binding exists and the canvas has painted, or with the reason no frame could be read; it never polls and never rejects.
+- `requestSceneThumbnail` (function): function requestSceneThumbnail(options: SceneCaptureRequestOptions & SaveThumbnailOptions = {}): Promise<SceneThumbnailResult> — Request a save-card thumbnail from the live scene: the shared capture request, then `shrinkCapture`. Pass what the slot card stores; omit everything for a 320x180 JPEG.
+
+## @jgengine/shell/render/sceneCaptureRequest
+
+- `SceneCapture` (type): type SceneCapture = () => string | null — Reads the current scene frame as an image data URL, or null when the frame cannot be read.
+- `SceneCaptureFailure` (type): type SceneCaptureFailure = "no-binding" | "no-frame" | "undecodable" — Why a capture request produced no image.
+- `SceneCaptureRequestOptions` (interface): interface SceneCaptureRequestOptions — How a capture request waits and retries.
+- `SceneCaptureResult` (type): type SceneCaptureResult = | { ok: true; capture: string } | { ok: false; reason: SceneCaptureFailure } — A captured frame, or the stated reason there is none.
+- `SceneThumbnailResult` (type): type SceneThumbnailResult = | { ok: true; thumbnail: string } | { ok: false; reason: SceneCaptureFailure } — A save-card thumbnail, or the stated reason there is none.
+- `registerSceneCapture` (function): function registerSceneCapture(capture: SceneCapture | null): () => void — Hand the capture path a reader for the live frame, or `null` to retire it. The returned function unbinds only that reader, so a canvas that remounts cannot be unbound by its predecessor.
+- `requestSceneCapture` (function): function requestSceneCapture(options: SceneCaptureRequestOptions = {}): Promise<SceneCaptureResult> — Request the current scene frame. Resolves once a binding exists and the canvas has painted, or with the reason no frame could be read; it never polls and never rejects.
+- `requestSceneThumbnail` (function): function requestSceneThumbnail(options: SceneCaptureRequestOptions & SaveThumbnailOptions = {}): Promise<SceneThumbnailResult> — Request a save-card thumbnail from the live scene: the shared capture request, then `shrinkCapture`. Pass what the slot card stores; omit everything for a 320x180 JPEG.
 
 ## @jgengine/shell/render/shaderWarmup
 

package/skills/jgengine-ui/capabilities.md

@@ -805,6 +805,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `RainImpactField` (function) · `import { RainImpactField } from "@jgengine/shell/weather"`
 
+## request-scene-capture — request the live scene frame, waiting for a late binding and the first painted frame
+
+- `requestSceneCapture` (function) · `import { requestSceneCapture } from "@jgengine/shell/render/sceneCapture"`
+
+## request-scene-thumbnail — request a save-card thumbnail from the live scene, or a stated failure
+
+- `requestSceneThumbnail` (function) · `import { requestSceneThumbnail } from "@jgengine/shell/render/sceneCapture"`
+
 ## resolve-game-look — expand a look preset into concrete lighting/backdrop/post knobs
 
 - `resolveGameLook` (function) · `import { resolveGameLook } from "@jgengine/core/ui"`
@@ -821,7 +829,7 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `SaveSlotsPane` (function) · `import { SaveSlotsPane } from "@jgengine/react"`
 
-## scene-capture-binding — expose the in-Canvas scene-capture function to outside-Canvas HUD (photo mode)
+## scene-capture-binding — expose the in-Canvas scene-capture function to outside-Canvas HUD (photo mode, save thumbnails)
 
 - `SceneCaptureBinding` (function) · `import { SceneCaptureBinding } from "@jgengine/shell/render/sceneCapture"`
 

package/skills/jgengine-world/api.md

@@ -2655,7 +2655,7 @@
 - `ModelAssetRef` (interface): interface ModelAssetRef { url: string; anchor?: "center" | "origin"; dims?: ModelDims; collisionMesh?: CollisionMeshData; space?: AssetSpace; clips?: readonly string[] } — ⚠ undocumented · used by `createHostedWorldSessionAsync` (@jgengine/core/runtime/hostedWorldSession): Build a hosted session from an asynchronous persistence backend.
 - `ModelDims` (interface): interface ModelDims — Measured horizontal footprint, footprint center, and lowest Y of a model in model space.
 - `ModelNode` (interface): interface ModelNode — Generic named-socket reader for loaded 3D models. Walks a node tree (any object with `.name`, `.position`, and `.children` — structurally satisfied by `THREE.Object3D`) and collects the local offsets of nodes whose name marks an attachment point. Genre-agnostic: wire anchors on a pylon, muzzle/hand mounts on a character, hardpoints on a ship, seat/decal slots on furniture — anything an artist tags with an empty in the GLB. Pure data (no three.js import), so it lives in core.
-- `ModelVariantConfig` (interface): interface ModelVariantConfig — One mesh level of a {@link ModelVariantLodConfig}: a full or decimated GLB and how far it draws.
+- `ModelVariantConfig` (interface): interface ModelVariantConfig — One mesh level of a {@link ModelVariantLodConfig}: a full or decimated GLB, how far it draws and how it shadows.
 - `ModelVariantLodConfig` (interface): interface ModelVariantLodConfig — Ordered mesh detail levels for one model, switched per instance by camera distance. The first level is the full mesh the model's own `url` names; every later level is a cheaper asset. A tree line uses this so near trees keep their full mesh while far ones draw a decimated copy of the same species.
 - `ModelVariantSelector` (interface): interface ModelVariantSelector — Per-instance distance switch over a model's detail levels: one answer per id, held across a boundary until the instance clears it.
 - `ModelVariantSelectorState` (interface): interface ModelVariantSelectorState — Plain JSON state of a {@link ModelVariantSelector}: each id's current level index.
@@ -4041,7 +4041,8 @@
 ## @jgengine/core/world/modelLod
 
 - `DEFAULT_VARIANT_HYSTERESIS` (const): const DEFAULT_VARIANT_HYSTERESIS: 6 — Metres an instance must travel past a switch boundary before it changes level unless the model declares its own.
-- `ModelVariantConfig` (interface): interface ModelVariantConfig — One mesh level of a {@link ModelVariantLodConfig}: a full or decimated GLB and how far it draws.
+- `ModelShadowMode` (type): type ModelShadowMode = "cast" | "receive" | "both" | "none" — How a model, or one of its variant levels, takes part in the shadow pass.
+- `ModelVariantConfig` (interface): interface ModelVariantConfig — One mesh level of a {@link ModelVariantLodConfig}: a full or decimated GLB, how far it draws and how it shadows.
 - `ModelVariantLodConfig` (interface): interface ModelVariantLodConfig — Ordered mesh detail levels for one model, switched per instance by camera distance. The first level is the full mesh the model's own `url` names; every later level is a cheaper asset. A tree line uses this so near trees keep their full mesh while far ones draw a decimated copy of the same species.
 - `ModelVariantSelector` (interface): interface ModelVariantSelector — Per-instance distance switch over a model's detail levels: one answer per id, held across a boundary until the instance clears it.
 - `ModelVariantSelectorState` (interface): interface ModelVariantSelectorState — Plain JSON state of a {@link ModelVariantSelector}: each id's current level index.