@jgengine/react 0.10.0 → 0.12.0

package/dist/fogOverlay.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function forEachUnrevealedFogCell(fog, visit) {
     let count = 0;
     for (let row = 0; row < fog.rows; row += 1) {
@@ -10,6 +11,7 @@ export function forEachUnrevealedFogCell(fog, visit) {
     }
     return count;
 }
+/** @internal */
 export function paintFogOverlay(surface, canvasSize, fog, cellRect, fill = "rgba(11, 15, 20, 0.82)") {
     surface.clearRect(0, 0, canvasSize.width, canvasSize.height);
     surface.fillStyle = fill;
@@ -20,6 +22,7 @@ export function paintFogOverlay(surface, canvasSize, fog, cellRect, fill = "rgba
         surface.fillRect(rect.x, rect.y, rect.width, rect.height);
     });
 }
+/** @internal */
 export function createFogDataUrl(fog, canvasSize, cellRect, fill = "rgba(11, 15, 20, 0.82)") {
     if (typeof document === "undefined")
         return null;

package/dist/gameViewport.js

@@ -67,6 +67,19 @@ function createRegionRegistry() {
 }
 const RegionRegistryContext = createContext(null);
 const GameLayoutContext = createContext(null);
+const INPUT_HINT_STYLE_ID = "jg-input-hints";
+const INPUT_HINT_CSS = "@media (pointer: coarse){[data-jg-kbd-hint]{display:none!important}}";
+/** Install the backstop rule that hides keyboard/mouse hints on touch, once per document. */
+function ensureInputHintStylesheet() {
+    if (typeof document === "undefined")
+        return;
+    if (document.getElementById(INPUT_HINT_STYLE_ID) !== null)
+        return;
+    const style = document.createElement("style");
+    style.id = INPUT_HINT_STYLE_ID;
+    style.textContent = INPUT_HINT_CSS;
+    document.head.appendChild(style);
+}
 const SERVER_METRICS = {
     layout: { left: 0, top: 0, right: 0, bottom: 0 },
     visual: { left: 0, top: 0, right: 0, bottom: 0 },
@@ -156,6 +169,9 @@ export function GameViewportProvider({ platforms, className, style, children, })
     const probeRef = useRef(null);
     const [safeArea, setSafeArea] = useState({ top: 0, right: 0, bottom: 0, left: 0 });
     const rootRef = useRef(null);
+    useEffect(() => {
+        ensureInputHintStylesheet();
+    }, []);
     useEffect(() => {
         const update = () => {
             const next = measureSafeArea(probeRef.current);

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";
@@ -19,6 +21,8 @@ import type { ClockSnapshot, SimClock } from "@jgengine/core/time/simClock";
 import { type PositionedPrompt } from "@jgengine/core/interaction/proximityPrompt";
 import { type GamePhase } from "@jgengine/core/game/gamePhase";
 export declare function useGameStore<T>(selector: (ctx: GameContext) => T, isEqual?: (previous: T, next: T) => boolean): T;
+/** Subscribe to a single keyed slice of the game store, returning `fallback` until the key is set. */
+export declare function useGameStoreValue<T>(key: string, fallback: T): T;
 export declare function useGame(): {
     commands: GameContext["game"]["commands"];
     events: GameEvents;
@@ -36,6 +40,15 @@ export declare function useGamePhase(): {
 export declare function useOptionalGamePhase(): GamePhase;
 export declare function useSceneEntities(): readonly SceneEntity[];
 export declare function useSceneObjects(): readonly SceneObject[];
+/**
+ * Membership-only entity id list: the returned array keeps a stable identity across per-frame pose
+ * writes and only changes when an entity spawns, despawns, or the store is hydrated (#625). A marker
+ * mapped from these ids reads its own live pose imperatively (useFrame), so the actor tree no longer
+ * re-reconciles every frame. Prefer this over {@link useSceneEntities} for large scenes.
+ */
+export declare function useSceneEntityIds(): readonly string[];
+/** Membership-only object id list — the object counterpart of {@link useSceneEntityIds}; stable across move/rotate/setVisual, changes only on place/remove. */
+export declare function useSceneObjectIds(): readonly string[];
 export declare function useWorldItems(): readonly WorldItemRecord[];
 /** Nearest ground item within `radius` of the local player — drives a pickup prompt/highlight. */
 export declare function useNearestWorldItem(radius: number): WorldItemRecord | null;
@@ -90,19 +103,46 @@ export declare function useGameClock(): ClockSnapshot & {
 };
 export declare function useActivePrompt<T extends PositionedPrompt>(prompts?: readonly T[]): T | null;
 export declare function abilityKitNeedsHeartbeat(kit: AbilityKit, resourceAvailable?: number): boolean;
+/** True when `meter`'s value/fraction/tier/ready diverge from `previous` — the re-render check `useEventMeter` polls on its heartbeat. */
 export declare function eventMeterNeedsHeartbeat(meter: EventMeter, previous: EventMeterView | null): boolean;
 export interface AbilitySlotBindingOptions {
     intervalMs?: number;
 }
 export declare function useAbilitySlots(kit: AbilityKit, resourceAvailable?: number, options?: AbilitySlotBindingOptions): AbilitySlotSnapshot[];
 export declare function useAbilitySlot(kit: AbilityKit, slotId: string, resourceAvailable?: number, options?: AbilitySlotBindingOptions): AbilitySlotSnapshot | null;
+/** A rendered snapshot of an {@link EventMeter}: current value, fill fraction, active tier, and ready-to-consume flag. */
 export interface EventMeterView {
     value: number;
     fraction: number;
     tier: string | null;
     ready: boolean;
 }
+/**
+ * Bind a `createEventMeter` (`@jgengine/core/stats/eventMeter`) heat/streak gauge to a component — the react-render
+ * half of the ult/adrenaline and streak/combo meters (`event-meter` capability) that lets a HUD gauge re-render
+ * on tick without the game hand-rolling a `useEffect`/`setInterval` heartbeat around `meter.value()`.
+ *
+ * @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";
@@ -16,6 +17,10 @@ export function useGameStore(selector, isEqual = Object.is) {
     const getSnapshot = useCallback(() => readSelectSnapshot(cacheRef.current, ctx.version(), () => selectorRef.current(ctx), (previous, next) => isEqualRef.current(previous, next)), [ctx]);
     return useSyncExternalStore(ctx.subscribe, getSnapshot, getSnapshot);
 }
+/** Subscribe to a single keyed slice of the game store, returning `fallback` until the key is set. */
+export function useGameStoreValue(key, fallback) {
+    return useGameStore((ctx) => ctx.game.store.get(key) ?? fallback);
+}
 export function useGame() {
     const ctx = useGameContext();
     return useMemo(() => ({ commands: ctx.game.commands, events: ctx.game.events }), [ctx]);
@@ -43,6 +48,23 @@ export function useSceneEntities() {
 export function useSceneObjects() {
     return useGameStore((ctx) => ctx.scene.object.list());
 }
+/**
+ * Membership-only entity id list: the returned array keeps a stable identity across per-frame pose
+ * writes and only changes when an entity spawns, despawns, or the store is hydrated (#625). A marker
+ * mapped from these ids reads its own live pose imperatively (useFrame), so the actor tree no longer
+ * re-reconciles every frame. Prefer this over {@link useSceneEntities} for large scenes.
+ */
+export function useSceneEntityIds() {
+    const ctx = useGameContext();
+    const entity = ctx.scene.entity;
+    return useSyncExternalStore(entity.subscribeMembership, entity.ids, entity.ids);
+}
+/** Membership-only object id list — the object counterpart of {@link useSceneEntityIds}; stable across move/rotate/setVisual, changes only on place/remove. */
+export function useSceneObjectIds() {
+    const ctx = useGameContext();
+    const object = ctx.scene.object;
+    return useSyncExternalStore(object.subscribeMembership, object.ids, object.ids);
+}
 export function useWorldItems() {
     return useGameStore((ctx) => ctx.scene.worldItem.list());
 }
@@ -71,8 +93,9 @@ export function useCurrency(currencyId) {
 export function useFeed({ action, limit }) {
     return useGameStore((ctx) => ctx.game.feed.recent(action, limit === undefined ? undefined : { limit }));
 }
+const EMPTY_QUESTS = [];
 export function useQuestJournal() {
-    return useGameStore((ctx) => ctx.game.quest.list(ctx.player.userId));
+    return useGameStore((ctx) => ctx.game.quest?.list(ctx.player.userId) ?? EMPTY_QUESTS);
 }
 const EMPTY_FRIENDS = [];
 const EMPTY_PARTY = [];
@@ -191,6 +214,7 @@ export function abilityKitNeedsHeartbeat(kit, resourceAvailable) {
     }
     return false;
 }
+/** True when `meter`'s value/fraction/tier/ready diverge from `previous` — the re-render check `useEventMeter` polls on its heartbeat. */
 export function eventMeterNeedsHeartbeat(meter, previous) {
     const next = {
         value: meter.value(),
@@ -227,6 +251,13 @@ export function useAbilitySlot(kit, slotId, resourceAvailable, options) {
     useEngineHeartbeat(options?.intervalMs ?? 80, () => abilityKitNeedsHeartbeat(kit, resourceAvailable));
     return kit.state(slotId, resourceAvailable);
 }
+/**
+ * Bind a `createEventMeter` (`@jgengine/core/stats/eventMeter`) heat/streak gauge to a component — the react-render
+ * half of the ult/adrenaline and streak/combo meters (`event-meter` capability) that lets a HUD gauge re-render
+ * on tick without the game hand-rolling a `useEffect`/`setInterval` heartbeat around `meter.value()`.
+ *
+ * @capability event-meter-hud render a core event/heat meter's live value, fraction, tier, and ready state in a HUD gauge
+ */
 export function useEventMeter(meter, options) {
     const previous = useRef(null);
     useEngineHeartbeat(options?.intervalMs ?? 80, () => {
@@ -245,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

@@ -0,0 +1,104 @@
+import { type CSSProperties, type ReactNode } from "react";
+/** Named color ramps for {@link StatBar} tones. `fn` maps fill fraction (0..1) → gradient stops. */
+declare const TONES: Record<string, (t: number) => [string, string]>;
+/** A stat tone — picks the bar's color ramp. */
+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;
+    entityId?: string;
+    tone?: StatTone;
+    label?: string;
+    showValue?: boolean;
+    width?: number;
+    icon?: ReactNode;
+    style?: CSSProperties;
+    className?: string;
+}): import("react").JSX.Element | null;
+/**
+ * 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, 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;
+/**
+ * A speedometer for an entity (defaults to the local player) — an SVG arc gauge + a digital readout.
+ * `scale` converts world units/second to your display unit (3.6 → km/h, 2.237 → mph); `max` sets the
+ * gauge's top of scale.
+ */
+export declare function Speedometer({ entityId, scale, unit, max, size, style, className, }: {
+    entityId?: string;
+    scale?: number;
+    unit?: string;
+    max?: number;
+    size?: number;
+    style?: CSSProperties;
+    className?: string;
+}): import("react").JSX.Element;
+/**
+ * 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";
+    showDay?: boolean;
+    controls?: boolean;
+    style?: CSSProperties;
+    className?: string;
+}): import("react").JSX.Element;
+/**
+ * A wave / round banner — a bold centered pill for "WAVE 3" style callouts, with an optional subtitle
+ * (enemies remaining, timer). Pure display: pass the current `wave` and whatever subtitle you track.
+ */
+export declare function WaveBanner({ wave, label, subtitle, style, className, }: {
+    wave: number | string;
+    label?: string;
+    subtitle?: ReactNode;
+    style?: CSSProperties;
+    className?: string;
+}): import("react").JSX.Element;
+/** 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;
+    style?: CSSProperties;
+    className?: string;
+}): import("react").JSX.Element;
+/** A minimal center crosshair reticle — four ticks around a gap. Purely presentational. */
+export declare function Crosshair({ size, gap, thickness, color, style, className, }: {
+    size?: number;
+    gap?: number;
+    thickness?: number;
+    color?: string;
+    style?: CSSProperties;
+    className?: string;
+}): import("react").JSX.Element;
+export {};

package/dist/hud.js

@@ -0,0 +1,155 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { groundSpeed } from "@jgengine/core/scene/entityStore";
+import { iconForItemId } from "./gameIcons.js";
+import { hudFrameStyle } from "./hudFrame.js";
+import { IconTreatment, schoolForItem } from "./iconTreatment.js";
+import { useCurrency, useEntityStat, useGameClock, useGameStore, useInventory, localPlayerEntity } from "./hooks.js";
+/**
+ * Optional HUD building blocks bound to live game state — not a finished game face. Every game
+ * owns custom presentation (see AGENTS.md); import these only as temporary scaffolding, previews,
+ * or under game-owned chrome. Prefer headless hooks + game markup for shipped UI. The engine
+ * mounts none of these by default. Styling is self-contained dark-glass for demos; pass
+ * `style`/`className` to override. Anything reading the player defaults to the local player entity.
+ *
+ * @capability hud-components optional health/hotbar/speed/clock/wave/currency building blocks — games own custom chrome
+ */
+const PANEL = hudFrameStyle("glass");
+/** Named color ramps for {@link StatBar} tones. `fn` maps fill fraction (0..1) → gradient stops. */
+const TONES = {
+    health: (t) => (t > 0.5 ? ["#22c55e", "#4ade80"] : t > 0.25 ? ["#f59e0b", "#fbbf24"] : ["#dc2626", "#f87171"]),
+    mana: () => ["#2563eb", "#60a5fa"],
+    stamina: () => ["#65a30d", "#a3e635"],
+    shield: () => ["#0891b2", "#22d3ee"],
+    xp: () => ["#7c3aed", "#a78bfa"],
+    neutral: () => ["#475569", "#94a3b8"],
+};
+function useLocalPlayerId(entityId) {
+    return useGameStore((ctx) => entityId ?? localPlayerEntity(ctx)?.id ?? null);
+}
+/**
+ * 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 function StatBar({ statId = "health", entityId, tone = "health", label, showValue = true, width = 200, icon, style, className, }) {
+    const id = useLocalPlayerId(entityId);
+    const stat = useEntityStat(id ?? "", statId);
+    if (id === null || stat === null)
+        return null;
+    const range = stat.max - stat.min;
+    const fraction = range <= 0 ? 0 : Math.max(0, Math.min(1, (stat.current - stat.min) / range));
+    const [from, to] = (TONES[tone] ?? TONES.neutral)(fraction);
+    return (_jsxs("div", { className: className, style: { ...PANEL, padding: "6px 8px", width, ...style }, "data-stat": statId, children: [(label !== undefined || icon !== undefined || showValue) && (_jsxs("div", { style: { display: "flex", alignItems: "center", gap: 6, marginBottom: 4, fontSize: 11, fontWeight: 600, letterSpacing: 0.3 }, children: [icon, _jsx("span", { style: { textTransform: "uppercase", opacity: 0.75 }, children: label ?? statId }), showValue ? (_jsxs("span", { style: { marginLeft: "auto", fontVariantNumeric: "tabular-nums", opacity: 0.9 }, children: [Math.round(stat.current), _jsxs("span", { style: { opacity: 0.5 }, children: [" / ", Math.round(stat.max)] })] })) : null] })), _jsx("div", { style: { height: 8, borderRadius: 999, background: "rgba(255,255,255,0.10)", overflow: "hidden" }, children: _jsx("div", { style: { width: `${fraction * 100}%`, height: "100%", borderRadius: 999, background: `linear-gradient(90deg, ${from}, ${to})`, transition: "width 160ms ease" } }) })] }));
+}
+/**
+ * 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 function Hotbar({ inventoryId, activeSlot, keys, slotSize = 46, itemIcon, style, className, }) {
+    const slots = useInventory(inventoryId);
+    return (_jsx("div", { className: className, style: { display: "flex", gap: 6, ...style }, "data-inventory": inventoryId, children: slots.map((slot, index) => {
+            const active = index === activeSlot;
+            const keycap = keys?.[index] ?? String(index + 1);
+            const custom = slot !== null ? itemIcon?.(slot.itemId) : undefined;
+            return (_jsx("div", { "data-slot": index, style: {
+                    width: slotSize,
+                    height: slotSize,
+                    position: "relative",
+                }, children: slot !== null ? (custom !== undefined && custom !== null ? (_jsx(IconTreatment, { glyph: custom, size: slotSize, count: slot.count, keycap: keycap, active: active })) : (_jsx(IconTreatment, { ...(iconForItemId(slot.itemId) === null ? {} : { icon: iconForItemId(slot.itemId) }), school: schoolForItem(slot.itemId), size: slotSize, count: slot.count, keycap: keycap, active: active }))) : (_jsx("div", { style: {
+                        ...PANEL,
+                        width: slotSize,
+                        height: slotSize,
+                        position: "relative",
+                        borderColor: active ? "rgba(56,189,248,0.9)" : "rgba(255,255,255,0.10)",
+                    }, children: _jsx("span", { style: { position: "absolute", top: 2, left: 4, fontSize: 9, fontWeight: 700, opacity: 0.55 }, children: keycap }) })) }, index));
+        }) }));
+}
+/**
+ * A speedometer for an entity (defaults to the local player) — an SVG arc gauge + a digital readout.
+ * `scale` converts world units/second to your display unit (3.6 → km/h, 2.237 → mph); `max` sets the
+ * gauge's top of scale.
+ */
+export function Speedometer({ entityId, scale = 3.6, unit = "km/h", max = 60, size = 96, style, className, }) {
+    const speed = useGameStore((ctx) => {
+        const entity = entityId === undefined ? localPlayerEntity(ctx) : ctx.scene.entity.get(entityId);
+        return entity === null ? 0 : groundSpeed(entity) * scale;
+    });
+    const fraction = Math.max(0, Math.min(1, speed / max));
+    // 240° sweep from -210° to +30°.
+    const startDeg = -210;
+    const sweep = 240;
+    const radius = size / 2 - 8;
+    const cx = size / 2;
+    const cy = size / 2;
+    const arc = (fromFrac, toFrac) => {
+        const a0 = ((startDeg + sweep * fromFrac) * Math.PI) / 180;
+        const a1 = ((startDeg + sweep * toFrac) * Math.PI) / 180;
+        const large = sweep * (toFrac - fromFrac) > 180 ? 1 : 0;
+        return `M ${cx + radius * Math.cos(a0)} ${cy + radius * Math.sin(a0)} A ${radius} ${radius} 0 ${large} 1 ${cx + radius * Math.cos(a1)} ${cy + radius * Math.sin(a1)}`;
+    };
+    return (_jsxs("div", { className: className, style: { ...PANEL, width: size, padding: 6, textAlign: "center", ...style }, children: [_jsxs("svg", { width: size - 12, height: (size - 12) * 0.72, viewBox: `0 0 ${size} ${size * 0.72}`, style: { display: "block", margin: "0 auto" }, children: [_jsx("path", { d: arc(0, 1), fill: "none", stroke: "rgba(255,255,255,0.12)", strokeWidth: 7, strokeLinecap: "round" }), _jsx("path", { d: arc(0, fraction), fill: "none", stroke: fraction > 0.85 ? "#f87171" : "#38bdf8", strokeWidth: 7, strokeLinecap: "round" })] }), _jsx("div", { style: { marginTop: -8, fontVariantNumeric: "tabular-nums", fontWeight: 700, fontSize: 18, lineHeight: 1 }, children: Math.round(speed) }), _jsx("div", { style: { fontSize: 9, opacity: 0.6, letterSpacing: 0.4, textTransform: "uppercase" }, children: unit })] }));
+}
+/**
+ * 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 function Clock({ format = "24h", showDay = true, controls = false, style, className, }) {
+    const clock = useGameClock();
+    const { hour, minute, day } = clock.calendar;
+    const label = useMemo(() => {
+        const mm = minute.toString().padStart(2, "0");
+        if (format === "12h") {
+            const h12 = hour % 12 === 0 ? 12 : hour % 12;
+            return `${h12}:${mm} ${hour < 12 ? "AM" : "PM"}`;
+        }
+        return `${hour.toString().padStart(2, "0")}:${mm}`;
+    }, [hour, minute, format]);
+    return (_jsxs("div", { className: className, style: { ...PANEL, padding: "5px 10px", display: "inline-flex", alignItems: "center", gap: 8, fontVariantNumeric: "tabular-nums", ...style }, children: [showDay ? _jsxs("span", { style: { fontSize: 11, opacity: 0.6 }, children: ["Day ", day + 1] }) : null, _jsx("span", { style: { fontWeight: 700, fontSize: 14 }, children: label }), controls ? (_jsxs("span", { style: { display: "inline-flex", gap: 3, marginLeft: 4 }, children: [_jsx(ClockPill, { label: clock.paused ? "▶" : "❚❚", active: false, onClick: () => (clock.paused ? clock.controls.play() : clock.controls.pause()) }), clock.speeds.map((s) => (_jsx(ClockPill, { label: `${s}×`, active: !clock.paused && clock.speed === s, onClick: () => clock.controls.setSpeed(s) }, s)))] })) : null] }));
+}
+function ClockPill({ label, active, onClick }) {
+    return (_jsx("button", { type: "button", onClick: onClick, style: {
+            pointerEvents: "auto",
+            cursor: "pointer",
+            fontSize: 10,
+            fontWeight: 600,
+            padding: "1px 6px",
+            borderRadius: 6,
+            border: "none",
+            color: active ? "#0a0c10" : "#cbd5e1",
+            background: active ? "#38bdf8" : "rgba(255,255,255,0.08)",
+        }, children: label }));
+}
+/**
+ * A wave / round banner — a bold centered pill for "WAVE 3" style callouts, with an optional subtitle
+ * (enemies remaining, timer). Pure display: pass the current `wave` and whatever subtitle you track.
+ */
+export function WaveBanner({ wave, label = "Wave", subtitle, style, className, }) {
+    return (_jsxs("div", { className: className, style: { ...PANEL, padding: "6px 16px", textAlign: "center", display: "inline-block", ...style }, children: [_jsx("div", { style: { fontSize: 10, letterSpacing: 2, textTransform: "uppercase", opacity: 0.65 }, children: label }), _jsx("div", { style: { fontSize: 24, fontWeight: 800, lineHeight: 1.1 }, children: wave }), subtitle !== undefined ? _jsx("div", { style: { fontSize: 11, opacity: 0.7, marginTop: 2 }, children: subtitle }) : null] }));
+}
+/** 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 function Coins({ currencyId, icon = "🪙", style, className, }) {
+    const amount = useCurrency(currencyId);
+    return (_jsxs("span", { className: className, style: { ...PANEL, padding: "3px 10px", display: "inline-flex", alignItems: "center", gap: 6, fontWeight: 700, fontVariantNumeric: "tabular-nums", ...style }, "data-currency": currencyId, children: [_jsx("span", { "aria-hidden": true, children: icon }), amount] }));
+}
+/** A minimal center crosshair reticle — four ticks around a gap. Purely presentational. */
+export function Crosshair({ size = 18, gap = 5, thickness = 2, color = "rgba(255,255,255,0.85)", style, className, }) {
+    const tick = (extra) => ({ position: "absolute", background: color, borderRadius: thickness, ...extra });
+    return (_jsx("div", { className: className, style: { position: "absolute", inset: 0, display: "flex", alignItems: "center", justifyContent: "center", pointerEvents: "none", ...style }, children: _jsxs("div", { style: { position: "relative", width: size, height: size }, children: [_jsx("div", { style: tick({ left: "50%", top: 0, width: thickness, height: size / 2 - gap, transform: "translateX(-50%)" }) }), _jsx("div", { style: tick({ left: "50%", bottom: 0, width: thickness, height: size / 2 - gap, transform: "translateX(-50%)" }) }), _jsx("div", { style: tick({ top: "50%", left: 0, height: thickness, width: size / 2 - gap, transform: "translateY(-50%)" }) }), _jsx("div", { style: tick({ top: "50%", right: 0, height: thickness, width: size / 2 - gap, transform: "translateY(-50%)" }) })] }) }));
+}

package/dist/hudFrame.d.ts

@@ -0,0 +1,47 @@
+import type { CSSProperties, ReactNode } from "react";
+/** Frame skin — `glass` (the shared dark-glass panel), `plate` (a heavier opaque plate), `retro` (a hard black-outlined frame), or `themed` (driven by the `--jg-frame-*` `HudTheme` tokens). */
+export type HudFrameVariation = "glass" | "plate" | "retro" | "themed";
+/** Frame corner shape — `rounded` (the variation's default radius), `circle` (fully round), or `square` (no radius). */
+export type HudFrameShape = "rounded" | "circle" | "square";
+/**
+ * Bare style object for a HUD frame's look (no wrapper element) — spread it onto
+ * a widget that already owns its element when it just needs the chrome CSS. The
+ * `glass` variation is byte-for-byte the shared dark-glass panel used across the
+ * built-in HUD widgets; `plate` is a heavier opaque plate; `retro` is a hard
+ * black-outlined frame. `shape` overrides the corner radius.
+ *
+ * @internal helper behind {@link HudFrame} (and the built-in HUD `PANEL`); widgets normally use `HudFrame`.
+ */
+export declare function hudFrameStyle(variation?: HudFrameVariation, shape?: HudFrameShape): CSSProperties;
+/** Props for {@link HudFrame}. */
+export interface HudFrameProps {
+    /** Frame skin (default `glass`). */
+    variation?: HudFrameVariation;
+    /** Corner shape (default `rounded`). */
+    shape?: HudFrameShape;
+    /** Small uppercase header label rendered at the top-left of the frame. */
+    title?: ReactNode;
+    /** Header content rendered at the top-right, opposite `title` (e.g. a readout or cardinal). */
+    aside?: ReactNode;
+    /** Inner padding of the frame. */
+    padding?: number | string;
+    /** Fixed frame width. */
+    width?: number | string;
+    /** Accept pointer events (default off, so the frame never eats clicks meant for the game). */
+    interactive?: boolean;
+    /** Extra class on the frame element. */
+    className?: string;
+    /** Style overrides merged last, so callers can pin exact gradients/colors. */
+    style?: CSSProperties;
+    /** Frame body. */
+    children?: ReactNode;
+}
+/**
+ * Optional framed panel primitive — a single `<div data-hud-frame>` with a `glass`,
+ * `plate`, `retro`, or `themed` skin, optional `title`/`aside` header, and caller
+ * `style` merged last. Shared building block for demos and token-themed widgets;
+ * games own product chrome and art direction (see AGENTS.md).
+ *
+ * @capability hud-frame optional framed panel skins (glass/plate/retro/themed) — games own product chrome
+ */
+export declare function HudFrame({ variation, shape, title, aside, padding, width, interactive, className, style, children, }: HudFrameProps): ReactNode;

package/dist/hudFrame.js

@@ -0,0 +1,80 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Bare style object for a HUD frame's look (no wrapper element) — spread it onto
+ * a widget that already owns its element when it just needs the chrome CSS. The
+ * `glass` variation is byte-for-byte the shared dark-glass panel used across the
+ * built-in HUD widgets; `plate` is a heavier opaque plate; `retro` is a hard
+ * black-outlined frame. `shape` overrides the corner radius.
+ *
+ * @internal helper behind {@link HudFrame} (and the built-in HUD `PANEL`); widgets normally use `HudFrame`.
+ */
+export function hudFrameStyle(variation = "glass", shape = "rounded") {
+    const base = variation === "themed"
+        ? {
+            background: "var(--jg-frame-bg, rgba(10,12,16,0.62))",
+            border: "var(--jg-frame-border, 1px solid rgba(255,255,255,0.10))",
+            borderRadius: "var(--jg-frame-radius, 10px)",
+            boxShadow: "var(--jg-frame-glow, 0 4px 16px rgba(0,0,0,0.35))",
+            color: "var(--jg-bar-text, #f4f6fb)",
+            fontFamily: "ui-sans-serif, system-ui, -apple-system, sans-serif",
+        }
+        : variation === "retro"
+            ? {
+                border: "2px solid #000",
+                borderRadius: 4,
+                boxShadow: "4px 4px 0 #000",
+                color: "#fff",
+            }
+            : variation === "plate"
+                ? {
+                    background: "rgba(16,18,24,0.92)",
+                    border: "1px solid rgba(255,255,255,0.10)",
+                    borderRadius: 10,
+                    color: "#f4f6fb",
+                    fontFamily: "ui-sans-serif, system-ui, -apple-system, sans-serif",
+                    boxShadow: "0 6px 20px rgba(0,0,0,0.45)",
+                }
+                : {
+                    background: "rgba(10,12,16,0.62)",
+                    backdropFilter: "blur(6px)",
+                    WebkitBackdropFilter: "blur(6px)",
+                    border: "1px solid rgba(255,255,255,0.10)",
+                    borderRadius: 10,
+                    color: "#f4f6fb",
+                    fontFamily: "ui-sans-serif, system-ui, -apple-system, sans-serif",
+                    boxShadow: "0 4px 16px rgba(0,0,0,0.35)",
+                };
+    if (shape === "circle")
+        return { ...base, borderRadius: 9999 };
+    if (shape === "square")
+        return { ...base, borderRadius: 0 };
+    return base;
+}
+/**
+ * Optional framed panel primitive — a single `<div data-hud-frame>` with a `glass`,
+ * `plate`, `retro`, or `themed` skin, optional `title`/`aside` header, and caller
+ * `style` merged last. Shared building block for demos and token-themed widgets;
+ * games own product chrome and art direction (see AGENTS.md).
+ *
+ * @capability hud-frame optional framed panel skins (glass/plate/retro/themed) — games own product chrome
+ */
+export function HudFrame({ variation = "glass", shape = "rounded", title, aside, padding, width, interactive, className, style, children, }) {
+    const hasHeader = title !== undefined || aside !== undefined;
+    return (_jsxs("div", { className: className, "data-hud-frame": true, style: {
+            ...hudFrameStyle(variation, shape),
+            padding,
+            width,
+            pointerEvents: interactive === true ? "auto" : undefined,
+            ...style,
+        }, children: [hasHeader ? (_jsxs("div", { "data-hud-frame-header": true, style: {
+                    display: "flex",
+                    justifyContent: "space-between",
+                    alignItems: "center",
+                    gap: 8,
+                    marginBottom: 6,
+                    fontSize: 10,
+                    letterSpacing: 1.4,
+                    textTransform: "uppercase",
+                    opacity: 0.75,
+                }, children: [_jsx("span", { children: title }), aside !== undefined ? _jsx("span", { children: aside }) : null] })) : null, children] }));
+}