@jgengine/react 0.37.0 → 0.38.1

package/CHANGELOG.md

@@ -26,6 +26,88 @@ 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.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
+
+- **Bump lockstep SDK packages to `^0.38.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.35.0`; `@jgengine/github` is `0.25.0`.
+- Composing a session loop directly: pass your rule as `settle`, `carries: false` when nothing is carried, and your authored options as `offers`. `createRunLoop` is removed one minor release after Beacon Bastion and Drift Foundry stop using it.
+
+### Added
+
+- `GameMenu` and `GamePauseMenu` (`@jgengine/react/gameMenu`): a full-bleed menu surface over the live scene or drifting key art, with a token-sized logo, an animated navigable verb list, a generated selection tick and a detail pane per verb. The document scroll is locked while it is open, so the surface is exactly the viewport at any size.
+- Panes for the detail slot: `ContinuePane`, `NewCharacterPane`, `SaveSlotsPane` (slot cards with a `meta.thumbnail`, playtime, progress, timestamp and a two-press delete) and `CreditsPane` (`@jgengine/react/gameMenuSaves`).
+- `shrinkCapture` (`@jgengine/react/saveThumbnail`) turns a `captureCanvas` frame into a card-sized thumbnail data URL.
+- `createSessionLoop` (`@jgengine/core/run/sessionLoop`) is one session loop for every game: a session opens, may carry a quantity, closes at its boundary, and the game's own `settle` callback decides what happens to what it carried. `carries: false` for a session with nothing at stake, and an optional `offers` table (with `present`/`choose`) for a game whose next session opens with an authored change; without a table nothing is drawn. `installSessionProbe` reports the live session on `window.__jgengineRun`.
+
+### Changed
+
+- `switchSlot(slot, { flush: false })` (`@jgengine/core/game/gameSave`) loads a slot without first writing the live state over it. Opening a save from a menu uses it so Continue cannot overwrite the save it resumes.
+- The dev runner's registry and environment modules import outside Vite, so a test or tool can read them.
+- `createRunLoop` is now a thin composition of `createSessionLoop` and is deprecated: bank-or-lose and a per-run change table are one game type's rules, so they live in the composition instead of the base. Its API, state shape and tests are unchanged. One difference: the option draw is seeded under `:offer:` rather than `:run:` (`seededRng(\`${seed}:offer:${index}\`)`), so a career that keeps its seed draws a different change on a given session than 0.37.0 did for the same seed. Ids, payloads and saves stay valid: a saved `changeId` still restores the same change.
+
+### Fixed
+
+- `shoot` fails instead of writing a PNG when the whole frame is one flat colour, and when a scene is still behind its loading cover. Both used to write a plausible screenshot that read as evidence of a rendered frame.
+- The editor's play-mode pixel test waits for the warmup cover to clear before screenshotting. It shot the cover, so it read `0.9988` one-colour locally and passed in CI where the race fell the other way.
+- `shoot` prints the WebGL2 renderer it draws with and fails the capture outright when the launched browser has none.
+
+Root cause: capture readiness was trusted to mean "the scene has rendered", but a loading cover and a canvas that never committed both photograph as a flat frame, and nothing measured the frame after the fact. Headless Chrome on this PC was never the problem: it renders with the GPU (`ANGLE (NVIDIA GeForce RTX 3070, D3D11)`) and with SwiftShader when asked.
+
+Before: `bun run shoot --url <flat canvas page>` exited 0 and wrote a one-colour PNG, and `packages/editor/src/CreatorApp.test.ts` failed locally at `dominantColorShare 0.9988`.
+After: the same shoot exits 1 with `the whole frame is one flat color (100.0%) - no scene reached the capture - nothing was written`, and the editor test passes in 12s with sky and ground in the PNG.
+
+Cost: forcing SwiftShader on the same game shot costs 2.4x the capture (16.0s vs 6.7s warm, beacon-bastion play at half size), so the launch keeps the native GPU. The two checks add about 10ms to a shot.
+
+Verification:
+- `bun test scripts/shot-metrics.test.ts` - pass
+- `bun test packages/editor/src/CreatorApp.test.ts` - pass
+- `bun run shoot beacon-bastion --mode play --size half` - exit 0, scene renders
+- `bun run shoot --url <flat canvas page>` - exit 1, no PNG written
+- `bun run verify:fast` - pass
+
+The CI reliability fix this lane also carried (a browser setup hook shorter than Playwright's launch default) is #2335, so either change can be reverted without the other.
+- The publish workflow's last step no longer reports a whole release as unpublished because it ran seconds after `npm publish`. `check:release-artifacts --wait <seconds>` re-checks while the only failures are absent packages (no metadata, version missing, tarball 404) and gives up when the budget runs out; a wrong version in the tarball, a missing subpath or a main entry that will not import still fails on the first check. The 0.37.0 publish run failed this step at 04:48 listing all 13 packages, then npm served every one of them. The step now passes `-- --wait 300`.
+- A Playwright test file's `beforeAll` now outlives the Chrome launch it waits on, and `browser-test-budget` rejects a file that leaves the hook at or under Playwright's 30 s launch default. On `test (g)` in #2326 the hook's 30 s budget and that default expired together, so CI reported only `(unnamed) hook timed out` beside `killed 1 dangling process` and nothing named the launch.
+- `packages/react/src/dialogBehavior.test.ts` gives its browser navigation its own 20 s deadline and one retry inside a 60 s hook.
+
+Root cause: Bun prints a `beforeAll` timeout as an unnamed hook timeout, so a setup budget equal to Playwright's own 30 s launch default reports the anonymous timer instead of the launch that stalled.
+
+Before: `test (g)` on #2326 reported `(fail) (unnamed) [30001.51ms] ^ a beforeEach/afterEach hook timed out` and `killed 1 dangling process`.
+After: a stall now surfaces as Playwright's own `Timeout ... exceeded`, and `bun scripts/browser-test-budget.ts` names any file whose setup hook sits at or under the launch default.
+
+Verification:
+- `bun scripts/browser-test-budget.ts` - pass, and the new rule names the unraised files on the previous tip
+- `bun test scripts/browser-test-budget.test.ts` - pass
+- `bun test packages/react/src/dialogBehavior.test.ts packages/react/src/scrollRail.test.ts packages/shell/src/settingsBoundary.test.ts` - pass
+- `bun run verify:fast` - pass
+- A prop placed at runtime honours its model's `variants` levels. `StaticObjectModels` applied the level switch only inside its batched branch, so a prop placed with `scene.object.place` — Harbor Heat's palm line — drew its full asset at every camera distance: 15 palms at 9,134 triangles each, and pointing the far level at a dispatch booth changed nothing on screen. `IsolatedEntityModel` now mounts `SingleVariantModel`, which asks the same `createModelVariantSelector` and `lodBandIndex` authority the batched path uses, at the prop's own camera distance, and keeps only the active level mounted so both levels never draw at once. The switch carries the selector's hysteresis, warms every level at mount, measures only the near level, and reads the placement from the scene store through scratch vectors, so a frame allocates nothing. One palm past 60 m draws 4,110 triangles instead of 9,134 (5,024 saved, 45% of the full level).
+
+- `singleVariantLevel` and `singleVariantModel` (`@jgengine/shell` internal, `render/singleVariantLod`) are the isolated path's level decision and the model it draws, so a fixture pins the same switch the component runs.
+
+`bun test packages/shell/src/render/singleVariantLod.test.ts` — 6 pass. With the old render decision restored, the wiring test fails (`Expected: SingleVariantModel, Received: EntityModel`).
+`bun --cwd=packages/shell run test` — 1,229 pass, 0 fail.
+`bun --cwd=packages/shell run check-types` — clean.
+
 ## 0.37.0
 
 ### Migrate

package/dist/engineStyles.js

@@ -52,6 +52,11 @@ export const ENGINE_STYLESHEET = `/* @jgengine/react engine stylesheet */
 @keyframes jg-spin { from { transform: rotate(0deg); } to { transform: rotate(360deg); } }
 @keyframes jg-delta-up { 0% { color: var(--jg-success, #3fa34d); text-shadow: 0 0 10px var(--jg-success, #3fa34d); scale: 1.12; } 100% { scale: 1; } }
 @keyframes jg-delta-down { 0% { color: var(--jg-danger, #e5484d); text-shadow: 0 0 10px var(--jg-danger, #e5484d); scale: 0.94; } 100% { scale: 1; } }
+@keyframes jg-menu-drift { from { transform: scale(1.06) translate3d(-1.4%, -1%, 0); } to { transform: scale(1.12) translate3d(1.6%, 1.2%, 0); } }
+@keyframes jg-menu-rise { from { opacity: 0; transform: translateY(14px); } to { opacity: 1; transform: translateY(0); } }
+@keyframes jg-menu-pane-in { from { opacity: 0; transform: translateX(14px); } to { opacity: 1; transform: translateX(0); } }
+[data-jg-game-menu] * { scrollbar-width: none; }
+[data-jg-game-menu] *::-webkit-scrollbar { width: 0; height: 0; }
 
 [data-jg-hud] { font-family: var(--jg-font-body, ${HUD_FONT_STACK}); -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; text-rendering: optimizeLegibility; }
 :where([data-jg-hud]) :where(button, [role="button"], a[href], summary, [data-jg-interactive]):focus-visible { outline: 2px solid var(--jg-accent, #38bdf8); outline-offset: 2px; }

package/dist/gameMenu.d.ts

@@ -0,0 +1,120 @@
+import { type CSSProperties, type ReactNode } from "react";
+import { type GameMenuSound } from "./gameMenuSound.js";
+/**
+ * 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.
+ *
+ * The surface is exactly the viewport: `position: fixed` with `overflow: hidden`, and the document
+ * scroll is locked while it is open, so a tall menu can never grow a page scrollbar. Content that
+ * genuinely scrolls (credits) scrolls inside its own pane.
+ */
+/** One primary verb in a {@link GameMenu}. */
+export interface GameMenuItem {
+    /** Stable id the game routes on. */
+    id: string;
+    /** Player-facing label. */
+    label: string;
+    /** One short line under the label — a save summary, a state note. Omit for a clean row. */
+    hint?: string;
+    /** Show the row but skip it in navigation and clicks. */
+    disabled?: boolean;
+    /** Small marker at the end of the row (a badge, a count, a key glyph). */
+    badge?: ReactNode;
+}
+/** The logo slot. Give it `image` for art, or `text` for a styled wordmark. */
+export interface GameMenuLogo {
+    /** Image URL for the game's logo. Sized by the `--jg-menu-logo` token, never by a heading tag. */
+    image?: string;
+    /** Alt text for the logo image. Defaults to `title` when that is a string. */
+    alt?: string;
+    /** Styled type instead of an image. */
+    text?: ReactNode;
+    /** Plain title, used for the accessible name and as the alt fallback. */
+    title?: string;
+}
+/** How a {@link GameMenu} is used. `pause` is the same system at a smaller scale. */
+export type GameMenuVariant = "title" | "pause";
+/** Props for {@link GameMenu}. */
+export interface GameMenuProps {
+    /** Primary verbs, in focus order. */
+    items: readonly GameMenuItem[];
+    /** The verb focused on mount. Default the first enabled one. */
+    initialId?: string;
+    /** A verb was confirmed (Enter, Space, A, or a click). */
+    onSelect: (id: string) => void;
+    /** Back (Escape, Backspace, B, Start). On a pause menu this is the resume action. */
+    onBack?: () => void;
+    /** The highlighted verb changed — use it to load the detail for `id`. */
+    onHighlight?: (id: string | null) => void;
+    /** The right-hand pane's content for the highlighted verb. */
+    detail?: ReactNode | ((id: string | null) => ReactNode);
+    /** Logo slot: an image or styled type, sized by the logo token. */
+    logo?: GameMenuLogo | ReactNode;
+    /** Small line above the logo (studio, chapter, mode). */
+    eyebrow?: ReactNode;
+    /** One line under the logo. */
+    tagline?: ReactNode;
+    /**
+     * Layer painted across the whole viewport behind the menu: a live scene component, key art, a
+     * video. Leave it out when the engine's own 3D canvas sits behind the menu — the menu stays
+     * transparent and only tints and vignettes it, so play keeps rendering underneath.
+     */
+    background?: ReactNode;
+    /**
+     * Key-art URL for the drifting background layer. Omit when the live scene behind the menu is the
+     * background. With neither, the menu still tints and vignettes whatever is behind it.
+     */
+    art?: string;
+    /** Secondary verbs at the bottom-left (quit, back). Same navigation, quieter styling. */
+    secondary?: readonly GameMenuItem[];
+    /** Footer left slot: build version, studio. */
+    footer?: ReactNode;
+    /** Footer right slot: replaces the default control hint. */
+    controlHint?: ReactNode;
+    /** Selection sound. Default on. Pass `false` for silence, or a player from `createGameMenuSound`. */
+    sound?: boolean | GameMenuSound;
+    /** Title menu or the smaller pause menu. Default `"title"`. */
+    variant?: GameMenuVariant;
+    /** Open state the game owns. A closed menu renders nothing and releases the document scroll. */
+    open?: boolean;
+    /** Force motion off. Reduced motion is also read from the accessibility preference and the OS. */
+    reducedMotion?: boolean;
+    /** Accessible name of the surface. Default `"Main menu"` (`"Paused"` for the pause variant). */
+    label?: string;
+    className?: string;
+    style?: CSSProperties;
+    detailClassName?: string;
+    detailStyle?: CSSProperties;
+}
+/**
+ * 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.
+ *
+ * @capability use-viewport-scroll-lock count-aware document scroll lock for full-bleed surfaces
+ */
+export declare function useViewportScrollLock(active: boolean): void;
+/**
+ * A game front-end menu: full-bleed over a living background, with a logo, an animated primary list
+ * and a detail pane that follows the highlighted verb. One system covers the main menu and the pause
+ * menu (`variant="pause"`), keyboard and gamepad navigation come from `useMenuNav`, confirmation
+ * ticks are generated (no audio asset), and the document never scrolls while it is open.
+ *
+ * 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.
+ *
+ * @capability game-menu full-bleed game menu — living background, token-sized logo, animated navigable verbs, detail pane, selection sound, pause variant, no page scrollbar
+ */
+export declare function GameMenu({ items, initialId, onSelect, onBack, onHighlight, detail, logo, eyebrow, tagline, background, art, secondary, footer, controlHint, sound, variant, open, reducedMotion, label, className, style, detailClassName, detailStyle, }: GameMenuProps): 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.
+ *
+ * @capability game-pause-menu pause menu from the shared game-menu system — same navigation and surface, sized down
+ */
+export declare function GamePauseMenu(props: Omit<GameMenuProps, "variant"> & {
+    onResume?: () => void;
+}): ReactNode;

package/dist/gameMenu.js

@@ -0,0 +1,400 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef, } from "react";
+import { useReducedMotion } from "./accessibility.js";
+import { createGameMenuSound } from "./gameMenuSound.js";
+import { hudDuration, hudEase, hudFont, hudType } from "./hudTokens.js";
+import { useMenuNav } from "./menuNav.js";
+let scrollLocks = 0;
+let savedDocumentOverflow = "";
+let savedBodyOverflow = "";
+function lockDocumentScroll() {
+    if (typeof document === "undefined")
+        return () => { };
+    if (scrollLocks === 0) {
+        savedDocumentOverflow = document.documentElement.style.overflow;
+        savedBodyOverflow = document.body.style.overflow;
+        document.documentElement.style.overflow = "hidden";
+        document.body.style.overflow = "hidden";
+    }
+    scrollLocks += 1;
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        scrollLocks -= 1;
+        if (scrollLocks > 0 || typeof document === "undefined")
+            return;
+        document.documentElement.style.overflow = savedDocumentOverflow;
+        document.body.style.overflow = savedBodyOverflow;
+    };
+}
+/**
+ * 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.
+ *
+ * @capability use-viewport-scroll-lock count-aware document scroll lock for full-bleed surfaces
+ */
+export function useViewportScrollLock(active) {
+    useEffect(() => {
+        if (!active)
+            return;
+        return lockDocumentScroll();
+    }, [active]);
+}
+const ROW_HEIGHT = { title: 58, pause: 46 };
+const VIGNETTE = "radial-gradient(125% 110% at 26% 42%, rgba(4,7,12,0.02) 0%, rgba(4,7,12,0.34) 66%, rgba(2,4,7,0.8) 100%)";
+const TINT = "linear-gradient(100deg, rgba(6,10,16,0.9) 0%, rgba(6,10,16,0.74) 34%, rgba(6,10,16,0.34) 56%, rgba(6,10,16,0.08) 78%, rgba(6,10,16,0.28) 100%)";
+function logoNode(logo, title, reduced) {
+    if (logo === undefined || logo === null || logo === false)
+        return null;
+    if (typeof logo === "object" && !Array.isArray(logo) && !("type" in logo)) {
+        const spec = logo;
+        const size = "var(--jg-menu-logo-size, clamp(30px, 4.6vw, 66px))";
+        if (spec.image !== undefined) {
+            return (_jsx("img", { "data-jg-game-menu-logo": "", src: spec.image, alt: spec.alt ?? spec.title ?? title ?? "", style: {
+                    display: "block",
+                    width: "auto",
+                    height: `calc(${size} * 1.15)`,
+                    maxWidth: "min(420px, 46vw)",
+                    objectFit: "contain",
+                    filter: "drop-shadow(0 8px 30px rgba(0,0,0,0.6))",
+                } }));
+        }
+        return (_jsx("div", { "data-jg-game-menu-logo": "", style: {
+                fontFamily: hudFont.display,
+                fontSize: size,
+                fontWeight: 800,
+                lineHeight: 0.98,
+                letterSpacing: "-0.02em",
+                color: "var(--jg-text, #f7f9fc)",
+                textShadow: "0 2px 24px rgba(0,0,0,0.65), 0 0 60px var(--jg-accent-glow, rgba(88,196,255,0.25))",
+                animation: reduced ? undefined : `jg-menu-rise 620ms ${hudEase("easeOut")} both`,
+            }, children: spec.text ?? spec.title ?? title }));
+    }
+    return (_jsx("div", { "data-jg-game-menu-logo": "", style: {
+            fontFamily: hudFont.display,
+            fontSize: "var(--jg-menu-logo-size, clamp(30px, 4.6vw, 66px))",
+            fontWeight: 800,
+            lineHeight: 0.98,
+            letterSpacing: "-0.02em",
+            color: "var(--jg-text, #f7f9fc)",
+            textShadow: "0 2px 24px rgba(0,0,0,0.65), 0 0 60px var(--jg-accent-glow, rgba(88,196,255,0.25))",
+            animation: reduced ? undefined : `jg-menu-rise 620ms ${hudEase("easeOut")} both`,
+        }, children: logo }));
+}
+/**
+ * A game front-end menu: full-bleed over a living background, with a logo, an animated primary list
+ * and a detail pane that follows the highlighted verb. One system covers the main menu and the pause
+ * menu (`variant="pause"`), keyboard and gamepad navigation come from `useMenuNav`, confirmation
+ * ticks are generated (no audio asset), and the document never scrolls while it is open.
+ *
+ * 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.
+ *
+ * @capability game-menu full-bleed game menu — living background, token-sized logo, animated navigable verbs, detail pane, selection sound, pause variant, no page scrollbar
+ */
+export function GameMenu({ items, initialId, onSelect, onBack, onHighlight, detail, logo, eyebrow, tagline, background, art, secondary, footer, controlHint, sound = true, variant = "title", open = true, reducedMotion, label, className, style, detailClassName, detailStyle, }) {
+    const prefersReduced = useReducedMotion();
+    const reduced = reducedMotion === undefined ? prefersReduced : reducedMotion || prefersReduced;
+    useViewportScrollLock(open);
+    const allItems = useMemo(() => [...items, ...(secondary ?? [])], [items, secondary]);
+    const disabled = useMemo(() => allItems.filter((item) => item.disabled === true).map((item) => item.id), [allItems]);
+    const soundRef = useRef(null);
+    useEffect(() => {
+        if (sound === false)
+            return;
+        const player = typeof sound === "object" ? sound : createGameMenuSound();
+        soundRef.current = player;
+        return () => {
+            if (typeof sound !== "object")
+                player.dispose();
+            soundRef.current = null;
+        };
+    }, [sound]);
+    const onHighlightRef = useRef(onHighlight);
+    onHighlightRef.current = onHighlight;
+    const nav = useMenuNav({
+        ids: allItems.map((item) => item.id),
+        disabled,
+        enabled: open,
+        ...(initialId === undefined ? {} : { initialId }),
+        onConfirm: (id) => {
+            const item = allItems.find((candidate) => candidate.id === id);
+            if (item === undefined || item.disabled === true)
+                return;
+            soundRef.current?.play("confirm");
+            onSelect(id);
+        },
+        ...(onBack === undefined
+            ? {}
+            : {
+                onBack: () => {
+                    soundRef.current?.play("back");
+                    onBack();
+                },
+            }),
+    });
+    // A cursor that happens to rest over a row when the menu opens must not select it: hover only
+    // counts once the pointer has actually moved in this session.
+    const pointerMoved = useRef(false);
+    useEffect(() => {
+        if (typeof window === "undefined")
+            return;
+        const mark = () => { pointerMoved.current = true; };
+        window.addEventListener("pointermove", mark, { passive: true });
+        return () => window.removeEventListener("pointermove", mark);
+    }, []);
+    const hoverProps = (id) => {
+        const props = nav.itemProps(id);
+        return { ...props, onPointerEnter: () => { if (pointerMoved.current)
+                props.onPointerEnter(); } };
+    };
+    const activeId = nav.activeId;
+    const activeIndex = allItems.findIndex((item) => item.id === activeId);
+    const mounted = useRef(false);
+    const appliedInitial = useRef(initialId);
+    // `initialId` is the verb the game wants focused (Continue when a save exists). When that changes
+    // after mount — a save finished loading, a screen swapped — move the selection rather than
+    // remounting the whole menu, which would replay the entry animation and drop focus.
+    useEffect(() => {
+        if (initialId === undefined || appliedInitial.current === initialId || disabled.includes(initialId))
+            return;
+        appliedInitial.current = initialId;
+        nav.setActive(initialId);
+    }, [initialId, disabled, nav.activeId, nav.setActive]);
+    // The first pass can run before item refs exist, so focus the selection once after paint when the
+    // menu owns an idle document. Arrow keys then land on the menu itself instead of the page.
+    useEffect(() => {
+        if (!open)
+            return;
+        if (typeof requestAnimationFrame !== "function")
+            return;
+        const frame = requestAnimationFrame(() => {
+            const active = typeof document === "undefined" ? null : document.activeElement;
+            const insideMenu = active !== null && typeof active.closest === "function" && active.closest("[data-jg-game-menu]") !== null;
+            if (insideMenu && active !== document.body)
+                return;
+            const target = document.querySelector("[data-jg-game-menu] [data-jg-menu-item][aria-current='true']");
+            target?.focus({ preventScroll: true });
+        });
+        return () => cancelAnimationFrame(frame);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [open, activeId]);
+    useEffect(() => {
+        if (!mounted.current) {
+            mounted.current = true;
+        }
+        else if (activeId !== null) {
+            soundRef.current?.play("move");
+        }
+        onHighlightRef.current?.(activeId);
+    }, [activeId]);
+    if (!open)
+        return null;
+    const isPause = variant === "pause";
+    const rowHeight = ROW_HEIGHT[variant];
+    const primaryCount = items.length;
+    const detailNode = typeof detail === "function" ? detail(activeId) : detail;
+    const title = typeof logo === "object" && logo !== null && !Array.isArray(logo) ? logo.title : undefined;
+    const surfaceLabel = label ?? (isPause ? "Paused" : "Main menu");
+    return (_jsxs("div", { "data-jg-game-menu": "", "data-variant": variant, "data-open": "", role: "dialog", "aria-modal": "true", "aria-label": surfaceLabel, className: className, style: {
+            position: "fixed",
+            inset: 0,
+            width: "100vw",
+            height: "100dvh",
+            maxWidth: "100vw",
+            maxHeight: "100dvh",
+            overflow: "hidden",
+            overscrollBehavior: "contain",
+            display: "grid",
+            gridTemplateRows: "auto minmax(0, 1fr) auto",
+            gridTemplateColumns: "minmax(232px, clamp(232px, 27vw, 360px)) minmax(0, 1fr)",
+            columnGap: "clamp(16px, 3vw, 56px)",
+            padding: isPause
+                ? "clamp(16px, 2.4vw, 34px) clamp(20px, 3.2vw, 56px)"
+                : "clamp(18px, 3.2vw, 56px) clamp(20px, 3.6vw, 64px)",
+            boxSizing: "border-box",
+            color: "var(--jg-text, #f5f7fa)",
+            fontFamily: hudFont.body,
+            animation: reduced ? undefined : `jg-fade-in ${hudDuration("slow")} ${hudEase("easeOut")} both`,
+            ...style,
+        }, children: [_jsxs("div", { "data-jg-game-menu-backdrop": "", "aria-hidden": "true", style: { position: "absolute", inset: 0, overflow: "hidden", pointerEvents: "none", zIndex: 0 }, children: [background === undefined ? null : (_jsx("div", { "data-jg-game-menu-live": "", style: { position: "absolute", inset: 0 }, children: background })), art === undefined ? null : (_jsx("div", { "data-jg-game-menu-art": "", style: {
+                            position: "absolute",
+                            inset: "-8%",
+                            backgroundImage: `url(${art})`,
+                            backgroundSize: "cover",
+                            backgroundPosition: "center",
+                            transform: "scale(1.06)",
+                            animation: reduced ? undefined : "jg-menu-drift 46s ease-in-out infinite alternate",
+                            willChange: "transform",
+                        } })), _jsx("div", { "data-jg-game-menu-tint": "", style: { position: "absolute", inset: 0, background: TINT, opacity: isPause ? 1 : 0.94 } }), _jsx("div", { "data-jg-game-menu-vignette": "", style: { position: "absolute", inset: 0, background: VIGNETTE } }), _jsx("div", { "data-jg-game-menu-grain": "", style: {
+                            position: "absolute",
+                            inset: 0,
+                            opacity: 0.06,
+                            backgroundImage: "repeating-linear-gradient(0deg, rgba(255,255,255,0.5) 0px, rgba(255,255,255,0.5) 1px, transparent 1px, transparent 3px)",
+                            mixBlendMode: "overlay",
+                        } })] }), _jsxs("header", { "data-jg-game-menu-header": "", style: {
+                    position: "relative",
+                    zIndex: 1,
+                    gridColumn: "1 / -1",
+                    display: "flex",
+                    flexDirection: "column",
+                    gap: 6,
+                    minWidth: 0,
+                }, children: [eyebrow === undefined ? null : (_jsx("div", { "data-jg-game-menu-eyebrow": "", style: {
+                            fontSize: hudType("xs"),
+                            letterSpacing: "0.3em",
+                            textTransform: "uppercase",
+                            color: "var(--jg-accent, #7dd3fc)",
+                            fontWeight: 700,
+                        }, children: eyebrow })), logoNode(logo, title, reduced), tagline === undefined ? null : (_jsx("div", { "data-jg-game-menu-tagline": "", style: {
+                            fontSize: hudType(isPause ? "sm" : "md"),
+                            color: "var(--jg-text-dim, rgba(226,235,245,0.68))",
+                            maxWidth: "46ch",
+                        }, children: tagline }))] }), _jsx("div", { "data-jg-game-menu-nav-wrap": "", style: {
+                    position: "relative",
+                    zIndex: 1,
+                    display: "flex",
+                    flexDirection: "column",
+                    justifyContent: isPause ? "center" : "flex-start",
+                    minHeight: 0,
+                    paddingTop: isPause ? 0 : "clamp(8px, 2vh, 28px)",
+                }, children: _jsxs("nav", { "data-jg-game-menu-items": "", ...nav.containerProps, style: { position: "relative", display: "flex", flexDirection: "column", gap: 2 }, onKeyDown: (event) => {
+                        nav.containerProps.onKeyDown(event);
+                        if (event.key === "ArrowDown" || event.key === "ArrowUp")
+                            event.stopPropagation();
+                    }, 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,
+                                top: 0,
+                                height: rowHeight,
+                                borderRadius: 10,
+                                opacity: activeIndex < 0 ? 0 : 1,
+                                transform: `translate3d(0, ${Math.max(0, activeIndex) * (rowHeight + 2)}px, 0) scale(${activeIndex >= primaryCount ? 0.98 : 1})`,
+                                transition: reduced
+                                    ? undefined
+                                    : `transform ${hudDuration("base")} ${hudEase("spring")}, opacity ${hudDuration("fast")} ${hudEase("easeOut")}`,
+                                background: "linear-gradient(90deg, var(--jg-accent-glow, rgba(94,196,255,0.22)) 0%, rgba(255,255,255,0.05) 62%, transparent 100%)",
+                                boxShadow: "inset 0 0 0 1px rgba(255,255,255,0.14), 0 10px 30px -14px rgba(0,0,0,0.9)",
+                                borderLeft: "2px solid var(--jg-accent, #7dd3fc)",
+                            } }), items.map((item) => {
+                            const active = item.id === activeId;
+                            return (_jsxs("button", { type: "button", ...hoverProps(item.id), "data-jg-game-menu-item": item.id, "data-active": active ? "" : undefined, disabled: item.disabled === true, onClick: () => {
+                                    if (item.disabled === true)
+                                        return;
+                                    soundRef.current?.play("confirm");
+                                    onSelect(item.id);
+                                }, style: {
+                                    position: "relative",
+                                    display: "flex",
+                                    alignItems: "center",
+                                    justifyContent: "space-between",
+                                    gap: 10,
+                                    height: rowHeight,
+                                    paddingLeft: active ? 18 : 12,
+                                    paddingRight: 12,
+                                    border: "none",
+                                    background: "transparent",
+                                    color: item.disabled === true ? "rgba(226,235,245,0.32)" : active ? "var(--jg-text, #ffffff)" : "rgba(226,235,245,0.78)",
+                                    fontFamily: hudFont.display,
+                                    fontSize: hudType(isPause ? "md" : "xl"),
+                                    fontWeight: active ? 700 : 600,
+                                    letterSpacing: "0.01em",
+                                    textAlign: "left",
+                                    cursor: item.disabled === true ? "not-allowed" : "pointer",
+                                    transition: reduced ? undefined : `padding ${hudDuration("base")} ${hudEase("spring")}, color ${hudDuration("fast")} linear`,
+                                    textShadow: active
+                                        ? "0 1px 12px rgba(0,0,0,0.8), 0 0 22px var(--jg-accent-glow, rgba(94,196,255,0.4))"
+                                        : "0 1px 10px rgba(0,0,0,0.72)",
+                                    outline: "none",
+                                }, children: [_jsxs("span", { style: { display: "flex", flexDirection: "column", gap: 1, minWidth: 0 }, children: [_jsx("span", { style: { whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis" }, children: item.label }), item.hint === undefined ? null : (_jsx("span", { style: {
+                                                    fontSize: hudType("xs"),
+                                                    fontWeight: 500,
+                                                    letterSpacing: 0,
+                                                    color: "var(--jg-text-dim, rgba(203,213,225,0.66))",
+                                                    whiteSpace: "nowrap",
+                                                    overflow: "hidden",
+                                                    textOverflow: "ellipsis",
+                                                    opacity: active ? 1 : 0.72,
+                                                }, children: item.hint }))] }), item.badge === undefined ? null : (_jsx("span", { style: { fontSize: hudType("xs"), color: "var(--jg-accent, #7dd3fc)", fontWeight: 700 }, children: item.badge }))] }, item.id));
+                        }), secondary === undefined || secondary.length === 0 ? null : (_jsx("div", { style: { height: 1, margin: "10px 12px", background: "rgba(255,255,255,0.12)" }, "aria-hidden": "true" })), (secondary ?? []).map((item) => {
+                            const active = item.id === activeId;
+                            return (_jsx("button", { type: "button", ...hoverProps(item.id), "data-jg-game-menu-item": item.id, "data-secondary": "", "data-active": active ? "" : undefined, disabled: item.disabled === true, onClick: () => {
+                                    if (item.disabled === true)
+                                        return;
+                                    soundRef.current?.play("confirm");
+                                    onSelect(item.id);
+                                }, style: {
+                                    position: "relative",
+                                    display: "flex",
+                                    alignItems: "center",
+                                    height: rowHeight,
+                                    paddingLeft: active ? 18 : 12,
+                                    border: "none",
+                                    background: "transparent",
+                                    color: active ? "var(--jg-text, #ffffff)" : "rgba(203,213,225,0.6)",
+                                    fontFamily: hudFont.body,
+                                    fontSize: hudType("md"),
+                                    fontWeight: 600,
+                                    textAlign: "left",
+                                    cursor: item.disabled === true ? "not-allowed" : "pointer",
+                                    transition: reduced ? undefined : `padding ${hudDuration("base")} ${hudEase("spring")}`,
+                                    outline: "none",
+                                }, children: item.label }, item.id));
+                        })] }) }), _jsx("div", { "data-jg-game-menu-detail": "", "data-detail-id": activeId ?? "", className: detailClassName, style: {
+                    position: "relative",
+                    zIndex: 1,
+                    minWidth: 0,
+                    minHeight: 0,
+                    maxHeight: "100%",
+                    overflow: "hidden",
+                    display: "flex",
+                    flexDirection: "column",
+                    paddingTop: isPause ? 0 : "clamp(6px, 1.6vh, 20px)",
+                    ...detailStyle,
+                }, children: detailNode === undefined || detailNode === null ? null : (_jsx("div", { "data-jg-game-menu-pane": "", style: {
+                        minHeight: 0,
+                        flex: 1,
+                        display: "flex",
+                        flexDirection: "column",
+                        animation: reduced ? undefined : `jg-menu-pane-in ${hudDuration("slow")} ${hudEase("easeOut")} both`,
+                    }, children: detailNode }, activeId ?? "none")) }), _jsxs("footer", { "data-jg-game-menu-footer": "", style: {
+                    position: "relative",
+                    zIndex: 1,
+                    gridColumn: "1 / -1",
+                    display: "flex",
+                    alignItems: "center",
+                    justifyContent: "space-between",
+                    gap: 16,
+                    paddingTop: 8,
+                    fontSize: hudType("xs"),
+                    letterSpacing: "0.08em",
+                    textTransform: "uppercase",
+                    color: "rgba(203,213,225,0.45)",
+                }, children: [_jsx("span", { "data-jg-game-menu-footer-left": "", children: footer }), _jsx("span", { "data-jg-kbd-hint": "", "data-jg-game-menu-footer-hint": "", children: controlHint ??
+                            (isPause ? "Esc resume · Enter select" : "↑↓ move · Enter select · Esc back") })] })] }));
+}
+/**
+ * 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.
+ *
+ * @capability game-pause-menu pause menu from the shared game-menu system — same navigation and surface, sized down
+ */
+export function GamePauseMenu(props) {
+    const { onResume, onBack, ...rest } = props;
+    return _jsx(GameMenu, { ...rest, variant: "pause", onBack: onBack ?? onResume, label: rest.label ?? "Paused" });
+}