@jgengine/react 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -12,6 +12,32 @@ 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.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/components.d.ts

@@ -12,7 +12,14 @@ export declare function SlotGrid({ inventoryId, className, renderSlot, }: {
     className?: string;
     renderSlot?: (slot: InventorySlot, index: number) => ReactNode;
 }): import("react").JSX.Element;
-export declare function HealthBar({ instanceId, statId, className, fillClassName, }: {
+/**
+ * A headless, unstyled stat meter — an accessible `role="progressbar"` you paint entirely through
+ * `className`/`fillClassName`. This is the class-hook primitive for teams supplying their own CSS;
+ * for a batteries-included themed bar use the atomic, token-styled components in
+ * `@jgengine/react/bars` (`HealthBar`, `ShieldBar`, …). Renamed from `HealthBar` in #1033 so the
+ * purpose-named atomic bar owns that name and no two components share it.
+ */
+export declare function StatMeter({ instanceId, statId, className, fillClassName, }: {
     instanceId: string;
     statId: string;
     className?: string;

package/dist/components.js

@@ -17,7 +17,14 @@ export function SlotGrid({ inventoryId, className, renderSlot, }) {
                     ? `${slot.itemId} x${slot.count}`
                     : null }, index))) }));
 }
-export function HealthBar({ instanceId, statId, className, fillClassName, }) {
+/**
+ * A headless, unstyled stat meter — an accessible `role="progressbar"` you paint entirely through
+ * `className`/`fillClassName`. This is the class-hook primitive for teams supplying their own CSS;
+ * for a batteries-included themed bar use the atomic, token-styled components in
+ * `@jgengine/react/bars` (`HealthBar`, `ShieldBar`, …). Renamed from `HealthBar` in #1033 so the
+ * purpose-named atomic bar owns that name and no two components share it.
+ */
+export function StatMeter({ instanceId, statId, className, fillClassName, }) {
     const stat = useEntityStat(instanceId, statId);
     if (stat === null)
         return null;

package/dist/hooks.d.ts

@@ -1,4 +1,6 @@
+import { type DependencyList } from "react";
 import { AxisChannel, type AxisChannelConfig } from "@jgengine/core/input/axisInput";
+import { type MarkerSet } from "@jgengine/core/world/markers";
 import type { GameContext } from "@jgengine/core/runtime/gameContext";
 import type { AbilityKit, AbilitySlotSnapshot } from "@jgengine/core/combat/abilityKit";
 import type { EventMeter } from "@jgengine/core/stats/eventMeter";
@@ -123,6 +125,24 @@ export interface EventMeterView {
  * @capability event-meter-hud render a core event/heat meter's live value, fraction, tier, and ready state in a HUD gauge
  */
 export declare function useEventMeter(meter: EventMeter, options?: AbilitySlotBindingOptions): EventMeterView;
+/**
+ * A self-ticking {@link MarkerSet} kept in sync with the live scene: on a
+ * heartbeat (default 100ms, and once immediately) it clears the set and calls
+ * `rebuild(markers, ctx)` to repopulate it from the current scene, so a HUD map
+ * never hand-rolls a `setInterval` + `markers.clear()` + rescan. Each heartbeat
+ * also re-renders the calling component, so player-centered props derived from
+ * the live scene each tick (`center`, `facingYaw`, zone name) stay fresh — this
+ * fully subsumes the hand-rolled ticker, not just the marker rebuild. The set is
+ * stable across renders and re-seeded whenever `ctx`, `intervalMs`, or the
+ * supplied `deps` change. SSR-safe: the heartbeat only arms when `window` is
+ * available.
+ *
+ * @capability live-markers a self-ticking MarkerSet kept in sync from the live scene each HUD tick — pass a rebuild(markers, ctx) that clears+repopulates, no hand-rolled setInterval
+ */
+export declare function useLiveMarkers(rebuild: (markers: MarkerSet, ctx: GameContext) => void, options?: {
+    intervalMs?: number;
+    deps?: DependencyList;
+}): MarkerSet;
 type HeldKeyEventTarget = Pick<Window, "addEventListener" | "removeEventListener">;
 export declare function createHeldKeyTracker(target: HeldKeyEventTarget): {
     isDown: (code: string) => boolean;

package/dist/hooks.js

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { AxisChannel } from "@jgengine/core/input/axisInput";
+import { createMarkerSet } from "@jgengine/core/world/markers";
 import { browseSessions, } from "@jgengine/core/multiplayer/matchmaking";
 import { resolveActivePrompt, } from "@jgengine/core/interaction/proximityPrompt";
 import { gamePhase, setGamePhase } from "@jgengine/core/game/gamePhase";
@@ -275,6 +276,43 @@ export function useEventMeter(meter, options) {
     previous.current = view;
     return view;
 }
+/**
+ * A self-ticking {@link MarkerSet} kept in sync with the live scene: on a
+ * heartbeat (default 100ms, and once immediately) it clears the set and calls
+ * `rebuild(markers, ctx)` to repopulate it from the current scene, so a HUD map
+ * never hand-rolls a `setInterval` + `markers.clear()` + rescan. Each heartbeat
+ * also re-renders the calling component, so player-centered props derived from
+ * the live scene each tick (`center`, `facingYaw`, zone name) stay fresh — this
+ * fully subsumes the hand-rolled ticker, not just the marker rebuild. The set is
+ * stable across renders and re-seeded whenever `ctx`, `intervalMs`, or the
+ * supplied `deps` change. SSR-safe: the heartbeat only arms when `window` is
+ * available.
+ *
+ * @capability live-markers a self-ticking MarkerSet kept in sync from the live scene each HUD tick — pass a rebuild(markers, ctx) that clears+repopulates, no hand-rolled setInterval
+ */
+export function useLiveMarkers(rebuild, options) {
+    const ctx = useGameContext();
+    const markers = useMemo(() => createMarkerSet(() => ctx.time.now()), [ctx]);
+    const rebuildRef = useRef(rebuild);
+    rebuildRef.current = rebuild;
+    const intervalMs = options?.intervalMs ?? 100;
+    const deps = options?.deps ?? [];
+    const [, forceTick] = useState(0);
+    useEffect(() => {
+        const run = () => {
+            markers.clear();
+            rebuildRef.current(markers, ctx);
+            forceTick((value) => (value + 1) % 1_000_000);
+        };
+        run();
+        if (intervalMs <= 0 || typeof window === "undefined")
+            return undefined;
+        const id = window.setInterval(run, intervalMs);
+        return () => window.clearInterval(id);
+        // deps is spread so callers can re-seed on their own inputs.
+    }, [markers, ctx, intervalMs, ...deps]);
+    return markers;
+}
 export function createHeldKeyTracker(target) {
     const held = new Set();
     const onKeyDown = (event) => held.add(event.code);

package/dist/hud.d.ts

@@ -7,6 +7,13 @@ export type StatTone = keyof typeof TONES;
  * A polished stat bar (health/mana/stamina/shield/xp) — a rounded, glassy meter with a tone-colored
  * fill and an optional value readout. Reads `statId` off `entityId` (defaults to the local player).
  * Renders nothing until the stat exists.
+ *
+ * @deprecated The `tone`-switched umbrella is being retired (#1033). Use the atomic, purpose-named,
+ * token-themed bars from `@jgengine/react/bars` instead — `HealthBar`, `ShieldBar`, `ManaBar`,
+ * `StaminaBar`, `ExperienceBar`, `SoulBar`, `BossBar`, `AmmoCounter` — each does one readout and is
+ * restyled globally via the shared `--jg-*` tokens (`barTokens`). Kept as a thin shim during migration.
+  *
+ * @capability hud-stat-bar optional stat-bound bar building block (health, mana, stamina) — prefer game-owned chrome
  */
 export declare function StatBar({ statId, entityId, tone, label, showValue, width, icon, style, className, }: {
     statId?: string;
@@ -20,14 +27,20 @@ export declare function StatBar({ statId, entityId, tone, label, showValue, widt
     className?: string;
 }): import("react").JSX.Element | null;
 /**
- * A numbered hotbar bound to an inventory — glassy slots, an active-slot highlight, item id + count,
- * and a keycap per slot. Place it and pass the `inventoryId`; `activeSlot` highlights the equipped one.
+ * A numbered hotbar bound to an inventory — painted iconed slots (a `GameIcon` glyph over a
+ * school-keyed gradient with a count badge, #1035), an active-slot highlight, and a keycap per slot.
+ * Place it and pass the `inventoryId`; `activeSlot` highlights the equipped one. Supply `itemIcon` to
+ * map your item ids to your own glyphs — the default resolves a `GameIcon` from the item id.
+  *
+ * @capability hud-hotbar optional inventory hotbar building block — games own slot chrome
  */
-export declare function Hotbar({ inventoryId, activeSlot, keys, slotSize, style, className, }: {
+export declare function Hotbar({ inventoryId, activeSlot, keys, slotSize, itemIcon, style, className, }: {
     inventoryId: string;
     activeSlot?: number;
     keys?: readonly string[];
     slotSize?: number;
+    /** Caller-supplied item id → icon registry; return null/undefined to fall back to the default glyph. */
+    itemIcon?: (itemId: string) => ReactNode;
     style?: CSSProperties;
     className?: string;
 }): import("react").JSX.Element;
@@ -49,6 +62,8 @@ export declare function Speedometer({ entityId, scale, unit, max, size, style, c
  * A time-of-day clock reading the sim calendar — `Day N · HH:MM`, 24h or 12h. `controls` adds
  * pause + the game's speed multipliers as clickable pills (the "fast-forward" bar), off by default so
  * a game opts into letting the player scrub time.
+  *
+ * @capability hud-clock in-game time-of-day readout bound to the sim clock
  */
 export declare function Clock({ format, showDay, controls, style, className, }: {
     format?: "24h" | "12h";
@@ -68,7 +83,9 @@ export declare function WaveBanner({ wave, label, subtitle, style, className, }:
     style?: CSSProperties;
     className?: string;
 }): import("react").JSX.Element;
-/** A currency counter — an icon (emoji/char, default a coin) plus the live amount for `currencyId`. */
+/** A currency counter — an icon (emoji/char, default a coin) plus the live amount for `currencyId`.  *
+ * @capability hud-coins currency counter widget bound to a currency id
+ */
 export declare function Coins({ currencyId, icon, style, className, }: {
     currencyId: string;
     icon?: ReactNode;