@jgengine/react 0.14.0 → 0.15.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/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;

package/dist/hudTheme.js

@@ -1,15 +1,20 @@
 import {} from "react";
 /** Emits the CSS custom properties for a theme — spread onto any HUD ancestor to re-skin the subtree. */
 export function hudThemeVars(theme) {
-    const { palette, frame, bar, slot } = theme;
+    const { palette, surface, status, font, rarity, frame, bar, slot } = theme;
     return {
         // atomic-bar tokens (same names the bars read — #1033)
         "--jg-health": palette.health,
         "--jg-health-low": palette.healthLow,
+        "--jg-health-deep": palette.healthDeep,
         "--jg-mana": palette.mana,
+        "--jg-mana-deep": palette.manaDeep,
         "--jg-stamina": palette.stamina,
+        "--jg-stamina-deep": palette.staminaDeep,
         "--jg-shield": palette.shield,
+        "--jg-shield-deep": palette.shieldDeep,
         "--jg-xp": palette.xp,
+        "--jg-xp-deep": palette.xpDeep,
         "--jg-soul": palette.soul,
         "--jg-ammo": palette.ammo,
         "--jg-boss": palette.boss,
@@ -21,6 +26,30 @@ export function hudThemeVars(theme) {
         "--jg-bar-text": bar.text,
         // shared chrome tokens
         "--jg-accent": palette.accent,
+        "--jg-accent-deep": palette.accentDeep,
+        "--jg-accent-glow": palette.accentGlow,
+        "--jg-accent-dim": palette.accentDim,
+        "--jg-surface": surface.surface,
+        "--jg-surface-deep": surface.surfaceDeep,
+        "--jg-edge": surface.edge,
+        "--jg-edge-bright": surface.edgeBright,
+        "--jg-text": surface.text,
+        "--jg-text-dim": surface.textDim,
+        "--jg-backdrop": surface.backdrop,
+        "--jg-danger": status.danger,
+        "--jg-warning": status.warning,
+        "--jg-success": status.success,
+        "--jg-hostile": status.hostile,
+        "--jg-friendly": status.friendly,
+        "--jg-neutral": status.neutral,
+        "--jg-font-display": font.display,
+        "--jg-font-numeric": font.numeric,
+        "--jg-font-body": font.body,
+        "--jg-rarity-common": rarity.common,
+        "--jg-rarity-uncommon": rarity.uncommon,
+        "--jg-rarity-rare": rarity.rare,
+        "--jg-rarity-epic": rarity.epic,
+        "--jg-rarity-legendary": rarity.legendary,
         "--jg-frame-bg": frame.bg,
         "--jg-frame-border": frame.border,
         "--jg-frame-radius": frame.radius,
@@ -44,6 +73,43 @@ export const defaultHudTheme = {
         ammo: "#f8b84e",
         boss: "#ef4444",
         accent: "#38bdf8",
+        healthDeep: "#7f1d1f",
+        manaDeep: "#1d4ed8",
+        staminaDeep: "#3f6212",
+        shieldDeep: "#0e7490",
+        xpDeep: "#6b21a8",
+        accentDeep: "#0b5f88",
+        accentGlow: "rgba(56, 189, 248, 0.5)",
+        accentDim: "rgba(56, 189, 248, 0.18)",
+    },
+    surface: {
+        surface: "#141820",
+        surfaceDeep: "#0a0c10",
+        edge: "#2c3340",
+        edgeBright: "#4a5566",
+        text: "#f5f7fa",
+        textDim: "#94a3b8",
+        backdrop: "rgba(4,7,12,0.62)",
+    },
+    status: {
+        danger: "#e5484d",
+        warning: "#f8b84e",
+        success: "#3fa34d",
+        hostile: "#e5484d",
+        friendly: "#38bdf8",
+        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',
+    },
+    rarity: {
+        common: "#b4b2a8",
+        uncommon: "#57c14f",
+        rare: "#4a86d8",
+        epic: "#a04fd0",
+        legendary: "#e0862e",
     },
     frame: {
         bg: "linear-gradient(180deg, rgba(20,24,32,0.86), rgba(10,12,16,0.9))",
@@ -62,15 +128,73 @@ export const defaultHudTheme = {
     slot: { bg: "rgba(12,14,20,0.7)", border: "1px solid rgba(255,255,255,0.12)", radius: "8px" },
     ring: "rgba(140,170,200,0.35)",
 };
-function theme(overrides) {
+/**
+ * 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 function hudTheme(overrides) {
     return {
         palette: { ...defaultHudTheme.palette, ...overrides.palette },
+        surface: { ...defaultHudTheme.surface, ...overrides.surface },
+        status: { ...defaultHudTheme.status, ...overrides.status },
+        font: { ...defaultHudTheme.font, ...overrides.font },
+        rarity: { ...defaultHudTheme.rarity, ...overrides.rarity },
         frame: { ...defaultHudTheme.frame, ...overrides.frame },
         bar: { ...defaultHudTheme.bar, ...overrides.bar },
         slot: { ...defaultHudTheme.slot, ...overrides.slot },
         ring: overrides.ring ?? defaultHudTheme.ring,
     };
 }
+const theme = hudTheme;
+/** Builds a chrome-led preset: the named surface/edge values drive frames, troughs, and slots. */
+function chrome(spec) {
+    return theme({
+        palette: {
+            health: spec.fills.health,
+            healthLow: spec.deeps.health,
+            healthDeep: spec.deeps.health,
+            mana: spec.fills.mana,
+            manaDeep: spec.deeps.mana,
+            stamina: spec.fills.stamina,
+            staminaDeep: spec.deeps.stamina,
+            shield: spec.fills.shield,
+            shieldDeep: spec.deeps.shield,
+            xp: spec.fills.xp,
+            xpDeep: spec.deeps.xp,
+            soul: mix(spec.fills.xp, "#ffffff", 0.25),
+            ammo: spec.status.warning,
+            boss: spec.status.danger,
+            accent: spec.accent,
+            accentDeep: spec.accentDeep,
+            accentGlow: spec.accentGlow,
+            accentDim: alpha(spec.accent, 0.18),
+        },
+        surface: {
+            surface: spec.surface,
+            surfaceDeep: spec.surfaceDeep,
+            edge: spec.edge,
+            edgeBright: spec.edgeBright,
+            text: spec.text,
+            textDim: spec.textDim,
+            backdrop: alpha(spec.surfaceDeep, 0.72),
+        },
+        status: spec.status,
+        font: { display: spec.display },
+        rarity: spec.rarity,
+        frame: {
+            bg: `linear-gradient(180deg, ${alpha(spec.surface, 0.92)}, ${alpha(spec.surfaceDeep, 0.94)})`,
+            border: `1px solid ${spec.edge}`,
+            radius: "6px",
+            glow: `0 6px 20px ${alpha(spec.surfaceDeep, 0.7)}`,
+        },
+        bar: { track: alpha(spec.surfaceDeep, 0.8), frame: spec.surfaceDeep, text: spec.text },
+        slot: { bg: alpha(spec.surface, 0.8), border: `1px solid ${spec.edge}`, radius: "6px" },
+        ring: alpha(spec.edgeBright, 0.55),
+    });
+}
 /** Built-in theme presets for demos/scaffold only — not product identity; games author their own theme. */
 export const HUD_THEME_PRESETS = {
     "arcane-stone": theme({
@@ -145,7 +269,181 @@ export const HUD_THEME_PRESETS = {
         slot: { bg: "#4a4a4a", border: "3px solid #2a2a2a", radius: "0px" },
         ring: "rgba(240,192,64,0.5)",
     }),
+    ember: chrome({
+        accent: "#e3b054",
+        accentGlow: "rgba(227, 176, 84, 0.55)",
+        accentDeep: "#8a6425",
+        surface: "#17120d",
+        surfaceDeep: "#0b0906",
+        edge: "#57452c",
+        edgeBright: "#93794c",
+        text: "#f2e7d0",
+        textDim: "#a3947a",
+        fills: { health: "#5cc35f", mana: "#4a86d8", stamina: "#d9c33f", xp: "#a566d9", shield: "#9fb9c9" },
+        deeps: { health: "#26662c", mana: "#20406f", stamina: "#6e621c", xp: "#4e2c6e", shield: "#48606e" },
+        status: {
+            danger: "#e0483e",
+            warning: "#e8a33d",
+            success: "#6fce6f",
+            hostile: "#d84a3a",
+            friendly: "#4fa9e0",
+            neutral: "#d9d04f",
+        },
+        display: '"Palatino Linotype", Palatino, "Book Antiqua", Georgia, serif',
+        rarity: {
+            common: "#b4b2a8",
+            uncommon: "#57c14f",
+            rare: "#4a86d8",
+            epic: "#a04fd0",
+            legendary: "#e0862e",
+        },
+    }),
+    synthwave: chrome({
+        accent: "#41e6f0",
+        accentGlow: "rgba(65, 230, 240, 0.55)",
+        accentDeep: "#136b74",
+        surface: "#12101f",
+        surfaceDeep: "#080711",
+        edge: "#3c3467",
+        edgeBright: "#6a5daa",
+        text: "#e9ecff",
+        textDim: "#8d8bb3",
+        fills: { health: "#3ee08a", mana: "#5a7bff", stamina: "#f0e341", xp: "#e050d8", shield: "#8ad4f0" },
+        deeps: { health: "#136b44", mana: "#243487", stamina: "#77701a", xp: "#6e2069", shield: "#2f6d85" },
+        status: {
+            danger: "#ff4d6a",
+            warning: "#ffb347",
+            success: "#3ee08a",
+            hostile: "#ff4d6a",
+            friendly: "#41e6f0",
+            neutral: "#f0e341",
+        },
+        display: '"Segoe UI", system-ui, sans-serif',
+        rarity: {
+            common: "#9fa4bd",
+            uncommon: "#3ee08a",
+            rare: "#5a7bff",
+            epic: "#e050d8",
+            legendary: "#ffb347",
+        },
+    }),
+    fieldkit: chrome({
+        accent: "#d8c169",
+        accentGlow: "rgba(216, 193, 105, 0.45)",
+        accentDeep: "#6e6230",
+        surface: "#14160f",
+        surfaceDeep: "#0a0b07",
+        edge: "#454a35",
+        edgeBright: "#6f7657",
+        text: "#e6e8d8",
+        textDim: "#95997f",
+        fills: { health: "#7fb84a", mana: "#57a8b8", stamina: "#c9b73e", xp: "#b88f4a", shield: "#a8b4a0" },
+        deeps: { health: "#3d5c1f", mana: "#265059", stamina: "#645a1c", xp: "#5c451f", shield: "#4e594a" },
+        status: {
+            danger: "#d84f35",
+            warning: "#d8952f",
+            success: "#7fb84a",
+            hostile: "#d84f35",
+            friendly: "#57a8b8",
+            neutral: "#c9b73e",
+        },
+        display: '"Arial Narrow", "Roboto Condensed", "Segoe UI", sans-serif',
+        rarity: {
+            common: "#a8ab99",
+            uncommon: "#7fb84a",
+            rare: "#57a8b8",
+            epic: "#b06fc9",
+            legendary: "#d8952f",
+        },
+    }),
 };
+function hexToRgb(hex) {
+    const raw = hex.replace("#", "");
+    const full = raw.length === 3 ? raw.split("").map((c) => c + c).join("") : raw;
+    return {
+        r: parseInt(full.slice(0, 2), 16),
+        g: parseInt(full.slice(2, 4), 16),
+        b: parseInt(full.slice(4, 6), 16),
+    };
+}
+function rgbToHex({ r, g, b }) {
+    const channel = (v) => Math.round(Math.min(255, Math.max(0, v))).toString(16).padStart(2, "0");
+    return `#${channel(r)}${channel(g)}${channel(b)}`;
+}
+function mix(from, to, amount) {
+    const a = hexToRgb(from);
+    const b = hexToRgb(to);
+    return rgbToHex({
+        r: a.r + (b.r - a.r) * amount,
+        g: a.g + (b.g - a.g) * amount,
+        b: a.b + (b.b - a.b) * amount,
+    });
+}
+function alpha(hex, value) {
+    const { r, g, b } = hexToRgb(hex);
+    return `rgba(${r}, ${g}, ${b}, ${value})`;
+}
+/**
+ * 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 function deriveHudTheme(seed) {
+    const { accent, surface } = seed;
+    const text = seed.text ?? mix("#f4f4f0", accent, 0.12);
+    const health = seed.health ?? "#e0483e";
+    const mana = seed.mana ?? "#4a86d8";
+    const stamina = seed.stamina ?? "#d9c33f";
+    const xp = seed.xp ?? "#a566d9";
+    const shield = seed.shield ?? "#9fb9c9";
+    const danger = seed.danger ?? "#e0483e";
+    const surfaceDeep = mix(surface, "#000000", 0.5);
+    const edge = mix(surface, accent, 0.22);
+    const edgeBright = mix(surface, accent, 0.42);
+    return hudTheme({
+        palette: {
+            health,
+            healthLow: mix(health, "#000000", 0.3),
+            healthDeep: mix(health, "#000000", 0.5),
+            mana,
+            manaDeep: mix(mana, "#000000", 0.5),
+            stamina,
+            staminaDeep: mix(stamina, "#000000", 0.5),
+            shield,
+            shieldDeep: mix(shield, "#000000", 0.5),
+            xp,
+            xpDeep: mix(xp, "#000000", 0.5),
+            soul: mix(xp, "#ffffff", 0.25),
+            ammo: seed.warning ?? "#e8a33d",
+            boss: danger,
+            accent,
+            accentDeep: mix(accent, "#000000", 0.55),
+            accentGlow: alpha(accent, 0.5),
+            accentDim: alpha(accent, 0.18),
+        },
+        surface: { surface, surfaceDeep, edge, edgeBright, text, textDim: mix(text, surface, 0.42), backdrop: alpha(surfaceDeep, 0.72) },
+        status: {
+            danger,
+            warning: seed.warning ?? "#e8a33d",
+            success: accent,
+            hostile: danger,
+            friendly: seed.friendly ?? mana,
+            neutral: stamina,
+        },
+        font: { display: seed.fontDisplay ?? defaultHudTheme.font.display },
+        frame: {
+            bg: `linear-gradient(180deg, ${alpha(surface, 0.92)}, ${alpha(surfaceDeep, 0.94)})`,
+            border: `1px solid ${edge}`,
+            glow: `0 6px 20px ${alpha(surfaceDeep, 0.7)}`,
+        },
+        bar: { track: alpha(surfaceDeep, 0.8), frame: surfaceDeep, text },
+        slot: { bg: alpha(surface, 0.8), border: `1px solid ${edge}`, radius: "6px" },
+        ring: alpha(edgeBright, 0.55),
+    });
+}
 /** Resolves a preset name (or a full theme) to a `HudTheme`; falls back to the default theme. */
 export function resolveHudTheme(theme) {
     if (theme === undefined)