@jgengine/react 0.22.0 → 0.24.0

package/dist/engineStyles.js

@@ -0,0 +1,119 @@
+import { useInsertionEffect } from "react";
+import { HUD_FONT_STACK } from "./hudTokens.js";
+const ms = (speed, fallback) => `calc(var(--jg-motion-${speed}, ${fallback}ms) * var(--jg-motion-scale, 1))`;
+const FAST = ms("fast", 120);
+const BASE = ms("base", 180);
+const SLOW = ms("slow", 320);
+const EASE = "var(--jg-ease, cubic-bezier(0.2, 0, 0, 1))";
+const EASE_OUT = "var(--jg-ease-out, cubic-bezier(0.16, 1, 0.3, 1))";
+const SPRING = "var(--jg-ease-spring, cubic-bezier(0.34, 1.56, 0.64, 1))";
+const HIGHLIGHT = "var(--jg-highlight, inset 0 1px 0 rgba(255,255,255,0.08))";
+const RAISED = "var(--jg-elevation-raised, 0 1px 2px rgba(0,0,0,0.45), 0 4px 12px -2px rgba(0,0,0,0.4))";
+const OVERLAY = "var(--jg-elevation-overlay, 0 2px 4px rgba(0,0,0,0.4), 0 10px 24px -4px rgba(0,0,0,0.5))";
+const MODAL = "var(--jg-elevation-modal, 0 4px 8px rgba(0,0,0,0.35), 0 24px 56px -12px rgba(0,0,0,0.7))";
+const FOCUS = "var(--jg-focus-ring, 0 0 0 2px #0a0c10, 0 0 0 4px var(--jg-accent, #38bdf8))";
+const ENABLED = ':not(:disabled, [aria-disabled="true"])';
+const KILL_MOTION = "animation-duration: 1ms !important; animation-delay: 0ms !important; animation-iteration-count: 1 !important; transition-duration: 1ms !important; transition-delay: 0ms !important;";
+/**
+ * The engine stylesheet: every `jg-*` keyframe the shared blocks and registry components animate
+ * with, the `[data-jg-*]` interaction-state rules behind {@link HudButton} / {@link HudPanel}, the
+ * quiet hover/press/focus defaults for plain buttons inside the HUD root, and reduced-motion
+ * handling (`prefers-reduced-motion` or `[data-reduced-motion="true"]` zero `--jg-motion-scale`).
+ * Generic HUD rules sit in `:where()` so any game selector wins. The shell injects it; games that
+ * mount outside the shell import `@jgengine/react/styles.css`, which holds the same text.
+ */
+export const ENGINE_STYLESHEET = `/* @jgengine/react engine stylesheet */
+:root { --jg-motion-scale: 1; }
+@media (prefers-reduced-motion: reduce) { :root { --jg-motion-scale: 0; } }
+[data-reduced-motion="true"] { --jg-motion-scale: 0; }
+@media (prefers-reduced-motion: reduce) {
+  [data-jg-hud] *, [data-jg-hud] *::before, [data-jg-hud] *::after { ${KILL_MOTION} }
+}
+[data-reduced-motion="true"] *, [data-reduced-motion="true"] *::before, [data-reduced-motion="true"] *::after { ${KILL_MOTION} }
+
+@keyframes jg-fade-in { from { opacity: 0; } to { opacity: 1; } }
+@keyframes jg-fade-out { from { opacity: 1; } to { opacity: 0; } }
+@keyframes jg-panel-in { from { opacity: 0; transform: translateY(6px) scale(0.98); } to { opacity: 1; transform: none; } }
+@keyframes jg-panel-out { from { opacity: 1; transform: none; } to { opacity: 0; transform: translateY(4px) scale(0.98); } }
+@keyframes jg-slide-up { from { transform: translateY(14px); opacity: 0; } to { transform: translateY(0); opacity: 1; } }
+@keyframes jg-slide-down { from { transform: translateY(-18px); opacity: 0; } to { transform: translateY(0); opacity: 1; } }
+@keyframes jg-pop { 0% { transform: scale(0.4); opacity: 0; } 60% { transform: scale(1.18); opacity: 1; } 100% { transform: scale(1); opacity: 1; } }
+@keyframes jg-flash { 0% { opacity: 0.9; } 100% { opacity: 0; } }
+@keyframes jg-sheen { from { background-position: -160px 0; } to { background-position: 260px 0; } }
+@keyframes jg-pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.55; } }
+@keyframes jg-ready-glow { 0%, 100% { filter: brightness(1); } 50% { filter: brightness(1.45); } }
+@keyframes jg-shake { 0%, 100% { transform: translateX(0); } 20% { transform: translateX(-3px); } 40% { transform: translateX(3px); } 60% { transform: translateX(-2px); } 80% { transform: translateX(2px); } }
+@keyframes jg-float-up { from { transform: translateY(0); opacity: 1; } to { transform: translateY(-46px); opacity: 0; } }
+@keyframes jg-spin { from { transform: rotate(0deg); } to { transform: rotate(360deg); } }
+@keyframes jg-delta-up { 0% { color: var(--jg-success, #3fa34d); text-shadow: 0 0 10px var(--jg-success, #3fa34d); scale: 1.12; } 100% { scale: 1; } }
+@keyframes jg-delta-down { 0% { color: var(--jg-danger, #e5484d); text-shadow: 0 0 10px var(--jg-danger, #e5484d); scale: 0.94; } 100% { scale: 1; } }
+
+[data-jg-hud] { font-family: var(--jg-font-body, ${HUD_FONT_STACK}); -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; text-rendering: optimizeLegibility; }
+:where([data-jg-hud]) :where(button, [role="button"], a[href], summary, [data-jg-interactive]):focus-visible { outline: 2px solid var(--jg-accent, #38bdf8); outline-offset: 2px; }
+:where([data-jg-hud]) :where(button, [role="button"]) { transition: scale ${FAST} ${EASE}, filter ${FAST} ${EASE}; }
+@media (hover: hover) {
+  :where([data-jg-hud]) :where(button, [role="button"]):where(${ENABLED}):hover { filter: brightness(1.08); }
+}
+:where([data-jg-hud]) :where(button, [role="button"]):where(${ENABLED}):active { scale: var(--jg-press-scale, 0.97); }
+
+[data-jg-button] { appearance: none; box-sizing: border-box; position: relative; isolation: isolate; display: inline-flex; align-items: center; justify-content: center; gap: var(--jg-space-sm, 8px); min-height: 36px; padding: 0 var(--jg-space-lg, 16px); margin: 0; font-family: var(--jg-font-body, ${HUD_FONT_STACK}); font-size: var(--jg-type-md, 14px); font-weight: 600; line-height: 1; letter-spacing: 0.01em; white-space: nowrap; color: var(--jg-text, #f5f7fa); background: linear-gradient(180deg, rgba(255,255,255,0.10), rgba(255,255,255,0.03)), var(--jg-slot-bg, rgba(12,15,21,0.78)); border: var(--jg-slot-border, 1px solid rgba(255,255,255,0.13)); border-radius: var(--jg-slot-radius, 8px); box-shadow: ${HIGHLIGHT}, ${RAISED}; cursor: pointer; user-select: none; -webkit-tap-highlight-color: transparent; transition: translate ${FAST} ${EASE}, scale ${FAST} ${SPRING}, box-shadow ${FAST} ${EASE}, border-color ${FAST} ${EASE}, background-color ${FAST} ${EASE}; }
+[data-jg-button]::after { content: ""; position: absolute; inset: 0; z-index: -1; border-radius: inherit; background: var(--jg-hover-overlay, rgba(255,255,255,0.07)); opacity: 0; pointer-events: none; transition: opacity ${FAST} ${EASE}; }
+@media (hover: hover) {
+  [data-jg-button]${ENABLED}:hover { translate: 0 var(--jg-hover-lift, -1px); box-shadow: ${HIGHLIGHT}, ${OVERLAY}; }
+  [data-jg-button]${ENABLED}:hover::after { opacity: 1; }
+}
+[data-jg-button]${ENABLED}:active { translate: 0 0; scale: var(--jg-press-scale, 0.97); box-shadow: ${HIGHLIGHT}, ${RAISED}; transition-duration: calc(60ms * var(--jg-motion-scale, 1)); }
+[data-jg-button]${ENABLED}:active::after { opacity: 1; background: var(--jg-press-overlay, rgba(0,0,0,0.14)); }
+[data-jg-button]:focus-visible { outline: none; box-shadow: ${FOCUS}, ${RAISED}; }
+[data-jg-button]:is(:disabled, [aria-disabled="true"]) { opacity: var(--jg-disabled-opacity, 0.45); cursor: not-allowed; box-shadow: none; }
+[data-jg-button][data-variant="primary"] { color: var(--jg-surface-deep, #0a0c10); background: linear-gradient(180deg, rgba(255,255,255,0.22), rgba(255,255,255,0) 60%), var(--jg-accent, #38bdf8); border: 1px solid rgba(255,255,255,0.28); }
+[data-jg-button][data-variant="danger"] { color: #fff; background: linear-gradient(180deg, rgba(255,255,255,0.16), rgba(255,255,255,0) 60%), var(--jg-danger, #e5484d); border: 1px solid rgba(255,255,255,0.22); }
+[data-jg-button][data-variant="ghost"] { background: transparent; border-color: transparent; box-shadow: none; }
+[data-jg-button][data-variant="ghost"]${ENABLED}:hover { box-shadow: none; }
+[data-jg-button][data-size="sm"] { min-height: 28px; padding: 0 var(--jg-space-md, 12px); font-size: var(--jg-type-sm, 13px); }
+[data-jg-button][data-size="lg"] { min-height: 44px; padding: 0 var(--jg-space-xl, 24px); font-size: var(--jg-type-lg, 16px); }
+[data-jg-button][data-size="icon"] { min-height: 0; width: 28px; height: 28px; padding: 0; font-size: var(--jg-type-sm, 13px); }
+[data-jg-button][data-block] { display: flex; width: 100%; }
+
+[data-jg-panel] { box-sizing: border-box; color: var(--jg-text, #f5f7fa); font-family: var(--jg-font-body, ${HUD_FONT_STACK}); background: var(--jg-frame-bg, rgba(12,15,21,0.9)); border: var(--jg-frame-border, 1px solid rgba(255,255,255,0.13)); border-radius: var(--jg-frame-radius, 10px); box-shadow: var(--jg-frame-glow, ${HIGHLIGHT}, ${RAISED}); }
+[data-jg-panel][data-elevation="overlay"] { box-shadow: var(--jg-frame-glow, ${HIGHLIGHT}), ${OVERLAY}; }
+[data-jg-panel][data-elevation="modal"] { box-shadow: var(--jg-frame-glow, ${HIGHLIGHT}), ${MODAL}; }
+[data-jg-panel][data-state="open"] { animation: jg-panel-in ${BASE} ${EASE_OUT} both; }
+[data-jg-panel][data-state="closed"] { animation: jg-panel-out ${FAST} ${EASE} both; pointer-events: none; }
+[data-jg-window][data-state="open"] { animation: jg-panel-in ${BASE} ${EASE_OUT} both; }
+[data-jg-window][data-state="closed"] { animation: jg-panel-out ${FAST} ${EASE} both; pointer-events: none !important; }
+[data-jg-panel-header] { display: flex; align-items: center; justify-content: space-between; gap: var(--jg-space-sm, 8px); font-size: var(--jg-type-xs, 12px); font-weight: 650; letter-spacing: var(--jg-tracking-label, 0.08em); text-transform: uppercase; color: var(--jg-text-dim, #94a3b8); }
+
+[data-modal-backdrop] { animation: jg-fade-in ${BASE} ${EASE_OUT} both; -webkit-backdrop-filter: blur(3px); backdrop-filter: blur(3px); }
+[data-modal-host] > [role="dialog"] { animation: jg-panel-in ${BASE} ${EASE_OUT} both; }
+[data-toast] { animation: jg-slide-up ${BASE} ${EASE_OUT} both; }
+[data-levelup] { animation: jg-pop ${SLOW} ${SPRING} both; }
+[data-jg-delta="up"] { display: inline-block; animation: jg-delta-up ${SLOW} ${EASE_OUT}; }
+[data-jg-delta="down"] { display: inline-block; animation: jg-delta-down ${SLOW} ${EASE_OUT}; }
+[data-action-id] { transition: translate ${FAST} ${EASE}, scale ${FAST} ${SPRING}, border-color ${FAST} ${EASE}, box-shadow ${FAST} ${EASE}; }
+@media (hover: hover) { [data-action-id][data-enabled]:hover { translate: 0 var(--jg-hover-lift, -1px); } }
+[data-action-id][data-enabled]:active { translate: 0 0; scale: var(--jg-press-scale, 0.97); }
+[data-action-id]:focus-visible { outline: none; box-shadow: ${FOCUS}; }
+`;
+const STYLE_ID = "jg-engine-styles";
+/** Injects {@link ENGINE_STYLESHEET} into `doc` once. Safe to call repeatedly and during SSR (no-op). */
+export function ensureEngineStyles(doc = typeof document === "undefined" ? undefined : document) {
+    if (doc === undefined || doc.getElementById(STYLE_ID) !== null)
+        return;
+    const style = doc.createElement("style");
+    style.id = STYLE_ID;
+    style.setAttribute("data-jg-engine-styles", "");
+    style.textContent = ENGINE_STYLESHEET;
+    doc.head.prepend(style);
+}
+/**
+ * Ensures the engine stylesheet is in the document before the calling component paints. Engine
+ * primitives call it, so they animate and show interaction states even outside the shell.
+ *
+ * @capability engine-styles inject the engine stylesheet (jg-* keyframes, interaction states, reduced motion) once
+ */
+export function useEngineStyles() {
+    useInsertionEffect(() => {
+        ensureEngineStyles();
+    }, []);
+}

