@jgengine/react 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/gameMenu.d.ts

@@ -36,6 +36,11 @@ export interface GameMenuLogo {
 }
 /** How a {@link GameMenu} is used. `pause` is the same system at a smaller scale. */
 export type GameMenuVariant = "title" | "pause";
+/**
+ * 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`.
+ */
+export type GameMenuStyle = CSSProperties & Record<`--${string}`, string | number>;
 /** Props for {@link GameMenu}. */
 export interface GameMenuProps {
     /** Primary verbs, in focus order. */
@@ -84,9 +89,9 @@ export interface GameMenuProps {
     /** Accessible name of the surface. Default `"Main menu"` (`"Paused"` for the pause variant). */
     label?: string;
     className?: string;
-    style?: CSSProperties;
+    style?: GameMenuStyle;
     detailClassName?: string;
-    detailStyle?: CSSProperties;
+    detailStyle?: GameMenuStyle;
 }
 /**
  * Lock the page scroll while `active`, so a fixed full-bleed surface is exactly the viewport and the
@@ -104,7 +109,9 @@ export declare function useViewportScrollLock(active: boolean): void;
  *
  * The engine owns the surface, layout, motion, focus order, sound and the save/character panes it
  * exports next to this component. The game owns the art, the logo, the wording, the verbs and what
- * each detail pane shows.
+ * each detail pane shows. The surface takes pointer input for itself and leaves its painted
+ * backdrop transparent to input, so a HUD wrapper that passes clicks through does not make the
+ * verbs dead; `style` and `detailStyle` accept `--jg-*` tokens without a cast.
  *
  * @capability game-menu full-bleed game menu — living background, token-sized logo, animated navigable verbs, detail pane, selection sound, pause variant, no page scrollbar
  */

package/dist/gameMenu.js

@@ -92,7 +92,9 @@ function logoNode(logo, title, reduced) {
  *
  * The engine owns the surface, layout, motion, focus order, sound and the save/character panes it
  * exports next to this component. The game owns the art, the logo, the wording, the verbs and what
- * each detail pane shows.
+ * each detail pane shows. The surface takes pointer input for itself and leaves its painted
+ * backdrop transparent to input, so a HUD wrapper that passes clicks through does not make the
+ * verbs dead; `style` and `detailStyle` accept `--jg-*` tokens without a cast.
  *
  * @capability game-menu full-bleed game menu — living background, token-sized logo, animated navigable verbs, detail pane, selection sound, pause variant, no page scrollbar
  */
@@ -217,6 +219,9 @@ export function GameMenu({ items, initialId, onSelect, onBack, onHighlight, deta
                 ? "clamp(16px, 2.4vw, 34px) clamp(20px, 3.2vw, 56px)"
                 : "clamp(18px, 3.2vw, 56px) clamp(20px, 3.6vw, 64px)",
             boxSizing: "border-box",
+            // The surface is an overlay: it takes its own input even when the HUD wrapper around it
+            // passes every pointer through to the scene.
+            pointerEvents: "auto",
             color: "var(--jg-text, #f5f7fa)",
             fontFamily: hudFont.body,
             animation: reduced ? undefined : `jg-fade-in ${hudDuration("slow")} ${hudEase("easeOut")} both`,
@@ -266,7 +271,17 @@ export function GameMenu({ items, initialId, onSelect, onBack, onHighlight, deta
                         nav.containerProps.onKeyDown(event);
                         if (event.key === "ArrowDown" || event.key === "ArrowUp")
                             event.stopPropagation();
-                    }, children: [_jsx("div", { "data-jg-game-menu-rail": "", "aria-hidden": "true", style: {
+                    }, children: [_jsx("div", { "data-jg-game-menu-nav-surface": "", "aria-hidden": "true", style: {
+                                position: "absolute",
+                                inset: "-16px -22px",
+                                borderRadius: "var(--jg-menu-surface-radius, 8px)",
+                                background: "linear-gradient(96deg, rgba(4,7,11,0.6) 0%, rgba(4,7,11,0.34) 56%, rgba(4,7,11,0) 100%)",
+                                maskImage: "linear-gradient(180deg, transparent 0, #000 9%, #000 91%, transparent 100%)",
+                                WebkitMaskImage: "linear-gradient(180deg, transparent 0, #000 9%, #000 91%, transparent 100%)",
+                                backdropFilter: "blur(2px)",
+                                WebkitBackdropFilter: "blur(2px)",
+                                pointerEvents: "none",
+                            } }), _jsx("div", { "data-jg-game-menu-rail": "", "aria-hidden": "true", style: {
                                 position: "absolute",
                                 left: 0,
                                 right: 8,

package/dist/gameMenuSaves.js

@@ -14,15 +14,18 @@ export const SAVE_SLOT_CHARACTER_KEY = "character";
 const cardSurface = {
     position: "relative",
     width: "100%",
+    minWidth: 0,
+    height: "var(--jg-menu-card-height, clamp(244px, 27vh, 300px))",
     boxSizing: "border-box",
+    overflow: "hidden",
     display: "flex",
     flexDirection: "column",
     gap: 8,
-    minWidth: 0,
     padding: 10,
     borderRadius: "var(--jg-menu-card-radius, 12px)",
-    background: "linear-gradient(180deg, rgba(16,22,30,0.78), rgba(8,11,16,0.86))",
-    boxShadow: "inset 0 0 0 1px rgba(255,255,255,0.09), 0 14px 34px -18px rgba(0,0,0,0.9)",
+    background: "linear-gradient(180deg, rgba(16,22,30,0.9), rgba(8,11,16,0.94))",
+    border: "1px solid rgba(255,255,255,0.14)",
+    boxShadow: "inset 0 0 0 1px rgba(255,255,255,0.05), 0 14px 34px -18px rgba(0,0,0,0.9)",
     backdropFilter: "blur(6px)",
     color: "var(--jg-text, #f2f6fb)",
     fontFamily: hudFont.body,
@@ -67,9 +70,9 @@ export function SaveSlotCard({ slot, now = Date.now, recent = false, onSelect, o
                 cursor: onSelect === undefined ? "default" : "pointer",
                 alignItems: "flex-start",
                 justifyContent: "flex-end",
-                border: "none",
+                border: "1px solid rgba(255,255,255,0.1)",
                 boxShadow: "inset 0 0 0 1px rgba(255,255,255,0.07), inset 0 0 40px -18px rgba(125,211,252,0.4), 0 10px 26px -20px rgba(0,0,0,0.9)",
-                background: "linear-gradient(180deg, rgba(12,17,24,0.6), rgba(6,9,13,0.72))",
+                background: "linear-gradient(180deg, rgba(12,17,24,0.82), rgba(6,9,13,0.9))",
                 ...style,
             }, children: [_jsx("div", { "data-save-slot-thumb": "", "data-empty": "", style: {
                         width: "100%",
@@ -94,7 +97,8 @@ export function SaveSlotCard({ slot, now = Date.now, recent = false, onSelect, o
         }, children: [_jsxs("div", { "data-save-slot-thumb": "", style: {
                     position: "relative",
                     width: "100%",
-                    aspectRatio: "16 / 9",
+                    flexShrink: 0,
+                    height: "var(--jg-menu-card-thumb, clamp(88px, 14vh, 160px))",
                     borderRadius: 8,
                     overflow: "hidden",
                     background: "radial-gradient(120% 120% at 30% 20%, rgba(125,211,252,0.22), rgba(8,12,18,0.9))",
@@ -124,6 +128,10 @@ export function SaveSlotCard({ slot, now = Date.now, recent = false, onSelect, o
                             fontWeight: 800,
                             letterSpacing: "0.01em",
                             textShadow: "0 2px 12px rgba(0,0,0,0.8)",
+                            maxWidth: "calc(100% - 16px)",
+                            whiteSpace: "nowrap",
+                            overflow: "hidden",
+                            textOverflow: "ellipsis",
                         }, children: slot.name ?? slot.id }), recent ? (_jsx("span", { "data-save-slot-recent": "", style: {
                             position: "absolute",
                             top: 6,
@@ -231,6 +239,10 @@ export function SaveSlotsPane({ model, onContinue, onLoad, onNew, onDelete, head
                         }, children: ["Continue ", recent.name ?? recent.id] }))] }), _jsx("div", { ...nav.containerProps, "data-save-slots-grid": "", style: {
                     display: "grid",
                     gridTemplateColumns: columns === "auto" ? "repeat(auto-fill, minmax(230px, 1fr))" : `repeat(${columns}, minmax(0, 1fr))`,
+                    // Every card gets the same box: equal tracks, equal rows, and content that cannot widen it.
+                    gridAutoRows: "auto",
+                    alignItems: "stretch",
+                    flex: 1,
                     gap: hudSpace("md"),
                     minHeight: 0,
                     overflowY: "auto",
@@ -240,25 +252,25 @@ export function SaveSlotsPane({ model, onContinue, onLoad, onNew, onDelete, head
                     paddingBottom: 4,
                 }, children: slots.map((slot) => {
                     const active = nav.activeId === slot.id;
-                    return (_jsx("div", { style: { minWidth: 0, outline: active ? "none" : undefined }, children: _jsx(SaveSlotCard, { slot: slot, now: now, recent: recent !== null && recent.id === slot.id, ...(onLoad === undefined && onNew === undefined
-                                ? {}
-                                : {
-                                    onSelect: (chosen) => {
-                                        if (chosen.empty)
-                                            onNew?.(chosen);
-                                        else
-                                            onLoad?.(chosen);
-                                    },
-                                }), ...(onDelete === undefined ? {} : { onDelete }), style: {
-                                height: "100%",
-                                ...(active
-                                    ? {
-                                        boxShadow: "inset 0 0 0 1px var(--jg-accent, #7dd3fc), 0 0 0 1px rgba(125,211,252,0.5), 0 18px 40px -18px rgba(0,0,0,0.95)",
-                                        transform: "translateY(-2px)",
-                                        transition: `transform ${hudDuration("fast")} ${hudEase("spring")}`,
-                                    }
-                                    : {}),
-                            } }) }, slot.id));
+                    return (_jsx(SaveSlotCard, { slot: slot, now: now, recent: recent !== null && recent.id === slot.id, ...(onLoad === undefined && onNew === undefined
+                            ? {}
+                            : {
+                                onSelect: (chosen) => {
+                                    if (chosen.empty)
+                                        onNew?.(chosen);
+                                    else
+                                        onLoad?.(chosen);
+                                },
+                            }), ...(onDelete === undefined ? {} : { onDelete }), style: {
+                            minWidth: 0,
+                            ...(active
+                                ? {
+                                    boxShadow: "inset 0 0 0 1px var(--jg-accent, #7dd3fc), 0 0 0 1px rgba(125,211,252,0.5), 0 18px 40px -18px rgba(0,0,0,0.95)",
+                                    transform: "translateY(-2px)",
+                                    transition: `transform ${hudDuration("fast")} ${hudEase("spring")}`,
+                                }
+                                : {}),
+                        } }, slot.id));
                 }) })] }));
 }
 /**

package/dist/hudTheme.js

@@ -105,10 +105,14 @@ export function hudThemeVars(theme) {
         "--jg-frame-bg": frame.bg,
         "--jg-frame-border": frame.border,
         "--jg-frame-radius": frame.radius,
-        // The game menu's two design tokens: a logo sized off the display step and card corners that
-        // follow the frame radius, so a menu inherits the theme it is rendered under.
+        // The game menu's design tokens: a logo sized off the display step, card corners that follow the
+        // frame radius, and the card's fixed height and thumbnail band, so a slot card is the same box
+        // whatever it holds and a game can retune the menu from its theme.
         "--jg-menu-logo-size": "clamp(30px, 4.6vw, 66px)",
         "--jg-menu-card-radius": frame.radius,
+        "--jg-menu-card-height": "clamp(244px, 27vh, 300px)",
+        "--jg-menu-card-thumb": "clamp(88px, 14vh, 160px)",
+        "--jg-menu-surface-radius": "8px",
         "--jg-frame-glow": frame.glow,
         "--jg-slot-bg": slot.bg,
         "--jg-slot-border": slot.border,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/react",
-  "version": "0.38.0",
+  "version": "0.38.2",
   "description": "React UI layer for JGengine: GameProvider, hooks, and headless primitives over @jgengine/core.",
   "license": "Apache-2.0",
   "type": "module",
@@ -35,7 +35,7 @@
     "styles": "bun scripts/styles.ts"
   },
   "dependencies": {
-    "@jgengine/core": "^0.38.0"
+    "@jgengine/core": "^0.38.2"
   },
   "peerDependencies": {
     "react": "^19.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"`