@jgengine/react 0.24.0 → 0.25.0

package/CHANGELOG.md

@@ -26,6 +26,33 @@ 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.25.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.25.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.22.0`; `@jgengine/github` is `0.12.0`.
+- The frame panel from `@jgengine/react/hudPanel` is now `HudSurface` in `@jgengine/react/hudSurface` (`HudSurfaceProps`, `HudSurfaceElevation`). `HudPanel`, `HudPanelProps` and `HudPanelElevation` from `@jgengine/react/hudPanel` stay as deprecated aliases for this release. The `HudCanvas` layout slot keeps the name `HudPanel`.
+- Engine HUD control sounds (button click/hover, panel and window open/close) no longer turn off with `notices: false` or `notices.cues: false`. Set `audio.hudCues: false` to silence them; `notices.cues` now covers notice sounds only.
+- The notice stack now defaults to z-index 85 (was 45), above `ModalHost`. Pass `notices.zIndex` to put it back under a game overlay.
+
+### Added
+
+- `HudSurface` takes `as` (`section`, `aside`, `nav`, ...) to render as a landmark.
+- `notices.offset`, `notices.avoidHud` and `notices.zIndex`, with matching `NoticeStack` props. The offset adds to the device safe-area inset.
+- `ctx.game.notices.push({ text, silent: true })` shows a notice without its sound.
+
+### Changed
+
+- The engine stylesheet (`@jgengine/react/styles.css` and the injected copy) sits in the `components.jgengine` cascade layer, after a `theme, base, components, utilities` layer order, so plain game CSS and Tailwind utilities override engine buttons and panels without `!important`.
+- `HudSurface` padding comes from `--jg-panel-padding` (default 12px); the `padding` prop sets that variable instead of an inline `padding`, so a game class or media query can override it.
+- `HudButton` labels wrap (`white-space: normal`, line height 1.2, 4px vertical padding) instead of overflowing on one line.
+- The shell renders the notice stack inside the HUD theme root, so notices use the game's `hudTheme` colours and font.
+- A top or bottom notice stack moves clear of `HudCanvas` panels and touch controls registered in its column (Harbor Heat's courier card, action bars).
+
+### Fixed
+
+- Flowing `HudCanvas` panels now register their layout region once their anchor region mounts; before, most never registered, so layout collision checks and region consumers missed them.
+
 ## 0.24.0
 
 ### Migrate

package/dist/engineStyles.d.ts

@@ -1,10 +1,13 @@
 /**
  * The engine stylesheet: every `jg-*` keyframe the shared blocks and registry components animate
- * with, the `[data-jg-*]` interaction-state rules behind {@link HudButton} / {@link HudPanel}, the
+ * with, the `[data-jg-*]` interaction-state rules behind {@link HudButton} / {@link HudSurface}, the
  * quiet hover/press/focus defaults for plain buttons inside the HUD root, and reduced-motion
  * handling (`prefers-reduced-motion` or `[data-reduced-motion="true"]` zero `--jg-motion-scale`).
- * Generic HUD rules sit in `:where()` so any game selector wins. The shell injects it; games that
- * mount outside the shell import `@jgengine/react/styles.css`, which holds the same text.
+ * Every rule sits in the `components.jgengine` cascade layer, so unlayered game CSS, a game's own
+ * `components` rules and Tailwind utilities win without `!important`. It first declares
+ * `theme, base, components, utilities` so Tailwind v4's preflight stays below engine controls even
+ * when the engine sheet loads first. The shell injects it; games that mount outside the shell import
+ * `@jgengine/react/styles.css`, which holds the same text.
  */
 export declare const ENGINE_STYLESHEET: string;
 /** Injects {@link ENGINE_STYLESHEET} into `doc` once. Safe to call repeatedly and during SSR (no-op). */

package/dist/engineStyles.js

@@ -16,13 +16,18 @@ const ENABLED = ':not(:disabled, [aria-disabled="true"])';
 const KILL_MOTION = "animation-duration: 1ms !important; animation-delay: 0ms !important; animation-iteration-count: 1 !important; transition-duration: 1ms !important; transition-delay: 0ms !important;";
 /**
  * The engine stylesheet: every `jg-*` keyframe the shared blocks and registry components animate
- * with, the `[data-jg-*]` interaction-state rules behind {@link HudButton} / {@link HudPanel}, the
+ * with, the `[data-jg-*]` interaction-state rules behind {@link HudButton} / {@link HudSurface}, the
  * quiet hover/press/focus defaults for plain buttons inside the HUD root, and reduced-motion
  * handling (`prefers-reduced-motion` or `[data-reduced-motion="true"]` zero `--jg-motion-scale`).
- * Generic HUD rules sit in `:where()` so any game selector wins. The shell injects it; games that
- * mount outside the shell import `@jgengine/react/styles.css`, which holds the same text.
+ * Every rule sits in the `components.jgengine` cascade layer, so unlayered game CSS, a game's own
+ * `components` rules and Tailwind utilities win without `!important`. It first declares
+ * `theme, base, components, utilities` so Tailwind v4's preflight stays below engine controls even
+ * when the engine sheet loads first. The shell injects it; games that mount outside the shell import
+ * `@jgengine/react/styles.css`, which holds the same text.
  */
 export const ENGINE_STYLESHEET = `/* @jgengine/react engine stylesheet */