package/dist/fastTravel.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useReducer } from "react";
+import { hudType } from "./hudTokens.js";
 /**
  * Subscribe a component to a fast-travel network's discovery changes. Returns the
  * network unchanged; the hook only forces a re-render when a point is discovered
@@ -73,11 +74,11 @@ export function FastTravelMenu({ network, from, onTravel, currentId, title = "Fa
                             borderRadius: 6,
                             background: "transparent",
                             color: "rgba(226,232,240,0.85)",
-                            fontSize: 11,
+                            fontSize: hudType("xs"),
                             padding: "3px 8px",
                             cursor: "pointer",
                         }, children: "\u2715" })) : null] }), destinations.length === 0 ? (_jsx("p", { style: { margin: 0, padding: "16px 12px", fontSize: 12, color: "rgba(148,163,184,0.8)" }, children: emptyLabel })) : (_jsx("div", { style: { overflowY: "auto", padding: 6, display: "flex", flexDirection: "column", gap: 8 }, children: groups.map((group) => (_jsxs("div", { "data-region": group.region ?? "", children: [group.region !== null ? (_jsx("div", { style: {
-                                fontSize: 10,
+                                fontSize: hudType("xs"),
                                 fontWeight: 700,
                                 letterSpacing: 1,
                                 textTransform: "uppercase",
@@ -98,6 +99,6 @@ export function FastTravelMenu({ network, from, onTravel, currentId, title = "Fa
                                             color: "#e2e8f0",
                                             textAlign: "left",
                                             cursor: isCurrent ? "default" : "pointer",
-                                        }, children: [_jsx("span", { style: { fontSize: 18, width: 22, textAlign: "center", flexShrink: 0 }, children: point.icon ?? "📍" }), _jsxs("span", { style: { display: "flex", flexDirection: "column", minWidth: 0, flex: 1 }, children: [_jsx("span", { style: { fontSize: 13, fontWeight: 600 }, children: point.name }), isCurrent ? (_jsx("span", { style: { fontSize: 10, color: "rgba(56,189,248,0.85)" }, children: "You are here" })) : null] }), distance !== null && !isCurrent ? (_jsx("span", { style: { fontSize: 11, color: "rgba(148,163,184,0.75)", whiteSpace: "nowrap" }, children: distance })) : null] }) }, point.id));
+                                        }, children: [_jsx("span", { style: { fontSize: 18, width: 22, textAlign: "center", flexShrink: 0 }, children: point.icon ?? "📍" }), _jsxs("span", { style: { display: "flex", flexDirection: "column", minWidth: 0, flex: 1 }, children: [_jsx("span", { style: { fontSize: 13, fontWeight: 600 }, children: point.name }), isCurrent ? (_jsx("span", { style: { fontSize: hudType("xs"), color: "rgba(56,189,248,0.85)" }, children: "You are here" })) : null] }), distance !== null && !isCurrent ? (_jsx("span", { style: { fontSize: hudType("xs"), color: "rgba(148,163,184,0.75)", whiteSpace: "nowrap" }, children: distance })) : null] }) }, point.id));
                             }) })] }, group.region ?? "__none__"))) }))] }));
 }

package/dist/hud.js

@@ -5,6 +5,7 @@ import { iconForItemId } from "./gameIcons.js";
 import { hudFrameStyle } from "./hudFrame.js";
 import { IconTreatment, schoolForItem } from "./iconTreatment.js";
 import { useCurrency, useEntityStat, useGameClock, useGameStore, useInventory, localPlayerEntity } from "./hooks.js";
+import { hudType } from "./hudTokens.js";
 /**
  * Optional HUD building blocks bound to live game state — not a finished game face. Every game
  * owns custom presentation (see AGENTS.md); import these only as temporary scaffolding, previews,
@@ -47,7 +48,7 @@ export function StatBar({ statId = "health", entityId, tone = "health", label, s
     const range = stat.max - stat.min;
     const fraction = range <= 0 ? 0 : Math.max(0, Math.min(1, (stat.current - stat.min) / range));
     const [from, to] = (TONES[tone] ?? TONES.neutral)(fraction);
-    return (_jsxs("div", { className: className, style: { ...PANEL, padding: "6px 8px", width, ...style }, "data-stat": statId, children: [(label !== undefined || icon !== undefined || showValue) && (_jsxs("div", { style: { display: "flex", alignItems: "center", gap: 6, marginBottom: 4, fontSize: 11, fontWeight: 600, letterSpacing: 0.3 }, children: [icon, _jsx("span", { style: { textTransform: "uppercase", opacity: 0.75 }, children: label ?? statId }), showValue ? (_jsxs("span", { style: { marginLeft: "auto", fontVariantNumeric: "tabular-nums", opacity: 0.9 }, children: [Math.round(stat.current), _jsxs("span", { style: { opacity: 0.5 }, children: [" / ", Math.round(stat.max)] })] })) : null] })), _jsx("div", { style: { height: 8, borderRadius: 999, background: "rgba(255,255,255,0.10)", overflow: "hidden" }, children: _jsx("div", { style: { width: `${fraction * 100}%`, height: "100%", borderRadius: 999, background: `linear-gradient(90deg, ${from}, ${to})`, transition: "width 160ms ease" } }) })] }));
+    return (_jsxs("div", { className: className, style: { ...PANEL, padding: "6px 8px", width, ...style }, "data-stat": statId, children: [(label !== undefined || icon !== undefined || showValue) && (_jsxs("div", { style: { display: "flex", alignItems: "center", gap: 6, marginBottom: 4, fontSize: hudType("xs"), fontWeight: 600, letterSpacing: 0.3 }, children: [icon, _jsx("span", { style: { textTransform: "uppercase", opacity: 0.75 }, children: label ?? statId }), showValue ? (_jsxs("span", { style: { marginLeft: "auto", fontVariantNumeric: "tabular-nums", opacity: 0.9 }, children: [Math.round(stat.current), _jsxs("span", { style: { opacity: 0.5 }, children: [" / ", Math.round(stat.max)] })] })) : null] })), _jsx("div", { style: { height: 8, borderRadius: 999, background: "rgba(255,255,255,0.10)", overflow: "hidden" }, children: _jsx("div", { style: { width: `${fraction * 100}%`, height: "100%", borderRadius: 999, background: `linear-gradient(90deg, ${from}, ${to})`, transition: "width 160ms ease" } }) })] }));
 }
 /**
  * A numbered hotbar bound to an inventory — painted iconed slots (a `GameIcon` glyph over a
@@ -73,7 +74,7 @@ export function Hotbar({ inventoryId, activeSlot, keys, slotSize = 46, itemIcon,
                         height: slotSize,
                         position: "relative",
                         borderColor: active ? "rgba(56,189,248,0.9)" : "rgba(255,255,255,0.10)",
-                    }, children: _jsx("span", { style: { position: "absolute", top: 2, left: 4, fontSize: 9, fontWeight: 700, opacity: 0.55 }, children: keycap }) })) }, index));
+                    }, children: _jsx("span", { style: { position: "absolute", top: 2, left: 4, fontSize: hudType("xs"), fontWeight: 700, opacity: 0.55 }, children: keycap }) })) }, index));
         }) }));
 }
 /**
@@ -99,7 +100,7 @@ export function Speedometer({ entityId, scale = 3.6, unit = "km/h", max = 60, si
         const large = sweep * (toFrac - fromFrac) > 180 ? 1 : 0;
         return `M ${cx + radius * Math.cos(a0)} ${cy + radius * Math.sin(a0)} A ${radius} ${radius} 0 ${large} 1 ${cx + radius * Math.cos(a1)} ${cy + radius * Math.sin(a1)}`;
     };
-    return (_jsxs("div", { className: className, style: { ...PANEL, width: size, padding: 6, textAlign: "center", ...style }, children: [_jsxs("svg", { width: size - 12, height: (size - 12) * 0.72, viewBox: `0 0 ${size} ${size * 0.72}`, style: { display: "block", margin: "0 auto" }, children: [_jsx("path", { d: arc(0, 1), fill: "none", stroke: "rgba(255,255,255,0.12)", strokeWidth: 7, strokeLinecap: "round" }), _jsx("path", { d: arc(0, fraction), fill: "none", stroke: fraction > 0.85 ? "#f87171" : "#38bdf8", strokeWidth: 7, strokeLinecap: "round" })] }), _jsx("div", { style: { marginTop: -8, fontVariantNumeric: "tabular-nums", fontWeight: 700, fontSize: 18, lineHeight: 1 }, children: Math.round(speed) }), _jsx("div", { style: { fontSize: 9, opacity: 0.6, letterSpacing: 0.4, textTransform: "uppercase" }, children: unit })] }));
+    return (_jsxs("div", { className: className, style: { ...PANEL, width: size, padding: 6, textAlign: "center", ...style }, children: [_jsxs("svg", { width: size - 12, height: (size - 12) * 0.72, viewBox: `0 0 ${size} ${size * 0.72}`, style: { display: "block", margin: "0 auto" }, children: [_jsx("path", { d: arc(0, 1), fill: "none", stroke: "rgba(255,255,255,0.12)", strokeWidth: 7, strokeLinecap: "round" }), _jsx("path", { d: arc(0, fraction), fill: "none", stroke: fraction > 0.85 ? "#f87171" : "#38bdf8", strokeWidth: 7, strokeLinecap: "round" })] }), _jsx("div", { style: { marginTop: -8, fontVariantNumeric: "tabular-nums", fontWeight: 700, fontSize: 18, lineHeight: 1 }, children: Math.round(speed) }), _jsx("div", { style: { fontSize: hudType("xs"), opacity: 0.6, letterSpacing: 0.4, textTransform: "uppercase" }, children: unit })] }));
 }
 /**
  * A time-of-day clock reading the sim calendar — `Day N · HH:MM`, 24h or 12h. `controls` adds
@@ -119,13 +120,13 @@ export function Clock({ format = "24h", showDay = true, controls = false, style,
         }
         return `${hour.toString().padStart(2, "0")}:${mm}`;
     }, [hour, minute, format]);
-    return (_jsxs("div", { className: className, style: { ...PANEL, padding: "5px 10px", display: "inline-flex", alignItems: "center", gap: 8, fontVariantNumeric: "tabular-nums", ...style }, children: [showDay ? _jsxs("span", { style: { fontSize: 11, opacity: 0.6 }, children: ["Day ", day + 1] }) : null, _jsx("span", { style: { fontWeight: 700, fontSize: 14 }, children: label }), controls ? (_jsxs("span", { style: { display: "inline-flex", gap: 3, marginLeft: 4 }, children: [_jsx(ClockPill, { label: clock.paused ? "▶" : "❚❚", active: false, onClick: () => (clock.paused ? clock.controls.play() : clock.controls.pause()) }), clock.speeds.map((s) => (_jsx(ClockPill, { label: `${s}×`, active: !clock.paused && clock.speed === s, onClick: () => clock.controls.setSpeed(s) }, s)))] })) : null] }));
+    return (_jsxs("div", { className: className, style: { ...PANEL, padding: "5px 10px", display: "inline-flex", alignItems: "center", gap: 8, fontVariantNumeric: "tabular-nums", ...style }, children: [showDay ? _jsxs("span", { style: { fontSize: hudType("xs"), opacity: 0.6 }, children: ["Day ", day + 1] }) : null, _jsx("span", { style: { fontWeight: 700, fontSize: 14 }, children: label }), controls ? (_jsxs("span", { style: { display: "inline-flex", gap: 3, marginLeft: 4 }, children: [_jsx(ClockPill, { label: clock.paused ? "▶" : "❚❚", active: false, onClick: () => (clock.paused ? clock.controls.play() : clock.controls.pause()) }), clock.speeds.map((s) => (_jsx(ClockPill, { label: `${s}×`, active: !clock.paused && clock.speed === s, onClick: () => clock.controls.setSpeed(s) }, s)))] })) : null] }));
 }
 function ClockPill({ label, active, onClick }) {
     return (_jsx("button", { type: "button", onClick: onClick, style: {
             pointerEvents: "auto",
             cursor: "pointer",
-            fontSize: 10,
+            fontSize: hudType("xs"),
             fontWeight: 600,
             padding: "1px 6px",
             borderRadius: 6,
@@ -139,7 +140,7 @@ function ClockPill({ label, active, onClick }) {
  * (enemies remaining, timer). Pure display: pass the current `wave` and whatever subtitle you track.
  */
 export function WaveBanner({ wave, label = "Wave", subtitle, style, className, }) {
-    return (_jsxs("div", { className: className, style: { ...PANEL, padding: "6px 16px", textAlign: "center", display: "inline-block", ...style }, children: [_jsx("div", { style: { fontSize: 10, letterSpacing: 2, textTransform: "uppercase", opacity: 0.65 }, children: label }), _jsx("div", { style: { fontSize: 24, fontWeight: 800, lineHeight: 1.1 }, children: wave }), subtitle !== undefined ? _jsx("div", { style: { fontSize: 11, opacity: 0.7, marginTop: 2 }, children: subtitle }) : null] }));
+    return (_jsxs("div", { className: className, style: { ...PANEL, padding: "6px 16px", textAlign: "center", display: "inline-block", ...style }, children: [_jsx("div", { style: { fontSize: hudType("xs"), letterSpacing: 2, textTransform: "uppercase", opacity: 0.65 }, children: label }), _jsx("div", { style: { fontSize: 24, fontWeight: 800, lineHeight: 1.1 }, children: wave }), subtitle !== undefined ? _jsx("div", { style: { fontSize: hudType("xs"), opacity: 0.7, marginTop: 2 }, children: subtitle }) : null] }));
 }
 /** A currency counter — an icon (emoji/char, default a coin) plus the live amount for `currencyId`.  *
  * @capability hud-coins currency counter widget bound to a currency id

package/dist/hudButton.d.ts

@@ -0,0 +1,29 @@
+import { type ButtonHTMLAttributes, type ReactNode } from "react";
+import { type HudInteractListener } from "./hudInteract.js";
+/** Visual weight of a {@link HudButton}. */
+export type HudButtonVariant = "secondary" | "primary" | "danger" | "ghost";
+/** Size of a {@link HudButton}; `icon` is a 28px square. */
+export type HudButtonSize = "sm" | "md" | "lg" | "icon";
+/** Props for {@link HudButton}: native button attributes plus theme-driven variant, size, and feedback hooks. */
+export interface HudButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type"> {
+    variant?: HudButtonVariant;
+    size?: HudButtonSize;
+    /** Stretch to the container width. */
+    block?: boolean;
+    /** Native button type. Default `"button"`. */
+    type?: "button" | "submit" | "reset";
+    /** Feedback cue name, rendered as `data-jg-cue` and passed to `onInteract`. */
+    cue?: string;
+    /** Called on hover, press, focus, and activate — the seam a UI sound system hooks. */
+    onInteract?: HudInteractListener;
+    children?: ReactNode;
+}
+/**
+ * Themed HUD button: reads the `HudTheme` slot, accent, elevation, motion, and state tokens, and
+ * gets hover lift, press scale, a focus-visible ring, and a disabled state from the engine
+ * stylesheet. `className` and `style` restyle it per game. Interactions report to `onInteract` and
+ * the nearest `HudInteractProvider`.
+ *
+ * @capability hud-button themed button with hover lift, press scale, focus ring, disabled state, and an interaction cue seam
+ */
+export declare const HudButton: import("react").ForwardRefExoticComponent<HudButtonProps & import("react").RefAttributes<HTMLButtonElement>>;

