@jgengine/react 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -12,6 +12,58 @@ Agents building on the published SDK can also read this programmatically:
 same data as typed values, so an updater can diff its installed version against
 the latest and surface the migration steps.
 
+## 0.13.0
+
+### Migrate
+
+- **Nothing required** — this release is additive fixes, defaults, and new drop-in primitives. Bump `@jgengine/*` pins to `^0.13.0` (CLI `jgengine` is 0.10.0; `@jgengine/github` unchanged at 0.1.0) and rebuild.
+- Two defaults changed in the player's favor, both overridable: **offline games now persist to localStorage automatically** (#1207) and **rigged catalog assets animate by default** via clip metadata + semantic clip roles (#1209). If a game relied on rigged models staying frozen or on saves being memory-only, opt out explicitly; otherwise you get better behavior for free.
+
+### Added
+
+- **Drop-in inventory grid, window manager, and character sheet** (#1220) — `@jgengine/react` ships `InventoryGrid` (real drag/stack/split), a toggleable-window system (`panels`: bag, character sheet, spellbook-style windows with `@jgengine/core/ui/panelModel` state), and a `CharacterSheet` paperdoll, all HudTheme-skinnable — wire in a line or two instead of re-deriving from raw divs.
+- **Serializable runtime snapshots** (#1179) — capture/restore of live runtime state, including magazine state (`@jgengine/core/combat/magazine`) and stat modifiers, for saves and replication.
+- **Portable weapon plumbing** (#1211) — `@jgengine/core/combat/weaponFire` composes trigger → magazine → spread → projectile/hitscan as data, no game-local glue.
+- **Portable leveling** (#1206) and **portable damage-pool access** (#1208) — progression and damage pools exposed as genre-agnostic seams on the game context.
+- **Named combat VFX presets** (#1204) — `@jgengine/core/combat/vfxPresets`: a visible attack is one line.
+- **Runtime-measured render-bounds hitboxes** (#1227) — colliders wrap what the shell actually mounts, not the raw asset bounds.
+- **Character motion feel** — procedural part motion for rig-less part-composed characters (#1222) plus squash & stretch and death splat (#1229).
+- **City fabric** (#1191) — `streetGenerator` + `cityGenerator`, editor bake verb, street-aware lots, road junctions, grounding, and a web playground.
+- **`jgengine recipe` CLI** (#1214, #1231) — vetted wired compositions, compile-pinned against the SDK, listed and copied from the CLI.
+- **Editor/debug modes mirror to the URL** with a proper editor exit (#1203); game template ships a dependency-free WebGL screenshot script (#1202).
+
+### Changed
+
+- Offline games persist to localStorage by default (#1207); rigged assets animate by default (#1209).
+- RTS camera pan inversion fixed (#1228); sprite raycast warning silenced and duplicate nameplate health bars removed (#1194); scaffolded F2+E editor Tailwind `@source` renders its theme (#1195).
+- Outside-game DX: stat-pool no-op stability, camera-transparent decor, cleaner install/version output, headless UI-intent seam (#1223); new-game briefs direct engine bugs/gaps upstream (#1200).
+
+## 0.12.0
+
+### Migrate
+
+- **Author games through `defineGame` from `@jgengine/shell`** — it is the single public authoring entry (and carries the define-game capability tag). Core's constructor was renamed `defineGame` → `defineGameDefinition` (`@jgengine/core/game/defineGame`); only hosts and tooling call it. If you imported `defineGame` from core, switch the import to `@jgengine/shell`. `GamePlayer`/`GamePlayerShell` are `@internal` now — `GameHost` is the documented mount, and it owns the editor summon (`?mode=editor`, F2+E, dev save endpoint), so delete any per-game editor bootstrap.
+- **Declare your world with `world()`** (`@jgengine/core/world/place`): `world({ id, ground: { mode, size, surface? }, physics? })` with `flat` / `round` / `voxel` / `board` ground. New scaffolds emit a thin infinite flat place instead of the old 96 m meadow. `environment()` still works but is demoted to the legacy consumption path for editor-written scene data — **nothing required** for existing games; new worlds should use `world()` and author all dressing in the editor.
+- Everything else is additive — stat pools, minimap marker sources, auction house, city/path generation, editor workspaces require no changes to existing games.
+
+### Added
+
+- **World = place: `world()` API** (#1178) — a world is substrate + laws, not a coded diorama. `@jgengine/core/world/place` ships `world({ id, ground: { mode, size, surface?, generator? }, physics? })`; size is discriminated by mode (flat `{x,z}` with `Infinity` axes, round `{radius}`, voxel generator domain, board `{x,y}` cells — TS and runtime both reject mismatches). `ground.surface` carries matter/feel laws (metal vs slime vs felt) read by the same rule systems; per-place `physics` resolves over the game default; multiple worlds per game are first-class. The shell renders place substrates (`PlaceScene`) under the engine default sky; seeds derive from world id + save via `seedForPlace`.
+- **`@jgengine/shell/gameKit`** — happy-path authoring surface: authoring, mount, stores, systems, authored-scene helpers, HUD primitives, seeded rng in one import.
+- **Portable generic stat pools** — `@jgengine/core/stats/statPool`: bounded named pools (health, energy, heat, ammo…) with the entity-stats integration rebuilt on them; recipe in skill `jgengine-combat`.
+- **Auction-house economy primitives** (#1086) — `@jgengine/core/economy/auctionBook` (timed bid auctions, escrowed bids, outbid refunds, optional buyout, anti-snipe close extension, seller settlement minus house cut) plus market price history.
+- **Portable minimap marker sources** — core world seam feeding game minimaps; recipe in skill `jgengine-ui`.
+- **Unified seed-driven path network + city generation v2** (#1103, #1106) — streets/blocks/buildings with grid-ness, curviness, branching and block-size dials; zone bands, weighted building-class mixes, massing pieces, balance presets, junction-centered clustering, road-derived block polygons and parcels. Shell renders realistic roads: real intersections, curbs, lane lines, tunnels, and roads riding bridge decks.
+- **Physical fidelity** — mesh-accurate hitboxes (shots pass through holes in concave models, #1075), auto-fit entity/object colliders from measured model bounds (#1072), movement obstruction reading fitted boxes + compound-box openings (#1077).
+- **Editor overhaul** (#1110) — materials / lighting / scripting / animation-timeline / multiplayer workspaces, command palette, minimap bake wired end-to-end (#1036), real offscreen GLB thumbnails in the content browser, hierarchy drag-drop + keyboard + context menus + per-object visibility/lock, multi-select inspector, console RPC, asset drag-place, ortho projection, pivot modes, play chrome.
+- **Editor authoring pipeline** — author entity definitions and starter catalogs (#1012), author catalogs/schema fields in the Data tab (#1043), promote an authored scene folder into a runnable game (#1011), authored triggers promoted to a shared primitive with goal/win rules (#1013), asset import rewrites the game's `game/assets.ts` (#1042).
+- **Skills** — research-backed `game-design` and `level-design` skills (#962); every-game-owns-custom-UI invariant codified (#1148).
+
+### Changed
+
+- `npx jgengine create` scaffolds a thin infinite flat `world()` place; the editor `blankWorld` no longer pre-bakes seeded grass. Dressing belongs in `editor.scene.json`.
+- Environment studio visual-quality pass — turf tufts, depth-aware water, relief soil, weathered poles; grass fields no longer rebuild geometry per frame (#1090).
+
 ## 0.11.0
 
 ### Migrate

package/dist/actionHud.d.ts

@@ -120,12 +120,12 @@ export declare function ActionBarChrome({ model, layout, itemSize, gap, ariaLabe
     style?: CSSProperties;
 }): import("react").JSX.Element;
 /**
- * The batteries-included default: a skinned glass panel wrapping {@link useActionBar} +
- * {@link ActionBarChrome}. Pass `defs`, choose `grid`/`list`, and hand it `onActivate`. The renderer
- * and item chrome are still swappable via `renderItem`; a game that wants a different frame composes
- * the hook and chrome directly.
+ * Convenience composition of {@link useActionBar} + glass {@link ActionBarChrome} for demos and
+ * scaffolding — not a shipped game face. Pass `defs`, choose `grid`/`list`, and hand it `onActivate`.
+ * Games that own their UI compose the headless hook + custom chrome (or swap `renderItem`) instead
+ * of shipping this default panel.
  *
- * @capability action-bar drop-in cooldown/cost/hotkey action bar over the headless action model
+ * @capability action-bar optional skinned action-bar composition over the headless model — games own chrome
  */
 export declare function ActionBar({ defs, columns, layout, wrap, hotkeys, itemSize, ariaLabel, onActivate, renderItem, className, style, }: {
     defs: readonly ActionDef[];

package/dist/actionHud.js

@@ -113,6 +113,8 @@ export function useActionBar(defs, options) {
         onKeyDown,
     };
 }
+// Slot chrome reads the shared HudTheme tokens (#1034) with the built-in look as fallbacks, so a
+// theme restyles action slots alongside the bars/frames and a bare game is byte-identical to before.
 const ITEM_BASE = {
     position: "relative",
     boxSizing: "border-box",
@@ -121,9 +123,9 @@ const ITEM_BASE = {
     alignItems: "center",
     justifyContent: "center",
     gap: 2,
-    border: "1px solid rgba(255,255,255,0.14)",
-    borderRadius: 8,
-    background: "rgba(14,17,22,0.72)",
+    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",
     cursor: "pointer",
@@ -218,20 +220,20 @@ export function ActionBarChrome({ model, layout = "grid", itemSize = 52, gap = 6
 }
 const PANEL = {
     padding: 8,
-    borderRadius: 12,
-    background: "rgba(10,12,16,0.6)",
+    borderRadius: "var(--jg-frame-radius, 12px)",
+    background: "var(--jg-frame-bg, rgba(10,12,16,0.6))",
     backdropFilter: "blur(6px)",
     WebkitBackdropFilter: "blur(6px)",
-    border: "1px solid rgba(255,255,255,0.1)",
-    boxShadow: "0 4px 16px rgba(0,0,0,0.35)",
+    border: "var(--jg-frame-border, 1px solid rgba(255,255,255,0.1))",
+    boxShadow: "var(--jg-frame-glow, 0 4px 16px rgba(0,0,0,0.35))",
 };
 /**
- * The batteries-included default: a skinned glass panel wrapping {@link useActionBar} +
- * {@link ActionBarChrome}. Pass `defs`, choose `grid`/`list`, and hand it `onActivate`. The renderer
- * and item chrome are still swappable via `renderItem`; a game that wants a different frame composes
- * the hook and chrome directly.
+ * Convenience composition of {@link useActionBar} + glass {@link ActionBarChrome} for demos and
+ * scaffolding — not a shipped game face. Pass `defs`, choose `grid`/`list`, and hand it `onActivate`.
+ * Games that own their UI compose the headless hook + custom chrome (or swap `renderItem`) instead
+ * of shipping this default panel.
  *
- * @capability action-bar drop-in cooldown/cost/hotkey action bar over the headless action model
+ * @capability action-bar optional skinned action-bar composition over the headless model — games own chrome
  */
 export function ActionBar({ defs, columns, layout = "grid", wrap, hotkeys, itemSize, ariaLabel, onActivate, renderItem, className, style, }) {
     const model = useActionBar(defs, { columns, wrap, hotkeys, onActivate });

package/dist/bars.d.ts

@@ -0,0 +1,103 @@
+import { type CSSProperties, type ReactNode } from "react";
+/**
+ * Atomic, purpose-named vitals — one component per readout (`HealthBar`, `ShieldBar`, …), never a
+ * `tone`-switched umbrella and never a bundled combo. Every bar reads the same shared CSS custom
+ * properties (`--jg-health`, `--jg-shield`, `--jg-xp`, plus frame/shape tokens). Default token
+ * colors are scaffolding only: games own layout, framing, and art direction, and must set tokens
+ * (or replace the markup) so the HUD is unique to the pitch — the engine ships parts, not a face.
+ *
+ * Each bar accepts either an explicit `value`/`max` (pure, provider-free — for composition, tests,
+ * and preview fixtures) or binds to a live entity stat (`statId`/`entityId`, defaulting to the local
+ * player). It renders nothing until it has a value.
+ *
+ * @capability hud-vitals atomic purpose-named vitals bars (token-themed parts, not a finished HUD)
+ */
+/** The shared vitals token contract — CSS custom properties every atomic bar reads. */
+export interface BarTokens {
+    /** Fill color per readout. */
+    health?: string;
+    healthLow?: string;
+    mana?: string;
+    stamina?: string;
+    shield?: string;
+    xp?: string;
+    soul?: string;
+    ammo?: string;
+    boss?: string;
+    /** Frame + shape. */
+    track?: string;
+    frame?: string;
+    frameWidth?: string;
+    radius?: string;
+    height?: string;
+    text?: string;
+    bevel?: string;
+}
+/** Built-in default values for every vitals token — scaffolding/preview only, not a shipped look. */
+export declare const DEFAULT_BAR_TOKENS: Required<BarTokens>;
+/**
+ * A style object binding vitals tokens to CSS custom properties — spread onto any HUD ancestor to
+ * restyle every atomic bar under it at once. Only the keys you pass are set; the rest fall back to
+ * {@link DEFAULT_BAR_TOKENS} inside the bars. This is the single global-theming seam.
+ * @capability hud-vitals bind shared vitals CSS tokens onto a HUD subtree
+ */
+export declare function barTokens(tokens: BarTokens): CSSProperties;
+/** Trough shape language — `rect` (default), `pill` (fully round), `skew` (parallelogram, upright
+ * label), or `chamfer` (cut corners). Matches a game's skin without hand-rolling a local bar. */
+export type BarShape = "rect" | "pill" | "skew" | "chamfer";
+/** Shared props for every atomic bar — bound to a stat (`statId`/`entityId`) or explicit (`value`). */
+export interface AtomicBarProps {
+    /** Trough shape language. Default `rect`. */
+    shape?: BarShape;
+    /** Explicit fill color, overriding the token (and the low-threshold swap) — for per-instance
+     * colors a token can't express (e.g. a class-colored resource bar). Caller overrides win. */
+    fill?: string;
+    /** Explicit current value; when set the bar is pure and needs no game provider. */
+    value?: number;
+    /** Explicit max (default 100 when `value` is set without one). */
+    max?: number;
+    /** Explicit min (default 0). */
+    min?: number;
+    /** Stat id to bind when `value` is omitted. */
+    statId?: string;
+    /** Entity to read the stat off; defaults to the local player. */
+    entityId?: string;
+    /** Uppercase label rendered at the start of the trough. */
+    label?: string;
+    /** Show the centered `current / max` readout. Default true. */
+    showValue?: boolean;
+    /** Trough width in px (or any CSS length). Default 200. */
+    width?: number | string;
+    /** Divide the trough into N segments with tick dividers (hearts/ammo/evo style). */
+    segments?: number;
+    /** A ReactNode anchored at the start — portrait / orb / icon. Composes, never bundled. */
+    endCap?: ReactNode;
+    style?: CSSProperties;
+    className?: string;
+}
+/** Player/enemy health — danger-flashes to `--jg-health-low` below a quarter full. */
+export declare const HealthBar: (props: AtomicBarProps) => import("react").JSX.Element;
+/** Absorb/armor shield overlay. */
+export declare const ShieldBar: (props: AtomicBarProps) => import("react").JSX.Element;
+/** Spell/energy resource pool. */
+export declare const ManaBar: (props: AtomicBarProps) => import("react").JSX.Element;
+/** Sprint/action stamina pool. */
+export declare const StaminaBar: (props: AtomicBarProps) => import("react").JSX.Element;
+/** Level progress / experience. */
+export declare const ExperienceBar: (props: AtomicBarProps) => import("react").JSX.Element;
+/** Resource-charge / soul-box meter — segmented by default. */
+export declare const SoulBar: (props: AtomicBarProps) => import("react").JSX.Element;
+/** A wide encounter/boss health bar with the boss name at the start. */
+export declare function BossBar(props: AtomicBarProps & {
+    name?: string;
+}): import("react").JSX.Element;
+/** Loaded-vs-reserve ammunition counter — a segmented magazine plus a reserve tally. */
+export declare function AmmoCounter({ loaded, reserve, magazine, width, style, className, }: {
+    loaded: number;
+    reserve?: number;
+    /** Magazine capacity; drives the segment count and fill fraction. Default = `loaded`. */
+    magazine?: number;
+    width?: number | string;
+    style?: CSSProperties;
+    className?: string;
+}): import("react").JSX.Element;

package/dist/bars.js

@@ -0,0 +1,180 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import {} from "react";
+import { useEntityStat, useGameStore, localPlayerEntity } from "./hooks.js";
+const TOKEN_VAR = {
+    health: "--jg-health",
+    healthLow: "--jg-health-low",
+    mana: "--jg-mana",
+    stamina: "--jg-stamina",
+    shield: "--jg-shield",
+    xp: "--jg-xp",
+    soul: "--jg-soul",
+    ammo: "--jg-ammo",
+    boss: "--jg-boss",
+    track: "--jg-bar-track",
+    frame: "--jg-bar-frame",
+    frameWidth: "--jg-bar-frame-width",
+    radius: "--jg-bar-radius",
+    height: "--jg-bar-height",
+    text: "--jg-bar-text",
+    bevel: "--jg-bar-bevel",
+};
+/** Built-in default values for every vitals token — scaffolding/preview only, not a shipped look. */
+export const DEFAULT_BAR_TOKENS = {
+    health: "#e5484d",
+    healthLow: "#b21e23",
+    mana: "#3b82f6",
+    stamina: "#84cc16",
+    shield: "#22d3ee",
+    xp: "#a855f7",
+    soul: "#c084fc",
+    ammo: "#f8b84e",
+    boss: "#ef4444",
+    track: "rgba(0,0,0,0.55)",
+    frame: "rgba(0,0,0,0.82)",
+    frameWidth: "2px",
+    radius: "4px",
+    height: "18px",
+    text: "#f5f7fa",
+    bevel: "inset 0 2px 4px rgba(0,0,0,0.55), inset 0 -1px 2px rgba(255,255,255,0.08)",
+};
+/**
+ * A style object binding vitals tokens to CSS custom properties — spread onto any HUD ancestor to
+ * restyle every atomic bar under it at once. Only the keys you pass are set; the rest fall back to
+ * {@link DEFAULT_BAR_TOKENS} inside the bars. This is the single global-theming seam.
+ * @capability hud-vitals bind shared vitals CSS tokens onto a HUD subtree
+ */
+export function barTokens(tokens) {
+    const style = {};
+    for (const [key, value] of Object.entries(tokens)) {
+        if (value !== undefined)
+            style[TOKEN_VAR[key]] = value;
+    }
+    return style;
+}
+function clampFraction(current, min, max) {
+    const range = max - min;
+    if (range <= 0)
+        return 0;
+    return Math.max(0, Math.min(1, (current - min) / range));
+}
+function cssVar(key) {
+    return `var(${TOKEN_VAR[key]}, ${DEFAULT_BAR_TOKENS[key]})`;
+}
+const SKEW_DEG = 8;
+/** Shape → trough clip/radius/transform, plus the counter-transform that keeps the label upright. */
+function shapeStyles(shape) {
+    switch (shape) {
+        case "pill":
+            return { trough: { borderRadius: 9999 }, label: {} };
+        case "skew":
+            return { trough: { borderRadius: 2, transform: `skewX(-${SKEW_DEG}deg)` }, label: { transform: `skewX(${SKEW_DEG}deg)` } };
+        case "chamfer":
+            return { trough: { borderRadius: 0, clipPath: "polygon(7px 0, 100% 0, calc(100% - 7px) 100%, 0 100%)" }, label: {} };
+        default:
+            return { trough: { borderRadius: cssVar("radius") }, label: {} };
+    }
+}
+/** The pure, hook-free bar renderer every atomic component funnels through. */
+function BarView({ fraction, valueText, config, label, width = 200, segments, endCap, shape = "rect", fillOverride, style, className, }) {
+    const low = fillOverride === undefined && config.lowColorKey !== undefined && fraction <= (config.lowThreshold ?? 0.25);
+    const fill = fillOverride ?? cssVar(low ? config.lowColorKey : config.colorKey);
+    const shaped = shapeStyles(shape);
+    const trough = (_jsxs("div", { "data-bar": config.dataBar, "data-bar-shape": shape, "data-fill-fraction": fraction.toFixed(4), ...(low ? { "data-low": "" } : {}), style: {
+            position: "relative",
+            flex: endCap === undefined ? undefined : "1 1 auto",
+            width: endCap === undefined ? "100%" : undefined,
+            height: cssVar("height"),
+            border: `${cssVar("frameWidth")} solid ${cssVar("frame")}`,
+            background: cssVar("track"),
+            boxShadow: cssVar("bevel"),
+            overflow: "hidden",
+            boxSizing: "border-box",
+            ...shaped.trough,
+        }, children: [_jsx("div", { style: {
+                    position: "absolute",
+                    inset: 0,
+                    width: `${fraction * 100}%`,
+                    background: fill,
+                    transition: "width 160ms ease",
+                } }), _jsx("div", { style: {
+                    position: "absolute",
+                    inset: 0,
+                    width: `${fraction * 100}%`,
+                    background: "linear-gradient(180deg, rgba(255,255,255,0.28), rgba(255,255,255,0) 48%)",
+                    pointerEvents: "none",
+                } }), segments !== undefined && segments > 1
+                ? Array.from({ length: segments - 1 }, (_, index) => (_jsx("div", { style: {
+                        position: "absolute",
+                        top: 0,
+                        bottom: 0,
+                        left: `${((index + 1) / segments) * 100}%`,
+                        width: 1,
+                        background: "rgba(0,0,0,0.45)",
+                    } }, index)))
+                : null, _jsxs("div", { style: {
+                    position: "absolute",
+                    inset: 0,
+                    display: "flex",
+                    alignItems: "center",
+                    justifyContent: label === undefined ? "center" : "space-between",
+                    padding: "0 6px",
+                    fontSize: 11,
+                    fontWeight: 700,
+                    letterSpacing: 0.3,
+                    color: cssVar("text"),
+                    textShadow: "0 1px 2px rgba(0,0,0,0.85)",
+                    pointerEvents: "none",
+                }, children: [label !== undefined ? _jsx("span", { style: { textTransform: "uppercase", opacity: 0.85, ...shaped.label }, children: label }) : null, valueText !== null ? _jsx("span", { style: { fontVariantNumeric: "tabular-nums", ...shaped.label }, children: valueText }) : null] })] }));
+    if (endCap === undefined) {
+        return (_jsx("div", { className: className, style: { display: "inline-block", width, ...style }, children: trough }));
+    }
+    return (_jsxs("div", { className: className, style: { display: "flex", alignItems: "center", gap: 6, width, ...style }, children: [endCap, trough] }));
+}
+function valueReadout(current, max, show) {
+    if (!show)
+        return null;
+    return `${Math.round(current)} / ${Math.round(max)}`;
+}
+/** Renders an atomic bar from an explicit value — pure, no game provider needed. */
+function StaticBar({ props, config }) {
+    const min = props.min ?? 0;
+    const max = props.max ?? 100;
+    const current = props.value ?? 0;
+    return (_jsx(BarView, { fraction: clampFraction(current, min, max), valueText: valueReadout(current, max, props.showValue ?? true), config: config, label: props.label, width: props.width, segments: props.segments, endCap: props.endCap, shape: props.shape, fillOverride: props.fill, style: props.style, className: props.className }));
+}
+/** Renders an atomic bar bound to a live entity stat. */
+function BoundBar({ props, config, defaultStatId }) {
+    const id = useGameStore((ctx) => props.entityId ?? localPlayerEntity(ctx)?.id ?? null);
+    const stat = useEntityStat(id ?? "", props.statId ?? defaultStatId);
+    if (id === null || stat === null)
+        return null;
+    return (_jsx(BarView, { fraction: clampFraction(stat.current, stat.min, stat.max), valueText: valueReadout(stat.current, stat.max, props.showValue ?? true), config: config, label: props.label, width: props.width, segments: props.segments, endCap: props.endCap, shape: props.shape, fillOverride: props.fill, style: props.style, className: props.className }));
+}
+function atomicBar(defaultStatId, config) {
+    return function AtomicBar(props) {
+        return props.value !== undefined ? (_jsx(StaticBar, { props: props, config: config })) : (_jsx(BoundBar, { props: props, config: config, defaultStatId: defaultStatId }));
+    };
+}
+/** Player/enemy health — danger-flashes to `--jg-health-low` below a quarter full. */
+export const HealthBar = atomicBar("health", { colorKey: "health", lowColorKey: "healthLow", lowThreshold: 0.25, dataBar: "health" });
+/** Absorb/armor shield overlay. */
+export const ShieldBar = atomicBar("shield", { colorKey: "shield", dataBar: "shield" });
+/** Spell/energy resource pool. */
+export const ManaBar = atomicBar("mana", { colorKey: "mana", dataBar: "mana" });
+/** Sprint/action stamina pool. */
+export const StaminaBar = atomicBar("stamina", { colorKey: "stamina", dataBar: "stamina" });
+/** Level progress / experience. */
+export const ExperienceBar = atomicBar("xp", { colorKey: "xp", dataBar: "xp" });
+/** Resource-charge / soul-box meter — segmented by default. */
+export const SoulBar = atomicBar("soul", { colorKey: "soul", dataBar: "soul" });
+/** A wide encounter/boss health bar with the boss name at the start. */
+export function BossBar(props) {
+    const merged = { width: 420, ...props, label: props.label ?? props.name };
+    return props.value !== undefined ? (_jsx(StaticBar, { props: merged, config: { colorKey: "boss", dataBar: "boss" } })) : (_jsx(BoundBar, { props: merged, config: { colorKey: "boss", dataBar: "boss" }, defaultStatId: "health" }));
+}
+/** Loaded-vs-reserve ammunition counter — a segmented magazine plus a reserve tally. */
+export function AmmoCounter({ loaded, reserve, magazine, width = 160, style, className, }) {
+    const cap = magazine ?? Math.max(loaded, 1);
+    return (_jsxs("div", { className: className, "data-bar": "ammo", style: { display: "flex", alignItems: "center", gap: 8, width, color: cssVar("text"), ...style }, children: [_jsx("div", { style: { flex: "1 1 auto", minWidth: 0 }, children: _jsx(BarView, { fraction: clampFraction(loaded, 0, cap), valueText: `${loaded}`, config: { colorKey: "ammo", dataBar: "ammo-mag" }, width: "100%", segments: cap <= 20 ? cap : undefined, style: { display: "block" } }) }), reserve !== undefined ? (_jsxs("span", { style: { fontSize: 12, fontWeight: 700, fontVariantNumeric: "tabular-nums", opacity: 0.8, textShadow: "0 1px 2px rgba(0,0,0,0.8)" }, children: ["/", reserve] })) : null] }));
+}

package/dist/barsPreview.d.ts

@@ -0,0 +1,4 @@
+/** Renders the atomic bar matrix twice under different token blocks to prove global re-theming. */
+export declare function BarsPreview({ className }: {
+    className?: string;
+}): import("react").JSX.Element;

package/dist/barsPreview.js

@@ -0,0 +1,47 @@
+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";
+/**
+ * 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
+ * time for screenshots. Rendering the same set under two different {@link BarTokens} blocks proves
+ * that global theming survives the umbrella's decomposition: one token change restyles every bar.
+ */
+const PANEL = {
+    display: "flex",
+    flexDirection: "column",
+    gap: 8,
+    padding: 14,
+    borderRadius: 10,
+    background: "rgba(10,12,16,0.72)",
+    border: "1px solid rgba(255,255,255,0.08)",
+};
+function Portrait({ color }) {
+    return (_jsx("div", { style: {
+            width: 34,
+            height: 34,
+            borderRadius: 6,
+            background: `radial-gradient(circle at 40% 30%, ${color}, rgba(0,0,0,0.6))`,
+            border: "2px solid rgba(0,0,0,0.75)",
+            flex: "0 0 auto",
+        } }));
+}
+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 })] })] })] }));
+}
+/** Renders the atomic bar matrix twice under different token blocks to prove global re-theming. */
+export function BarsPreview({ className }) {
+    return (_jsxs("div", { "data-bars-preview": true, className: className, style: { display: "flex", gap: 16, flexWrap: "wrap", padding: 20, fontFamily: "system-ui, sans-serif", color: "#f5f7fa" }, children: [_jsx(AtomicMatrix, { label: "default tokens" }), _jsx(AtomicMatrix, { label: "restyled tokens", tokens: {
+                    health: "#2fbf71",
+                    healthLow: "#e0a80d",
+                    shield: "#f2c14e",
+                    mana: "#6c5ce7",
+                    stamina: "#00b894",
+                    xp: "#0984e3",
+                    soul: "#e17055",
+                    ammo: "#fdcb6e",
+                    frame: "#0a0a0a",
+                    radius: "2px",
+                    height: "20px",
+                } })] }));
+}

package/dist/characterSheet.d.ts

@@ -0,0 +1,120 @@
+import { type CSSProperties, type ReactNode } from "react";
+import { type SlotItem } from "./slots.js";
+import { type HudFrameVariation } from "./hudFrame.js";
+/**
+ * Character-sheet / paperdoll composition (#1033 follow-up): a drop-in `<CharacterSheet>` that
+ * arranges caller-supplied equip slots as a paperdoll around a portrait and lists derived stats,
+ * all inside a {@link HudFrame}. It reuses the atomic slot rendering ({@link EquipmentSlots}) and the
+ * shared `--jg-slot-*` / `--jg-accent` HudTheme tokens (#1034) — the game owns which slots and which
+ * stats matter (both are props), the skin, and the window that toggles it open/closed. No genre list
+ * is baked in; {@link defaultEquipLayout} is a convenience arrangement the game can override wholesale.
+ */
+/** Which flank of the paperdoll a slot sits on — `left`/`right` columns, or the `bottom` row under the portrait. */
+export type EquipSlotPosition = "left" | "right" | "bottom";
+/** One named equip slot: a stable `id`, a display `label`, its worn `item` (or `null` = empty), and where it sits. */
+export interface EquipSlot {
+    /** Stable slot id passed to `onSlotActivate` (e.g. `head`, `mainHand`, `ring1`). */
+    id: string;
+    /** Human label shown under/beside the slot and used as its accessible name. */
+    label: string;
+    /** The worn item, or `null` for an empty slot (renders the themed placeholder). */
+    item: SlotItem | null;
+    /** Which flank the slot sits on. Default `left`. */
+    position?: EquipSlotPosition;
+}
+/** An ordered set of equip slots that make up a paperdoll. Caller-supplied; see {@link defaultEquipLayout}. */
+export type EquipSlotLayout = readonly EquipSlot[];
+/** Slot ids used by {@link defaultEquipLayout}'s convenience arrangement. */
+export type DefaultEquipSlotId = "head" | "chest" | "hands" | "legs" | "feet" | "mainHand" | "offHand" | "ring1" | "ring2" | "trinket";
+/**
+ * A sensible default paperdoll arrangement — worn armor down the left flank, held gear and jewelry
+ * down the right — that the game fills by passing worn items keyed by slot id. Every id is optional;
+ * unfilled slots render empty. Games that need a different slot set pass their own {@link EquipSlotLayout}.
+ */
+export declare function defaultEquipLayout(items?: Partial<Record<DefaultEquipSlotId, SlotItem | null>>): EquipSlot[];
+/** Props for {@link Paperdoll}. */
+export interface PaperdollProps {
+    /** The equip slots to arrange. Order within a flank is preserved. */
+    slots: EquipSlotLayout;
+    /** Center node — a portrait, 3D preview, or custom art. A silhouette placeholder is drawn when omitted. */
+    portrait?: ReactNode;
+    /** Slot tile size in px. Default 44. */
+    slotSize?: number;
+    /** Fired with the slot `id` on click / Enter / Space — wire drag or an equip picker here. */
+    onSlotActivate?: (id: string) => void;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Arranges caller-supplied equip slots as a paperdoll — worn gear in two flanking columns around a
+ * center `portrait` (or a silhouette placeholder), with any `bottom` slots in a row beneath it. Each
+ * slot reuses the atomic {@link EquipmentSlots} tile (filled icon or themed empty placeholder), carries
+ * a label, and is a focusable `role="group"` with an `aria-label`; `onSlotActivate` fires on
+ * click/Enter/Space so games can wire drag or an equip picker. Composition and skin stay the game's.
+ *
+ * @capability character-paperdoll equip-slot paperdoll — flanking columns around a portrait, activatable slots
+ */
+export declare function Paperdoll({ slots, portrait, slotSize, onSlotActivate, className, style }: PaperdollProps): ReactNode;
+/** One derived-stat row. `group` optionally buckets rows under a small header. */
+export interface StatRow {
+    /** Stable row id. */
+    id: string;
+    /** Small-caps row label (e.g. `Armor`, `Crit`). */
+    label: string;
+    /** The value to show — the game formats it (a number, `"12%"`, `"1.2/s"`). */
+    value: string | number;
+    /** Optional secondary hint shown dimmed after the value (e.g. a delta or source). */
+    hint?: string;
+    /** Optional group header this row falls under; consecutive rows sharing a group render one header. */
+    group?: string;
+}
+/** Props for {@link StatList}. */
+export interface StatListProps {
+    /** Derived stat rows, in display order. The game owns which stats matter. */
+    stats: readonly StatRow[];
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Renders derived character stats as clean small-caps label→value rows, token-themed. Rows carrying a
+ * `group` field are bucketed under a small uppercase header (consecutive same-group rows share one).
+ * Pure and prop-driven — the game supplies the rows (from `useEntityStat`/derived values); the engine
+ * ships no stat list of its own.
+ *
+ * @capability character-statlist derived-stat readout — grouped small-caps label→value rows, token-themed
+ */
+export declare function StatList({ stats, className, style }: StatListProps): ReactNode;
+/** Props for {@link CharacterSheet}. */
+export interface CharacterSheetProps {
+    /** Equip slots to arrange as the paperdoll (see {@link defaultEquipLayout}). */
+    slots: EquipSlotLayout;
+    /** Derived stat rows for the {@link StatList}. */
+    stats: readonly StatRow[];
+    /** Character name shown in the header. */
+    name?: ReactNode;
+    /** Secondary header line — level, class, faction, etc. */
+    subtitle?: ReactNode;
+    /** Portrait node passed through to the {@link Paperdoll} center. */
+    portrait?: ReactNode;
+    /** Replace the whole header block (name/subtitle) with custom content. */
+    header?: ReactNode;
+    /** Frame title label. Default `Character`. */
+    title?: ReactNode;
+    /** {@link HudFrame} skin. Default `themed`. */
+    variation?: HudFrameVariation;
+    /** Slot tile size in px, forwarded to {@link Paperdoll}. */
+    slotSize?: number;
+    /** Fired with the equip slot `id` on activate. */
+    onSlotActivate?: (id: string) => void;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Drop-in character sheet: a {@link HudFrame} wrapping an optional name/subtitle/portrait header, the
+ * equip-slot {@link Paperdoll}, and the derived-stat {@link StatList}. The game supplies slots, stats,
+ * header content, and the activation callback, and owns the window that toggles it (this component does
+ * not manage its own open/close). Pure composition over existing primitives and HudTheme tokens.
+ *
+ * @capability character-sheet drop-in paperdoll + derived-stat sheet in a HudFrame — game supplies slots/stats
+ */
+export declare function CharacterSheet({ slots, stats, name, subtitle, portrait, header, title, variation, slotSize, onSlotActivate, className, style, }: CharacterSheetProps): ReactNode;