@jgengine/react 0.13.0 → 0.15.0-next.0

package/dist/gameViewport.js

@@ -219,18 +219,14 @@ export function GameViewportProvider({ platforms, className, style, children, })
     }, [regions, metrics.layout, visual, vw, vh, coarsePointer, mobileSupported, safeArea]);
     const collisions = useMemo(() => detectLayoutCollisions(regions), [regions]);
     const forbidden = useMemo(() => collisions.filter((c) => c.severity === "forbid"), [collisions]);
-    useEffect(() => {
-        const root = rootRef.current;
-        if (root === null)
-            return;
-        if (forbidden.length === 0) {
-            root.removeAttribute("data-jg-layout-collision");
-            return;
+    const collisionReport = forbidden.length === 0 ? undefined : JSON.stringify(forbidden);
+    const lastWarnedRef = useRef(undefined);
+    if (collisionReport !== lastWarnedRef.current) {
+        lastWarnedRef.current = collisionReport;
+        if (collisionReport !== undefined) {
+            console.warn(`[jgengine] ${formatLayoutCollisions(forbidden)}\n  mode=${layout.mode} viewport=${Math.round(vw)}x${Math.round(vh)} safe=${safeArea.top}/${safeArea.right}/${safeArea.bottom}/${safeArea.left}`);
         }
-        const report = JSON.stringify(forbidden);
-        root.setAttribute("data-jg-layout-collision", report);
-        console.warn(`[jgengine] ${formatLayoutCollisions(forbidden)}\n  mode=${layout.mode} viewport=${Math.round(vw)}x${Math.round(vh)} safe=${safeArea.top}/${safeArea.right}/${safeArea.bottom}/${safeArea.left}`);
-    }, [forbidden, layout.mode, vw, vh, safeArea]);
+    }
     useEffect(() => {
         const ids = new Set();
         for (const collision of forbidden) {
@@ -265,7 +261,7 @@ export function GameViewportProvider({ platforms, className, style, children, })
         "--jg-safe-left": `${safeArea.left}px`,
         ...style,
     };
-    return (_jsx(RegionRegistryContext.Provider, { value: registry, children: _jsx(GameLayoutContext.Provider, { value: layout, children: _jsxs("div", { ref: rootRef, "data-jg-viewport": "", "data-jg-layout-mode": layout.mode, "data-jg-orientation": layout.orientation, className: className, style: rootStyle, children: [_jsx("div", { ref: probeRef, "aria-hidden": true, style: SAFE_AREA_PROBE_STYLE }), children] }) }) }));
+    return (_jsx(RegionRegistryContext.Provider, { value: registry, children: _jsx(GameLayoutContext.Provider, { value: layout, children: _jsxs("div", { ref: rootRef, "data-jg-viewport": "", "data-jg-layout-mode": layout.mode, "data-jg-orientation": layout.orientation, "data-jg-layout-collision": collisionReport, className: className, style: rootStyle, children: [_jsx("div", { ref: probeRef, "aria-hidden": true, style: SAFE_AREA_PROBE_STYLE }), children] }) }) }));
 }
 /** The live shared viewport layout. Returns a neutral default outside a `GameViewportProvider` so it never throws in previews. */
 export function useGameViewportLayout() {

package/dist/hooks.d.ts

@@ -175,4 +175,46 @@ export interface UseAxisChannelResult {
  * constant at the call site) unless a rebind is intended.
  */
 export declare function useAxisChannel(config: AxisChannelConfig): UseAxisChannelResult;
+/**
+ * Re-render at a steady rate. Returns a monotonically increasing tick count driven by a
+ * setInterval, for HUD elements that display wall-clock-derived values (cooldowns, cast bars,
+ * swing timers) without an engine subscription to hang off. `hz <= 0` disables the ticker.
+ *
+ * @capability hud-ticker re-render a HUD element at a steady hz for time-derived readouts (cooldowns, cast/swing bars) — no hand-rolled setInterval effects
+ */
+export declare function useTicker(hz?: number): number;
+/** Minimal add/removeEventListener surface accepted by useDomEvent (window, document, elements). */
+export interface DomEventTarget {
+    addEventListener(type: string, listener: (event: never) => void, options?: unknown): void;
+    removeEventListener(type: string, listener: (event: never) => void, options?: unknown): void;
+}
+/**
+ * Attach a DOM event listener with automatic cleanup. `resolveTarget` runs inside the effect, so
+ * `() => window` and ref-reading resolvers are SSR-safe; return null to skip attaching. The
+ * handler is kept in a ref, so a fresh closure per render never re-binds the listener.
+ * Re-binds only when `type` or `options.capture`/`options.passive` change.
+ *
+ * @capability dom-event attach a window/document/element event listener with automatic cleanup and a stable handler ref — no hand-rolled addEventListener effects
+ */
+export declare function useDomEvent<E>(resolveTarget: () => DomEventTarget | null, type: string, handler: (event: E) => void, options?: {
+    capture?: boolean;
+    passive?: boolean;
+}): void;
+/**
+ * Run a requestAnimationFrame loop while `active`, calling `onFrame(deltaSeconds)` each frame.
+ * The callback is kept in a ref so re-renders never restart the loop; cleanup cancels the
+ * pending frame. For scene-graph work inside a canvas prefer R3F's useFrame — this is for
+ * DOM-side animation outside the renderer.
+ *
+ * @capability raf-loop run a cancellable requestAnimationFrame loop for DOM-side animation with delta seconds — no hand-rolled RAF effects
+ */
+export declare function useRafLoop(onFrame: (deltaSeconds: number) => void, active?: boolean): void;
+/**
+ * Pin a scrollable element to its bottom whenever `dep` changes (typically a length or the list
+ * itself). Attach the returned ref to the scroll container. Owns the log/chat/console
+ * scroll-to-bottom effect so panels don't hand-roll it.
+ *
+ * @capability auto-scroll pin a log/chat/console panel to its newest line as entries arrive — no hand-rolled scrollTop effects
+ */
+export declare function useAutoScroll<T extends HTMLElement>(dep: unknown): import("react").RefObject<T | null>;
 export {};

package/dist/hooks.js

@@ -375,3 +375,88 @@ export function useAxisChannel(config) {
     const channel = useMemo(() => new AxisChannel(config), [config]);
     return { channel, isDown };
 }
+/**
+ * Re-render at a steady rate. Returns a monotonically increasing tick count driven by a
+ * setInterval, for HUD elements that display wall-clock-derived values (cooldowns, cast bars,
+ * swing timers) without an engine subscription to hang off. `hz <= 0` disables the ticker.
+ *
+ * @capability hud-ticker re-render a HUD element at a steady hz for time-derived readouts (cooldowns, cast/swing bars) — no hand-rolled setInterval effects
+ */
+export function useTicker(hz = 10) {
+    const [tick, setTick] = useState(0);
+    useEffect(() => {
+        if (!Number.isFinite(hz) || hz <= 0)
+            return undefined;
+        const timer = setInterval(() => setTick((value) => value + 1), 1000 / hz);
+        return () => clearInterval(timer);
+    }, [hz]);
+    return tick;
+}
+/**
+ * Attach a DOM event listener with automatic cleanup. `resolveTarget` runs inside the effect, so
+ * `() => window` and ref-reading resolvers are SSR-safe; return null to skip attaching. The
+ * handler is kept in a ref, so a fresh closure per render never re-binds the listener.
+ * Re-binds only when `type` or `options.capture`/`options.passive` change.
+ *
+ * @capability dom-event attach a window/document/element event listener with automatic cleanup and a stable handler ref — no hand-rolled addEventListener effects
+ */
+export function useDomEvent(resolveTarget, type, handler, options) {
+    const handlerRef = useRef(handler);
+    handlerRef.current = handler;
+    const capture = options?.capture ?? false;
+    const passive = options?.passive;
+    useEffect(() => {
+        const target = resolveTarget();
+        if (target === null)
+            return undefined;
+        const listener = (event) => handlerRef.current(event);
+        const listenerOptions = passive === undefined ? { capture } : { capture, passive };
+        target.addEventListener(type, listener, listenerOptions);
+        return () => target.removeEventListener(type, listener, listenerOptions);
+        // resolveTarget is intentionally excluded: it is expected to be an inline closure over a
+        // stable target (window, document, a ref) and re-running on its identity would re-bind
+        // every render.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [type, capture, passive]);
+}
+/**
+ * Run a requestAnimationFrame loop while `active`, calling `onFrame(deltaSeconds)` each frame.
+ * The callback is kept in a ref so re-renders never restart the loop; cleanup cancels the
+ * pending frame. For scene-graph work inside a canvas prefer R3F's useFrame — this is for
+ * DOM-side animation outside the renderer.
+ *
+ * @capability raf-loop run a cancellable requestAnimationFrame loop for DOM-side animation with delta seconds — no hand-rolled RAF effects
+ */
+export function useRafLoop(onFrame, active = true) {
+    const frameRef = useRef(onFrame);
+    frameRef.current = onFrame;
+    useEffect(() => {
+        if (!active || typeof requestAnimationFrame !== "function")
+            return undefined;
+        let handle = 0;
+        let last = performance.now();
+        const step = (now) => {
+            frameRef.current(Math.max(0, now - last) / 1000);
+            last = now;
+            handle = requestAnimationFrame(step);
+        };
+        handle = requestAnimationFrame(step);
+        return () => cancelAnimationFrame(handle);
+    }, [active]);
+}
+/**
+ * Pin a scrollable element to its bottom whenever `dep` changes (typically a length or the list
+ * itself). Attach the returned ref to the scroll container. Owns the log/chat/console
+ * scroll-to-bottom effect so panels don't hand-roll it.
+ *
+ * @capability auto-scroll pin a log/chat/console panel to its newest line as entries arrive — no hand-rolled scrollTop effects
+ */
+export function useAutoScroll(dep) {
+    const ref = useRef(null);
+    useEffect(() => {
+        const node = ref.current;
+        if (node !== null)
+            node.scrollTop = node.scrollHeight;
+    }, [dep]);
+    return ref;
+}

package/dist/hudLayout.js

@@ -22,6 +22,91 @@ const EDIT_BAR_Z = 100000;
 const REGION_GAP = 10;
 const COMPACT_HUD_SCALE = 0.85;
 const HUD_ANCHORS = Object.keys(HUD_ANCHOR_FRACTIONS);
+/**
+ * Attribute a game puts on any HUD surface it *wants* to bleed past the viewport
+ * (a full-bleed backdrop, a deliberately clipped ticker), so the boundary check
+ * skips it. Opt-out, on purpose: the default is that shown UI must fit on screen.
+ */
+const ALLOW_OVERFLOW_ATTR = "data-hud-allow-overflow";
+/** Opt-in marker for a custom window mounted deeper than a direct HudCanvas child. */
+const WINDOW_ATTR = "data-hud-window";
+/**
+ * Dev-only, prod-safe. The on-screen boundary overlay must never reach players,
+ * so anything we cannot positively identify as a dev build resolves to `false`.
+ */
+function isDevBuild() {
+    try {
+        const meta = import.meta;
+        if (meta.env?.DEV === true)
+            return true;
+        if (meta.env?.PROD === true)
+            return false;
+    }
+    catch {
+        /* import.meta.env unavailable under this bundler */
+    }
+    const nodeEnv = globalThis.process
+        ?.env?.NODE_ENV;
+    if (typeof nodeEnv === "string")
+        return nodeEnv !== "production";
+    return false;
+}
+/** True unless the element (or an ancestor) is hidden, collapsed, or removed from the a11y tree. */
+function isSurfaceShown(el) {
+    if (el.closest('[aria-hidden="true"]') !== null)
+        return false;
+    const checkable = el;
+    if (typeof checkable.checkVisibility === "function") {
+        return checkable.checkVisibility({
+            contentVisibilityAuto: true,
+            opacityProperty: true,
+            visibilityProperty: true,
+        });
+    }
+    if (typeof getComputedStyle !== "function")
+        return true;
+    const style = getComputedStyle(el);
+    return style.visibility !== "hidden" && style.display !== "none" && Number(style.opacity) > 0.01;
+}
+function surfaceId(el) {
+    return (el.getAttribute("data-hud-panel") ??
+        el.getAttribute(WINDOW_ATTR) ??
+        el.getAttribute("data-hud-id") ??
+        el.getAttribute("aria-label") ??
+        (el.id.length > 0 ? el.id : null) ??
+        "<ui>");
+}
+/**
+ * Every HUD surface whose bounds we hold to the viewport: registered panels,
+ * any element tagged as a window, and the game's own direct children of the
+ * canvas (custom modals dropped straight into the HUD layer). Opted-out and
+ * hidden surfaces are dropped here so a closed drawer never reaches the check.
+ */
+function collectBoundarySurfaces(canvas) {
+    const seen = new Set();
+    const out = [];
+    const consider = (el) => {
+        if (seen.has(el))
+            return;
+        seen.add(el);
+        if (el.closest(`[${ALLOW_OVERFLOW_ATTR}]`) !== null)
+            return;
+        if (!isSurfaceShown(el))
+            return;
+        out.push({ id: surfaceId(el), el });
+    };
+    for (const el of canvas.querySelectorAll(`[data-hud-panel],[${WINDOW_ATTR}]`))
+        consider(el);
+    for (const el of Array.from(canvas.children)) {
+        if (el.hasAttribute("data-hud-region") ||
+            el.hasAttribute("data-hud-edit-bar") ||
+            el.hasAttribute("data-hud-overflow-overlay")) {
+            continue;
+        }
+        consider(el);
+    }
+    return out;
+}
 function sizeStyle(panel) {
     if (panel === undefined)
         return {};
@@ -200,6 +285,7 @@ export function HudCanvas({ layout, editChord, compactScale, showDuring, classNa
     const fitEnabled = hudViewport?.fitEnabled === true;
     const [viewport, setViewport] = useState(null);
     const [regions, setRegions] = useState({});
+    const [offenders, setOffenders] = useState([]);
     const regionRefs = useMemo(() => {
         const refs = {};
         for (const anchor of HUD_ANCHORS) {
@@ -285,18 +371,20 @@ export function HudCanvas({ layout, editChord, compactScale, showDuring, classNa
             return;
         let frame = 0;
         let lastReport = "";
+        const dev = isDevBuild();
         const check = () => {
             frame = 0;
             const hostRect = host.getBoundingClientRect();
             if (hostRect.width <= 0 || hostRect.height <= 0)
                 return;
-            const panels = [];
-            for (const el of canvas.querySelectorAll("[data-hud-panel]")) {
-                const rect = el.getBoundingClientRect();
+            const viewportSize = { width: hostRect.width, height: hostRect.height };
+            const surfaces = [];
+            for (const surface of collectBoundarySurfaces(canvas)) {
+                const rect = surface.el.getBoundingClientRect();
                 if (rect.width === 0 && rect.height === 0)
                     continue;
-                panels.push({
-                    id: el.getAttribute("data-hud-panel") ?? "?",
+                surfaces.push({
+                    id: surface.id,
                     rect: {
                         x: rect.left - hostRect.left,
                         y: rect.top - hostRect.top,
@@ -305,8 +393,10 @@ export function HudCanvas({ layout, editChord, compactScale, showDuring, classNa
                     },
                 });
             }
-            const offenders = overflowingPanels(panels, { width: hostRect.width, height: hostRect.height });
-            const report = offenders.length === 0 ? "" : JSON.stringify(offenders);
+            // overflowingPanels reports only surfaces that are partly on screen *and*
+            // cross an edge — a closed/parked/off-screen menu is never an offender.
+            const escaped = overflowingPanels(surfaces, viewportSize);
+            const report = escaped.length === 0 ? "" : JSON.stringify(escaped);
             if (report === lastReport)
                 return;
             lastReport = report;
@@ -315,7 +405,13 @@ export function HudCanvas({ layout, editChord, compactScale, showDuring, classNa
             }
             else {
                 canvas.setAttribute("data-hud-overflow", report);
-                console.warn(`[jgengine] HUD panels overflow the ${Math.round(hostRect.width)}x${Math.round(hostRect.height)} viewport: ${report}`);
+                console.warn(`[jgengine] HUD UI escapes the ${Math.round(hostRect.width)}x${Math.round(hostRect.height)} viewport: ${report}`);
+            }
+            if (dev) {
+                setOffenders(escaped.map((overflow) => {
+                    const rect = surfaces.find((s) => s.id === overflow.id)?.rect;
+                    return { ...overflow, x: rect?.x ?? 0, y: rect?.y ?? 0, width: rect?.width ?? 0, height: rect?.height ?? 0 };
+                }));
             }
         };
         const schedule = () => {
@@ -365,7 +461,40 @@ export function HudCanvas({ layout, editChord, compactScale, showDuring, classNa
                         pointerEvents: "none",
                         zIndex: 1,
                         ...REGION_LAYOUT[anchor],
-                    } }, anchor))), children, editing ? _jsx(HudEditBar, { layout: layout }) : null] }) }));
+                    } }, anchor))), children, offenders.length > 0 ? (_jsx("div", { "data-hud-overflow-overlay": "", style: { position: "absolute", inset: 0, pointerEvents: "none", zIndex: EDIT_BAR_Z - 1 }, children: offenders.map((o) => (_jsx("div", { style: {
+                            position: "absolute",
+                            left: o.x / scale,
+                            top: o.y / scale,
+                            width: o.width / scale,
+                            height: o.height / scale,
+                            border: "2px solid rgba(255, 64, 64, 0.95)",
+                            boxShadow: "0 0 0 2px rgba(255, 64, 64, 0.3)",
+                            boxSizing: "border-box",
+                        }, children: _jsxs("span", { style: {
+                                position: "absolute",
+                                left: 0,
+                                bottom: "100%",
+                                marginBottom: 2,
+                                padding: "2px 6px",
+                                borderRadius: 4,
+                                background: "rgba(180, 20, 20, 0.95)",
+                                color: "#fff",
+                                font: "600 10px/1.4 system-ui, sans-serif",
+                                whiteSpace: "nowrap",
+                            }, children: ["\u26A0 ", o.id, " escapes viewport (", overflowEdges(o), ")"] }) }, o.id))) })) : null, editing ? _jsx(HudEditBar, { layout: layout }) : null] }) }));
+}
+/** Human-readable edge list for the dev boundary badge, e.g. `right +260 · bottom +56`. */
+function overflowEdges(overflow) {
+    const parts = [];
+    if (overflow.left > 0)
+        parts.push(`left +${overflow.left}`);
+    if (overflow.top > 0)
+        parts.push(`top +${overflow.top}`);
+    if (overflow.right > 0)
+        parts.push(`right +${overflow.right}`);
+    if (overflow.bottom > 0)
+        parts.push(`bottom +${overflow.bottom}`);
+    return parts.length > 0 ? parts.join(" · ") : "edge";
 }
 function chipAlignment(anchor) {
     if (anchor.endsWith("right"))

package/dist/hudTheme.d.ts

@@ -1,27 +1,73 @@
 import { type CSSProperties } from "react";
 /**
- * `HudTheme` (#1034): one token object that restyles shared token-driven building blocks at once.
- * It is the superset of the atomic-bar tokens (#1033) — `hudThemeVars(theme)` emits the same
- * `--jg-*` custom properties the bars already read, plus frame / slot / minimap-ring tokens — so
- * setting a **game-authored** theme on any HUD ancestor re-skins those primitives. Purely CSS-token
+ * `HudTheme` (#1034, #1573): one token object that restyles every shared token-driven building
+ * block at once — the atomic bars (#1033), frames, slots, the minimap ring, and the chrome the
+ * registry blocks read (surfaces, edges, text, status colors, fonts, rarity). `hudThemeVars(theme)`
+ * emits the whole `--jg-*` vocabulary, so setting a **game-authored** theme on any HUD ancestor
+ * re-skins `packages/react` primitives and `registry/jgengine` components together. Purely CSS-token
  * driven (no image assets). Tokens are not a finished UI: every game still owns composition, skin,
  * and art direction (see AGENTS.md). Built-in presets are demo/scaffold starting points only.
  *
- * @capability hud-theme game-authored token object for bars, frames, slots, and minimap ring
+ * @capability hud-theme game-authored token object covering bars, frames, slots, chrome, text, status colors, fonts, and rarity
  */
-/** Per-readout fill colors plus a shared accent/glow. */
+/** Per-readout fill colors plus a shared accent/glow. Each `*Deep` is the shaded companion fill. */
 export interface HudThemePalette {
     health: string;
     healthLow: string;
+    healthDeep: string;
     mana: string;
+    manaDeep: string;
     stamina: string;
+    staminaDeep: string;
     shield: string;
+    shieldDeep: string;
     xp: string;
+    xpDeep: string;
     soul: string;
     ammo: string;
     boss: string;
     /** Accent used for glow/keycap/active states. */
     accent: string;
+    /** Shaded accent for gradients and pressed states. */
+    accentDeep: string;
+    /** Translucent accent for outer glows. */
+    accentGlow: string;
+    /** Soft accent wash for large background gradients. */
+    accentDim: string;
+}
+/** Chrome surfaces, edges, and text — what panels, overlays, and menus are built out of. */
+export interface HudThemeSurface {
+    surface: string;
+    surfaceDeep: string;
+    edge: string;
+    edgeBright: string;
+    text: string;
+    textDim: string;
+    /** Full-screen dim behind modals and overlays. */
+    backdrop: string;
+}
+/** Semantic status colors — outcome, threat, and relationship coloring. */
+export interface HudThemeStatus {
+    danger: string;
+    warning: string;
+    success: string;
+    hostile: string;
+    friendly: string;
+    neutral: string;
+}
+/** Typography roles. Any CSS `font-family` list. */
+export interface HudThemeFont {
+    display: string;
+    numeric: string;
+    body: string;
+}
+/** Item-rarity coloring shared by loot cards, tooltips, and inventory slots. */
+export interface HudThemeRarity {
+    common: string;
+    uncommon: string;
+    rare: string;
+    epic: string;
+    legendary: string;
 }
 /** Frame material + shape tokens (panels, `HudFrame variation="themed"`). */
 export interface HudThemeFrame {
@@ -48,9 +94,13 @@ export interface HudThemeSlot {
     border: string;
     radius: string;
 }
-/** A full HUD theme. */
+/** A full HUD theme. Author one with {@link hudTheme} or {@link deriveHudTheme}. */
 export interface HudTheme {
     palette: HudThemePalette;
+    surface: HudThemeSurface;
+    status: HudThemeStatus;
+    font: HudThemeFont;
+    rarity: HudThemeRarity;
     frame: HudThemeFrame;
     bar: HudThemeBar;
     slot: HudThemeSlot;
@@ -61,6 +111,26 @@ export interface HudTheme {
 export declare function hudThemeVars(theme: HudTheme): CSSProperties;
 /** Default theme tokens for previews/scaffold — not a finished game look; author a custom theme. */
 export declare const defaultHudTheme: HudTheme;
+/** Per-group partial overrides accepted by {@link hudTheme}. */
+export interface HudThemeOverrides {
+    palette?: Partial<HudThemePalette>;
+    surface?: Partial<HudThemeSurface>;
+    status?: Partial<HudThemeStatus>;
+    font?: Partial<HudThemeFont>;
+    rarity?: Partial<HudThemeRarity>;
+    frame?: Partial<HudThemeFrame>;
+    bar?: Partial<HudThemeBar>;
+    slot?: Partial<HudThemeSlot>;
+    ring?: string;
+}
+/**
+ * Builds a full {@link HudTheme} from per-group partials, filling the rest from
+ * {@link defaultHudTheme}. Reach for this when a game wants to name exact values; use
+ * {@link deriveHudTheme} when a seed color pair is enough.
+ *
+ * @capability hud-theme-author fill a full HudTheme from per-group partial overrides
+ */
+export declare function hudTheme(overrides: HudThemeOverrides): HudTheme;
 /** Built-in theme presets for demos/scaffold only — not product identity; games author their own theme. */
 export declare const HUD_THEME_PRESETS: {
     "arcane-stone": HudTheme;
@@ -69,8 +139,35 @@ export declare const HUD_THEME_PRESETS: {
     "sleek-hex": HudTheme;
     "elemental-circle": HudTheme;
     "sandbox-slot": HudTheme;
+    ember: HudTheme;
+    synthwave: HudTheme;
+    fieldkit: HudTheme;
 };
 /** Built-in demo/scaffold theme preset name — not a game identity. */
 export type HudThemePreset = keyof typeof HUD_THEME_PRESETS;
+/** Seed colors for {@link deriveHudTheme}. Only `accent` and `surface` are required. */
+export interface HudThemeSeed {
+    accent: string;
+    surface: string;
+    text?: string;
+    health?: string;
+    mana?: string;
+    stamina?: string;
+    xp?: string;
+    shield?: string;
+    danger?: string;
+    warning?: string;
+    friendly?: string;
+    fontDisplay?: string;
+}
+/**
+ * Derives a coherent full theme from an accent/surface pair — shades, edges, dim text, frames,
+ * bar troughs, and slots all fall out of the seed, so a game gets one consistent look across the
+ * `packages/react` primitives and the `registry/jgengine` blocks without naming 50 tokens.
+ * Hex seeds only (`#rgb` or `#rrggbb`).
+ *
+ * @capability hud-theme-derive build a full HudTheme from an accent + surface seed pair
+ */
+export declare function deriveHudTheme(seed: HudThemeSeed): HudTheme;
 /** Resolves a preset name (or a full theme) to a `HudTheme`; falls back to the default theme. */
 export declare function resolveHudTheme(theme?: HudThemePreset | HudTheme): HudTheme;