package/dist/hudButton.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef } from "react";
+import { useEngineStyles } from "./engineStyles.js";
+import { useHudInteract } from "./hudInteract.js";
+/**
+ * Themed HUD button: reads the `HudTheme` slot, accent, elevation, motion, and state tokens, and
+ * gets hover lift, press scale, a focus-visible ring, and a disabled state from the engine
+ * stylesheet. `className` and `style` restyle it per game. Interactions report to `onInteract` and
+ * the nearest `HudInteractProvider`.
+ *
+ * @capability hud-button themed button with hover lift, press scale, focus ring, disabled state, and an interaction cue seam
+ */
+export const HudButton = forwardRef(function HudButton({ variant = "secondary", size = "md", block, type = "button", cue, onInteract, onClick, onPointerEnter, onPointerDown, onFocus, disabled, children, ...rest }, ref) {
+    useEngineStyles();
+    const report = useHudInteract("button", cue, onInteract);
+    return (_jsx("button", { ...rest, ref: ref, type: type, disabled: disabled, "data-jg-button": "", "data-variant": variant, "data-size": size, "data-block": block === true ? "" : undefined, "data-jg-cue": cue, onPointerEnter: (event) => {
+            if (disabled !== true)
+                report("hover");
+            onPointerEnter?.(event);
+        }, onPointerDown: (event) => {
+            if (disabled !== true)
+                report("press");
+            onPointerDown?.(event);
+        }, onFocus: (event) => {
+            report("focus");
+            onFocus?.(event);
+        }, onClick: (event) => {
+            report("activate");
+            onClick?.(event);
+        }, children: children }));
+});