+@layer theme, base, components, utilities;
+@layer components.jgengine {
 :root { --jg-motion-scale: 1; }
 @media (prefers-reduced-motion: reduce) { :root { --jg-motion-scale: 0; } }
 [data-reduced-motion="true"] { --jg-motion-scale: 0; }
@@ -56,7 +61,7 @@ export const ENGINE_STYLESHEET = `/* @jgengine/react engine stylesheet */
 }
 :where([data-jg-hud]) :where(button, [role="button"]):where(${ENABLED}):active { scale: var(--jg-press-scale, 0.97); }
 
-[data-jg-button] { appearance: none; box-sizing: border-box; position: relative; isolation: isolate; display: inline-flex; align-items: center; justify-content: center; gap: var(--jg-space-sm, 8px); min-height: 36px; padding: 0 var(--jg-space-lg, 16px); margin: 0; font-family: var(--jg-font-body, ${HUD_FONT_STACK}); font-size: var(--jg-type-md, 14px); font-weight: 600; line-height: 1; letter-spacing: 0.01em; white-space: nowrap; color: var(--jg-text, #f5f7fa); background: linear-gradient(180deg, rgba(255,255,255,0.10), rgba(255,255,255,0.03)), var(--jg-slot-bg, rgba(12,15,21,0.78)); border: var(--jg-slot-border, 1px solid rgba(255,255,255,0.13)); border-radius: var(--jg-slot-radius, 8px); box-shadow: ${HIGHLIGHT}, ${RAISED}; cursor: pointer; user-select: none; -webkit-tap-highlight-color: transparent; transition: translate ${FAST} ${EASE}, scale ${FAST} ${SPRING}, box-shadow ${FAST} ${EASE}, border-color ${FAST} ${EASE}, background-color ${FAST} ${EASE}; }
+[data-jg-button] { appearance: none; box-sizing: border-box; position: relative; isolation: isolate; display: inline-flex; align-items: center; justify-content: center; gap: var(--jg-space-sm, 8px); min-height: 36px; padding: var(--jg-space-xs, 4px) var(--jg-space-lg, 16px); margin: 0; font-family: var(--jg-font-body, ${HUD_FONT_STACK}); font-size: var(--jg-type-md, 14px); font-weight: 600; line-height: 1.2; letter-spacing: 0.01em; text-align: center; white-space: normal; color: var(--jg-text, #f5f7fa); background: linear-gradient(180deg, rgba(255,255,255,0.10), rgba(255,255,255,0.03)), var(--jg-slot-bg, rgba(12,15,21,0.78)); border: var(--jg-slot-border, 1px solid rgba(255,255,255,0.13)); border-radius: var(--jg-slot-radius, 8px); box-shadow: ${HIGHLIGHT}, ${RAISED}; cursor: pointer; user-select: none; -webkit-tap-highlight-color: transparent; transition: translate ${FAST} ${EASE}, scale ${FAST} ${SPRING}, box-shadow ${FAST} ${EASE}, border-color ${FAST} ${EASE}, background-color ${FAST} ${EASE}; }
 [data-jg-button]::after { content: ""; position: absolute; inset: 0; z-index: -1; border-radius: inherit; background: var(--jg-hover-overlay, rgba(255,255,255,0.07)); opacity: 0; pointer-events: none; transition: opacity ${FAST} ${EASE}; }
 @media (hover: hover) {
   [data-jg-button]${ENABLED}:hover { translate: 0 var(--jg-hover-lift, -1px); box-shadow: ${HIGHLIGHT}, ${OVERLAY}; }
@@ -70,12 +75,12 @@ export const ENGINE_STYLESHEET = `/* @jgengine/react engine stylesheet */
 [data-jg-button][data-variant="danger"] { color: #fff; background: linear-gradient(180deg, rgba(255,255,255,0.16), rgba(255,255,255,0) 60%), var(--jg-danger, #e5484d); border: 1px solid rgba(255,255,255,0.22); }
 [data-jg-button][data-variant="ghost"] { background: transparent; border-color: transparent; box-shadow: none; }
 [data-jg-button][data-variant="ghost"]${ENABLED}:hover { box-shadow: none; }
-[data-jg-button][data-size="sm"] { min-height: 28px; padding: 0 var(--jg-space-md, 12px); font-size: var(--jg-type-sm, 13px); }
-[data-jg-button][data-size="lg"] { min-height: 44px; padding: 0 var(--jg-space-xl, 24px); font-size: var(--jg-type-lg, 16px); }
+[data-jg-button][data-size="sm"] { min-height: 28px; padding-inline: var(--jg-space-md, 12px); font-size: var(--jg-type-sm, 13px); }
+[data-jg-button][data-size="lg"] { min-height: 44px; padding-inline: var(--jg-space-xl, 24px); font-size: var(--jg-type-lg, 16px); }
 [data-jg-button][data-size="icon"] { min-height: 0; width: 28px; height: 28px; padding: 0; font-size: var(--jg-type-sm, 13px); }
 [data-jg-button][data-block] { display: flex; width: 100%; }
 
-[data-jg-panel] { box-sizing: border-box; color: var(--jg-text, #f5f7fa); font-family: var(--jg-font-body, ${HUD_FONT_STACK}); background: var(--jg-frame-bg, rgba(12,15,21,0.9)); border: var(--jg-frame-border, 1px solid rgba(255,255,255,0.13)); border-radius: var(--jg-frame-radius, 10px); box-shadow: var(--jg-frame-glow, ${HIGHLIGHT}, ${RAISED}); }
+[data-jg-panel] { box-sizing: border-box; padding: var(--jg-panel-padding, 12px); color: var(--jg-text, #f5f7fa); font-family: var(--jg-font-body, ${HUD_FONT_STACK}); background: var(--jg-frame-bg, rgba(12,15,21,0.9)); border: var(--jg-frame-border, 1px solid rgba(255,255,255,0.13)); border-radius: var(--jg-frame-radius, 10px); box-shadow: var(--jg-frame-glow, ${HIGHLIGHT}, ${RAISED}); }
 [data-jg-panel][data-elevation="overlay"] { box-shadow: var(--jg-frame-glow, ${HIGHLIGHT}), ${OVERLAY}; }
 [data-jg-panel][data-elevation="modal"] { box-shadow: var(--jg-frame-glow, ${HIGHLIGHT}), ${MODAL}; }
 [data-jg-panel][data-state="open"] { animation: jg-panel-in ${BASE} ${EASE_OUT} both; }
@@ -94,6 +99,7 @@ export const ENGINE_STYLESHEET = `/* @jgengine/react engine stylesheet */
 @media (hover: hover) { [data-action-id][data-enabled]:hover { translate: 0 var(--jg-hover-lift, -1px); } }
 [data-action-id][data-enabled]:active { translate: 0 0; scale: var(--jg-press-scale, 0.97); }
 [data-action-id]:focus-visible { outline: none; box-shadow: ${FOCUS}; }
+}
 `;
 const STYLE_ID = "jg-engine-styles";
 /** Injects {@link ENGINE_STYLESHEET} into `doc` once. Safe to call repeatedly and during SSR (no-op). */

package/dist/hudChromePreview.js

@@ -4,7 +4,7 @@ import { ActionButton } from "./actionHud.js";
 import { HealthBar, ManaBar } from "./bars.js";
 import { HudButton } from "./hudButton.js";
 import { HudFrame } from "./hudFrame.js";
-import { HudPanel } from "./hudPanel.js";
+import { HudSurface } from "./hudSurface.js";
 import { HudThemeRoot } from "./hudThemeRoot.js";
 import { ConfirmDialog, PauseMenu } from "./modals.js";
 import { Window } from "./panels.js";
@@ -23,5 +23,5 @@ const noop = () => undefined;
  * variants. Screenshots identically; the before/after evidence for theme and primitive changes.
  */
 export function HudChromePreview({ className }) {
-    return (_jsx("div", { className: className, style: { position: "relative", width: "100%", height: "100%", minHeight: 720, overflow: "hidden", background: "radial-gradient(ellipse at 30% 20%, #3b5a46, #1b2a24 55%, #0f1714)" }, children: _jsxs(HudThemeRoot, { children: [_jsx("div", { style: { position: "absolute", left: 24, top: 24, width: 280 }, children: _jsx(HudFrame, { title: "Warden \u00B7 Lv 12", aside: _jsx(TweenNumber, { value: 12480 }), padding: 12, children: _jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 6 }, children: [_jsx(HealthBar, { value: 78, max: 100, label: "HP", width: "100%" }), _jsx(ManaBar, { value: 50, max: 80, label: "MP", width: "100%" })] }) }) }), _jsx("div", { style: { position: "absolute", left: 24, bottom: 24, display: "flex", gap: 8 }, children: ACTIONS.map((action, index) => (_jsx(ActionButton, { action: action, focused: index === 0 }, action.id))) }), _jsx(Window, { title: "Inventory", x: 340, y: 24, width: 260, closable: true, onClose: noop, children: _jsx("div", { style: { display: "grid", gridTemplateColumns: "repeat(5, 1fr)", gap: 6 }, children: Array.from({ length: 10 }, (_, index) => (_jsx("div", { style: { aspectRatio: "1", background: "var(--jg-slot-bg)", border: "var(--jg-slot-border)", borderRadius: "var(--jg-slot-radius)" } }, index))) }) }), _jsx("div", { style: { position: "absolute", left: 640, top: 24 }, children: _jsx(ConfirmDialog, { title: "Abandon the expedition?", body: "Your haul stays in the wagon, but the crew returns home.", confirmLabel: "Abandon", danger: true, onConfirm: noop, onCancel: noop }) }), _jsx("div", { style: { position: "absolute", left: 1040, top: 24 }, children: _jsx(PauseMenu, { onResume: noop, items: [{ id: "settings", label: "Settings", onSelect: noop }, { id: "quit", label: "Quit to title", onSelect: noop, danger: true }] }) }), _jsx("div", { style: { position: "absolute", left: 340, top: 300 }, children: _jsx(HudPanel, { title: "Buttons", padding: 14, children: _jsxs("div", { style: { display: "flex", gap: 8, flexWrap: "wrap", width: 420 }, children: [_jsx(HudButton, { variant: "primary", children: "Deploy" }), _jsx(HudButton, { children: "Inspect" }), _jsx(HudButton, { variant: "ghost", children: "Skip" }), _jsx(HudButton, { variant: "danger", children: "Scrap" }), _jsx(HudButton, { disabled: true, children: "Locked" }), _jsx(HudButton, { size: "sm", children: "Small" })] }) }) })] }) }));
+    return (_jsx("div", { className: className, style: { position: "relative", width: "100%", height: "100%", minHeight: 720, overflow: "hidden", background: "radial-gradient(ellipse at 30% 20%, #3b5a46, #1b2a24 55%, #0f1714)" }, children: _jsxs(HudThemeRoot, { children: [_jsx("div", { style: { position: "absolute", left: 24, top: 24, width: 280 }, children: _jsx(HudFrame, { title: "Warden \u00B7 Lv 12", aside: _jsx(TweenNumber, { value: 12480 }), padding: 12, children: _jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 6 }, children: [_jsx(HealthBar, { value: 78, max: 100, label: "HP", width: "100%" }), _jsx(ManaBar, { value: 50, max: 80, label: "MP", width: "100%" })] }) }) }), _jsx("div", { style: { position: "absolute", left: 24, bottom: 24, display: "flex", gap: 8 }, children: ACTIONS.map((action, index) => (_jsx(ActionButton, { action: action, focused: index === 0 }, action.id))) }), _jsx(Window, { title: "Inventory", x: 340, y: 24, width: 260, closable: true, onClose: noop, children: _jsx("div", { style: { display: "grid", gridTemplateColumns: "repeat(5, 1fr)", gap: 6 }, children: Array.from({ length: 10 }, (_, index) => (_jsx("div", { style: { aspectRatio: "1", background: "var(--jg-slot-bg)", border: "var(--jg-slot-border)", borderRadius: "var(--jg-slot-radius)" } }, index))) }) }), _jsx("div", { style: { position: "absolute", left: 640, top: 24 }, children: _jsx(ConfirmDialog, { title: "Abandon the expedition?", body: "Your haul stays in the wagon, but the crew returns home.", confirmLabel: "Abandon", danger: true, onConfirm: noop, onCancel: noop }) }), _jsx("div", { style: { position: "absolute", left: 1040, top: 24 }, children: _jsx(PauseMenu, { onResume: noop, items: [{ id: "settings", label: "Settings", onSelect: noop }, { id: "quit", label: "Quit to title", onSelect: noop, danger: true }] }) }), _jsx("div", { style: { position: "absolute", left: 340, top: 300 }, children: _jsx(HudSurface, { title: "Buttons", padding: 14, children: _jsxs("div", { style: { display: "flex", gap: 8, flexWrap: "wrap", width: 420 }, children: [_jsx(HudButton, { variant: "primary", children: "Deploy" }), _jsx(HudButton, { children: "Inspect" }), _jsx(HudButton, { variant: "ghost", children: "Skip" }), _jsx(HudButton, { variant: "danger", children: "Scrap" }), _jsx(HudButton, { disabled: true, children: "Locked" }), _jsx(HudButton, { size: "sm", children: "Small" })] }) }) })] }) }));
 }

package/dist/hudLayout.js

@@ -579,7 +579,9 @@ export function HudPanel({ id, anchor = "top-left", order, compact: compactMode
         allowOverlapWith,
         collisionGroup,
     }), [id, mobileBehavior, priority, allowOverlapWith, collisionGroup]);
-    useRegisterLayoutRegion(regionSpec, rootRef, region && !regionHidden);
+    // A flowing panel portals into its anchor region, which HudCanvas only provides after its first commit.
+    const awaitingRegion = panel !== undefined && (compact || !panel.moved) && regions[compact ? anchor : panel.placement.anchor] === undefined;
+    useRegisterLayoutRegion(regionSpec, rootRef, region && !regionHidden && !awaitingRegion);
     const onPointerDown = (event) => {
         if (!draggable || event.button !== 0)
             return;

package/dist/hudPanel.d.ts

@@ -1,31 +1,17 @@
-import { type HTMLAttributes, type ReactNode } from "react";
-import { type HudInteractListener } from "./hudInteract.js";
-/** Shadow height of a {@link HudPanel}. */
-export type HudPanelElevation = "raised" | "overlay" | "modal";
-/** Props for {@link HudPanel}. */
-export interface HudPanelProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
-    /** Show or hide with an enter/exit transition. Unset renders a static panel with no transition. */
-    open?: boolean;
-    /** Uppercase header label at the top-left. */
-    title?: ReactNode;
-    /** Header content at the top-right, opposite `title`. */
-    aside?: ReactNode;
-    /** Shadow height. Default `raised`. */
-    elevation?: HudPanelElevation;
-    padding?: number | string;
-    width?: number | string;
-    /** Accept pointer events. Default `true`. */
-    interactive?: boolean;
-    /** Feedback cue name, rendered as `data-jg-cue` and passed to `onInteract`. */
-    cue?: string;
-    /** Called with `open` and `close` as the panel shows and hides. */
-    onInteract?: HudInteractListener;
-}
+import { type HudSurfaceElevation, type HudSurfaceProps } from "./hudSurface.js";
 /**
- * Themed panel/window frame over the `HudTheme` frame, elevation, and motion tokens. It enters with
- * a short rise-and-fade and stays mounted through its exit when `open` turns false
- * (`data-state="open" | "closed"`); reduced motion skips both. `className` and `style` restyle it.
- *
- * @capability hud-panel themed panel frame with elevation, header slots, and open/close transitions
+ * Old name of {@link HudSurfaceElevation} (`@jgengine/react/hudSurface`).
+ * @deprecated Use `HudSurfaceElevation`; this alias goes in the next release.
  */
-export declare const HudPanel: import("react").ForwardRefExoticComponent<HudPanelProps & import("react").RefAttributes<HTMLDivElement>>;
+export type HudPanelElevation = HudSurfaceElevation;
+/**
+ * Old name of {@link HudSurfaceProps} (`@jgengine/react/hudSurface`).
+ * @deprecated Use `HudSurfaceProps`; this alias goes in the next release.
+ */
+export type HudPanelProps = HudSurfaceProps;
+/**
+ * Old name of the themed frame {@link HudSurface} (`@jgengine/react/hudSurface`), renamed so it no longer
+ * shares a name with the `HudCanvas` layout slot `HudPanel`.
+ * @deprecated Use `HudSurface`; this alias goes in the next release.
+ */
+export declare const HudPanel: import("react").ForwardRefExoticComponent<HudSurfaceProps & import("react").RefAttributes<HTMLElement>>;

package/dist/hudPanel.js

