@jgengine/react 0.22.0 → 0.23.0

package/CHANGELOG.md

@@ -26,6 +26,102 @@ At publish, rename this heading to the new version and mirror the entries into
 `packages/core/src/meta/changelog.ts` (the typed `CHANGELOG` export).
 -->
 
+## 0.23.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.23.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.20.0`; `@jgengine/github` is `0.10.0`.
+
+### Added
+
+- `player_pose` agent-bridge verb (`@jgengine/shell`, `window.__jgengineAgent`, `drive --rpc '{"method":"player_pose"}'`) returns the local player's position and heading, and `debug_snapshot` carries the same `player` field, so a drive can prove movement from position deltas instead of screenshots.
+- `sim_advance` agent-bridge verb (`@jgengine/shell`, `drive --rpc '{"method":"sim_advance","seconds":30}'`) steps the mounted sim driver — input, movement, `onTick`, behaviors, bound actions — in 0.05 s frames without rendering, so a headless drive can reach waves, shifts and timers that never arrive at software-rendered frame rates. Capped at 120 s per call.
+- `time_scale` agent-bridge verb sets the game clock's timescale and reports `{ timescale, now }`.
+- `GameContextObjectEntry.scenery` (`@jgengine/core`): an object kind placed once and left alone. Its runtime placements now render through the shared instanced static-object batches that editor-authored props already used.
+- `BUILDING_STYLE_PROBABILITIES` and `resolveBuildingProbabilities` (`@jgengine/core/world/buildings`): each `BuildingStyle` now carries facade-part probabilities, so an industrial yard shows few windows and roof plant, a ruin loses awnings and clotheslines, coastal fronts gain awnings. `building({ probabilities })` overrides any part.
+- `debug_summary` agent-bridge verb and `debug_snapshot` `detail: "summary"`: fps, frame/sim ms, draw calls, triangles, entities, warnings and top culprit in about 1 KB. `drive --rpc '{"method":"debug_snapshot"}'` prints the summary; `"detail":"full"` keeps the full snapshot.
+- `modelLoadStarts()` (`@jgengine/shell/render/modelLoad`) counts model streaming bursts for capture quiescence checks.
+- `jgengine` warns when it is not the CLI the caller meant: a global install run inside a jgengine checkout, a project-local `jgengine` shadowed, or a CLI built for an older SDK than the project installs. Harness runs print the CLI version and harness revision.
+- `withGraphicsQualityOverride` and `parseGraphicsQuality` (`@jgengine/core/settings/graphicsSettings`) pin a graphics tier for one session without persisting it.
+- The player shell reads `?quality=<tier>` and pins that tier for the page. `bun run shoot`/`drive --quality draft` use it (low tier, half size) for fast iteration shots; `--quality full` stays the default for PR evidence.
+- `jgengine doctor` flags a silent game: one that neither declares `defineGame({ audio })` cues nor calls `ctx.game.audio.play`/`loop`. Four reference games shipped without a single sound; the fix text points at procedural `SoundDef` synth patches, which need no asset files.
+- `drive --key mouse0:<ms>` (also `mouse1`, `mouse2`) holds that mouse button over the play canvas, matching the shell's pointer binding codes, so hold-to-fire weapons can be driven headlessly. Keyboard codes are unchanged.
+- `drive --right-click-at x,y` sends a native right click in CSS viewport pixels, so RTS move/attack/gather orders and context actions can be driven headlessly; `--click-at` stays a left click.
+- `ctx.scene.entity.selection` (`@jgengine/core`): the player's selected entities as a reactive `SelectionSet`. The shell pointer (`pointer.select` click / marquee) now writes it instead of private component state, so game HUDs can show the selected unit's card or a "3 units selected" summary and can set the selection themselves (select-all, control groups); the selection ring follows either way. Despawned ids drop out.
+- `LightingConfig.iblAmbientScale` (default 0.5) and `LightingConfig.fallbackKey` (default true); `balanceLightingForIbl` in `@jgengine/core/render/lightingBalance` applies them.
+- `DirectionalLightingConfig.shadowRadius` (PCF penumbra in texels, default 1.25).
+- `DEFAULT_AO` in `@jgengine/core/render/postProcessing` and `mergePostProcessing` in `@jgengine/core/render/lookPreset`.
+- Loaded GLB models get a default painted finish: flat-colour, vertex-colour and palette-atlas materials have their exported roughness/metalness/`envMapIntensity` normalized and compile with one shared object-space detail shader (mottling, wear, roughness break-up, micro-normal, cavity). Normal-mapped, cutout and transparent materials are untouched.
+- `GraphicsProfile.surfaceDetail` (`"off" | "lite" | "full"`, `@jgengine/core/settings/graphicsProfile`): `"lite"` on low, `"full"` on medium and up.
+- `ModelConfig.surfaceDetail: false` opts one model out; `defineGame({ surfaceDetail: false })` opts a game out.
+- `createSurfaceRibbonMaterial`, `ribbonSurfaceFrame`, `resolvePathSurface` and `useSurfaceRibbonMaterial` (`@jgengine/shell/terrain`) shade ground ribbons with the terrain's procedural surface functions, plus wear and a noise-warped soft edge.
+- `road({ surface })` (`@jgengine/core/world/features`) picks the carriageway surface; `false` keeps flat colour.
+- `AuthoredScene`/`AuthoredPaths` `pathSurfaceDetail`/`surfaceDetail` props and path `meta.surface`, `meta.edgeSoftness`, `meta.wear`, `meta.surfaceDetail`.
+- `EditableTerrain.gridBounds` (`@jgengine/core/world/terraform`) exposes the world extent of the paint/height cell grid.
+- Painted terrain renders each layer's `surface` as its own procedural ground (grass, dirt, gravel, rock, sand, mud, snow, road) with albedo variation, roughness and micro-normals, blended along noise-warped, height-aware edges, in play and in the editor viewport. No game config or assets needed.
+- `TerrainDetailConfig.surfaceStrength` (0..1, default 1) scales the per-surface response; `detail: false` opts a terrain out to the flat vertex-colour ground.
+- `@jgengine/shell/terrain` exports `packTerrainPaintWeights`, `createTerrainPaintTextures`, `terrainSurfaceClass`, `createTerrainDetailMaterial` and `TerrainQualityContext`/`useTerrainQuality`.
+- `ctx.game.notices` (`@jgengine/core/game/notices`, `createNoticeFeed`): a player-facing notice feed with info/success/warn/deny tones, stacking dedupe (repeats show ×N and refresh their lifetime), a cap, TTL, `onPush`, `retune` and `snapshot`/`restore`. Pure state on the context clock, so headless and hosted runs are unaffected.
+- The shell mounts `NoticeStack` (`@jgengine/react/notices`) for every game: animated toned cards below top HUD bars, 14px text on `--jg-*` vars with fallbacks, no pointer capture. Configure with `notices: { placement, hidden, refusals, cues, cap, ttlMs }` or remove with `notices: false`.
+- Refusal feedback: `validate` may return `{ reason, message }`. `reason` stays the machine code; a `message` is shown automatically as a deduped deny notice with the deny cue when the local player's command is refused, locally or from a host. `ctx.game.commands` emits a `command.refused` event for every refusal; `attachRefusalNotices` is the headless hookup.
+- UI sound cues: `useUiCue()` / `playUiCue` (`@jgengine/react/uiCues`) play `click`, `hover`, `open`, `close`, `confirm`, `deny`, `notify`. Soft procedural defaults (`@jgengine/core/audio/uiCues`) mix on a new "ui" bus with a "UI volume" setting under master volume. A game sound named `ui.<cue>` replaces one; `audio.uiCues` overrides or silences cues (`false` for all).
+- `notice_push` and `run_command` agent-bridge verbs for `drive --rpc`.
+- `ui-feedback` dev probe (apps/dev) exercising refusals, the feed and cues.
+- `HudTheme` gains a type scale with a 12px floor, spacing, motion (durations and easings), elevation (layered shadows and a lit top rim), and hover/press/focus/disabled state tokens; `hudThemeVars` emits them as `--jg-type-*`, `--jg-space-*`, `--jg-motion-*`, `--jg-ease*`, `--jg-elevation-*`, `--jg-highlight`, `--jg-hover-*`, `--jg-press-*`, `--jg-focus-ring`, and `--jg-disabled-opacity`. `@jgengine/react/hudTokens` reads them in inline styles (`hudType`, `hudSpace`, `hudTransition`, `hudElevation`, `hudFont`, `HUD_FOCUS_RING`).
+- Engine stylesheet `@jgengine/react/styles.css` (also `ENGINE_STYLESHEET` / `useEngineStyles` in `@jgengine/react/engineStyles`): every `jg-*` keyframe the shared blocks and registry use, `[data-jg-*]` interaction states, quiet hover/press/focus defaults for plain HUD buttons, and reduced-motion handling for `prefers-reduced-motion` and `[data-reduced-motion="true"]`. The `jgengine create` template imports it.
+- `HudThemeRoot`: the shell wraps every `GameUI` in it, applying `defaultHudTheme` and the stylesheet. `defineGame({ hudTheme })` swaps the root theme; `hudTheme: false` opts out.
+- Primitives `HudButton`, `HudPanel` (open/close transition via `usePresence`), and `TweenNumber` / `useTweenedValue` with an up/down delta flash; `useReducedMotion` in `@jgengine/react/accessibility`.
+- `HudInteractProvider` / `useHudInteract`, plus `cue` and `onInteract` on the primitives, windows, modals, and `ActionButton`: one seam for a UI sound system.
+
+### Changed
+
+- Static-object batches group same-model props per 64 m cell from 3 placements (was 24 m cells and more than 8), so sparse city dressing such as palms, lamps and benches shares draws. Harbor Heat's opening drops from 5,310 to 4,650 draw calls.
+- `building()` districts with a non-generic `style` generate a different facade mix than before (previously a style changed colours only). `generic` is unchanged.
+- `bun run shoot/drive` and the scaffolded/bundled `shoot.mjs`/`drive.mjs` parse one shared flag table: `--click-at`, `--right-click-at`, `--width`, `--height`, `--port`, `--size`, `--settle`, `--param`, `--probe`, `--reload`, key chords and mouse holds work in both; unknown flags fail instead of being ignored or taken as a game id; dev-runner-only flags are refused by name in the portable harness.
+- Play-mode capture readiness waits until staged `--state`/`--run` commands have ticked, their entities mounted and model streaming stopped, and never declares ready over "Loading game view…". A rejected staged command fails the capture.
+- Play-mode captures of a game with a start menu and no `capture.play` click its start action and report what they clicked.
+- Monorepo tests, type-checks and `bun run gen` resolve `@jgengine/*` to package source through the `paths` in `tsconfig.base.json` (`bun run gen:source-paths` keeps every workspace tsconfig in sync), so a fresh checkout or worktree is testable with no build. Published packages are unchanged: `exports` still point at `dist`, and the built output is byte-identical.
+- The export manifest is computed from the files each package's build emits, not from `dist` on disk, so it can no longer drift with a stale or partial build. `bun run ship:preflight` now fails with the fix (`bun run gen`) when any generated artifact is stale.
+- `bun run agent:worktree -- <name>` produces a clean, ready worktree locally and in cloud sessions: it links dependencies, `Games` and the dev runner's ignored assets from the main checkout instead of installing and building. `agent:bootstrap` only installs; pass `--build` to also build dist.
+- The procedural IBL probe has a zenith/horizon/ground gradient and an HDR sun disc plus a broad lobe, with the horizon leaning toward the ambient colour, at intensity 0.45 (was a 2-colour gradient at 0.35), so forms get a lit and a shaded side from IBL alone.
+- Under IBL (every look but `"flat"`), authored ambient is halved, and lighting with no directional light gets a soft shadowless key light (intensity 0.6, tinted by the ambient colour).
+- A post chain that omits `ao` now runs `DEFAULT_AO` on medium tier and above; `ao: false` still opts out. `NEUTRAL_POST_PROCESSING` no longer sets `ao: false`.
+- Styled look presets deep-merge their post stages under a partial game `postProcessing` instead of being dropped whole.
+- Shadows use `PCFShadowMap` instead of `PCFSoftShadowMap`, which three r182 compiles as unfiltered basic shadows (stair-stepped edges), with a default radius of 1.25 texels on configured and cascaded lights.
+- GTAO samples are tiered: 8 on medium, 12 on high (was 16), 16 on ultra.
+- A model `material.rim` override now chains the material's live program cache key instead of a snapshot.
+- Authored paths now render as dirt (or their `meta.surface`/kind) with wheel ruts and edges that fade into the terrain, instead of flat-colour ribbons with hard cut edges.
+- `road()` carriageways, curbs, sidewalks and welded junctions, and city studio ground (streets, block land, sidewalks, drives, parks), shade with matching procedural asphalt, gravel, concrete and dirt. City volumes opt out with `meta.surfaceDetail: false`.
+- Terrain noise and micro-normal GLSL moved to shared exports in `terrainSurfaceShader.ts` so terrain and ribbons compile the same code.
+- A terrain without `detail` now renders with default procedural detail instead of flat vertex colour.
+- Slope rock no longer fades with `detail.strength`; it follows `surfaceStrength`.
+- The textured terrain path's normal map is applied in view space (it was added to the view-space normal as a world-space offset).
+- The `low` graphics tier takes a cheap terrain surface path without micro-normals.
+- The shell plays UI cues for every engine HUD primitive (`HudButton`, `HudPanel`, `Window`, `ModalHost`, `ActionButton`): activate → `click` (or the primitive's `cue` when it names a cue, e.g. `cue="confirm"`), button/action hover → `hover`, panel open/close → `open`/`close`. Off with `notices: false` or `notices.cues: false`; `audio.uiCues` silences single cues. `uiCueForInteraction` (`@jgengine/react/uiCues`) exposes the mapping.
+- `CommandRejection`, `CommandValidationError`, `CommandResult`, `RunCommandResult` and `TransportRunCommandResult` carry an optional `message`; the ws hosts forward it. Results without one are unchanged.
+- `defaultHudTheme` is the engine's default look: a system UI font stack led by Inter, layered translucent panels with a lit rim and hairline borders, and gradient slots.
+- `Window` / `PanelHost` render on `HudPanel` with enter and exit transitions and a `HudButton` close; `ModalHost` fades its backdrop and lifts its dialog, with an exit; `ConfirmDialog` / `PauseMenu` use `HudPanel` and `HudButton`; `HudFrame` and `ActionButton` read the font, elevation, focus, and motion tokens.
+- Text under 12px in `@jgengine/react` and `registry/jgengine` now uses the type scale's `xs` step (12px floor).
+
+### Fixed
+
+- Games on the `rts` and `topDown` camera rigs hear positional sound again. The spatial-audio listener sat at the camera, 35–50 m above the ground, so the default 24 m falloff silenced every ground event even at screen centre; for these rigs it now sits where the camera looks at the ground. Chase, first-person and other rigs keep the camera-anchored listener.
+- The bundled `jgengine drive` and `jgengine shoot` harnesses let Chrome pick a free debug port instead of guessing one from the clock, so they no longer attach to another Chrome that holds the same port. An interrupted drive or shoot (SIGINT/SIGTERM) now closes its Chrome instead of leaving it running.
+- `jgengine doctor` flags component folders reached through a `tsconfig` path alias (such as a shared `@/components/ui/*` registry) that game code imports but `src/index.css` never scans with `@source`. Their Tailwind classes were silently not generated, so those HUD blocks rendered tiny and unstyled; the fix text names the exact `@source` line to add.
+- `jgengine doctor` now flags a 3D game that sets neither a `look` preset nor `postProcessing`; such a game renders the unstyled `"neutral"` look with no tone-map grade, AO or bloom. Its fix text no longer claims cinematic is the default. Write `look: "neutral"` when unstyled output is deliberate.
+- `jgengine create` scaffolds name `look: "cinematic"` explicitly, so a new 3D game starts graded instead of on the unstyled default.
+- Generated city districts (`@jgengine/shell` `CityRenderer`) fade their developed ground to transparent over its outer 9 m, so it melts into the terrain or authored paint beyond it instead of ending in a hard, stair-stepped green rim.
+- City districts (`@jgengine/shell` `CityRenderer`) draw a crossing of gravel lanes as gravel instead of a dark asphalt slab; a crossing that touches any paved street stays asphalt.
+- The published CLI and scaffold browser driver restore game keyboard focus before key holds and wait for a rendered frame under the held key. Menu clicks and slow headless rendering no longer silently swallow movement inputs; failed frame sampling releases held keys.
+- After a click on a control that then unmounts (a start screen's "Play", a menu's last button), `@jgengine/shell` returns focus to the play surface instead of leaving it on `<body>`, so gameplay keys work without an extra click on the canvas.
+- `sim_advance` (`@jgengine/shell` agent bridge) yields to the browser every ten simulated seconds, so models for entities spawned mid-advance mount as in play; a 30 s advance through Beacon Bastion's first wave previously left every raider with health bars but no model.
+- Generated city districts no longer lay a checkerboard over their ground. The developed-ground fabric drew one flat quad per 2.5 m cell with a per-cell random roll that flipped neighbours between zone bands; it is now one shared-vertex sheet coloured from smooth noise, so yards and lots blend.
+- Authored terrain paint (paths, clearings, painted layers) now blends smoothly between neighbouring cells in the runtime ground and the editor sculpt view, instead of snapping each vertex to its 2 m cell and drawing grid-aligned stair-step edges. Unpainted cells blend toward the caller's base ground color, so painted edges fade into the terrain palette.
+- A terrain detail `material` no longer overrides the ground's authored roughness with its roughness map. The map now varies roughness around the authored value, so scanned ground maps (roughness near 0.45) stop giving dry terrain a wet specular sheen; games no longer need to lower `material.strength` to stay matte.
+- A terrain without a `waterLevel` no longer paints the detail shader's beach sand band. Previously the band defaulted to water at height 0, so any flat terrain near 0 (a park, a meadow) rendered as beach; six reference games set `detail.waterLevel` far below the world only to avoid it. Set `waterLevel` on the terrain or `detail.waterLevel` to keep a shoreline.
+- Atomic vitals bars (`HealthBar`, `ManaBar`, … in `@jgengine/react`) cap their frame at a quarter of the bar height, so thin bars (e.g. `height: "4px"`) show their fill instead of only the two 2px frame lines.
+- Built-in world health bars (`worldHealthBars`, `@jgengine/shell`) span about 1.4 m at the entity's on-screen scale (28–112 px) instead of a fixed 112 px, so top-down and RTS cameras no longer paint bars ten times wider than the units under them.
+
 ## 0.22.0
 
 ### Migrate

package/dist/accessibility.d.ts

@@ -36,4 +36,9 @@ export declare function AccessibilityProvider({ store, children, className, styl
  * `reducedMotion` default.
  */
 export declare function usePrefersReducedMotion(): boolean;
+/**
+ * True when motion should be skipped: the OS `prefers-reduced-motion` preference, or the nearest
+ * {@link AccessibilityProvider}'s `reducedMotion` setting. Works without a provider.
+ */
+export declare function useReducedMotion(): boolean;
 export {};

package/dist/accessibility.js

@@ -59,3 +59,12 @@ export function usePrefersReducedMotion() {
         ? window.matchMedia("(prefers-reduced-motion: reduce)").matches
         : false, () => false);
 }
+/**
+ * True when motion should be skipped: the OS `prefers-reduced-motion` preference, or the nearest
+ * {@link AccessibilityProvider}'s `reducedMotion` setting. Works without a provider.
+ */
+export function useReducedMotion() {
+    const prefers = usePrefersReducedMotion();
+    const value = useContext(AccessibilityContext);
+    return prefers || value?.state.reducedMotion === true;
+}

package/dist/achievements.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useSyncExternalStore } from "react";
+import { hudType } from "./hudTokens.js";
 /**
  * Subscribe a component to an achievement tracker's live view list. The list
  * keeps a stable identity between changes, so this re-renders only on unlock or
@@ -40,7 +41,7 @@ export function AchievementToast({ name, description, icon, points, heading = "A
                     border: "1px solid rgba(245,158,11,0.4)",
                     fontSize: 20,
                     flexShrink: 0,
-                }, children: icon ?? "🏆" }), _jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 1, minWidth: 0 }, children: [_jsx("span", { style: { fontSize: 9, letterSpacing: 1.6, textTransform: "uppercase", color: "rgba(245,158,11,0.85)" }, children: heading }), _jsx("span", { style: { fontSize: 14, fontWeight: 700, whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis" }, children: name }), description !== undefined ? (_jsx("span", { style: { fontSize: 11, color: "rgba(226,232,240,0.7)" }, children: description })) : null] }), points !== undefined ? (_jsx("span", { style: { marginLeft: "auto", fontSize: 13, fontWeight: 700, color: "var(--jg-rarity-legendary, #f59e0b)", fontVariantNumeric: "tabular-nums" }, children: points })) : null] }));
+                }, children: icon ?? "🏆" }), _jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 1, minWidth: 0 }, children: [_jsx("span", { style: { fontSize: hudType("xs"), letterSpacing: 1.6, textTransform: "uppercase", color: "rgba(245,158,11,0.85)" }, children: heading }), _jsx("span", { style: { fontSize: 14, fontWeight: 700, whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis" }, children: name }), description !== undefined ? (_jsx("span", { style: { fontSize: hudType("xs"), color: "rgba(226,232,240,0.7)" }, children: description })) : null] }), points !== undefined ? (_jsx("span", { style: { marginLeft: "auto", fontSize: 13, fontWeight: 700, color: "var(--jg-rarity-legendary, #f59e0b)", fontVariantNumeric: "tabular-nums" }, children: points })) : null] }));
 }
 const MASK = "???";
 /**
@@ -63,7 +64,7 @@ export function AchievementGallery({ achievements, title = "Achievements", maskS
             color: "#e2e8f0",
             fontFamily: "ui-sans-serif, system-ui, sans-serif",
             ...style,
-        }, children: [_jsxs("div", { style: { display: "flex", alignItems: "baseline", justifyContent: "space-between", marginBottom: 10 }, children: [_jsx("span", { style: { fontSize: 13, fontWeight: 700, letterSpacing: 1.4, textTransform: "uppercase" }, children: title }), _jsxs("span", { style: { fontSize: 11, color: "rgba(203,213,225,0.75)", fontVariantNumeric: "tabular-nums" }, children: [unlockedCount, "/", achievements.length, hasPoints ? ` · ${score} pts` : ""] })] }), achievements.length === 0 ? (_jsx("p", { style: { margin: 0, fontSize: 12, color: "rgba(148,163,184,0.8)" }, children: emptyLabel })) : (_jsx("ul", { style: {
+        }, children: [_jsxs("div", { style: { display: "flex", alignItems: "baseline", justifyContent: "space-between", marginBottom: 10 }, children: [_jsx("span", { style: { fontSize: 13, fontWeight: 700, letterSpacing: 1.4, textTransform: "uppercase" }, children: title }), _jsxs("span", { style: { fontSize: hudType("xs"), color: "rgba(203,213,225,0.75)", fontVariantNumeric: "tabular-nums" }, children: [unlockedCount, "/", achievements.length, hasPoints ? ` · ${score} pts` : ""] })] }), achievements.length === 0 ? (_jsx("p", { style: { margin: 0, fontSize: 12, color: "rgba(148,163,184,0.8)" }, children: emptyLabel })) : (_jsx("ul", { style: {
                     listStyle: "none",
                     margin: 0,
                     padding: 0,
@@ -84,7 +85,7 @@ export function AchievementGallery({ achievements, title = "Achievements", maskS
                             background: achievement.unlocked ? "rgba(245,158,11,0.10)" : "rgba(148,163,184,0.06)",
                             border: `1px solid ${achievement.unlocked ? "rgba(245,158,11,0.4)" : "rgba(148,163,184,0.18)"}`,
                             opacity: achievement.unlocked ? 1 : 0.75,
-                        }, children: [_jsx("div", { style: { fontSize: 20, width: 26, textAlign: "center", flexShrink: 0 }, children: icon }), _jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 2, minWidth: 0, flex: 1 }, children: [_jsxs("span", { style: { fontSize: 13, fontWeight: 700, color: achievement.unlocked ? "#f8fafc" : "rgba(226,232,240,0.85)" }, children: [name, achievement.points !== undefined && !masked ? (_jsx("span", { style: { marginLeft: 6, fontSize: 10, color: "rgba(245,158,11,0.85)", fontWeight: 600 }, children: achievement.points })) : null] }), description !== undefined ? (_jsx("span", { style: { fontSize: 11, color: "rgba(203,213,225,0.7)" }, children: description })) : null, showProgress ? (_jsx("div", { "data-achievement-progress": true, style: { marginTop: 3, height: 5, borderRadius: 9999, background: "rgba(148,163,184,0.2)", overflow: "hidden" }, children: _jsx("div", { style: {
+                        }, children: [_jsx("div", { style: { fontSize: 20, width: 26, textAlign: "center", flexShrink: 0 }, children: icon }), _jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 2, minWidth: 0, flex: 1 }, children: [_jsxs("span", { style: { fontSize: 13, fontWeight: 700, color: achievement.unlocked ? "#f8fafc" : "rgba(226,232,240,0.85)" }, children: [name, achievement.points !== undefined && !masked ? (_jsx("span", { style: { marginLeft: 6, fontSize: hudType("xs"), color: "rgba(245,158,11,0.85)", fontWeight: 600 }, children: achievement.points })) : null] }), description !== undefined ? (_jsx("span", { style: { fontSize: hudType("xs"), color: "rgba(203,213,225,0.7)" }, children: description })) : null, showProgress ? (_jsx("div", { "data-achievement-progress": true, style: { marginTop: 3, height: 5, borderRadius: 9999, background: "rgba(148,163,184,0.2)", overflow: "hidden" }, children: _jsx("div", { style: {
                                                 width: `${Math.round(achievement.fraction * 100)}%`,
                                                 height: "100%",
                                                 borderRadius: 9999,

package/dist/actionHud.d.ts

@@ -2,6 +2,7 @@ import { type CSSProperties, type ReactNode } from "react";
 import type { AbilitySlotSnapshot } from "@jgengine/core/combat/abilityKit";
 import { type ActionDef, type ResolvedAction } from "@jgengine/core/ui/actionModel";
 import { type PopoverSide, type TooltipContent } from "@jgengine/core/ui/tooltipModel";
+import { type HudInteractListener } from "./hudInteract.js";
 /**
  * Composable React renderers over the headless action view model (`@jgengine/core/ui/actionModel`) —
  * the data/renderer/chrome split for an RTS command card, an ability action bar, a build menu, or a
@@ -86,8 +87,12 @@ export interface ActionItemContext {
  *
  * @capability action-button cooldown/cost/hotkey action button with complete interaction states
  */
-export declare function ActionButton({ action, focused, hovered, size, showHotkey, tabIndex, buttonRef, onActivate, onFocus, onHover, renderIcon, className, style, }: {
+export declare function ActionButton({ action, focused, hovered, size, showHotkey, tabIndex, buttonRef, onActivate, onFocus, onHover, renderIcon, cue, onInteract, className, style, }: {
     action: ResolvedAction;
+    /** Feedback cue name (default the action id), rendered as `data-jg-cue`. */
+    cue?: string;
+    /** Called on hover, press, and activate — the seam a UI sound system hooks. */
+    onInteract?: HudInteractListener;
     focused?: boolean;
     hovered?: boolean;
     size?: number;

package/dist/actionHud.js

@@ -2,6 +2,9 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState, } from "react";
 import { actionByHotkey, actionCooldownFromFraction, actionCost, moveGridFocus, resolveActionCollection, } from "@jgengine/core/ui/actionModel";
 import { actionTooltip, placePopover } from "@jgengine/core/ui/tooltipModel";
+import { useEngineStyles } from "./engineStyles.js";
+import { useHudInteract } from "./hudInteract.js";
+import { HUD_FOCUS_RING, hudElevation, hudFont, hudType } from "./hudTokens.js";
 import { Keycap } from "./keyHint.js";
 /**
  * Composable React renderers over the headless action view model (`@jgengine/core/ui/actionModel`) —
@@ -126,8 +129,11 @@ const ITEM_BASE = {
     border: "var(--jg-slot-border, 1px solid rgba(255,255,255,0.14))",
     borderRadius: "var(--jg-slot-radius, 8px)",
     background: "var(--jg-slot-bg, rgba(14,17,22,0.72))",
-    color: "#eef2f8",
-    font: "600 12px/1.1 ui-sans-serif, system-ui, sans-serif",
+    color: "var(--jg-text, #eef2f8)",
+    fontFamily: hudFont.body,
+    fontSize: hudType("xs"),
+    fontWeight: 600,
+    lineHeight: 1.1,
     cursor: "pointer",
     userSelect: "none",
     overflow: "hidden",
@@ -141,32 +147,43 @@ const ITEM_BASE = {
  *
  * @capability action-button cooldown/cost/hotkey action button with complete interaction states
  */
-export function ActionButton({ action, focused = false, hovered = false, size = 52, showHotkey = true, tabIndex, buttonRef, onActivate, onFocus, onHover, renderIcon, className, style, }) {
+export function ActionButton({ action, focused = false, hovered = false, size = 52, showHotkey = true, tabIndex, buttonRef, onActivate, onFocus, onHover, renderIcon, cue, onInteract, className, style, }) {
     const tip = actionTooltip(action);
     const title = [tip.title, ...(tip.notes ?? [])].join("\n");
     const cooldown = action.cooldown;
     const wipeDeg = cooldown !== null && !cooldown.ready ? Math.round(cooldown.fraction * 360) : 0;
-    return (_jsxs("button", { type: "button", ref: buttonRef, className: className, "data-action-id": action.id, "data-active": action.active ? "" : undefined, "data-enabled": action.enabled ? "" : undefined, "data-focused": focused ? "" : undefined, "aria-disabled": !action.enabled, "aria-pressed": action.active, "aria-keyshortcuts": action.hotkey, "aria-label": action.label, title: title, tabIndex: tabIndex, onClick: () => onActivate?.(action.id), onFocus: () => onFocus?.(action.id), onPointerEnter: () => onHover?.(action.id), onPointerLeave: () => onHover?.(null), style: {
+    useEngineStyles();
+    const report = useHudInteract("action", cue ?? action.id, onInteract);
+    return (_jsxs("button", { type: "button", ref: buttonRef, className: className, "data-action-id": action.id, "data-active": action.active ? "" : undefined, "data-enabled": action.enabled ? "" : undefined, "data-focused": focused ? "" : undefined, "data-jg-cue": cue ?? action.id, "aria-disabled": !action.enabled, "aria-pressed": action.active, "aria-keyshortcuts": action.hotkey, "aria-label": action.label, title: title, tabIndex: tabIndex, onClick: () => {
+            report("activate");
+            onActivate?.(action.id);
+        }, onFocus: () => onFocus?.(action.id), onPointerDown: () => {
+            if (action.enabled)
+                report("press");
+        }, onPointerEnter: () => {
+            if (action.enabled)
+                report("hover");
+            onHover?.(action.id);
+        }, onPointerLeave: () => onHover?.(null), style: {
             ...ITEM_BASE,
             width: size,
             height: size,
-            opacity: action.enabled ? 1 : 0.5,
+            opacity: action.enabled ? 1 : "var(--jg-disabled-opacity, 0.45)",
             borderColor: action.active
-                ? "rgba(56,189,248,0.95)"
+                ? "var(--jg-accent, #38bdf8)"
                 : focused
-                    ? "rgba(148,197,255,0.9)"
+                    ? "var(--jg-edge-bright, rgba(148,197,255,0.9))"
                     : hovered
                         ? "rgba(255,255,255,0.3)"
-                        : "rgba(255,255,255,0.14)",
+                        : undefined,
             boxShadow: focused
-                ? "0 0 0 2px rgba(96,165,250,0.7)"
+                ? HUD_FOCUS_RING
                 : action.active
-                    ? "0 0 0 1px rgba(56,189,248,0.6)"
-                    : "none",
-            transform: hovered && action.enabled ? "translateY(-1px)" : "none",
-            transition: "transform 120ms ease, border-color 120ms ease, box-shadow 120ms ease",
+                    ? "0 0 0 1px var(--jg-accent, #38bdf8), 0 0 14px var(--jg-accent-glow, rgba(56,189,248,0.5))"
+                    : hudElevation("raised"),
+            translate: hovered && action.enabled ? "0 var(--jg-hover-lift, -1px)" : undefined,
             ...style,
-        }, children: [showHotkey && action.hotkey !== undefined ? (_jsx("span", { style: { position: "absolute", top: 2, left: 3 }, "aria-hidden": true, children: _jsx(Keycap, { style: { fontSize: 9, padding: "0 3px", opacity: 0.85 }, children: action.hotkey }) })) : null, _jsx("span", { style: { fontSize: renderIcon ? undefined : 18, lineHeight: 1 }, "data-action-icon": true, "aria-hidden": true, children: renderIcon ? renderIcon(action) : (action.icon ?? action.label.slice(0, 2)) }), action.costs.length > 0 ? (_jsx("span", { "data-action-costs": true, style: { display: "flex", gap: 4, fontSize: 9 }, children: action.costs.map((cost) => (_jsx("span", { style: { color: cost.met ? "rgba(147,197,253,0.9)" : "#f87171" }, children: cost.amount }, cost.resourceId))) })) : null, wipeDeg > 0 ? (_jsx("span", { "data-action-cooldown": true, "aria-hidden": true, style: {
+        }, children: [showHotkey && action.hotkey !== undefined ? (_jsx("span", { style: { position: "absolute", top: 2, left: 3 }, "aria-hidden": true, children: _jsx(Keycap, { style: { fontSize: hudType("xs"), padding: "0 3px", opacity: 0.85 }, children: action.hotkey }) })) : null, _jsx("span", { style: { fontSize: renderIcon ? undefined : 18, lineHeight: 1 }, "data-action-icon": true, "aria-hidden": true, children: renderIcon ? renderIcon(action) : (action.icon ?? action.label.slice(0, 2)) }), action.costs.length > 0 ? (_jsx("span", { "data-action-costs": true, style: { display: "flex", gap: 4, fontSize: hudType("xs") }, children: action.costs.map((cost) => (_jsx("span", { style: { color: cost.met ? "rgba(147,197,253,0.9)" : "#f87171" }, children: cost.amount }, cost.resourceId))) })) : null, wipeDeg > 0 ? (_jsx("span", { "data-action-cooldown": true, "aria-hidden": true, style: {
                     position: "absolute",
                     inset: 0,
                     pointerEvents: "none",
@@ -287,8 +304,11 @@ export function ActionTooltip({ content, className, style, }) {
             background: "rgba(8,10,14,0.95)",
             border: "1px solid rgba(255,255,255,0.14)",
             color: "#eef2f8",
-            font: "500 12px/1.35 ui-sans-serif, system-ui, sans-serif",
-            boxShadow: "0 8px 24px rgba(0,0,0,0.5)",
+            fontFamily: hudFont.body,
+            fontSize: hudType("xs"),
+            fontWeight: 500,
+            lineHeight: 1.35,
+            boxShadow: hudElevation("overlay"),
             ...style,
-        }, children: [_jsxs("div", { style: { display: "flex", alignItems: "baseline", gap: 8 }, children: [_jsx("strong", { style: { fontSize: 13 }, children: content.title }), content.hotkey !== undefined ? (_jsx(Keycap, { style: { marginLeft: "auto", fontSize: 10 }, children: content.hotkey })) : null] }), content.subtitle !== undefined ? (_jsx("div", { style: { fontSize: 10, textTransform: "uppercase", letterSpacing: 0.4, opacity: 0.6 }, children: content.subtitle })) : null, content.body !== undefined ? _jsx("div", { style: { marginTop: 4, opacity: 0.9 }, children: content.body }) : null, content.costs !== undefined && content.costs.length > 0 ? (_jsx("div", { style: { marginTop: 4, display: "flex", gap: 8, fontSize: 11 }, children: content.costs.map((cost) => (_jsxs("span", { style: { color: cost.met ? "rgba(147,197,253,0.95)" : "#f87171" }, children: [cost.amount, " ", cost.resourceId] }, cost.resourceId))) })) : null, content.cooldown != null ? (_jsxs("div", { style: { marginTop: 4, fontSize: 11, opacity: 0.8 }, children: [(content.cooldown.remainingMs / 1000).toFixed(1), "s cooldown"] })) : null, content.notes !== undefined && content.notes.length > 0 ? (_jsx("div", { style: { marginTop: 6, paddingTop: 4, borderTop: "1px solid rgba(255,255,255,0.1)", fontSize: 11, color: "#fca5a5" }, children: content.notes.map((note) => (_jsx("div", { children: note }, note))) })) : null] }));
+        }, children: [_jsxs("div", { style: { display: "flex", alignItems: "baseline", gap: 8 }, children: [_jsx("strong", { style: { fontSize: hudType("sm") }, children: content.title }), content.hotkey !== undefined ? (_jsx(Keycap, { style: { marginLeft: "auto", fontSize: hudType("xs") }, children: content.hotkey })) : null] }), content.subtitle !== undefined ? (_jsx("div", { style: { fontSize: hudType("xs"), textTransform: "uppercase", letterSpacing: "var(--jg-tracking-label, 0.08em)", opacity: 0.65 }, children: content.subtitle })) : null, content.body !== undefined ? _jsx("div", { style: { marginTop: 4, opacity: 0.9 }, children: content.body }) : null, content.costs !== undefined && content.costs.length > 0 ? (_jsx("div", { style: { marginTop: 4, display: "flex", gap: 8, fontSize: hudType("xs") }, children: content.costs.map((cost) => (_jsxs("span", { style: { color: cost.met ? "rgba(147,197,253,0.95)" : "#f87171" }, children: [cost.amount, " ", cost.resourceId] }, cost.resourceId))) })) : null, content.cooldown != null ? (_jsxs("div", { style: { marginTop: 4, fontSize: hudType("xs"), opacity: 0.8 }, children: [(content.cooldown.remainingMs / 1000).toFixed(1), "s cooldown"] })) : null, content.notes !== undefined && content.notes.length > 0 ? (_jsx("div", { style: { marginTop: 6, paddingTop: 4, borderTop: "1px solid rgba(255,255,255,0.1)", fontSize: hudType("xs"), color: "#fca5a5" }, children: content.notes.map((note) => (_jsx("div", { children: note }, note))) })) : null] }));
 }

package/dist/bars.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import {} from "react";
 import { useEntityStat, useGameStore, localPlayerEntity } from "./hooks.js";
+import { hudType } from "./hudTokens.js";
 const TOKEN_VAR = {
     health: "--jg-health",
     healthLow: "--jg-health-low",
@@ -85,7 +86,9 @@ function BarView({ fraction, valueText, config, label, width = 200, segments, en
             flex: endCap === undefined ? undefined : "1 1 auto",
             width: endCap === undefined ? "100%" : undefined,
             height: cssVar("height"),
-            border: `${cssVar("frameWidth")} solid ${cssVar("frame")}`,
+            // The frame never takes more than a quarter of the height, so thin bars (4px roster/overhead
+            // bars) keep a visible fill instead of collapsing to two frame lines.
+            border: `min(${cssVar("frameWidth")}, calc(${cssVar("height")} / 4)) solid ${cssVar("frame")}`,
             background: cssVar("track"),
             backgroundImage: "var(--jg-bar-skin-track, none)",
             boxShadow: cssVar("bevel"),
@@ -120,7 +123,7 @@ function BarView({ fraction, valueText, config, label, width = 200, segments, en
                     alignItems: "center",
                     justifyContent: label === undefined ? "center" : "space-between",
                     padding: "0 6px",
-                    fontSize: 11,
+                    fontSize: hudType("xs"),
                     fontWeight: 700,
                     letterSpacing: 0.3,
                     color: cssVar("text"),

package/dist/barsPreview.js

@@ -2,6 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import {} from "react";
 import { AmmoCounter, barTokens, BossBar, ExperienceBar, HealthBar, ManaBar, ShieldBar, SoulBar, StaminaBar, } from "./bars.js";
 import { hudTheme, hudThemeVars } from "./hudTheme.js";
+import { hudType } from "./hudTokens.js";
 /**
  * A deterministic preview of every atomic vitals bar plus a composed example — the fixture behind
  * #1033's visual evidence. All values are static (no game provider), so it renders identically every
@@ -28,7 +29,7 @@ function Portrait({ color }) {
         } }));
 }
 function AtomicMatrix({ label, tokens }) {
-    return (_jsxs("div", { style: { ...PANEL, ...(tokens === undefined ? {} : barTokens(tokens)) }, children: [_jsx("span", { style: { fontSize: 11, fontWeight: 700, letterSpacing: 0.6, textTransform: "uppercase", color: "rgba(255,255,255,0.6)" }, children: label }), _jsx(HealthBar, { value: 82, max: 100, label: "HP" }), _jsx(HealthBar, { value: 14, max: 100, label: "HP" }), _jsx(ShieldBar, { value: 40, max: 60, label: "SH" }), _jsx(ManaBar, { value: 55, max: 80, label: "MP" }), _jsx(StaminaBar, { value: 90, max: 100, label: "ST" }), _jsx(ExperienceBar, { value: 3, max: 10, segments: 10, showValue: false, label: "XP" }), _jsx(SoulBar, { value: 3, max: 5, segments: 5, showValue: false, label: "SOUL" }), _jsx(AmmoCounter, { loaded: 17, reserve: 90, magazine: 30 }), _jsx(BossBar, { value: 640, max: 1000, name: "Ancient Wyrm", width: "100%" }), _jsxs("div", { style: { display: "flex", alignItems: "center", gap: 8, marginTop: 4 }, children: [_jsx(Portrait, { color: tokens?.health ?? "#e5484d" }), _jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 4, flex: "1 1 auto" }, children: [_jsx(HealthBar, { value: 82, max: 100, width: "100%", showValue: false }), _jsx(ShieldBar, { value: 40, max: 60, width: "100%", showValue: false })] })] })] }));
+    return (_jsxs("div", { style: { ...PANEL, ...(tokens === undefined ? {} : barTokens(tokens)) }, children: [_jsx("span", { style: { fontSize: hudType("xs"), fontWeight: 700, letterSpacing: 0.6, textTransform: "uppercase", color: "rgba(255,255,255,0.6)" }, children: label }), _jsx(HealthBar, { value: 82, max: 100, label: "HP" }), _jsx(HealthBar, { value: 14, max: 100, label: "HP" }), _jsx(ShieldBar, { value: 40, max: 60, label: "SH" }), _jsx(ManaBar, { value: 55, max: 80, label: "MP" }), _jsx(StaminaBar, { value: 90, max: 100, label: "ST" }), _jsx(ExperienceBar, { value: 3, max: 10, segments: 10, showValue: false, label: "XP" }), _jsx(SoulBar, { value: 3, max: 5, segments: 5, showValue: false, label: "SOUL" }), _jsx(AmmoCounter, { loaded: 17, reserve: 90, magazine: 30 }), _jsx(BossBar, { value: 640, max: 1000, name: "Ancient Wyrm", width: "100%" }), _jsxs("div", { style: { display: "flex", alignItems: "center", gap: 8, marginTop: 4 }, children: [_jsx(Portrait, { color: tokens?.health ?? "#e5484d" }), _jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 4, flex: "1 1 auto" }, children: [_jsx(HealthBar, { value: 82, max: 100, width: "100%", showValue: false }), _jsx(ShieldBar, { value: 40, max: 60, width: "100%", showValue: false })] })] })] }));
 }
 function ThemeFills() {
     const themed = hudTheme({ palette: { health: "#7fb06d", healthLow: "#d89b38" } });

package/dist/characterSheet.js

@@ -2,6 +2,7 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 import {} from "react";
 import { EquipmentSlots } from "./slots.js";
 import { HudFrame } from "./hudFrame.js";
+import { hudType } from "./hudTokens.js";
 const DEFAULT_ARRANGEMENT = [
     { id: "head", label: "Head", position: "left" },
     { id: "chest", label: "Chest", position: "left" },
@@ -29,7 +30,7 @@ export function defaultEquipLayout(items = {}) {
 }
 function SlotLabel({ children }) {
     return (_jsx("span", { style: {
-            fontSize: 9,
+            fontSize: hudType("xs"),
             letterSpacing: 0.6,
             fontVariant: "small-caps",
             textTransform: "lowercase",
@@ -92,7 +93,7 @@ export function Paperdoll({ slots, portrait, slotSize = 44, onSlotActivate, clas
     return (_jsxs("div", { "data-paperdoll": "", className: className, style: { display: "flex", flexDirection: "column", alignItems: "center", gap: 12, ...style }, children: [_jsxs("div", { style: { display: "flex", gap: 16, alignItems: "flex-start", justifyContent: "center" }, children: [column(left, "right"), _jsx("div", { "data-paperdoll-portrait": "", style: { display: "flex", alignItems: "center", justifyContent: "center", alignSelf: "stretch" }, children: portrait ?? _jsx(Silhouette, { size: slotSize * 1.4 }) }), column(right, "left")] }), bottom.length > 0 ? (_jsx("div", { style: { display: "flex", gap: 12, justifyContent: "center" }, children: bottom.map((slot) => (_jsx(EquipSlotCell, { slot: slot, slotSize: slotSize, align: "center", ...(onSlotActivate === undefined ? {} : { onSlotActivate }) }, slot.id))) })) : null] }));
 }
 function StatListRow({ row }) {
-    return (_jsxs("div", { "data-stat-row": row.id, style: { display: "flex", justifyContent: "space-between", alignItems: "baseline", gap: 12, padding: "2px 0" }, children: [_jsx("span", { style: { fontSize: 11, fontVariant: "small-caps", letterSpacing: 0.5, color: "var(--jg-bar-text, #f4f6fb)", opacity: 0.72 }, children: row.label }), _jsxs("span", { style: { fontSize: 12, fontWeight: 700, fontVariantNumeric: "tabular-nums", color: "var(--jg-accent, #38bdf8)" }, children: [row.value, row.hint !== undefined ? (_jsx("span", { style: { marginLeft: 5, fontWeight: 500, color: "var(--jg-bar-text, #f4f6fb)", opacity: 0.5 }, children: row.hint })) : null] })] }));
+    return (_jsxs("div", { "data-stat-row": row.id, style: { display: "flex", justifyContent: "space-between", alignItems: "baseline", gap: 12, padding: "2px 0" }, children: [_jsx("span", { style: { fontSize: hudType("xs"), fontVariant: "small-caps", letterSpacing: 0.5, color: "var(--jg-bar-text, #f4f6fb)", opacity: 0.72 }, children: row.label }), _jsxs("span", { style: { fontSize: 12, fontWeight: 700, fontVariantNumeric: "tabular-nums", color: "var(--jg-accent, #38bdf8)" }, children: [row.value, row.hint !== undefined ? (_jsx("span", { style: { marginLeft: 5, fontWeight: 500, color: "var(--jg-bar-text, #f4f6fb)", opacity: 0.5 }, children: row.hint })) : null] })] }));
 }
 /**
  * Renders derived character stats as clean small-caps label→value rows, token-themed. Rows carrying a
@@ -112,7 +113,7 @@ export function StatList({ stats, className, style }) {
             groups.push({ name: row.group, rows: [row] });
     }
     return (_jsx("div", { "data-stat-list": "", className: className, style: { display: "flex", flexDirection: "column", gap: 4, ...style }, children: groups.map((group, index) => (_jsxs("div", { "data-stat-group": group.name ?? "", children: [group.name !== undefined ? (_jsx("div", { style: {
-                        fontSize: 9,
+                        fontSize: hudType("xs"),
                         letterSpacing: 1.4,
                         textTransform: "uppercase",
                         opacity: 0.55,
@@ -130,5 +131,5 @@ export function StatList({ stats, className, style }) {
  */
 export function CharacterSheet({ slots, stats, name, subtitle, portrait, header, title = "Character", variation = "themed", slotSize, onSlotActivate, className, style, }) {
     const hasHeader = header !== undefined || name !== undefined || subtitle !== undefined;
-    return (_jsx(HudFrame, { variation: variation, title: title, interactive: true, padding: 14, ...(className === undefined ? {} : { className }), ...(style === undefined ? {} : { style }), children: _jsxs("div", { "data-character-sheet": "", style: { display: "flex", flexDirection: "column", gap: 12, minWidth: 260 }, children: [hasHeader ? (_jsx("div", { "data-character-header": "", style: { display: "flex", flexDirection: "column", gap: 1 }, children: header ?? (_jsxs(_Fragment, { children: [name !== undefined ? _jsx("div", { style: { fontSize: 16, fontWeight: 800, letterSpacing: 0.2 }, children: name }) : null, subtitle !== undefined ? (_jsx("div", { style: { fontSize: 11, opacity: 0.65, fontVariant: "small-caps", letterSpacing: 0.4 }, children: subtitle })) : null] })) })) : null, _jsxs("div", { style: { display: "flex", gap: 18, alignItems: "flex-start", flexWrap: "wrap" }, children: [_jsx(Paperdoll, { slots: slots, ...(portrait === undefined ? {} : { portrait }), ...(slotSize === undefined ? {} : { slotSize }), ...(onSlotActivate === undefined ? {} : { onSlotActivate }) }), _jsx(StatList, { stats: stats, style: { flex: "1 1 140px", minWidth: 140 } })] })] }) }));
+    return (_jsx(HudFrame, { variation: variation, title: title, interactive: true, padding: 14, ...(className === undefined ? {} : { className }), ...(style === undefined ? {} : { style }), children: _jsxs("div", { "data-character-sheet": "", style: { display: "flex", flexDirection: "column", gap: 12, minWidth: 260 }, children: [hasHeader ? (_jsx("div", { "data-character-header": "", style: { display: "flex", flexDirection: "column", gap: 1 }, children: header ?? (_jsxs(_Fragment, { children: [name !== undefined ? _jsx("div", { style: { fontSize: 16, fontWeight: 800, letterSpacing: 0.2 }, children: name }) : null, subtitle !== undefined ? (_jsx("div", { style: { fontSize: hudType("xs"), opacity: 0.65, fontVariant: "small-caps", letterSpacing: 0.4 }, children: subtitle })) : null] })) })) : null, _jsxs("div", { style: { display: "flex", gap: 18, alignItems: "flex-start", flexWrap: "wrap" }, children: [_jsx(Paperdoll, { slots: slots, ...(portrait === undefined ? {} : { portrait }), ...(slotSize === undefined ? {} : { slotSize }), ...(onSlotActivate === undefined ? {} : { onSlotActivate }) }), _jsx(StatList, { stats: stats, style: { flex: "1 1 140px", minWidth: 140 } })] })] }) }));
 }

package/dist/coachMarks.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useLayoutEffect, useReducer, useState } from "react";
+import { hudType } from "./hudTokens.js";
 /**
  * Subscribe to a coach-mark sequence and re-render on every change, returning the
  * current step view (or `null` when the tour is complete or waiting on a gate).
@@ -63,11 +64,11 @@ export function CoachMark({ view, positionStyle, onNext, onSkip, nextLabel = "Ne
             pointerEvents: "auto",
             ...positionStyle,
             ...style,
-        }, children: [_jsxs("div", { "data-coach-mark-counter": true, style: { fontSize: 10, letterSpacing: 1.4, textTransform: "uppercase", fontWeight: 700, color: t.accent }, children: [view.index + 1, " of ", view.total] }), _jsx("div", { "data-coach-mark-title": true, style: { marginTop: 6, fontSize: 15, fontWeight: 700 }, children: view.step.title }), view.step.body !== undefined ? (_jsx("p", { "data-coach-mark-body": true, style: { margin: "6px 0 0", fontSize: 12.5, lineHeight: 1.5, color: "rgba(203,213,225,0.85)" }, children: view.step.body })) : null, _jsxs("div", { style: { marginTop: 14, display: "flex", alignItems: "center", justifyContent: "space-between", gap: 10 }, children: [_jsx("button", { type: "button", "data-coach-mark-skip": true, onClick: onSkip, style: {
+        }, children: [_jsxs("div", { "data-coach-mark-counter": true, style: { fontSize: hudType("xs"), letterSpacing: 1.4, textTransform: "uppercase", fontWeight: 700, color: t.accent }, children: [view.index + 1, " of ", view.total] }), _jsx("div", { "data-coach-mark-title": true, style: { marginTop: 6, fontSize: 15, fontWeight: 700 }, children: view.step.title }), view.step.body !== undefined ? (_jsx("p", { "data-coach-mark-body": true, style: { margin: "6px 0 0", fontSize: 12.5, lineHeight: 1.5, color: "rgba(203,213,225,0.85)" }, children: view.step.body })) : null, _jsxs("div", { style: { marginTop: 14, display: "flex", alignItems: "center", justifyContent: "space-between", gap: 10 }, children: [_jsx("button", { type: "button", "data-coach-mark-skip": true, onClick: onSkip, style: {
                             border: "none",
                             background: "transparent",
                             color: "rgba(148,163,184,0.85)",
-                            fontSize: 11.5,
+                            fontSize: hudType("xs"),
                             cursor: "pointer",
                             padding: 0,
                             textDecoration: "underline",

package/dist/codex.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo, useState } from "react";
+import { hudType } from "./hudTokens.js";
 const ALL = "__all";
 const MASK = "???";
 /**
@@ -27,7 +28,7 @@ export function Codex({ entries, title = "Codex", columns = 3, maskSecrets = tru
         background: active ? "rgba(56,189,248,0.2)" : "transparent",
         color: active ? "#bae6fd" : "rgba(226,232,240,0.75)",
         padding: "3px 9px",
-        fontSize: 11,
+        fontSize: hudType("xs"),
         fontWeight: 600,
         cursor: "pointer",
     });
@@ -40,7 +41,7 @@ export function Codex({ entries, title = "Codex", columns = 3, maskSecrets = tru
             color: "#e2e8f0",
             fontFamily: "ui-sans-serif, system-ui, sans-serif",
             ...style,
-        }, children: [_jsxs("div", { style: { display: "flex", alignItems: "baseline", justifyContent: "space-between", marginBottom: 10 }, children: [_jsx("span", { style: { fontSize: 13, fontWeight: 700, letterSpacing: 1.4, textTransform: "uppercase" }, children: title }), _jsxs("span", { style: { fontSize: 11, color: "rgba(203,213,225,0.75)", fontVariantNumeric: "tabular-nums" }, children: [discovered, "/", entries.length, " discovered"] })] }), categories.length > 0 ? (_jsxs("div", { style: { display: "flex", flexWrap: "wrap", gap: 5, marginBottom: 10 }, children: [_jsx("button", { type: "button", "data-codex-tab": ALL, style: tabStyle(tab === ALL), onClick: () => setTab(ALL), children: "All" }), categories.map((category) => (_jsx("button", { type: "button", "data-codex-tab": category, style: tabStyle(tab === category), onClick: () => setTab(category), children: category }, category)))] })) : null, shown.length === 0 ? (_jsx("p", { style: { margin: 0, fontSize: 12, color: "rgba(148,163,184,0.8)" }, children: emptyLabel })) : (_jsx("ul", { style: { listStyle: "none", margin: 0, padding: 0, display: "grid", gridTemplateColumns: `repeat(${columns}, 1fr)`, gap: 8 }, children: shown.map((entry) => {
+        }, children: [_jsxs("div", { style: { display: "flex", alignItems: "baseline", justifyContent: "space-between", marginBottom: 10 }, children: [_jsx("span", { style: { fontSize: 13, fontWeight: 700, letterSpacing: 1.4, textTransform: "uppercase" }, children: title }), _jsxs("span", { style: { fontSize: hudType("xs"), color: "rgba(203,213,225,0.75)", fontVariantNumeric: "tabular-nums" }, children: [discovered, "/", entries.length, " discovered"] })] }), categories.length > 0 ? (_jsxs("div", { style: { display: "flex", flexWrap: "wrap", gap: 5, marginBottom: 10 }, children: [_jsx("button", { type: "button", "data-codex-tab": ALL, style: tabStyle(tab === ALL), onClick: () => setTab(ALL), children: "All" }), categories.map((category) => (_jsx("button", { type: "button", "data-codex-tab": category, style: tabStyle(tab === category), onClick: () => setTab(category), children: category }, category)))] })) : null, shown.length === 0 ? (_jsx("p", { style: { margin: 0, fontSize: 12, color: "rgba(148,163,184,0.8)" }, children: emptyLabel })) : (_jsx("ul", { style: { listStyle: "none", margin: 0, padding: 0, display: "grid", gridTemplateColumns: `repeat(${columns}, 1fr)`, gap: 8 }, children: shown.map((entry) => {
                     const masked = maskSecrets && entry.secret === true && !entry.discovered;
                     const name = masked ? MASK : entry.name;
                     const icon = renderIcon?.(entry) ?? (masked ? "🔒" : entry.discovered ? entry.icon ?? "📖" : "◻");
@@ -57,6 +58,6 @@ export function Codex({ entries, title = "Codex", columns = 3, maskSecrets = tru
                                 color: "#e2e8f0",
                                 cursor: onSelect !== undefined ? "pointer" : "default",
                                 opacity: entry.discovered ? 1 : 0.7,
-                            }, children: [_jsx("span", { style: { fontSize: 24, filter: entry.discovered ? "none" : "grayscale(1) brightness(0.7)" }, children: icon }), _jsx("span", { style: { fontSize: 11, fontWeight: entry.discovered ? 700 : 500, textAlign: "center" }, children: name }), entry.discovered && entry.description !== undefined ? (_jsx("span", { style: { fontSize: 10, color: "rgba(203,213,225,0.7)", textAlign: "center" }, children: entry.description })) : null] }) }, entry.id));
+                            }, children: [_jsx("span", { style: { fontSize: 24, filter: entry.discovered ? "none" : "grayscale(1) brightness(0.7)" }, children: icon }), _jsx("span", { style: { fontSize: hudType("xs"), fontWeight: entry.discovered ? 700 : 500, textAlign: "center" }, children: name }), entry.discovered && entry.description !== undefined ? (_jsx("span", { style: { fontSize: hudType("xs"), color: "rgba(203,213,225,0.7)", textAlign: "center" }, children: entry.description })) : null] }) }, entry.id));
                 }) }))] }));
 }

package/dist/components.js

@@ -159,8 +159,15 @@ export function ToastStack({ action, limit = 4, className, renderToast, }) {
     const entries = useFeed({ action, limit });
     if (entries.length === 0)
         return null;
-    const newestFirst = [...entries].reverse();
-    return (_jsx("div", { className: className, "data-toast-stack": action, children: newestFirst.map((entry, index) => (_jsx("div", { "data-toast": true, children: renderToast !== undefined ? renderToast(entry, index) : defaultToast(entry) }, `${entry.at}-${index}`))) }));
+    // Keys stay stable as newer entries arrive so a toast's entrance animation plays once.
+    const seen = new Map();
+    const keyed = entries.map((entry) => {
+        const n = seen.get(entry.at) ?? 0;
+        seen.set(entry.at, n + 1);
+        return { entry, key: `${entry.at}-${n}` };
+    });
+    const newestFirst = keyed.reverse();
+    return (_jsx("div", { className: className, "data-toast-stack": action, children: newestFirst.map(({ entry, key }, index) => (_jsx("div", { "data-toast": true, children: renderToast !== undefined ? renderToast(entry, index) : defaultToast(entry) }, key))) }));
 }
 export function DeathScreen({ statId = "health", open, className, children, }) {
     const dead = useLocalPlayerDead(statId);

package/dist/creditsScreen.js

@@ -1,5 +1,6 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import {} from "react";
+import { hudType } from "./hudTokens.js";
 /**
  * Renders a {@link CreditsDocument} as headed sections of credited lines. Skinned entirely through
  * the `--jg-*` HudTheme tokens, so it inherits the game's look from the surrounding theme block;
@@ -22,7 +23,7 @@ export function CreditsScreen({ document, className, style, renderEntry, }) {
                 }, children: document.title })), document.sections.map((section) => (_jsxs("section", { "data-jg": "credits-section", style: { display: "flex", flexDirection: "column", gap: 8 }, children: [_jsx("h3", { style: {
                             margin: 0,
                             fontFamily: "var(--jg-font-display, inherit)",
-                            fontSize: 11,
+                            fontSize: hudType("xs"),
                             fontWeight: 700,
                             letterSpacing: "0.24em",
                             textTransform: "uppercase",

package/dist/engineStyles.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 declare const ENGINE_STYLESHEET: string;
+/** Injects {@link ENGINE_STYLESHEET} into `doc` once. Safe to call repeatedly and during SSR (no-op). */
+export declare function ensureEngineStyles(doc?: Document | undefined): void;
+/**
+ * Ensures the engine stylesheet is in the document before the calling component paints. Engine
+ * primitives call it, so they animate and show interaction states even outside the shell.
+ *
+ * @capability engine-styles inject the engine stylesheet (jg-* keyframes, interaction states, reduced motion) once
+ */
+export declare function useEngineStyles(): void;