package/dist/hudChromePreview.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The shared HUD chrome under the shell's default root theme, from static values: a glass frame with
+ * vitals and a counter, an action bar, a window, a confirm dialog, a pause menu, and the button
+ * variants. Screenshots identically; the before/after evidence for theme and primitive changes.
+ */
+export declare function HudChromePreview({ className }: {
+    className?: string;
+}): import("react").JSX.Element;

package/dist/hudChromePreview.js

@@ -0,0 +1,27 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { actionCooldownFromFraction, actionCost, resolveAction } from "@jgengine/core/ui/actionModel";
+import { ActionButton } from "./actionHud.js";
+import { HealthBar, ManaBar } from "./bars.js";
+import { HudButton } from "./hudButton.js";
+import { HudFrame } from "./hudFrame.js";
+import { HudPanel } from "./hudPanel.js";
+import { HudThemeRoot } from "./hudThemeRoot.js";
+import { ConfirmDialog, PauseMenu } from "./modals.js";
+import { Window } from "./panels.js";
+import { TweenNumber } from "./tweenNumber.js";
+const ACTIONS = [
+    resolveAction({ id: "slash", label: "Slash", icon: "⚔", hotkey: "1" }),
+    resolveAction({ id: "guard", label: "Guard", icon: "⛨", hotkey: "2", active: true }),
+    resolveAction({ id: "bolt", label: "Bolt", icon: "⚡", hotkey: "3", costs: [actionCost("mana", 30, 50)] }),
+    resolveAction({ id: "heal", label: "Heal", icon: "✚", hotkey: "4", cooldown: actionCooldownFromFraction(4200, 0.6) }),
+    resolveAction({ id: "nova", label: "Nova", icon: "✺", hotkey: "5", costs: [actionCost("mana", 80, 50)] }),
+];
+const noop = () => undefined;
+/**
+ * The shared HUD chrome under the shell's default root theme, from static values: a glass frame with
+ * vitals and a counter, an action bar, a window, a confirm dialog, a pause menu, and the button
+ * variants. Screenshots identically; the before/after evidence for theme and primitive changes.
+ */
+export function HudChromePreview({ className }) {
+    return (_jsx("div", { className: className, style: { position: "relative", width: "100%", height: "100%", minHeight: 720, overflow: "hidden", background: "radial-gradient(ellipse at 30% 20%, #3b5a46, #1b2a24 55%, #0f1714)" }, children: _jsxs(HudThemeRoot, { children: [_jsx("div", { style: { position: "absolute", left: 24, top: 24, width: 280 }, children: _jsx(HudFrame, { title: "Warden \u00B7 Lv 12", aside: _jsx(TweenNumber, { value: 12480 }), padding: 12, children: _jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 6 }, children: [_jsx(HealthBar, { value: 78, max: 100, label: "HP", width: "100%" }), _jsx(ManaBar, { value: 50, max: 80, label: "MP", width: "100%" })] }) }) }), _jsx("div", { style: { position: "absolute", left: 24, bottom: 24, display: "flex", gap: 8 }, children: ACTIONS.map((action, index) => (_jsx(ActionButton, { action: action, focused: index === 0 }, action.id))) }), _jsx(Window, { title: "Inventory", x: 340, y: 24, width: 260, closable: true, onClose: noop, children: _jsx("div", { style: { display: "grid", gridTemplateColumns: "repeat(5, 1fr)", gap: 6 }, children: Array.from({ length: 10 }, (_, index) => (_jsx("div", { style: { aspectRatio: "1", background: "var(--jg-slot-bg)", border: "var(--jg-slot-border)", borderRadius: "var(--jg-slot-radius)" } }, index))) }) }), _jsx("div", { style: { position: "absolute", left: 640, top: 24 }, children: _jsx(ConfirmDialog, { title: "Abandon the expedition?", body: "Your haul stays in the wagon, but the crew returns home.", confirmLabel: "Abandon", danger: true, onConfirm: noop, onCancel: noop }) }), _jsx("div", { style: { position: "absolute", left: 1040, top: 24 }, children: _jsx(PauseMenu, { onResume: noop, items: [{ id: "settings", label: "Settings", onSelect: noop }, { id: "quit", label: "Quit to title", onSelect: noop, danger: true }] }) }), _jsx("div", { style: { position: "absolute", left: 340, top: 300 }, children: _jsx(HudPanel, { title: "Buttons", padding: 14, children: _jsxs("div", { style: { display: "flex", gap: 8, flexWrap: "wrap", width: 420 }, children: [_jsx(HudButton, { variant: "primary", children: "Deploy" }), _jsx(HudButton, { children: "Inspect" }), _jsx(HudButton, { variant: "ghost", children: "Skip" }), _jsx(HudButton, { variant: "danger", children: "Scrap" }), _jsx(HudButton, { disabled: true, children: "Locked" }), _jsx(HudButton, { size: "sm", children: "Small" })] }) }) })] }) }));
+}