@@ -1,32 +1,7 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { forwardRef, useEffect, useRef } from "react";
-import { useReducedMotion } from "./accessibility.js";
-import { useEngineStyles } from "./engineStyles.js";
-import { useHudInteract } from "./hudInteract.js";
-import { usePresence } from "./presence.js";
-const EXIT_MS = 140;
+import { HudSurface } from "./hudSurface.js";
 /**
- * Themed panel/window frame over the `HudTheme` frame, elevation, and motion tokens. It enters with
- * a short rise-and-fade and stays mounted through its exit when `open` turns false
- * (`data-state="open" | "closed"`); reduced motion skips both. `className` and `style` restyle it.
- *
- * @capability hud-panel themed panel frame with elevation, header slots, and open/close transitions
+ * Old name of the themed frame {@link HudSurface} (`@jgengine/react/hudSurface`), renamed so it no longer
+ * shares a name with the `HudCanvas` layout slot `HudPanel`.
+ * @deprecated Use `HudSurface`; this alias goes in the next release.
  */
-export const HudPanel = forwardRef(function HudPanel({ open, title, aside, elevation = "raised", padding = 12, width, interactive = true, cue, onInteract, style, children, ...rest }, ref) {
-    useEngineStyles();
-    const reduced = useReducedMotion();
-    const shown = open ?? true;
-    const presence = usePresence(shown, reduced ? 0 : EXIT_MS);
-    const report = useHudInteract("panel", cue, onInteract);
-    const wasOpen = useRef(shown);
-    useEffect(() => {
-        if (wasOpen.current === shown)
-            return;
-        wasOpen.current = shown;
-        report(shown ? "open" : "close");
-    }, [shown, report]);
-    if (presence === "unmounted")
-        return null;
-    const hasHeader = title !== undefined || aside !== undefined;
-    return (_jsxs("div", { ...rest, ref: ref, "data-jg-panel": "", "data-state": open === undefined ? undefined : presence, "data-elevation": elevation, "data-jg-cue": cue, style: { padding, width, pointerEvents: interactive ? "auto" : undefined, ...style }, children: [hasHeader ? (_jsxs("div", { "data-jg-panel-header": "", style: { marginBottom: 8 }, children: [_jsx("span", { children: title }), aside !== undefined ? _jsx("span", { children: aside }) : null] })) : null, children] }));
-});
+export const HudPanel = HudSurface;

package/dist/hudSurface.d.ts

@@ -0,0 +1,38 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+import { type HudInteractListener } from "./hudInteract.js";
+/** Shadow height of a {@link HudSurface}. */
+export type HudSurfaceElevation = "raised" | "overlay" | "modal";
+/** Block elements a {@link HudSurface} can render as, so it can be a landmark. */
+export type HudSurfaceElement = "div" | "section" | "aside" | "nav" | "header" | "footer" | "article" | "main" | "form" | "dialog";
+/** Props for {@link HudSurface}. */
+export interface HudSurfaceProps extends Omit<HTMLAttributes<HTMLElement>, "title"> {
+    /** Element to render. Default `div`; `section`, `aside`, `nav` and the like make it a landmark. */
+    as?: HudSurfaceElement;
+    /** Show or hide with an enter/exit transition. Unset renders a static panel with no transition. */
+    open?: boolean;
+    /** Uppercase header label at the top-left. */
+    title?: ReactNode;
+    /** Header content at the top-right, opposite `title`. */
+    aside?: ReactNode;
+    /** Shadow height. Default `raised`. */
+    elevation?: HudSurfaceElevation;
+    /** Sets `--jg-panel-padding` (default 12px from the stylesheet), so a game class or media query still overrides it. */
+    padding?: number | string;
+    width?: number | string;
+    /** Accept pointer events. Default `true`. */
+    interactive?: boolean;
+    /** Feedback cue name, rendered as `data-jg-cue` and passed to `onInteract`. */
+    cue?: string;
+    /** Called with `open` and `close` as the panel shows and hides. */
+    onInteract?: HudInteractListener;
+}
+/**
+ * Themed panel/window frame over the `HudTheme` frame, elevation, and motion tokens. It enters with
+ * a short rise-and-fade and stays mounted through its exit when `open` turns false
+ * (`data-state="open" | "closed"`); reduced motion skips both. Padding comes from
+ * `--jg-panel-padding`, and the engine rules sit in a cascade layer, so a game's `className`
+ * restyles it without `!important`. Not the `HudCanvas` layout slot (`HudPanel` in `@jgengine/react/hudLayout`).
+ *
+ * @capability hud-surface themed panel frame with elevation, header slots, landmark element, and open/close transitions
+ */
+export declare const HudSurface: import("react").ForwardRefExoticComponent<HudSurfaceProps & import("react").RefAttributes<HTMLElement>>;

package/dist/hudSurface.js

@@ -0,0 +1,40 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useEffect, useRef } from "react";
+import { useReducedMotion } from "./accessibility.js";
+import { useEngineStyles } from "./engineStyles.js";
+import { useHudInteract } from "./hudInteract.js";
+import { usePresence } from "./presence.js";
+const EXIT_MS = 140;
+/**
+ * Themed panel/window frame over the `HudTheme` frame, elevation, and motion tokens. It enters with
+ * a short rise-and-fade and stays mounted through its exit when `open` turns false
+ * (`data-state="open" | "closed"`); reduced motion skips both. Padding comes from
+ * `--jg-panel-padding`, and the engine rules sit in a cascade layer, so a game's `className`
+ * restyles it without `!important`. Not the `HudCanvas` layout slot (`HudPanel` in `@jgengine/react/hudLayout`).
+ *
+ * @capability hud-surface themed panel frame with elevation, header slots, landmark element, and open/close transitions
+ */
+export const HudSurface = forwardRef(function HudSurface({ as: Element = "div", open, title, aside, elevation = "raised", padding, width, interactive = true, cue, onInteract, style, children, ...rest }, ref) {
+    useEngineStyles();
+    const reduced = useReducedMotion();
+    const shown = open ?? true;
+    const presence = usePresence(shown, reduced ? 0 : EXIT_MS);
+    const report = useHudInteract("panel", cue, onInteract);
+    const wasOpen = useRef(shown);
+    useEffect(() => {
+        if (wasOpen.current === shown)
+            return;
+        wasOpen.current = shown;
+        report(shown ? "open" : "close");
+    }, [shown, report]);
+    if (presence === "unmounted")
+        return null;
+    const hasHeader = title !== undefined || aside !== undefined;
+    const frameStyle = {
+        width,
+        pointerEvents: interactive ? "auto" : undefined,
+        ...(padding === undefined ? {} : { "--jg-panel-padding": typeof padding === "number" ? `${padding}px` : padding }),
+        ...style,
+    };
+    return (_jsxs(Element, { ...rest, ref: ref, "data-jg-panel": "", "data-state": open === undefined ? undefined : presence, "data-elevation": elevation, "data-jg-cue": cue, style: frameStyle, children: [hasHeader ? (_jsxs("div", { "data-jg-panel-header": "", style: { marginBottom: 8 }, children: [_jsx("span", { children: title }), aside !== undefined ? _jsx("span", { children: aside }) : null] })) : null, children] }));
+});

package/dist/modals.d.ts

