@jgengine/react 0.22.0 → 0.23.0

package/dist/hudTheme.d.ts

@@ -96,6 +96,73 @@ export interface HudThemeSlot {
     border: string;
     radius: string;
 }
+/**
+ * Type scale (any CSS length). `min` is the readability floor every engine block clamps to;
+ * `xs` is the smallest step a block uses, so it never drops below `min`.
+ */
+export interface HudThemeType {
+    min: string;
+    xs: string;
+    sm: string;
+    md: string;
+    lg: string;
+    xl: string;
+    xxl: string;
+    display: string;
+    /** Body line height (unitless). */
+    leading: string;
+    /** Letter spacing for uppercase labels and headers. */
+    tracking: string;
+}
+/** Spacing steps (any CSS length). */
+export interface HudThemeSpace {
+    xs: string;
+    sm: string;
+    md: string;
+    lg: string;
+    xl: string;
+}
+/**
+ * Motion durations and easings. Blocks multiply durations by `--jg-motion-scale`, which the engine
+ * stylesheet sets to 0 under `prefers-reduced-motion` or `[data-reduced-motion="true"]`.
+ */
+export interface HudThemeMotion {
+    fast: string;
+    base: string;
+    slow: string;
+    /** Standard ease for state changes. */
+    ease: string;
+    /** Decelerating ease for entrances. */
+    easeOut: string;
+    /** Slight overshoot for pops and presses releasing. */
+    spring: string;
+}
+/** Layered `box-shadow` stacks by height, plus the inner top highlight a lit panel edge gets. */
+export interface HudThemeElevation {
+    /** Resting panels and buttons. */
+    raised: string;
+    /** Hovered buttons, popovers, tooltips. */
+    overlay: string;
+    /** Windows and modal dialogs. */
+    modal: string;
+    /** Inset top-edge highlight, layered into the stacks above by blocks that want a lit rim. */
+    highlight: string;
+}
+/** Interactive-state tokens shared by every engine button, slot, and window. */
+export interface HudThemeState {
+    /** Overlay color washed over a hovered control. */
+    hover: string;
+    /** Hover lift as a `translate` Y length (e.g. `"-1px"`). */
+    hoverLift: string;
+    /** Overlay color washed over a pressed control. */
+    press: string;
+    /** Pressed `scale` factor (e.g. `"0.97"`). */
+    pressScale: string;
+    /** Focus ring as a `box-shadow` value. Unset derives a two-tone ring from the accent. */
+    focusRing?: string;
+    /** Opacity of a disabled control. */
+    disabledOpacity: string;
+}
 /** A full HUD theme. Author one with {@link hudTheme} or {@link deriveHudTheme}. */
 export interface HudTheme {
     palette: HudThemePalette;
@@ -109,10 +176,25 @@ export interface HudTheme {
     /** Minimap chrome ring color. */
     ring: string;
     skin?: HudSkin;
+    /** Type scale; unset uses {@link defaultHudTheme}'s. */
+    type?: HudThemeType;
+    /** Spacing steps; unset uses {@link defaultHudTheme}'s. */
+    space?: HudThemeSpace;
+    /** Durations and easings; unset uses {@link defaultHudTheme}'s. */
+    motion?: HudThemeMotion;
+    /** Shadow stacks; unset uses {@link defaultHudTheme}'s. */
+    elevation?: HudThemeElevation;
+    /** Hover, press, focus, and disabled tokens; unset uses {@link defaultHudTheme}'s. */
+    state?: HudThemeState;
 }
 /** Emits theme CSS properties, resetting inherited bar fills when absent. Spread onto a HUD ancestor. */
 export declare function hudThemeVars(theme: HudTheme): CSSProperties;
-/** Default theme tokens for previews/scaffold — not a finished game look; author a custom theme. */
+/**
+ * The engine's default HUD look, applied by the shell at the HUD root of every game that does not
+ * opt out: a strong system UI font stack, layered translucent panels with a lit top rim and crisp
+ * hairline borders, a 12px type floor, and motion that honours reduced-motion. Games override any
+ * part with their own theme on a HUD ancestor.
+ */
 export declare const defaultHudTheme: HudTheme;
 /** Per-group partial overrides accepted by {@link hudTheme}. */
 export interface HudThemeOverrides {
@@ -126,6 +208,11 @@ export interface HudThemeOverrides {
     slot?: Partial<HudThemeSlot>;
     ring?: string;
     skin?: HudSkin;
+    type?: Partial<HudThemeType>;
+    space?: Partial<HudThemeSpace>;
+    motion?: Partial<HudThemeMotion>;
+    elevation?: Partial<HudThemeElevation>;
+    state?: Partial<HudThemeState>;
 }
 /**
  * Builds a full {@link HudTheme} from per-group partials, filling the rest from

package/dist/hudTheme.js

@@ -1,6 +1,43 @@
 import {} from "react";
 import { hudSkinVars } from "./hudSkin.js";
 export { hudSkinVars } from "./hudSkin.js";
+const DEFAULT_TYPE = {
+    min: "12px",
+    xs: "12px",
+    sm: "13px",
+    md: "14px",
+    lg: "16px",
+    xl: "20px",
+    xxl: "26px",
+    display: "34px",
+    leading: "1.4",
+    tracking: "0.08em",
+};
+const DEFAULT_SPACE = { xs: "4px", sm: "8px", md: "12px", lg: "16px", xl: "24px" };
+const DEFAULT_MOTION = {
+    fast: "120ms",
+    base: "180ms",
+    slow: "320ms",
+    ease: "cubic-bezier(0.2, 0, 0, 1)",
+    easeOut: "cubic-bezier(0.16, 1, 0.3, 1)",
+    spring: "cubic-bezier(0.34, 1.56, 0.64, 1)",
+};
+const DEFAULT_ELEVATION = {
+    raised: "0 1px 2px rgba(0,0,0,0.45), 0 4px 12px -2px rgba(0,0,0,0.4)",
+    overlay: "0 2px 4px rgba(0,0,0,0.4), 0 10px 24px -4px rgba(0,0,0,0.5)",
+    modal: "0 4px 8px rgba(0,0,0,0.35), 0 24px 56px -12px rgba(0,0,0,0.7)",
+    highlight: "inset 0 1px 0 rgba(255,255,255,0.08)",
+};
+const DEFAULT_STATE = {
+    hover: "rgba(255,255,255,0.07)",
+    hoverLift: "-1px",
+    press: "rgba(0,0,0,0.14)",
+    pressScale: "0.97",
+    disabledOpacity: "0.45",
+};
+function focusRing(theme) {
+    return theme.state?.focusRing ?? `0 0 0 2px ${theme.surface.surfaceDeep}, 0 0 0 4px ${theme.palette.accent}`;
+}
 /** Emits theme CSS properties, resetting inherited bar fills when absent. Spread onto a HUD ancestor. */
 export function hudThemeVars(theme) {
     const { palette, surface, status, font, rarity, frame, bar, slot } = theme;
@@ -72,9 +109,73 @@ export function hudThemeVars(theme) {
         "--jg-slot-border": slot.border,
         "--jg-slot-radius": slot.radius,
         "--jg-ring": theme.ring,
+        ...typeVars(theme.type ?? DEFAULT_TYPE),
+        ...spaceVars(theme.space ?? DEFAULT_SPACE),
+        ...motionVars(theme.motion ?? DEFAULT_MOTION),
+        ...elevationVars(theme.elevation ?? DEFAULT_ELEVATION),
+        ...stateVars(theme.state ?? DEFAULT_STATE),
+        "--jg-focus-ring": focusRing(theme),
+    };
+}
+function typeVars(type) {
+    const floor = (size) => `max(${type.min}, ${size})`;
+    return {
+        "--jg-type-min": type.min,
+        "--jg-type-xs": floor(type.xs),
+        "--jg-type-sm": floor(type.sm),
+        "--jg-type-md": floor(type.md),
+        "--jg-type-lg": floor(type.lg),
+        "--jg-type-xl": floor(type.xl),
+        "--jg-type-xxl": floor(type.xxl),
+        "--jg-type-display": floor(type.display),
+        "--jg-leading": type.leading,
+        "--jg-tracking-label": type.tracking,
+    };
+}
+function spaceVars(space) {
+    return {
+        "--jg-space-xs": space.xs,
+        "--jg-space-sm": space.sm,
+        "--jg-space-md": space.md,
+        "--jg-space-lg": space.lg,
+        "--jg-space-xl": space.xl,
+    };
+}
+function motionVars(motion) {
+    return {
+        "--jg-motion-fast": motion.fast,
+        "--jg-motion-base": motion.base,
+        "--jg-motion-slow": motion.slow,
+        "--jg-ease": motion.ease,
+        "--jg-ease-out": motion.easeOut,
+        "--jg-ease-spring": motion.spring,
+    };
+}
+function elevationVars(elevation) {
+    return {
+        "--jg-elevation-raised": elevation.raised,
+        "--jg-elevation-overlay": elevation.overlay,
+        "--jg-elevation-modal": elevation.modal,
+        "--jg-highlight": elevation.highlight,
+    };
+}
+function stateVars(state) {
+    return {
+        "--jg-hover-overlay": state.hover,
+        "--jg-hover-lift": state.hoverLift,
+        "--jg-press-overlay": state.press,
+        "--jg-press-scale": state.pressScale,
+        "--jg-disabled-opacity": state.disabledOpacity,
     };
 }
-/** Default theme tokens for previews/scaffold — not a finished game look; author a custom theme. */
+const UI_FONT = '"Inter Variable", Inter, "SF Pro Text", -apple-system, BlinkMacSystemFont, "Segoe UI Variable Text", "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif';
+const DISPLAY_FONT = '"Inter Display", "Inter Variable", Inter, "SF Pro Display", -apple-system, BlinkMacSystemFont, "Segoe UI Variable Display", "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif';
+/**
+ * The engine's default HUD look, applied by the shell at the HUD root of every game that does not
+ * opt out: a strong system UI font stack, layered translucent panels with a lit top rim and crisp
+ * hairline borders, a 12px type floor, and motion that honours reduced-motion. Games override any
+ * part with their own theme on a HUD ancestor.
+ */
 export const defaultHudTheme = {
     palette: {
         health: "#e5484d",
@@ -114,9 +215,9 @@ export const defaultHudTheme = {
         neutral: "#c9b458",
     },
     font: {
-        display: '"Segoe UI", system-ui, sans-serif',
-        numeric: 'Consolas, "Cascadia Mono", "SF Mono", "Roboto Mono", monospace',
-        body: '"Segoe UI", system-ui, sans-serif',
+        display: DISPLAY_FONT,
+        numeric: UI_FONT,
+        body: UI_FONT,
     },
     rarity: {
         common: "#b4b2a8",
@@ -126,10 +227,10 @@ export const defaultHudTheme = {
         legendary: "#e0862e",
     },
     frame: {
-        bg: "linear-gradient(180deg, rgba(20,24,32,0.86), rgba(10,12,16,0.9))",
-        border: "1px solid rgba(255,255,255,0.12)",
+        bg: "linear-gradient(180deg, rgba(255,255,255,0.045), rgba(255,255,255,0) 42%), linear-gradient(180deg, rgba(22,27,36,0.9), rgba(10,13,18,0.94))",
+        border: "1px solid rgba(255,255,255,0.13)",
         radius: "10px",
-        glow: "0 6px 20px rgba(0,0,0,0.45)",
+        glow: `${DEFAULT_ELEVATION.highlight}, ${DEFAULT_ELEVATION.raised}`,
     },
     bar: {
         track: "rgba(0,0,0,0.55)",
@@ -139,8 +240,17 @@ export const defaultHudTheme = {
         bevel: "inset 0 2px 4px rgba(0,0,0,0.55), inset 0 -1px 2px rgba(255,255,255,0.08)",
         text: "#f5f7fa",
     },
-    slot: { bg: "rgba(12,14,20,0.7)", border: "1px solid rgba(255,255,255,0.12)", radius: "8px" },
+    slot: {
+        bg: "linear-gradient(180deg, rgba(255,255,255,0.05), rgba(255,255,255,0) 50%), rgba(12,15,21,0.78)",
+        border: "1px solid rgba(255,255,255,0.13)",
+        radius: "8px",
+    },
     ring: "rgba(140,170,200,0.35)",
+    type: DEFAULT_TYPE,
+    space: DEFAULT_SPACE,
+    motion: DEFAULT_MOTION,
+    elevation: DEFAULT_ELEVATION,
+    state: DEFAULT_STATE,
 };
 /**
  * Builds a full {@link HudTheme} from per-group partials, filling the rest from
@@ -161,6 +271,11 @@ export function hudTheme(overrides) {
         slot: { ...defaultHudTheme.slot, ...overrides.slot },
         ring: overrides.ring ?? defaultHudTheme.ring,
         skin: overrides.skin,
+        type: { ...DEFAULT_TYPE, ...overrides.type },
+        space: { ...DEFAULT_SPACE, ...overrides.space },
+        motion: { ...DEFAULT_MOTION, ...overrides.motion },
+        elevation: { ...DEFAULT_ELEVATION, ...overrides.elevation },
+        state: { ...DEFAULT_STATE, ...overrides.state },
     };
 }
 const theme = hudTheme;

package/dist/hudThemePreview.js

@@ -3,6 +3,7 @@ import {} from "react";
 import { AmmoCounter, ExperienceBar, HealthBar, ManaBar, ShieldBar } from "./bars.js";
 import { HudFrame } from "./hudFrame.js";
 import { HUD_THEME_PRESETS, defaultHudTheme, hudThemeVars } from "./hudTheme.js";
+import { hudType } from "./hudTokens.js";
 /**
  * A deterministic preset matrix for {@link HudTheme} (#1034): every genre preset × (bars + a themed
  * frame + a slot row), rendered from static values. One `hudThemeVars(theme)` block per cell drives
@@ -19,7 +20,7 @@ function Slot({ index }) {
             display: "flex",
             alignItems: "center",
             justifyContent: "center",
-            fontSize: 10,
+            fontSize: hudType("xs"),
             color: "var(--jg-bar-text, #f4f6fb)",
             opacity: index === 0 ? 1 : 0.6,
         }, children: index + 1 }));

package/dist/hudThemeRoot.d.ts

@@ -0,0 +1,15 @@
+import { type ReactNode } from "react";
+import { type HudTheme } from "./hudTheme.js";
+/**
+ * The HUD root the shell mounts around every `GameUI`: a layout-free (`display: contents`)
+ * `[data-jg-hud]` element carrying the theme's `--jg-*` variables, plus the engine stylesheet. Unset
+ * `theme` applies {@link defaultHudTheme}; a game's own theme on any descendant still wins by
+ * inheritance. `false` opts out of the default theme and the generic HUD control defaults; the
+ * keyframes stay so engine blocks still animate.
+ *
+ * @capability hud-theme-root apply the default (or a game) HudTheme and the engine stylesheet at the HUD root
+ */
+export declare function HudThemeRoot({ theme, children }: {
+    theme?: HudTheme | false;
+    children?: ReactNode;
+}): ReactNode;

package/dist/hudThemeRoot.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { useEngineStyles } from "./engineStyles.js";
+import { defaultHudTheme, hudThemeVars } from "./hudTheme.js";
+/**
+ * The HUD root the shell mounts around every `GameUI`: a layout-free (`display: contents`)
+ * `[data-jg-hud]` element carrying the theme's `--jg-*` variables, plus the engine stylesheet. Unset
+ * `theme` applies {@link defaultHudTheme}; a game's own theme on any descendant still wins by
+ * inheritance. `false` opts out of the default theme and the generic HUD control defaults; the
+ * keyframes stay so engine blocks still animate.
+ *
+ * @capability hud-theme-root apply the default (or a game) HudTheme and the engine stylesheet at the HUD root
+ */
+export function HudThemeRoot({ theme, children }) {
+    useEngineStyles();
+    const vars = useMemo(() => (theme === false ? null : hudThemeVars(theme ?? defaultHudTheme)), [theme]);
+    if (vars === null)
+        return children;
+    return (_jsx("div", { "data-jg-hud": "", style: { display: "contents", ...vars }, children: children }));
+}

package/dist/hudTokens.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Inline-style accessors for the `HudTheme` scale tokens (#1034): each returns a `var(--jg-*)`
+ * reference with the default theme's value as fallback, so a block reads the active theme when one
+ * is applied and still renders the default look outside the shell.
+ *
+ * @capability hud-tokens inline-style accessors for the HudTheme type scale, spacing, motion, elevation, and focus ring
+ */
+/** Type-scale step. `xs` is the smallest step and never renders below the theme's 12px floor. */
+export type HudTypeStep = "xs" | "sm" | "md" | "lg" | "xl" | "xxl" | "display";
+/** Spacing step. */
+export type HudSpaceStep = "xs" | "sm" | "md" | "lg" | "xl";
+/** Motion duration step. */
+export type HudMotionSpeed = "fast" | "base" | "slow";
+/** Motion easing. */
+export type HudEase = "ease" | "easeOut" | "spring";
+/** Shadow stack height. */
+export type HudElevation = "raised" | "overlay" | "modal";
+/** UI sans stack used when no theme supplies `--jg-font-body`. */
+export declare const HUD_FONT_STACK = "\"Inter Variable\", Inter, \"SF Pro Text\", -apple-system, BlinkMacSystemFont, \"Segoe UI Variable Text\", \"Segoe UI\", Roboto, \"Helvetica Neue\", Arial, sans-serif";
+/** Font-size reference for a type-scale step, e.g. `fontSize: hudType("xs")`. */
+export declare function hudType(step: HudTypeStep): string;
+/** Spacing reference for a step, e.g. `padding: hudSpace("sm")`. */
+export declare function hudSpace(step: HudSpaceStep): string;
+/** Duration reference scaled by `--jg-motion-scale` (0 under reduced motion). */
+export declare function hudDuration(speed?: HudMotionSpeed): string;
+/** Easing reference. */
+export declare function hudEase(ease?: HudEase): string;
+/** `transition` value for the given properties at one speed and easing, honouring reduced motion. */
+export declare function hudTransition(properties: string | readonly string[], speed?: HudMotionSpeed, ease?: HudEase): string;
+/** `box-shadow` reference for a height, with the lit top rim layered in. */
+export declare function hudElevation(level?: HudElevation): string;
+/** Font-family references for each theme role. */
+export declare const hudFont: {
+    readonly body: "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)";
+    readonly display: "var(--jg-font-display, \"Inter Variable\", Inter, \"SF Pro Text\", -apple-system, BlinkMacSystemFont, \"Segoe UI Variable Text\", \"Segoe UI\", Roboto, \"Helvetica Neue\", Arial, sans-serif)";
+    readonly numeric: "var(--jg-font-numeric, \"Inter Variable\", Inter, \"SF Pro Text\", -apple-system, BlinkMacSystemFont, \"Segoe UI Variable Text\", \"Segoe UI\", Roboto, \"Helvetica Neue\", Arial, sans-serif)";
+};
+/** Focus ring `box-shadow` reference. */
+export declare const HUD_FOCUS_RING = "var(--jg-focus-ring, 0 0 0 2px #0a0c10, 0 0 0 4px var(--jg-accent, #38bdf8))";

package/dist/hudTokens.js

@@ -0,0 +1,56 @@
+/**
+ * Inline-style accessors for the `HudTheme` scale tokens (#1034): each returns a `var(--jg-*)`
+ * reference with the default theme's value as fallback, so a block reads the active theme when one
+ * is applied and still renders the default look outside the shell.
+ *
+ * @capability hud-tokens inline-style accessors for the HudTheme type scale, spacing, motion, elevation, and focus ring
+ */
+const TYPE_PX = { xs: 12, sm: 13, md: 14, lg: 16, xl: 20, xxl: 26, display: 34 };
+const SPACE_PX = { xs: 4, sm: 8, md: 12, lg: 16, xl: 24 };
+const MOTION_MS = { fast: 120, base: 180, slow: 320 };
+const EASE = {
+    ease: ["--jg-ease", "cubic-bezier(0.2, 0, 0, 1)"],
+    easeOut: ["--jg-ease-out", "cubic-bezier(0.16, 1, 0.3, 1)"],
+    spring: ["--jg-ease-spring", "cubic-bezier(0.34, 1.56, 0.64, 1)"],
+};
+const ELEVATION = {
+    raised: "0 1px 2px rgba(0,0,0,0.45), 0 4px 12px -2px rgba(0,0,0,0.4)",
+    overlay: "0 2px 4px rgba(0,0,0,0.4), 0 10px 24px -4px rgba(0,0,0,0.5)",
+    modal: "0 4px 8px rgba(0,0,0,0.35), 0 24px 56px -12px rgba(0,0,0,0.7)",
+};
+/** UI sans stack used when no theme supplies `--jg-font-body`. */
+export const HUD_FONT_STACK = '"Inter Variable", Inter, "SF Pro Text", -apple-system, BlinkMacSystemFont, "Segoe UI Variable Text", "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif';
+/** Font-size reference for a type-scale step, e.g. `fontSize: hudType("xs")`. */
+export function hudType(step) {
+    return `var(--jg-type-${step}, ${TYPE_PX[step]}px)`;
+}
+/** Spacing reference for a step, e.g. `padding: hudSpace("sm")`. */
+export function hudSpace(step) {
+    return `var(--jg-space-${step}, ${SPACE_PX[step]}px)`;
+}
+/** Duration reference scaled by `--jg-motion-scale` (0 under reduced motion). */
+export function hudDuration(speed = "fast") {
+    return `calc(var(--jg-motion-${speed}, ${MOTION_MS[speed]}ms) * var(--jg-motion-scale, 1))`;
+}
+/** Easing reference. */
+export function hudEase(ease = "ease") {
+    const [name, fallback] = EASE[ease];
+    return `var(${name}, ${fallback})`;
+}
+/** `transition` value for the given properties at one speed and easing, honouring reduced motion. */
+export function hudTransition(properties, speed = "fast", ease = "ease") {
+    const list = typeof properties === "string" ? [properties] : properties;
+    return list.map((property) => `${property} ${hudDuration(speed)} ${hudEase(ease)}`).join(", ");
+}
+/** `box-shadow` reference for a height, with the lit top rim layered in. */
+export function hudElevation(level = "raised") {
+    return `var(--jg-highlight, inset 0 1px 0 rgba(255,255,255,0.08)), var(--jg-elevation-${level}, ${ELEVATION[level]})`;
+}
+/** Font-family references for each theme role. */
+export const hudFont = {
+    body: `var(--jg-font-body, ${HUD_FONT_STACK})`,
+    display: `var(--jg-font-display, ${HUD_FONT_STACK})`,
+    numeric: `var(--jg-font-numeric, ${HUD_FONT_STACK})`,
+};
+/** Focus ring `box-shadow` reference. */
+export const HUD_FOCUS_RING = "var(--jg-focus-ring, 0 0 0 2px #0a0c10, 0 0 0 4px var(--jg-accent, #38bdf8))";

package/dist/iconTreatment.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import {} from "react";
 import { GameIcon, iconForAction, iconForItemId } from "./gameIcons.js";
+import { hudType } from "./hudTokens.js";
 const SCHOOL_GRADIENT = {
     fire: ["#ff8a3d", "#661805"],
     frost: ["#8fe3ff", "#0e3357"],
@@ -58,11 +59,11 @@ export function IconTreatment({ icon, glyph, school = "neutral", size = 44, coun
             justifyContent: "center",
             boxSizing: "border-box",
             ...style,
-        }, children: [_jsx("div", { style: { position: "absolute", inset: 0, background: "linear-gradient(180deg, rgba(255,255,255,0.3), rgba(255,255,255,0) 46%)", pointerEvents: "none" } }), _jsx("div", { style: { position: "absolute", inset: 0, borderRadius: "inherit", boxShadow: "inset 0 0 12px rgba(0,0,0,0.55)", pointerEvents: "none" } }), content, keycap !== undefined ? (_jsx("span", { style: { position: "absolute", top: 1, left: 4, fontSize: 9, fontWeight: 700, color: "#fff", opacity: 0.75, textShadow: "0 1px 2px rgba(0,0,0,0.9)" }, children: keycap })) : null, count !== undefined && count > 1 ? (_jsx("span", { "data-count": true, style: {
+        }, children: [_jsx("div", { style: { position: "absolute", inset: 0, background: "linear-gradient(180deg, rgba(255,255,255,0.3), rgba(255,255,255,0) 46%)", pointerEvents: "none" } }), _jsx("div", { style: { position: "absolute", inset: 0, borderRadius: "inherit", boxShadow: "inset 0 0 12px rgba(0,0,0,0.55)", pointerEvents: "none" } }), content, keycap !== undefined ? (_jsx("span", { style: { position: "absolute", top: 1, left: 4, fontSize: hudType("xs"), fontWeight: 700, color: "#fff", opacity: 0.75, textShadow: "0 1px 2px rgba(0,0,0,0.9)" }, children: keycap })) : null, count !== undefined && count > 1 ? (_jsx("span", { "data-count": true, style: {
                     position: "absolute",
                     bottom: 1,
                     right: 3,
-                    fontSize: 11,
+                    fontSize: hudType("xs"),
                     fontWeight: 800,
                     color: "#fff",
                     fontVariantNumeric: "tabular-nums",

package/dist/iconsPreview.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { IconTreatment } from "./iconTreatment.js";
+import { hudType } from "./hudTokens.js";
 /**
  * A deterministic showcase of the painted {@link IconTreatment} (#1035): a school row (one gradient
  * each) and a mock hotbar of treated item icons with count badges and an active slot. Static, so it
@@ -25,5 +26,5 @@ const HOTBAR = [
 ];
 /** Renders the school-gradient row and a treated-icon hotbar — the deterministic #1035 fixture. */
 export function IconsPreview({ className }) {
-    return (_jsxs("div", { "data-icons-preview": true, className: className, style: { display: "flex", flexDirection: "column", gap: 22, padding: 26, background: "#0e1216", fontFamily: "system-ui, sans-serif", color: "#e8edf2" }, children: [_jsxs("div", { children: [_jsx("div", { style: { fontSize: 11, fontWeight: 700, letterSpacing: 0.6, textTransform: "uppercase", opacity: 0.6, marginBottom: 8 }, children: "school gradients" }), _jsx("div", { style: { display: "flex", gap: 10 }, children: SCHOOLS.map(([school, icon]) => (_jsx(IconTreatment, { icon: icon, school: school, size: 52 }, school))) })] }), _jsxs("div", { children: [_jsx("div", { style: { fontSize: 11, fontWeight: 700, letterSpacing: 0.6, textTransform: "uppercase", opacity: 0.6, marginBottom: 8 }, children: "hotbar \u2014 treated icons + count badges (slot 1 active)" }), _jsx("div", { style: { display: "flex", gap: 6 }, children: HOTBAR.map((entry, index) => (_jsx(IconTreatment, { icon: entry.icon, school: entry.school, size: 50, keycap: String(index + 1), active: index === 0, ...(entry.count === undefined ? {} : { count: entry.count }) }, index))) })] })] }));
+    return (_jsxs("div", { "data-icons-preview": true, className: className, style: { display: "flex", flexDirection: "column", gap: 22, padding: 26, background: "#0e1216", fontFamily: "system-ui, sans-serif", color: "#e8edf2" }, children: [_jsxs("div", { children: [_jsx("div", { style: { fontSize: hudType("xs"), fontWeight: 700, letterSpacing: 0.6, textTransform: "uppercase", opacity: 0.6, marginBottom: 8 }, children: "school gradients" }), _jsx("div", { style: { display: "flex", gap: 10 }, children: SCHOOLS.map(([school, icon]) => (_jsx(IconTreatment, { icon: icon, school: school, size: 52 }, school))) })] }), _jsxs("div", { children: [_jsx("div", { style: { fontSize: hudType("xs"), fontWeight: 700, letterSpacing: 0.6, textTransform: "uppercase", opacity: 0.6, marginBottom: 8 }, children: "hotbar \u2014 treated icons + count badges (slot 1 active)" }), _jsx("div", { style: { display: "flex", gap: 6 }, children: HOTBAR.map((entry, index) => (_jsx(IconTreatment, { icon: entry.icon, school: entry.school, size: 50, keycap: String(index + 1), active: index === 0, ...(entry.count === undefined ? {} : { count: entry.count }) }, index))) })] })] }));
 }

package/dist/keybindingMenu.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useReducer } from "react";
 import { Keycap } from "./keyHint.js";
+import { hudType } from "./hudTokens.js";
 /**
  * Subscribe to a rebind session and re-render on every change (capture, reset,
  * arm/disarm, restore). Returns the session unchanged for convenient inline use.
@@ -98,7 +99,7 @@ function KeybindingRow({ row, armed, capturePrompt, theme, onArm, onReset, }) {
                             marginLeft: 8,
                             padding: "1px 7px",
                             borderRadius: 999,
-                            fontSize: 10,
+                            fontSize: hudType("xs"),
                             fontWeight: 800,
                             letterSpacing: "0.06em",
                             textTransform: "uppercase",
@@ -128,7 +129,7 @@ function KeybindingRow({ row, armed, capturePrompt, theme, onArm, onReset, }) {
                     opacity: row.isDefault ? 0.35 : 1,
                     cursor: row.isDefault ? "default" : "pointer",
                     padding: "4px 8px",
-                    fontSize: 11,
+                    fontSize: hudType("xs"),
                 }, children: "Reset" })] }));
 }
 function buttonStyle(color, border) {

package/dist/map.js

@@ -4,6 +4,7 @@ import { DEFAULT_MARKER_KINDS, markerKindStyle, } from "@jgengine/core/world/mar
 import { bearingToCardinal, clampToMinimapEdge, compassBearing, headingToBearing, projectToMinimap, relativeBearing, unprojectFromMinimap, } from "@jgengine/core/world/minimap";
 import { mapLayerColor, } from "@jgengine/core/world/mapLayers";
 import { createFogDataUrl } from "./fogOverlay.js";
+import { hudType } from "./hudTokens.js";
 function routeNodes(routes, project, keyPrefix) {
     if (routes === undefined)
         return [];
@@ -150,7 +151,7 @@ export function Minimap({ markers, center, worldRadius, fog, size = 176, facingY
                     justifyContent: "space-between",
                     alignItems: "center",
                     marginBottom: 6,
-                    fontSize: 10,
+                    fontSize: hudType("xs"),
                     letterSpacing: 1.4,
                     textTransform: "uppercase",
                     color: "rgba(203,213,225,0.75)",
@@ -291,7 +292,7 @@ export function Compass({ facingYaw, center, markers, width = 340, fov = (Math.P
                             left: x,
                             bottom: 2,
                             transform: "translateX(-50%)",
-                            fontSize: 11,
+                            fontSize: hudType("xs"),
                             color: style.color,
                             fontWeight: 700,
                         }, children: style.glyph }, marker.id));
@@ -317,7 +318,7 @@ export function MinimapPanel({ zoneLabel, clock, showCompass = true, compassProp
                     width: minimapProps.size ?? 176,
                     color: "#e2e8f0",
                     fontFamily: "ui-sans-serif, system-ui, sans-serif",
-                }, children: [zoneLabel !== undefined ? (_jsx("span", { className: zoneLabelClassName, "data-minimap-chrome-zone": true, style: { fontSize: 12, fontWeight: 700 }, children: zoneLabel })) : (_jsx("span", {})), clock !== undefined ? (_jsx("span", { className: clockClassName, "data-minimap-chrome-clock": true, style: { fontSize: 11, color: "rgba(226,232,240,0.75)" }, children: clock })) : null] })) : null, _jsx(Minimap, { ...minimapProps, children: children }), showCompass ? (_jsx("div", { className: compassClassName, "data-minimap-chrome-compass": true, style: { marginTop: 6 }, children: _jsx(Compass, { facingYaw: minimapProps.facingYaw ?? 0, center: minimapProps.center, markers: minimapProps.markers, width: minimapProps.size ?? 176, ...compassProps }) })) : null] }));
+                }, children: [zoneLabel !== undefined ? (_jsx("span", { className: zoneLabelClassName, "data-minimap-chrome-zone": true, style: { fontSize: 12, fontWeight: 700 }, children: zoneLabel })) : (_jsx("span", {})), clock !== undefined ? (_jsx("span", { className: clockClassName, "data-minimap-chrome-clock": true, style: { fontSize: hudType("xs"), color: "rgba(226,232,240,0.75)" }, children: clock })) : null] })) : null, _jsx(Minimap, { ...minimapProps, children: children }), showCompass ? (_jsx("div", { className: compassClassName, "data-minimap-chrome-compass": true, style: { marginTop: 6 }, children: _jsx(Compass, { facingYaw: minimapProps.facingYaw ?? 0, center: minimapProps.center, markers: minimapProps.markers, width: minimapProps.size ?? 176, ...compassProps }) })) : null] }));
 }
 const TRACK_PIP_DIAMETER = {
     dot: 6,
@@ -449,7 +450,7 @@ export function WorldMap({ markers, bounds, player, facingYaw = 0, fog, backgrou
                             borderRadius: 6,
                             background: "transparent",
                             color: "rgba(226,232,240,0.85)",
-                            fontSize: 11,
+                            fontSize: hudType("xs"),
                             padding: "3px 9px",
                             cursor: "pointer",
                         }, children: "Close" })) : null] }), _jsx(WorldMapSurface, { markers: markers, bounds: bounds, player: player, facingYaw: facingYaw, fog: fog, background: background, width: width, height: height, kindStyles: kindStyles, routes: routes, zones: zones, cellStates: cellStates, onWorldClick: onWorldClick })] }));
@@ -605,7 +606,7 @@ export function FullscreenMap({ open = true, bounds, contentWidth = 900, minScal
                     justifyContent: "space-between",
                     padding: "10px 16px",
                     borderBottom: "1px solid rgba(148,163,184,0.2)",
-                }, children: [_jsx("span", { style: { fontSize: 13, fontWeight: 700, letterSpacing: 1.6, textTransform: "uppercase" }, children: title }), _jsxs("div", { style: { display: "flex", gap: 8, alignItems: "center" }, children: [_jsx("button", { type: "button", "aria-label": "Zoom out", style: controlButton, onClick: () => zoomBy(1 / 1.2, contentWidth / 2, contentHeight / 2), children: "\u2212" }), _jsx("button", { type: "button", "aria-label": "Zoom in", style: controlButton, onClick: () => zoomBy(1.2, contentWidth / 2, contentHeight / 2), children: "+" }), _jsx("button", { type: "button", "aria-label": "Reset view", style: { ...controlButton, width: "auto", padding: "0 10px", fontSize: 11 }, onClick: () => setViewport(IDENTITY_VIEWPORT), children: "Reset" }), onClose !== undefined ? (_jsx("button", { type: "button", "aria-label": "Close map", style: { ...controlButton, width: "auto", padding: "0 12px", fontSize: 11 }, onClick: onClose, children: "Close" })) : null] })] }), _jsxs("div", { "data-fullscreen-map-viewport": true, "data-map-tool": tool, style: {
+                }, children: [_jsx("span", { style: { fontSize: 13, fontWeight: 700, letterSpacing: 1.6, textTransform: "uppercase" }, children: title }), _jsxs("div", { style: { display: "flex", gap: 8, alignItems: "center" }, children: [_jsx("button", { type: "button", "aria-label": "Zoom out", style: controlButton, onClick: () => zoomBy(1 / 1.2, contentWidth / 2, contentHeight / 2), children: "\u2212" }), _jsx("button", { type: "button", "aria-label": "Zoom in", style: controlButton, onClick: () => zoomBy(1.2, contentWidth / 2, contentHeight / 2), children: "+" }), _jsx("button", { type: "button", "aria-label": "Reset view", style: { ...controlButton, width: "auto", padding: "0 10px", fontSize: hudType("xs") }, onClick: () => setViewport(IDENTITY_VIEWPORT), children: "Reset" }), onClose !== undefined ? (_jsx("button", { type: "button", "aria-label": "Close map", style: { ...controlButton, width: "auto", padding: "0 12px", fontSize: hudType("xs") }, onClick: onClose, children: "Close" })) : null] })] }), _jsxs("div", { "data-fullscreen-map-viewport": true, "data-map-tool": tool, style: {
                     position: "relative",
                     flex: 1,
                     minHeight: 0,
@@ -680,9 +681,9 @@ export function MapLegend({ kinds, labels, kindStyles = DEFAULT_MARKER_KINDS, ti
             border: "1px solid rgba(148,163,184,0.28)",
             color: "#e2e8f0",
             fontFamily: "ui-sans-serif, system-ui, sans-serif",
-            fontSize: 11,
+            fontSize: hudType("xs"),
             ...style,
-        }, children: [title !== "" ? (_jsx("div", { style: { fontSize: 9, letterSpacing: 1.4, textTransform: "uppercase", color: "rgba(203,213,225,0.7)", marginBottom: 5 }, children: title })) : null, _jsx("ul", { style: { listStyle: "none", margin: 0, padding: 0, display: "flex", flexDirection: "column", gap: 3 }, children: kinds.map((kind) => {
+        }, children: [title !== "" ? (_jsx("div", { style: { fontSize: hudType("xs"), letterSpacing: 1.4, textTransform: "uppercase", color: "rgba(203,213,225,0.7)", marginBottom: 5 }, children: title })) : null, _jsx("ul", { style: { listStyle: "none", margin: 0, padding: 0, display: "flex", flexDirection: "column", gap: 3 }, children: kinds.map((kind) => {
                     const kindStyle = markerKindStyle(kind, kindStyles);
                     return (_jsxs("li", { "data-legend-kind": kind, style: { display: "flex", alignItems: "center", gap: 7 }, children: [_jsx("span", { "aria-hidden": true, style: { width: 14, textAlign: "center", color: kindStyle.color, fontWeight: 700 }, children: kindStyle.glyph }), _jsx("span", { children: labels?.[kind] ?? kind })] }, kind));
                 }) })] }));
@@ -704,5 +705,5 @@ export function WaypointArrow({ relative, distance, label, formatDistance = (val
             fontFamily: "ui-sans-serif, system-ui, sans-serif",
             textShadow: "0 1px 2px rgba(0,0,0,0.9)",
             ...style,
-        }, children: [_jsx("svg", { width: size, height: size, viewBox: "0 0 44 44", "aria-hidden": true, "data-waypoint-arrow-needle": true, children: _jsx("g", { transform: `rotate(${(relative * 180) / Math.PI} 22 22)`, children: _jsx("path", { d: "M22 6 L32 34 L22 27 L12 34 Z", fill: color, stroke: "rgba(0,0,0,0.7)", strokeWidth: 1.2, strokeLinejoin: "round" }) }) }), label !== undefined ? (_jsx("span", { style: { fontSize: 10, fontWeight: 700, letterSpacing: 0.6, textTransform: "uppercase" }, children: label })) : null, distance !== undefined ? (_jsx("span", { style: { fontSize: 11, fontVariantNumeric: "tabular-nums", color: "rgba(226,232,240,0.9)" }, children: formatDistance(distance) })) : null] }));
+        }, children: [_jsx("svg", { width: size, height: size, viewBox: "0 0 44 44", "aria-hidden": true, "data-waypoint-arrow-needle": true, children: _jsx("g", { transform: `rotate(${(relative * 180) / Math.PI} 22 22)`, children: _jsx("path", { d: "M22 6 L32 34 L22 27 L12 34 Z", fill: color, stroke: "rgba(0,0,0,0.7)", strokeWidth: 1.2, strokeLinejoin: "round" }) }) }), label !== undefined ? (_jsx("span", { style: { fontSize: hudType("xs"), fontWeight: 700, letterSpacing: 0.6, textTransform: "uppercase" }, children: label })) : null, distance !== undefined ? (_jsx("span", { style: { fontSize: hudType("xs"), fontVariantNumeric: "tabular-nums", color: "rgba(226,232,240,0.9)" }, children: formatDistance(distance) })) : null] }));
 }

package/dist/modals.d.ts

@@ -1,5 +1,6 @@
 import { type CSSProperties, type ReactNode } from "react";
 import { type ModalRecord, type ModalStack } from "@jgengine/core/ui/modalStack";
+import { type HudInteractListener } from "./hudInteract.js";
 /**
  * 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.
@@ -43,6 +44,8 @@ export interface ModalHostProps {
     closeOnEsc?: boolean;
     /** z-index of the host's stacking context — sits above the HUD/windows. Default 80. */
     zIndexBase?: number;
+    /** Called with `open` / `close` as modals show and the stack empties (`cue` is the modal kind) — the UI sound seam. */
+    onInteract?: HudInteractListener;
     className?: string;
     style?: CSSProperties;
 }
@@ -64,7 +67,7 @@ export interface ModalControls {
  *
  * @capability modal-host full-screen modal/dialog host over a modal stack — dimmed backdrop, focus trap, Esc/backdrop-to-cancel, aria-modal dialog
  */
-export declare function ModalHost({ stack, children, showBackdrop, backdrop, closeOnBackdrop, closeOnEsc, zIndexBase, className, style, }: ModalHostProps): ReactNode;
+export declare function ModalHost({ stack, children, showBackdrop, backdrop, closeOnBackdrop, closeOnEsc, zIndexBase, onInteract, className, style, }: ModalHostProps): ReactNode;
 /** Props for {@link ConfirmDialog}. */
 export interface ConfirmDialogProps {
     title: ReactNode;
@@ -85,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 HudFrame}. Presentation-only: wire `onConfirm`/`onCancel` to a
+ * 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.
@@ -121,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 HudFrame}. It ships
+ * 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.