package/dist/hudFrame.js

@@ -1,4 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { hudElevation, hudFont, hudType } from "./hudTokens.js";
 /**
  * Bare style object for a HUD frame's look (no wrapper element) — spread it onto
  * a widget that already owns its element when it just needs the chrome CSS. The
@@ -18,7 +19,7 @@ export function hudFrameStyle(variation = "glass", shape = "rounded") {
             borderImage: "var(--jg-frame-image, none) var(--jg-frame-slice, 0) / var(--jg-frame-scale, 1) var(--jg-frame-fill, stretch)",
             cursor: "var(--jg-skin-cursor, auto)",
             color: "var(--jg-bar-text, #f4f6fb)",
-            fontFamily: "ui-sans-serif, system-ui, -apple-system, sans-serif",
+            fontFamily: hudFont.body,
         }
         : variation === "retro"
             ? {
@@ -33,18 +34,19 @@ export function hudFrameStyle(variation = "glass", shape = "rounded") {
                     border: "1px solid rgba(255,255,255,0.10)",
                     borderRadius: 10,
                     color: "#f4f6fb",
-                    fontFamily: "ui-sans-serif, system-ui, -apple-system, sans-serif",
-                    boxShadow: "0 6px 20px rgba(0,0,0,0.45)",
+                    fontFamily: hudFont.body,
+                    boxShadow: hudElevation("raised"),
                 }
                 : {
                     background: "rgba(10,12,16,0.62)",
-                    backdropFilter: "blur(6px)",
-                    WebkitBackdropFilter: "blur(6px)",
-                    border: "1px solid rgba(255,255,255,0.10)",
+                    backgroundImage: "linear-gradient(180deg, rgba(255,255,255,0.05), rgba(255,255,255,0) 45%)",
+                    backdropFilter: "blur(8px) saturate(1.2)",
+                    WebkitBackdropFilter: "blur(8px) saturate(1.2)",
+                    border: "1px solid rgba(255,255,255,0.12)",
                     borderRadius: 10,
                     color: "#f4f6fb",
-                    fontFamily: "ui-sans-serif, system-ui, -apple-system, sans-serif",
-                    boxShadow: "0 4px 16px rgba(0,0,0,0.35)",
+                    fontFamily: hudFont.body,
+                    boxShadow: hudElevation("raised"),
                 };
     if (shape === "circle")
         return { ...base, borderRadius: 9999 };
@@ -74,9 +76,11 @@ export function HudFrame({ variation = "glass", shape = "rounded", title, aside,
                     alignItems: "center",
                     gap: 8,
                     marginBottom: 6,
-                    fontSize: 10,
-                    letterSpacing: 1.4,
+                    fontSize: hudType("xs"),
+                    fontWeight: 650,
+                    letterSpacing: "var(--jg-tracking-label, 0.08em)",
+                    lineHeight: 1.2,
                     textTransform: "uppercase",
-                    opacity: 0.75,
+                    opacity: 0.82,
                 }, children: [_jsx("span", { children: title }), aside !== undefined ? _jsx("span", { children: aside }) : null] })) : null, children] }));
 }

package/dist/hudInteract.d.ts

@@ -0,0 +1,26 @@
+import { type ReactNode } from "react";
+/** What happened to an engine HUD primitive. */
+export type HudInteractKind = "hover" | "press" | "activate" | "focus" | "open" | "close";
+/** One interaction reported by an engine HUD primitive to an `onInteract` listener. */
+export interface HudInteractEvent {
+    kind: HudInteractKind;
+    /** The primitive's `cue` (also rendered as `data-jg-cue`), naming which feedback to play. */
+    cue?: string;
+    /** Primitive family, e.g. `"button"`, `"panel"`, `"window"`, `"action"`. */
+    source: string;
+}
+/** Listener for {@link HudInteractEvent}s. */
+export type HudInteractListener = (event: HudInteractEvent) => void;
+/**
+ * Routes interactions from every engine HUD primitive below it (buttons, panels, windows, action
+ * slots) to one listener — the seam a UI sound or haptics system hooks without per-button wiring.
+ * Primitives also expose `data-jg-cue` and a per-instance `onInteract`.
+ *
+ * @capability hud-interact one listener for hover/press/activate/open/close from every engine HUD primitive
+ */
+export declare function HudInteractProvider({ onInteract, children }: {
+    onInteract: HudInteractListener;
+    children?: ReactNode;
+}): ReactNode;
+/** Returns a reporter that calls the instance listener, then the nearest {@link HudInteractProvider}. */
+export declare function useHudInteract(source: string, cue?: string, onInteract?: HudInteractListener): (kind: HudInteractKind) => void;