@@ -88,7 +88,7 @@ export interface ConfirmDialogProps {
 }
 /**
  * A generic two-button confirmation dialog — title, optional body, and Cancel / Confirm buttons over
- * a `HudTheme`-token-driven {@link HudPanel}. Presentation-only: wire `onConfirm`/`onCancel` to a
+ * a `HudTheme`-token-driven {@link HudSurface}. Presentation-only: wire `onConfirm`/`onCancel` to a
  * modal stack's `resolve` (typically inside a {@link ModalHost} render callback) and reskin via
  * `HudTheme` tokens or `danger` for a destructive action. It interprets nothing — the game supplies
  * the copy.
@@ -124,7 +124,7 @@ export interface PauseMenuProps {
 }
 /**
  * A reskinnable pause-menu building block: a primary Resume button plus a game-filled list of slot
- * items (Settings, Save, Quit, …), stacked in a `HudTheme`-token-driven {@link HudPanel}. It ships
+ * items (Settings, Save, Quit, …), stacked in a `HudTheme`-token-driven {@link HudSurface}. It ships
  * the common shape every game's pause screen needs and nothing genre-specific — the game supplies the
  * title, item labels/order, and destructive styling, and reskins with `HudTheme` tokens. Drop it into
  * a {@link ModalHost} keyed on a `"pause"` modal, or render it standalone.

package/dist/modals.js

@@ -6,7 +6,7 @@ import { useDialogBehavior } from "./dialogBehavior.js";
 import { useEngineStyles } from "./engineStyles.js";
 import { HudButton } from "./hudButton.js";
 import { useHudInteract } from "./hudInteract.js";
-import { HudPanel } from "./hudPanel.js";
+import { HudSurface } from "./hudSurface.js";
 import { hudType } from "./hudTokens.js";
 import { usePresence } from "./presence.js";
 /**
@@ -79,7 +79,7 @@ const DIALOG_BODY = { margin: "10px 0 0", fontSize: hudType("md"), lineHeight: 1
 const BUTTON_ROW = { display: "flex", gap: 10, marginTop: 20, justifyContent: "flex-end" };
 /**
  * A generic two-button confirmation dialog — title, optional body, and Cancel / Confirm buttons over
- * a `HudTheme`-token-driven {@link HudPanel}. Presentation-only: wire `onConfirm`/`onCancel` to a
+ * a `HudTheme`-token-driven {@link HudSurface}. Presentation-only: wire `onConfirm`/`onCancel` to a
  * modal stack's `resolve` (typically inside a {@link ModalHost} render callback) and reskin via
  * `HudTheme` tokens or `danger` for a destructive action. It interprets nothing — the game supplies
  * the copy.
@@ -87,7 +87,7 @@ const BUTTON_ROW = { display: "flex", gap: 10, marginTop: 20, justifyContent: "f
  * @capability confirm-dialog generic themeable confirm/cancel dialog — title, body, two buttons, danger styling
  */
 export function ConfirmDialog({ title, body, confirmLabel = "Confirm", cancelLabel = "Cancel", onConfirm, onCancel, danger = false, width = 360, className, style, }) {
-    return (_jsxs(HudPanel, { elevation: "modal", width: width, padding: 20, className: className, style: style, children: [_jsx("h2", { "data-confirm-title": "", style: DIALOG_TITLE, children: title }), body !== undefined ? _jsx("p", { "data-confirm-body": "", style: DIALOG_BODY, children: body }) : null, _jsxs("div", { style: BUTTON_ROW, children: [_jsx(HudButton, { "data-confirm-cancel": "", cue: "cancel", onClick: onCancel, children: cancelLabel }), _jsx(HudButton, { "data-confirm-accept": "", cue: "confirm", variant: danger ? "danger" : "primary", onClick: onConfirm, children: confirmLabel })] })] }));
+    return (_jsxs(HudSurface, { elevation: "modal", width: width, padding: 20, className: className, style: style, children: [_jsx("h2", { "data-confirm-title": "", style: DIALOG_TITLE, children: title }), body !== undefined ? _jsx("p", { "data-confirm-body": "", style: DIALOG_BODY, children: body }) : null, _jsxs("div", { style: BUTTON_ROW, children: [_jsx(HudButton, { "data-confirm-cancel": "", cue: "cancel", onClick: onCancel, children: cancelLabel }), _jsx(HudButton, { "data-confirm-accept": "", cue: "confirm", variant: danger ? "danger" : "primary", onClick: onConfirm, children: confirmLabel })] })] }));
 }
 const PAUSE_TITLE = {
     margin: "0 0 14px",
@@ -102,7 +102,7 @@ const PAUSE_ITEM = { marginTop: 8 };
 const PAUSE_DANGER_ITEM = { ...PAUSE_ITEM, color: "var(--jg-danger, #e5484d)", borderColor: "rgba(229,72,77,0.45)" };
 /**
  * A reskinnable pause-menu building block: a primary Resume button plus a game-filled list of slot
- * items (Settings, Save, Quit, …), stacked in a `HudTheme`-token-driven {@link HudPanel}. It ships
+ * items (Settings, Save, Quit, …), stacked in a `HudTheme`-token-driven {@link HudSurface}. It ships
  * the common shape every game's pause screen needs and nothing genre-specific — the game supplies the
  * title, item labels/order, and destructive styling, and reskins with `HudTheme` tokens. Drop it into
  * a {@link ModalHost} keyed on a `"pause"` modal, or render it standalone.
@@ -110,5 +110,5 @@ const PAUSE_DANGER_ITEM = { ...PAUSE_ITEM, color: "var(--jg-danger, #e5484d)", b
  * @capability pause-menu reskinnable pause-menu building block — Resume plus a game-filled Settings/Quit slot list, HudTheme-driven
  */
 export function PauseMenu({ title = "Paused", onResume, resumeLabel = "Resume", items = [], width = 300, className, style, }) {
-    return (_jsxs(HudPanel, { elevation: "modal", width: width, padding: 20, className: className, style: style, children: [_jsx("div", { "data-pause-title": "", style: PAUSE_TITLE, children: title }), _jsx(HudButton, { "data-pause-resume": "", cue: "resume", variant: "primary", size: "lg", block: true, onClick: onResume, children: resumeLabel }), items.map((item) => (_jsx(HudButton, { "data-pause-item": item.id, cue: `pause:${item.id}`, size: "lg", block: true, onClick: item.onSelect, disabled: item.disabled, style: item.danger ? PAUSE_DANGER_ITEM : PAUSE_ITEM, children: item.label }, item.id)))] }));
+    return (_jsxs(HudSurface, { elevation: "modal", width: width, padding: 20, className: className, style: style, children: [_jsx("div", { "data-pause-title": "", style: PAUSE_TITLE, children: title }), _jsx(HudButton, { "data-pause-resume": "", cue: "resume", variant: "primary", size: "lg", block: true, onClick: onResume, children: resumeLabel }), items.map((item) => (_jsx(HudButton, { "data-pause-item": item.id, cue: `pause:${item.id}`, size: "lg", block: true, onClick: item.onSelect, disabled: item.disabled, style: item.danger ? PAUSE_DANGER_ITEM : PAUSE_ITEM, children: item.label }, item.id)))] }));
 }

package/dist/notices.d.ts

@@ -1,8 +1,15 @@
 import { type ReactNode } from "react";
 import type { Notice, NoticeFeed } from "@jgengine/core/game/notices";
+import type { LayoutRect, LayoutRegion } from "@jgengine/core/ui/gameLayout";
 export type { Notice, NoticeTone } from "@jgengine/core/game/notices";
 /** Where {@link NoticeStack} sits: below top-edge HUD bars, over the play area, or above bottom action bars. */
 export type NoticePlacement = "top" | "center" | "bottom";
+/**
+ * How far a top or bottom notice stack must move toward the screen middle to clear the registered
+ * layout regions in its column. `stack` is its current rect, already moved by `shift`; regions
+ * reaching past the container's middle (full-height sidebars, screens) are ignored. @internal
+ */
+export declare function noticeAvoidShift(placement: NoticePlacement, stack: LayoutRect, shift: number, container: LayoutRect, regions: readonly Pick<LayoutRegion, "kind" | "rect">[], gap?: number): number;
 type Shown = {
     notice: Notice;
     leaving: boolean;
@@ -13,14 +20,22 @@ export declare function reconcileShown(previous: readonly Shown[], live: readonl
 export declare function useNoticeList(feed: NoticeFeed | null): readonly Notice[];
 /**
  * Animated, toned notice stack for a {@link NoticeFeed} — the default renderer the shell mounts for
- * `ctx.game.notices`. Uses `--jg-*` theme vars with fallbacks, 14px text, and never takes pointer input.
+ * `ctx.game.notices` inside the HUD theme root. Uses `--jg-*` theme vars with fallbacks, 14px text, and
+ * never takes pointer input. A top or bottom stack keeps clear of HUD panels registered in its column
+ * and sits above modal overlays.
  *
- * @capability notice-feed render ctx.game.notices as an animated toned stack (enter/exit motion, ×N stacking)
+ * @capability notice-feed render ctx.game.notices as an animated toned stack (enter/exit motion, ×N stacking, HUD avoidance)
  */
-export declare function NoticeStack({ feed, placement, scale, renderNotice, }: {
+export declare function NoticeStack({ feed, placement, offset, avoidHud, zIndex, scale, renderNotice, }: {
     /** Defaults to the surrounding game's `ctx.game.notices`. */
     feed?: NoticeFeed;
     placement?: NoticePlacement;
+    /** Distance from the band's screen edge (px or CSS length), added to the safe-area inset. */
+    offset?: number | string;
+    /** Move a top/bottom stack clear of registered HUD panels and touch controls in its column. Default true. */
+    avoidHud?: boolean;
+    /** Default 85: above `ModalHost` (80) and `PanelHost` (40). */
+    zIndex?: number;
     /** Multiplies text and spacing (the shell passes the player's UI scale). */
     scale?: number;
     renderNotice?: (notice: Notice) => ReactNode;

package/dist/notices.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useState, useSyncExternalStore } from "react";
+import { useEffect, useLayoutEffect, useRef, useState, useSyncExternalStore } from "react";
+import { useGameViewportLayout } from "./gameViewport.js";
 import { useOptionalGameContext } from "./provider.js";
 const EXIT_MS = 200;
 const EMPTY = [];
@@ -11,11 +12,48 @@ const TONE_COLOR = {
     deny: "var(--jg-danger, #f26d6d)",
 };
 const TONE_LABEL = { info: "Info", success: "Done", warn: "Warning", deny: "Can't do that" };
-const PLACEMENT_STYLE = {
-    top: { top: "clamp(64px, 14%, 150px)" },
-    center: { top: "34%" },
-    bottom: { bottom: "clamp(120px, 22%, 230px)", flexDirection: "column-reverse" },
+const DEFAULT_OFFSET = {
+    top: "clamp(64px, 14%, 150px)",
+    center: "34%",
+    bottom: "clamp(120px, 22%, 230px)",
 };
+const AVOID_GAP = 8;
+function placementStyle(placement, offset) {
+    const edge = offset === undefined ? DEFAULT_OFFSET[placement] : typeof offset === "number" ? `${offset}px` : offset;
+    if (placement === "bottom")
+        return { bottom: `calc(var(--jg-safe-bottom, 0px) + ${edge})`, flexDirection: "column-reverse" };
+    if (placement === "center")
+        return { top: edge };
+    return { top: `calc(var(--jg-safe-top, 0px) + ${edge})` };
+}
+/**
+ * How far a top or bottom notice stack must move toward the screen middle to clear the registered
+ * layout regions in its column. `stack` is its current rect, already moved by `shift`; regions
+ * reaching past the container's middle (full-height sidebars, screens) are ignored. @internal
+ */
+export function noticeAvoidShift(placement, stack, shift, container, regions, gap = AVOID_GAP) {
+    if (placement === "center")
+        return 0;
+    const middle = (container.top + container.bottom) / 2;
+    let need = 0;
+    for (const { kind, rect } of regions) {
+        if (kind === "screen" || rect.right <= rect.left || rect.bottom <= rect.top)
+            continue;
+        if (rect.right <= stack.left || rect.left >= stack.right)
+            continue;
+        if (placement === "top") {
+            if (rect.bottom > middle)
+                continue;
+            need = Math.max(need, rect.bottom + gap - (stack.top - shift));
+        }
+        else {
+            if (rect.top < middle)
+                continue;
+            need = Math.max(need, stack.bottom + shift - (rect.top - gap));
+        }
+    }
+    return Math.max(0, Math.round(need));
+}
 const KEYFRAMES = `
 @keyframes jg-notice-in { from { opacity: 0; transform: translateY(-8px) scale(0.97); } to { opacity: 1; transform: none; } }
 @keyframes jg-notice-out { from { opacity: 1; transform: none; } to { opacity: 0; transform: translateY(-6px) scale(0.98); } }
@@ -79,11 +117,13 @@ export function useNoticeList(feed) {
 }
 /**
  * Animated, toned notice stack for a {@link NoticeFeed} — the default renderer the shell mounts for
- * `ctx.game.notices`. Uses `--jg-*` theme vars with fallbacks, 14px text, and never takes pointer input.
+ * `ctx.game.notices` inside the HUD theme root. Uses `--jg-*` theme vars with fallbacks, 14px text, and
+ * never takes pointer input. A top or bottom stack keeps clear of HUD panels registered in its column
+ * and sits above modal overlays.
  *
- * @capability notice-feed render ctx.game.notices as an animated toned stack (enter/exit motion, ×N stacking)
+ * @capability notice-feed render ctx.game.notices as an animated toned stack (enter/exit motion, ×N stacking, HUD avoidance)
  */
-export function NoticeStack({ feed, placement = "top", scale = 1, renderNotice, }) {
+export function NoticeStack({ feed, placement = "top", offset, avoidHud = true, zIndex = 85, scale = 1, renderNotice, }) {
     const ctx = useOptionalGameContext();
     const source = feed ?? ctx?.game.notices ?? null;
     const live = useNoticeList(source);
@@ -93,6 +133,19 @@ export function NoticeStack({ feed, placement = "top", scale = 1, renderNotice,
         setSeenLive(live);
         setShown(reconcileShown(shown, live));
     }
+    const { regions } = useGameViewportLayout();
+    const stackRef = useRef(null);
+    const [shift, setShift] = useState(0);
+    const visible = shown.length > 0;
+    useLayoutEffect(() => {
+        const element = stackRef.current;
+        const container = element?.offsetParent;
+        const next = element == null || container == null || !avoidHud
+            ? 0
+            : noticeAvoidShift(placement, element.getBoundingClientRect(), shift, container.getBoundingClientRect(), regions);
+        if (next !== shift)
+            setShift(next);
+    }, [regions, visible, placement, avoidHud, shift]);
     const anyLeaving = shown.some((entry) => entry.leaving);
     useEffect(() => {
         if (!anyLeaving)
@@ -102,18 +155,19 @@ export function NoticeStack({ feed, placement = "top", scale = 1, renderNotice,
     }, [anyLeaving]);
     if (shown.length === 0)
         return null;
-    return (_jsxs("div", { "data-jg-notices": placement, role: "status", "aria-live": "polite", style: {
+    return (_jsxs("div", { ref: stackRef, "data-jg-notices": placement, role: "status", "aria-live": "polite", style: {
             position: "absolute",
             left: "50%",
             transform: "translateX(-50%)",
-            zIndex: 45,
+            zIndex,
             display: "flex",
             flexDirection: "column",
             alignItems: "center",
             gap: 6 * scale,
             width: "min(460px, calc(100% - 32px))",
             pointerEvents: "none",
-            ...PLACEMENT_STYLE[placement],
+            ...placementStyle(placement, offset),
+            ...(shift === 0 ? {} : placement === "bottom" ? { marginBottom: shift } : { marginTop: shift }),
         }, children: [_jsx("style", { children: KEYFRAMES }), shown.map(({ notice, leaving }) => (_jsx("div", { "data-jg-notice": notice.tone, "data-leaving": leaving ? "" : undefined, style: { maxWidth: "100%" }, children: renderNotice !== undefined ? renderNotice(notice) : (_jsxs("div", { "data-jg-notice-body": true, "data-bump": notice.count > 1 ? (notice.tone === "deny" ? "deny" : "other") : undefined, style: {
                         display: "flex",
                         alignItems: "center",

package/dist/panels.js

@@ -5,7 +5,7 @@ import { useReducedMotion } from "./accessibility.js";
 import { HudButton } from "./hudButton.js";
 import { HudFrame } from "./hudFrame.js";
 import { useHudInteract } from "./hudInteract.js";
-import { HudPanel } from "./hudPanel.js";
+import { HudSurface } from "./hudSurface.js";
 import { hudType } from "./hudTokens.js";
 import { observeBrowserSuspension } from "./browserLifecycle.js";
 import { usePresence } from "./presence.js";
@@ -214,7 +214,7 @@ function WindowView({ title, ariaLabel, open = true, closable, onClose, onFocus,
                         retireDrag.current = beginWindowDrag(event, pos, onMove, () => { retireDrag.current = null; });
                     }
                 }, style: TITLEBAR_STYLE, children: [_jsx("span", { "data-jg-window-title": "", children: title }), closable ? (_jsx(HudButton, { variant: "ghost", size: "icon", "data-jg-window-close": "", "aria-label": "Close", cue: "window-close", onClick: onClose, onPointerDown: (event) => event.stopPropagation(), style: CLOSE_BUTTON_STYLE, children: "\u2715" })) : null] }), _jsx("div", { "data-jg-window-body": "", style: { padding: 12, ...bodyStyle }, children: children })] }));
-    return (_jsx("div", { role: "dialog", "aria-label": ariaLabel, "data-jg-window": "", "data-state": presence, "data-jg-cue": cue, className: className, onPointerDown: () => onFocus?.(), style: { position: "absolute", left: pos.x, top: pos.y, zIndex: z, pointerEvents: "auto", ...style }, children: variation === undefined ? (_jsx(HudPanel, { elevation: "modal", padding: 0, width: width, style: shape === "square" ? { borderRadius: 0 } : undefined, children: frameBody })) : (_jsx(HudFrame, { variation: variation, shape: shape, width: width, padding: 0, interactive: true, children: frameBody })) }));
+    return (_jsx("div", { role: "dialog", "aria-label": ariaLabel, "data-jg-window": "", "data-state": presence, "data-jg-cue": cue, className: className, onPointerDown: () => onFocus?.(), style: { position: "absolute", left: pos.x, top: pos.y, zIndex: z, pointerEvents: "auto", ...style }, children: variation === undefined ? (_jsx(HudSurface, { elevation: "modal", padding: 0, width: width, style: shape === "square" ? { borderRadius: 0 } : undefined, children: frameBody })) : (_jsx(HudFrame, { variation: variation, shape: shape, width: width, padding: 0, interactive: true, children: frameBody })) }));
 }
 /** @internal Keeps just-closed panels rendered (closing) for `exitMs` so their exit transition plays. */
 function useLeavingPanels(open, exitMs) {

package/dist/styles.css

@@ -1,4 +1,6 @@
 /* @jgengine/react engine stylesheet */
+@layer theme, base, components, utilities;
+@layer components.jgengine {
 :root { --jg-motion-scale: 1; }
 @media (prefers-reduced-motion: reduce) { :root { --jg-motion-scale: 0; } }
 [data-reduced-motion="true"] { --jg-motion-scale: 0; }
@@ -32,7 +34,7 @@
 }
 :where([data-jg-hud]) :where(button, [role="button"]):where(:not(:disabled, [aria-disabled="true"])):active { scale: var(--jg-press-scale, 0.97); }
 
-[data-jg-button] { appearance: none; box-sizing: border-box; position: relative; isolation: isolate; display: inline-flex; align-items: center; justify-content: center; gap: var(--jg-space-sm, 8px); min-height: 36px; padding: 0 var(--jg-space-lg, 16px); margin: 0; font-family: var(--jg-font-body, "Inter Variable", Inter, "SF Pro Text", -apple-system, BlinkMacSystemFont, "Segoe UI Variable Text", "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif); font-size: var(--jg-type-md, 14px); font-weight: 600; line-height: 1; letter-spacing: 0.01em; white-space: nowrap; color: var(--jg-text, #f5f7fa); background: linear-gradient(180deg, rgba(255,255,255,0.10), rgba(255,255,255,0.03)), var(--jg-slot-bg, rgba(12,15,21,0.78)); border: var(--jg-slot-border, 1px solid rgba(255,255,255,0.13)); border-radius: var(--jg-slot-radius, 8px); box-shadow: var(--jg-highlight, inset 0 1px 0 rgba(255,255,255,0.08)), var(--jg-elevation-raised, 0 1px 2px rgba(0,0,0,0.45), 0 4px 12px -2px rgba(0,0,0,0.4)); cursor: pointer; user-select: none; -webkit-tap-highlight-color: transparent; transition: translate calc(var(--jg-motion-fast, 120ms) * var(--jg-motion-scale, 1)) var(--jg-ease, cubic-bezier(0.2, 0, 0, 1)), scale calc(var(--jg-motion-fast, 120ms) * var(--jg-motion-scale, 1)) var(--jg-ease-spring, cubic-bezier(0.34, 1.56, 0.64, 1)), box-shadow calc(var(--jg-motion-fast, 120ms) * var(--jg-motion-scale, 1)) var(--jg-ease, cubic-bezier(0.2, 0, 0, 1)), border-color calc(var(--jg-motion-fast, 120ms) * var(--jg-motion-scale, 1)) var(--jg-ease, cubic-bezier(0.2, 0, 0, 1)), background-color calc(var(--jg-motion-fast, 120ms) * var(--jg-motion-scale, 1)) var(--jg-ease, cubic-bezier(0.2, 0, 0, 1)); }
+[data-jg-button] { appearance: none; box-sizing: border-box; position: relative; isolation: isolate; display: inline-flex; align-items: center; justify-content: center; gap: var(--jg-space-sm, 8px); min-height: 36px; padding: var(--jg-space-xs, 4px) var(--jg-space-lg, 16px); margin: 0; font-family: var(--jg-font-body, "Inter Variable", Inter, "SF Pro Text", -apple-system, BlinkMacSystemFont, "Segoe UI Variable Text", "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif); font-size: var(--jg-type-md, 14px); font-weight: 600; line-height: 1.2; letter-spacing: 0.01em; text-align: center; white-space: normal; color: var(--jg-text, #f5f7fa); background: linear-gradient(180deg, rgba(255,255,255,0.10), rgba(255,255,255,0.03)), var(--jg-slot-bg, rgba(12,15,21,0.78)); border: var(--jg-slot-border, 1px solid rgba(255,255,255,0.13)); border-radius: var(--jg-slot-radius, 8px); box-shadow: var(--jg-highlight, inset 0 1px 0 rgba(255,255,255,0.08)), var(--jg-elevation-raised, 0 1px 2px rgba(0,0,0,0.45), 0 4px 12px -2px rgba(0,0,0,0.4)); cursor: pointer; user-select: none; -webkit-tap-highlight-color: transparent; transition: translate calc(var(--jg-motion-fast, 120ms) * var(--jg-motion-scale, 1)) var(--jg-ease, cubic-bezier(0.2, 0, 0, 1)), scale calc(var(--jg-motion-fast, 120ms) * var(--jg-motion-scale, 1)) var(--jg-ease-spring, cubic-bezier(0.34, 1.56, 0.64, 1)), box-shadow calc(var(--jg-motion-fast, 120ms) * var(--jg-motion-scale, 1)) var(--jg-ease, cubic-bezier(0.2, 0, 0, 1)), border-color calc(var(--jg-motion-fast, 120ms) * var(--jg-motion-scale, 1)) var(--jg-ease, cubic-bezier(0.2, 0, 0, 1)), background-color calc(var(--jg-motion-fast, 120ms) * var(--jg-motion-scale, 1)) var(--jg-ease, cubic-bezier(0.2, 0, 0, 1)); }
 [data-jg-button]::after { content: ""; position: absolute; inset: 0; z-index: -1; border-radius: inherit; background: var(--jg-hover-overlay, rgba(255,255,255,0.07)); opacity: 0; pointer-events: none; transition: opacity calc(var(--jg-motion-fast, 120ms) * var(--jg-motion-scale, 1)) var(--jg-ease, cubic-bezier(0.2, 0, 0, 1)); }
 @media (hover: hover) {
   [data-jg-button]:not(:disabled, [aria-disabled="true"]):hover { translate: 0 var(--jg-hover-lift, -1px); box-shadow: var(--jg-highlight, inset 0 1px 0 rgba(255,255,255,0.08)), var(--jg-elevation-overlay, 0 2px 4px rgba(0,0,0,0.4), 0 10px 24px -4px rgba(0,0,0,0.5)); }
@@ -46,12 +48,12 @@
 [data-jg-button][data-variant="danger"] { color: #fff; background: linear-gradient(180deg, rgba(255,255,255,0.16), rgba(255,255,255,0) 60%), var(--jg-danger, #e5484d); border: 1px solid rgba(255,255,255,0.22); }
 [data-jg-button][data-variant="ghost"] { background: transparent; border-color: transparent; box-shadow: none; }
 [data-jg-button][data-variant="ghost"]:not(:disabled, [aria-disabled="true"]):hover { box-shadow: none; }
-[data-jg-button][data-size="sm"] { min-height: 28px; padding: 0 var(--jg-space-md, 12px); font-size: var(--jg-type-sm, 13px); }
-[data-jg-button][data-size="lg"] { min-height: 44px; padding: 0 var(--jg-space-xl, 24px); font-size: var(--jg-type-lg, 16px); }
+[data-jg-button][data-size="sm"] { min-height: 28px; padding-inline: var(--jg-space-md, 12px); font-size: var(--jg-type-sm, 13px); }
+[data-jg-button][data-size="lg"] { min-height: 44px; padding-inline: var(--jg-space-xl, 24px); font-size: var(--jg-type-lg, 16px); }
 [data-jg-button][data-size="icon"] { min-height: 0; width: 28px; height: 28px; padding: 0; font-size: var(--jg-type-sm, 13px); }
 [data-jg-button][data-block] { display: flex; width: 100%; }
 
-[data-jg-panel] { box-sizing: border-box; color: var(--jg-text, #f5f7fa); font-family: var(--jg-font-body, "Inter Variable", Inter, "SF Pro Text", -apple-system, BlinkMacSystemFont, "Segoe UI Variable Text", "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif); background: var(--jg-frame-bg, rgba(12,15,21,0.9)); border: var(--jg-frame-border, 1px solid rgba(255,255,255,0.13)); border-radius: var(--jg-frame-radius, 10px); box-shadow: var(--jg-frame-glow, var(--jg-highlight, inset 0 1px 0 rgba(255,255,255,0.08)), var(--jg-elevation-raised, 0 1px 2px rgba(0,0,0,0.45), 0 4px 12px -2px rgba(0,0,0,0.4))); }
+[data-jg-panel] { box-sizing: border-box; padding: var(--jg-panel-padding, 12px); color: var(--jg-text, #f5f7fa); font-family: var(--jg-font-body, "Inter Variable", Inter, "SF Pro Text", -apple-system, BlinkMacSystemFont, "Segoe UI Variable Text", "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif); background: var(--jg-frame-bg, rgba(12,15,21,0.9)); border: var(--jg-frame-border, 1px solid rgba(255,255,255,0.13)); border-radius: var(--jg-frame-radius, 10px); box-shadow: var(--jg-frame-glow, var(--jg-highlight, inset 0 1px 0 rgba(255,255,255,0.08)), var(--jg-elevation-raised, 0 1px 2px rgba(0,0,0,0.45), 0 4px 12px -2px rgba(0,0,0,0.4))); }
 [data-jg-panel][data-elevation="overlay"] { box-shadow: var(--jg-frame-glow, var(--jg-highlight, inset 0 1px 0 rgba(255,255,255,0.08))), var(--jg-elevation-overlay, 0 2px 4px rgba(0,0,0,0.4), 0 10px 24px -4px rgba(0,0,0,0.5)); }
 [data-jg-panel][data-elevation="modal"] { box-shadow: var(--jg-frame-glow, var(--jg-highlight, inset 0 1px 0 rgba(255,255,255,0.08))), var(--jg-elevation-modal, 0 4px 8px rgba(0,0,0,0.35), 0 24px 56px -12px rgba(0,0,0,0.7)); }
 [data-jg-panel][data-state="open"] { animation: jg-panel-in calc(var(--jg-motion-base, 180ms) * var(--jg-motion-scale, 1)) var(--jg-ease-out, cubic-bezier(0.16, 1, 0.3, 1)) both; }
@@ -70,3 +72,4 @@
 @media (hover: hover) { [data-action-id][data-enabled]:hover { translate: 0 var(--jg-hover-lift, -1px); } }
 [data-action-id][data-enabled]:active { translate: 0 0; scale: var(--jg-press-scale, 0.97); }
 [data-action-id]:focus-visible { outline: none; box-shadow: var(--jg-focus-ring, 0 0 0 2px #0a0c10, 0 0 0 4px var(--jg-accent, #38bdf8)); }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/react",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "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.24.0"
+    "@jgengine/core": "^0.25.0"
   },
   "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.24.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.25.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -232,7 +232,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.24.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.25.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 

package/skills/jgengine-ui/SKILL.md

@@ -32,8 +32,8 @@ Existing React games keep their entity store and use the focused
 - **Settings is game-owned and reachable from a sensible place.** Every game ships settings as *its* settings — skinned and placed inline with its UI (main menu and pause), never the engine's stock face floated into a corner. Credits are a reachable in-game screen, not attribution buried in a build artifact.
 - **Route the front-end with `useMenuRouter`, and generate the credits.** `useMenuRouter(root)` is the screen stack behind title → save select → settings → credits: `open`/`back`/`replace`/`reset`, `path` for depth, and Escape-to-back bound by default (`escapeToBack: false` when the game owns Escape). `menuStackReducer` is the same transition as a pure function. For credits, `creditsForSourceIds(ids)` (`@jgengine/assets/credits`) turns the pack ids a game declares to `buildCatalog` into licensed, attributed sections, `mergeCredits` folds them into hand-authored lines, and `CreditsScreen` renders the result HudTheme-skinned.
 - **Skin the shared chrome with one `HudTheme` token object.** `hudThemeVars(theme)` emits the whole `--jg-*` vocabulary — bar fills and troughs, `HudFrame variation="themed"`, painted slots, the minimap ring, plus surfaces, edges, text, status colors, fonts, and rarity — so one theme spread on any HUD ancestor reskins the `@jgengine/react` primitives and the `registry/jgengine` blocks together. Author your own with `deriveHudTheme({ accent, surface })` or `hudTheme({ ... })`; `HUD_THEME_PRESETS` / `resolveHudTheme("<preset>")` are demo/scaffold starting points, never a game's identity. A component that needs a token no theme emits fails `check-hud-tokens` — add it to `HudTheme` rather than inventing a second vocabulary. Caller `style`/`renderItem` overrides still win.
-- **The shell applies `defaultHudTheme` at the GameUI root.** `HudThemeRoot` wraps every `GameUI` in a `display: contents` `[data-jg-hud]` element carrying the theme vars and injects the engine stylesheet (`jg-*` keyframes, `[data-jg-*]` interaction states, reduced motion). Set `defineGame({ hudTheme })` to swap the root theme, `hudTheme: false` to opt out; a theme spread inside `GameUI` still wins. Games outside the shell add `@import "@jgengine/react/styles.css";` to `src/index.css` (the `jgengine create` template does). The theme also carries a type scale with a 12px floor, spacing, motion, elevation, and hover/press/focus/disabled tokens; read them in inline styles through `hudType`, `hudSpace`, `hudTransition`, `hudElevation`, and `HUD_FOCUS_RING` (`@jgengine/react/hudTokens`) — never hardcode text under 12px.
-- **Build interactive chrome from `HudButton`, `HudPanel`, and `TweenNumber`.** `HudButton` gives hover lift, press scale, focus ring, and disabled from tokens; `HudPanel` gives elevation, header slots, and an `open` enter/exit transition; `TweenNumber` / `useTweenedValue` roll counters with an up/down delta flash. Each takes `cue` (`data-jg-cue`) and `onInteract`; `HudInteractProvider` routes every primitive's hover/press/activate/open/close to one listener; the shell mounts one that plays the matching UI cue, so engine primitives sound with no wiring (`cue="confirm"` picks the activate sound).
+- **The shell applies `defaultHudTheme` at the GameUI root.** `HudThemeRoot` wraps every `GameUI` in a `display: contents` `[data-jg-hud]` element carrying the theme vars and injects the engine stylesheet (`jg-*` keyframes, `[data-jg-*]` interaction states, reduced motion). Set `defineGame({ hudTheme })` to swap the root theme, `hudTheme: false` to opt out; a theme spread inside `GameUI` still wins. Games outside the shell add `@import "@jgengine/react/styles.css";` to `src/index.css` (the `jgengine create` template does). Every engine rule sits in the `components.jgengine` cascade layer, so plain game CSS and Tailwind utilities override engine buttons and panels without `!important`. The theme also carries a type scale with a 12px floor, spacing, motion, elevation, and hover/press/focus/disabled tokens; read them in inline styles through `hudType`, `hudSpace`, `hudTransition`, `hudElevation`, and `HUD_FOCUS_RING` (`@jgengine/react/hudTokens`) — never hardcode text under 12px.
+- **Build interactive chrome from `HudButton`, `HudSurface`, and `TweenNumber`.** `HudButton` gives hover lift, press scale, focus ring, and disabled from tokens, and wraps long labels; `HudSurface` (`@jgengine/react/hudSurface`; `HudPanel` from `@jgengine/react/hudPanel` is its deprecated old name, not the `HudCanvas` slot) gives elevation, header slots, an `as` landmark element, padding from `--jg-panel-padding`, and an `open` enter/exit transition; `TweenNumber` / `useTweenedValue` roll counters with an up/down delta flash. Each takes `cue` (`data-jg-cue`) and `onInteract`; `HudInteractProvider` routes every primitive's hover/press/activate/open/close to one listener; the shell mounts one that plays the matching UI cue, so engine primitives sound with no wiring (`cue="confirm"` picks the activate sound). `audio.hudCues: false` silences those control sounds; notice sounds are separate (`notices.cues`).
 - **Paint slot icons with `IconTreatment`, never render raw `itemId` strings.** It draws a `GameIcon` glyph over a school/element-keyed gradient with gloss, vignette, and optional count/keycap badges, reading the `--jg-slot-*` / `--jg-accent` tokens. `treatedItemIcon(itemId)` / `treatedActionIcon(action)` are ready adapters for hotbars and ability bars.
 - **Player death gets a visible screen and respawn feedback — never a silent teleport.** Build the moment `game-design` requires: an authored death/downed overlay that reads the lethal event, communicates the consequence, and surfaces the way back (respawn/revive/restart). Drive it from `createDownedState` (`@jgengine/core/combat`) rather than a hand-rolled flag, and mount it inside `HudCanvas`.
 - **Browser interruption listeners are shared.** Use `useBrowserSuspension` from `@jgengine/react/browserLifecycle` for blur, hidden-page and pointer-lock loss. Keep the decision to pause, release controls or preserve multiplayer simulation in the callback; use options to disable unwanted triggers.
@@ -43,7 +43,7 @@ Existing React games keep their entity store and use the focused
 
 ## Shared-world interaction rules
 
-- **Refusals and notices are engine feedback, not per-game toasts.** Return `{ reason: "insufficient-gold", message: "Needs 40 more gold" }` from a command's `validate`: the shell shows `message` in the shared notice feed with the deny cue and stacks repeats. Push other player messages with `ctx.game.notices.push({ text, tone })` (info/success/warn/deny) from game logic instead of a hand-built toast list. Tune or hide the stock feed with `notices: { placement, hidden }` (`hidden` keeps cues and lets the game render `useNoticeList(ctx.game.notices)` itself).
+- **Refusals and notices are engine feedback, not per-game toasts.** Return `{ reason: "insufficient-gold", message: "Needs 40 more gold" }` from a command's `validate`: the shell shows `message` in the shared notice feed with the deny cue and stacks repeats. Push other player messages with `ctx.game.notices.push({ text, tone })` (info/success/warn/deny) from game logic instead of a hand-built toast list. The stack renders inside the HUD theme root, so it takes the game's `hudTheme` colours and font; a top or bottom stack moves clear of `HudCanvas` panels and touch controls in its column and sits above `ModalHost` (z 85). Tune or hide it with `notices: { placement, offset, avoidHud, zIndex, cues, hidden }` (`hidden` keeps cues and lets the game render `useNoticeList(ctx.game.notices)` itself); `push({ text, silent: true })` skips one notice's sound.
 - **UI sounds come from `useUiCue()`.** Engine primitives already sound through the shell; for game-owned markup call `cue("click" | "hover" | "open" | "close" | "confirm" | "deny" | "notify")` from buttons and panels; replace a default by declaring `audio.sounds["ui.click"]`, or silence with `audio.uiCues: { hover: false }` / `false`.
 - Every rejected verb displays its reason on the triggering surface. Use `useServerSession(transport, gameId)` for join lifecycle. Join failure blocks play with `JoinGate` and retry; returning `{ ok: false }` without feedback is incomplete.
 - Placement previews display claim cost and affordability inline with `TerritoryOverlay`.

package/skills/jgengine-ui/api.md

@@ -601,7 +601,7 @@
 - `ComboMeterTheme` (interface): interface ComboMeterTheme — Reskin tokens for {@link ComboMeterHud}.
 - `Compass` (function): function Compass({ facingYaw, center, markers, width = 340, fov = (Math.PI * 2) / 3, kindStyles = DEFAULT_MARKER_KINDS, className, }: CompassProps): ReactNode — Horizontal compass strip centered on the player's facing direction, with the eight cardinals and optional marker pips from static views, an external source, or a native `MarkerSet`.
 - `CompassProps` (interface): interface CompassProps { facingYaw: number; center?: WorldXZ; markers?: MarkerCollection; width?: number; fov?: number; kindStyles?: Record<string, MarkerKindStyle>; className?: string } — ⚠ undocumented · used by `Compass`: Horizontal compass strip centered on the player's facing direction, with the eight cardinals and optional marker pips from static views, an …
-- `ConfirmDialog` (function): function ConfirmDialog({ title, body, confirmLabel = "Confirm", cancelLabel = "Cancel", onConfirm, onCancel, danger = false, width = 360, className, style, }: ConfirmDialogProps): ReactNode — A generic two-button confirmation dialog — title, optional body, and Cancel / Confirm buttons over a `HudTheme`-token-driven {@link HudPanel}. Presentation-only: wire `onConfirm`/`onCancel` to a modal stack's `resolve` (typically inside a {@link ModalHost} render callback) and reskin via `HudTheme` tokens or `danger` for a destructive action. It interprets nothing — the game supplies the copy.
+- `ConfirmDialog` (function): function ConfirmDialog({ title, body, confirmLabel = "Confirm", cancelLabel = "Cancel", onConfirm, onCancel, danger = false, width = 360, className, style, }: ConfirmDialogProps): ReactNode — A generic two-button confirmation dialog — title, optional body, and Cancel / Confirm buttons over a `HudTheme`-token-driven {@link HudSurface}. Presentation-only: wire `onConfirm`/`onCancel` to a modal stack's `resolve` (typically inside a {@link ModalHost} render callback) and reskin via `HudTheme` tokens or `danger` for a destructive action. It interprets nothing — the game supplies the copy.
 - `ConfirmDialogProps` (interface): interface ConfirmDialogProps — Props for {@link ConfirmDialog}.
 - `ControlHint` (interface): interface ControlHint — One row of a control legend. Name the game action(s) whose bound key(s) to show (`action`) so the glyphs come straight from the keybind map — never re-typed — or give literal `keys` for controls that live outside the map (`"Mouse"`, `"LMB"`). `label` says what the control does.
 - `ControlsList` (function): function ControlsList({ bindings, controls, hideOnCoarsePointer = true, separator = " / ", className, rowClassName, keysClassName, keyClassName, separatorClassName, labelClassName, renderKey, renderRow, }: { bindings?: ActionCodesMap; controls: readonly ControlHint[]; hideOnCoarsePointer?: boolean; … — Renders a controls legend whose key glyphs come from the game's keybind map, so bindings live in one place and never drift from a hand-typed table. Hides itself on coarse-pointer devices (a touchscreen has no keyboard) via the same `data-jg-kbd-hint` marker as `KeyHint`. Headless: every part carries a `className` slot and `data-*` hook; pass `renderKey`/`renderRow` to fully own the markup.
@@ -772,7 +772,7 @@
 - `PartyFrame` (function): function PartyFrame({ className, rowClassName, dotClassName, emptyState, renderMember, }: { className?: string; rowClassName?: string; dotClassName?: string; emptyState?: ReactNode; renderMember?: (member: PartyMemberEntry) => ReactNode; }): React.JSX.Element — ⚠ undocumented
 - `PartyInviteToast` (function): function PartyInviteToast({ className, acceptClassName, declineClassName, renderInvite, }: { className?: string; acceptClassName?: string; declineClassName?: string; renderInvite?: (invite: PartyInviteEntry) => ReactNode; }): React.JSX.Element | null — ⚠ undocumented
 - `PartyMemberRow` (function): function PartyMemberRow({ member, className, dotClassName, children, }: { member: PartyMemberEntry; className?: string; dotClassName?: string; children?: ReactNode; }): React.JSX.Element — ⚠ undocumented
-- `PauseMenu` (function): function PauseMenu({ title = "Paused", onResume, resumeLabel = "Resume", items = [], width = 300, className, style, }: PauseMenuProps): ReactNode — A reskinnable pause-menu building block: a primary Resume button plus a game-filled list of slot items (Settings, Save, Quit, …), stacked in a `HudTheme`-token-driven {@link HudPanel}. It ships the common shape every game's pause screen needs and nothing genre-specific — the game supplies the title, item labels/order, and destructive styling, and reskins with `HudTheme` tokens. Drop it into a {@link ModalHost} keyed on a `"pause"` modal, or render it standalone.
+- `PauseMenu` (function): function PauseMenu({ title = "Paused", onResume, resumeLabel = "Resume", items = [], width = 300, className, style, }: PauseMenuProps): ReactNode — A reskinnable pause-menu building block: a primary Resume button plus a game-filled list of slot items (Settings, Save, Quit, …), stacked in a `HudTheme`-token-driven {@link HudSurface}. It ships the common shape every game's pause screen needs and nothing genre-specific — the game supplies the title, item labels/order, and destructive styling, and reskins with `HudTheme` tokens. Drop it into a {@link ModalHost} keyed on a `"pause"` modal, or render it standalone.
 - `PauseMenuItem` (interface): interface PauseMenuItem — One selectable row in a {@link PauseMenu}'s slot list (Settings, Save, Quit, …).
 - `PauseMenuProps` (interface): interface PauseMenuProps — Props for {@link PauseMenu}.
 - `PhotoModeControls` (function): function PhotoModeControls({ store, onCapture, className, style }: PhotoModeControlsProps): ReactNode — Photo-mode toolbar — a hide/show-HUD toggle, a capture button, and an exit button, bound to a `createPhotoModeStore`. Presentation-only: the game wires `onCapture` to shell `captureCanvas`/`downloadImage` and reads `hideHud` to drop its gameplay HUD.
@@ -1241,7 +1241,7 @@
 
 ## @jgengine/react/engineStyles
 
-- `ENGINE_STYLESHEET` (const): const ENGINE_STYLESHEET: string — The engine stylesheet: every `jg-*` keyframe the shared blocks and registry components animate with, the `[data-jg-*]` interaction-state rules behind {@link HudButton} / {@link HudPanel}, the quiet hover/press/focus defaults for plain buttons inside the HUD root, and reduced-motion handling (`prefers-reduced-motion` or `[data-reduced-motion="true"]` zero `--jg-motion-scale`). Generic HUD rules sit in `:where()` so any game selector wins. The shell injects it; games that mount outside the shell import `@jgengine/react/styles.css`, which holds the same text.
+- `ENGINE_STYLESHEET` (const): const ENGINE_STYLESHEET: string — The engine stylesheet: every `jg-*` keyframe the shared blocks and registry components animate with, the `[data-jg-*]` interaction-state rules behind {@link HudButton} / {@link HudSurface}, the quiet hover/press/focus defaults for plain buttons inside the HUD root, and reduced-motion handling (`prefers-reduced-motion` or `[data-reduced-motion="true"]` zero `--jg-motion-scale`). Every rule sits in the `components.jgengine` cascade layer, so unlayered game CSS, a game's own `components` rules and Tailwind utilities win without `!important`. It first declares `theme, base, components, utilities` so Tailwind v4's preflight stays below engine controls even when the engine sheet loads first. The shell injects it; games that mount outside the shell import `@jgengine/react/styles.css`, which holds the same text.
 - `ensureEngineStyles` (function): function ensureEngineStyles(doc: Document | undefined = typeof document === "undefined" ? undefined : document): void — Injects {@link ENGINE_STYLESHEET} into `doc` once. Safe to call repeatedly and during SSR (no-op).
 - `useEngineStyles` (function): function useEngineStyles(): void — Ensures the engine stylesheet is in the document before the calling component paints. Engine primitives call it, so they animate and show interaction states even outside the shell.
 
@@ -1407,9 +1407,9 @@
 
 ## @jgengine/react/hudPanel
 
-- `HudPanel` (const): const HudPanel: React.ForwardRefExoticComponent<HudPanelProps & React.RefAttributes<HTMLDivElement>> — Themed panel/window frame over the `HudTheme` frame, elevation, and motion tokens. It enters with a short rise-and-fade and stays mounted through its exit when `open` turns false (`data-state="open" | "closed"`); reduced motion skips both. `className` and `style` restyle it.
-- `HudPanelElevation` (type): type HudPanelElevation = "raised" | "overlay" | "modal" — Shadow height of a {@link HudPanel}.
-- `HudPanelProps` (interface): interface HudPanelProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> — Props for {@link HudPanel}.
+- `HudPanel` (const): const HudPanel: React.ForwardRefExoticComponent<HudSurfaceProps & React.RefAttributes<HTMLElement>> — Old name of the themed frame {@link HudSurface} (`@jgengine/react/hudSurface`), renamed so it no longer shares a name with the `HudCanvas` layout slot `HudPanel`.
+- `HudPanelElevation` (type): type HudPanelElevation = HudSurfaceElevation — Old name of {@link HudSurfaceElevation} (`@jgengine/react/hudSurface`).
+- `HudPanelProps` (type): type HudPanelProps = HudSurfaceProps — Old name of {@link HudSurfaceProps} (`@jgengine/react/hudSurface`).
 
 ## @jgengine/react/hudSkin
 
@@ -1422,6 +1422,13 @@
 
 - `HudSkinPreview` (function): function HudSkinPreview({ className }: { className?: string }): React.JSX.Element — Procedural two-skin fixture for visual regression captures.
 
+## @jgengine/react/hudSurface
+
+- `HudSurface` (const): const HudSurface: React.ForwardRefExoticComponent<HudSurfaceProps & React.RefAttributes<HTMLElement>> — Themed panel/window frame over the `HudTheme` frame, elevation, and motion tokens. It enters with a short rise-and-fade and stays mounted through its exit when `open` turns false (`data-state="open" | "closed"`); reduced motion skips both. Padding comes from `--jg-panel-padding`, and the engine rules sit in a cascade layer, so a game's `className` restyles it without `!important`. Not the `HudCanvas` layout slot (`HudPanel` in `@jgengine/react/hudLayout`).
+- `HudSurfaceElement` (type): type HudSurfaceElement = "div" | "section" | "aside" | "nav" | "header" | "footer" | "article" | "main" | "form" | "dialog" — Block elements a {@link HudSurface} can render as, so it can be a landmark.
+- `HudSurfaceElevation` (type): type HudSurfaceElevation = "raised" | "overlay" | "modal" — Shadow height of a {@link HudSurface}.
+- `HudSurfaceProps` (interface): interface HudSurfaceProps extends Omit<HTMLAttributes<HTMLElement>, "title"> — Props for {@link HudSurface}.
+
 ## @jgengine/react/hudTheme
 
 - `HUD_THEME_PRESETS` (const): const HUD_THEME_PRESETS: { "arcane-stone": HudTheme; "survival-wood": HudTheme; "military-flat": HudTheme; "sleek-hex": HudTheme; "elemental-circle": HudTheme; "sandbox-slot": HudTheme; ember: HudTheme; synthwave: HudTheme; fieldkit: HudTheme; } — Built-in theme presets for demos/scaffold only — not product identity; games author their own theme.
@@ -1600,13 +1607,13 @@
 
 ## @jgengine/react/modals
 
-- `ConfirmDialog` (function): function ConfirmDialog({ title, body, confirmLabel = "Confirm", cancelLabel = "Cancel", onConfirm, onCancel, danger = false, width = 360, className, style, }: ConfirmDialogProps): ReactNode — A generic two-button confirmation dialog — title, optional body, and Cancel / Confirm buttons over a `HudTheme`-token-driven {@link HudPanel}. Presentation-only: wire `onConfirm`/`onCancel` to a modal stack's `resolve` (typically inside a {@link ModalHost} render callback) and reskin via `HudTheme` tokens or `danger` for a destructive action. It interprets nothing — the game supplies the copy.
+- `ConfirmDialog` (function): function ConfirmDialog({ title, body, confirmLabel = "Confirm", cancelLabel = "Cancel", onConfirm, onCancel, danger = false, width = 360, className, style, }: ConfirmDialogProps): ReactNode — A generic two-button confirmation dialog — title, optional body, and Cancel / Confirm buttons over a `HudTheme`-token-driven {@link HudSurface}. Presentation-only: wire `onConfirm`/`onCancel` to a modal stack's `resolve` (typically inside a {@link ModalHost} render callback) and reskin via `HudTheme` tokens or `danger` for a destructive action. It interprets nothing — the game supplies the copy.
 - `ConfirmDialogProps` (interface): interface ConfirmDialogProps — Props for {@link ConfirmDialog}.
 - `ModalControls` (interface): interface ModalControls — Stack-bound controls handed to a {@link ModalHost} render callback.
 - `ModalHost` (function): function ModalHost({ stack, children, showBackdrop = true, backdrop, closeOnBackdrop = true, closeOnEsc = true, zIndexBase = 80, onInteract, className, style, }: ModalHostProps): ReactNode — Full-screen modal host: watches a stack, renders only the topmost modal centered over a dimmed backdrop, and manages accessibility — the panel is a `role="dialog" aria-modal`, focus moves into it on open and is trapped with Tab/Shift+Tab cycling, Escape and (optionally) a backdrop click cancel the top modal, and focus returns to the previously focused element on close. It renders nothing when the stack is empty. Skin the panel and backdrop via `HudTheme` tokens.
 - `ModalHostProps` (interface): interface ModalHostProps — Props for {@link ModalHost}.
 - `ModalStackView` (interface): interface ModalStackView — React chrome over the headless modal stack (`@jgengine/core/ui/modalStack`) — the blocking-overlay layer a game raises over its scene: a pause menu, a "quit to menu?" confirm, a reward popup. {@link useModalStack} is the DATA/HOOK layer (subscribe + the active record), {@link ModalHost} renders the top modal with a backdrop, focus trap, and Esc-to-cancel, and {@link ConfirmDialog} / {@link PauseMenu} are ready-to-wire, HudTheme-token-driven building blocks. All unskinned and game-owned: the model never interprets a modal's `kind`, so a game switches on it to pick which of these (or its own) content to show, and reskins everything via `HudTheme` tokens and the frame.
-- `PauseMenu` (function): function PauseMenu({ title = "Paused", onResume, resumeLabel = "Resume", items = [], width = 300, className, style, }: PauseMenuProps): ReactNode — A reskinnable pause-menu building block: a primary Resume button plus a game-filled list of slot items (Settings, Save, Quit, …), stacked in a `HudTheme`-token-driven {@link HudPanel}. It ships the common shape every game's pause screen needs and nothing genre-specific — the game supplies the title, item labels/order, and destructive styling, and reskins with `HudTheme` tokens. Drop it into a {@link ModalHost} keyed on a `"pause"` modal, or render it standalone.
+- `PauseMenu` (function): function PauseMenu({ title = "Paused", onResume, resumeLabel = "Resume", items = [], width = 300, className, style, }: PauseMenuProps): ReactNode — A reskinnable pause-menu building block: a primary Resume button plus a game-filled list of slot items (Settings, Save, Quit, …), stacked in a `HudTheme`-token-driven {@link HudSurface}. It ships the common shape every game's pause screen needs and nothing genre-specific — the game supplies the title, item labels/order, and destructive styling, and reskins with `HudTheme` tokens. Drop it into a {@link ModalHost} keyed on a `"pause"` modal, or render it standalone.
 - `PauseMenuItem` (interface): interface PauseMenuItem — One selectable row in a {@link PauseMenu}'s slot list (Settings, Save, Quit, …).
 - `PauseMenuProps` (interface): interface PauseMenuProps — Props for {@link PauseMenu}.
 - `useModalStack` (function): function useModalStack(stack: ModalStack): ModalStackView — Subscribe to a modal stack and re-render on every change, returning the active modal and depth.
@@ -1615,7 +1622,7 @@
 
 - `Notice` (interface): interface Notice — A live notice as the HUD renders it.
 - `NoticePlacement` (type): type NoticePlacement = "top" | "center" | "bottom" — Where {@link NoticeStack} sits: below top-edge HUD bars, over the play area, or above bottom action bars.
-- `NoticeStack` (function): function NoticeStack({ feed, placement = "top", scale = 1, renderNotice, }: { /** Defaults to the surrounding game's `ctx.game.notices`. */ feed?: NoticeFeed; placement?: NoticePlacement; /** Multiplies text and spacing (the shell passes the player's UI scale). */ scale?: number; renderNotice?: (not… — Animated, toned notice stack for a {@link NoticeFeed} — the default renderer the shell mounts for `ctx.game.notices`. Uses `--jg-*` theme vars with fallbacks, 14px text, and never takes pointer input.
+- `NoticeStack` (function): function NoticeStack({ feed, placement = "top", offset, avoidHud = true, zIndex = 85, scale = 1, renderNotice, }: { /** Defaults to the surrounding game's `ctx.game.notices`. */ feed?: NoticeFeed; placement?: NoticePlacement; /** Distance from the band's screen edge (px or CSS length), added to the … — Animated, toned notice stack for a {@link NoticeFeed} — the default renderer the shell mounts for `ctx.game.notices` inside the HUD theme root. Uses `--jg-*` theme vars with fallbacks, 14px text, and never takes pointer input. A top or bottom stack keeps clear of HUD panels registered in its column and sits above modal overlays.
 - `NoticeTone` (type): type NoticeTone = "info" | "success" | "warn" | "deny" — How a notice reads: neutral info, a win, a caution, or a refused action.
 - `useNoticeList` (function): function useNoticeList(feed: NoticeFeed | null): readonly Notice[] — Live notices of `feed`, re-rendering on change and pruning each one when it expires.
 

package/skills/jgengine-ui/capabilities.md

@@ -336,6 +336,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `StatBar` (function) · `import { StatBar } from "@jgengine/react"`
 
+## hud-surface — themed panel frame with elevation, header slots, landmark element, and open/close transitions
+
+- `HudSurface` (const) · `import { HudSurface } from "@jgengine/react/hudSurface"`
+
 ## hud-theme — game-authored token object covering bars, frames, slots, chrome, text, status colors, fonts, and rarity
 
 - `HudThemePalette` (interface) · `import { HudThemePalette } from "@jgengine/react"`
@@ -502,7 +506,7 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `WorldNameplates` (function) · `import { WorldNameplates } from "@jgengine/shell/world/WorldHud"`
 
-## notice-feed — render ctx.game.notices as an animated toned stack (enter/exit motion, ×N stacking)
+## notice-feed — render ctx.game.notices as an animated toned stack (enter/exit motion, ×N stacking, HUD avoidance)
 
 - `NoticeStack` (function) · `import { NoticeStack } from "@jgengine/react/notices"`
 

package/skills/jgengine-ui/reference-primitives.md

@@ -70,7 +70,7 @@ instead of mirroring external entities into `createMarkerSet`.
 
 **Toggleable game windows** are already shipped, not hand-rolled open/close state: `usePanels(defs)` + `<PanelHost>` + `<Window>` (`@jgengine/react`) over the headless `@jgengine/core/ui/panelModel` are THE way to build openable windows — bag (`B`), character (`C`), spellbook, quest log — with keybind toggles, drag-to-move, close buttons, ESC-to-close, and z-stack ordering all handled. Declare each window in `defs` (id, keybind, title), mount one `<PanelHost>`, and render each panel's body inside a `<Window>`; the game owns the body content and skin, the model owns focus/stacking/keybind wiring. Never re-derive window toggling from local `useState` booleans and hand-rolled keydown listeners.
 
-Window title-bar movement belongs to one primary pointer. Release, cancellation, capture loss, blur, and window unmount retire that gesture's listeners; another pointer cannot move it. Controlled positions and panel z-order remain caller-owned. Windows without a `variation` render on `HudPanel` (theme frame plus modal elevation) and rise in on open; `PanelHost` keeps a closed window mounted for its short exit transition, and closing retires any drag in progress. `ModalHost` fades its backdrop and lifts the dialog in, and plays the same exit when the stack empties; `ConfirmDialog` and `PauseMenu` are built from `HudPanel` and `HudButton`.
+Window title-bar movement belongs to one primary pointer. Release, cancellation, capture loss, blur, and window unmount retire that gesture's listeners; another pointer cannot move it. Controlled positions and panel z-order remain caller-owned. Windows without a `variation` render on `HudSurface` (theme frame plus modal elevation) and rise in on open; `PanelHost` keeps a closed window mounted for its short exit transition, and closing retires any drag in progress. `ModalHost` fades its backdrop and lifts the dialog in, and plays the same exit when the stack empties; `ConfirmDialog` and `PauseMenu` are built from `HudSurface` and `HudButton`.
 
 **Character sheet / paperdoll** is already shipped, not hand-rolled: `<CharacterSheet>` / `<Paperdoll>` / `<StatList>` (`@jgengine/react`) compose the paperdoll equip layout (worn `EquipmentSlots` arranged around a portrait) and the derived-stat readout into one window body. `Paperdoll` is the equip-slot arrangement, `StatList` the derived-stat rows, `CharacterSheet` the batteries-included default that pairs them — the game composes and reskins them (slot layout, stat labels/terminology, skin) rather than re-deriving a paperdoll from raw divs and manual stat math.