package/dist/hudInteract.js

@@ -0,0 +1,28 @@
+import { createContext, createElement, useCallback, useContext } from "react";
+const HudInteractContext = createContext(null);
+/**
+ * Routes interactions from every engine HUD primitive below it (buttons, panels, windows, action
+ * slots) to one listener — the seam a UI sound or haptics system hooks without per-button wiring.
+ * Primitives also expose `data-jg-cue` and a per-instance `onInteract`.
+ *
+ * @capability hud-interact one listener for hover/press/activate/open/close from every engine HUD primitive
+ */
+export function HudInteractProvider({ onInteract, children }) {
+    const parent = useContext(HudInteractContext);
+    const listener = useCallback((event) => {
+        onInteract(event);
+        parent?.(event);
+    }, [onInteract, parent]);
+    return createElement(HudInteractContext.Provider, { value: listener }, children);
+}
+/** Returns a reporter that calls the instance listener, then the nearest {@link HudInteractProvider}. */
+export function useHudInteract(source, cue, onInteract) {
+    const context = useContext(HudInteractContext);
+    return useCallback((kind) => {
+        if (onInteract === undefined && context === null)
+            return;
+        const event = cue === undefined ? { kind, source } : { kind, source, cue };
+        onInteract?.(event);
+        context?.(event);
+    }, [context, cue, onInteract, source]);
+}

package/dist/hudLayout.js

@@ -11,6 +11,7 @@ import { useGameLayoutMode, useRegisterLayoutRegion } from "./gameViewport.js";
 import { useOptionalGamePhase } from "./hooks.js";
 import { useHudLayoutPersist } from "./hudLayoutPersist.js";
 import { useHudViewport } from "./hudViewport.js";
+import { hudFont, hudType } from "./hudTokens.js";
 /** Whether a HUD element opted into `showDuring` is visible in the current phase; `undefined` = always visible (default). */
 export function hudVisibleInPhase(showDuring, phase) {
     return showDuring === undefined || showDuring.includes(phase);
@@ -479,7 +480,7 @@ export function HudCanvas({ layout, editChord, compactScale, showDuring, classNa
                                 borderRadius: 4,
                                 background: "rgba(180, 20, 20, 0.95)",
                                 color: "#fff",
-                                font: "600 10px/1.4 system-ui, sans-serif",
+                                font: `600 ${hudType("xs")}/1.4 ${hudFont.body}`,
                                 whiteSpace: "nowrap",
                             }, children: ["\u26A0 ", o.id, " escapes viewport (", overflowEdges(o), ")"] }) }, o.id))) })) : null, editing ? _jsx(HudEditBar, { layout: layout }) : null] }) }));
 }
@@ -520,7 +521,7 @@ function HudChip({ label, anchor, children, }) {
                     background: "rgba(10, 10, 14, 0.72)",
                     border: "1px solid rgba(255, 255, 255, 0.22)",
                     color: "rgba(255, 255, 255, 0.92)",
-                    font: "600 11px/1.2 system-ui, sans-serif",
+                    font: `600 ${hudType("xs")}/1.2 ${hudFont.body}`,
                     letterSpacing: "0.04em",
                     textTransform: "uppercase",
                     cursor: "pointer",
@@ -695,7 +696,7 @@ export function HudPanel({ id, anchor = "top-left", order, compact: compactMode
                     borderRadius: 4,
                     background: "rgba(10, 10, 14, 0.85)",
                     color: "rgba(255, 255, 255, 0.9)",
-                    font: "10px/1.5 system-ui, sans-serif",
+                    font: `${hudType("xs")}/1.5 ${hudFont.body}`,
                     whiteSpace: "nowrap",
                 }, children: id }), resizable ? _jsx(ResizeHandles, { axes: resizeSpec.axes, onResizeStart: onResizeStart }) : null] })) : null;
     if (panel === undefined)

package/dist/hudPanel.d.ts

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

package/dist/hudPanel.js

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