@jgengine/react 0.10.0 → 0.12.0

package/README.md

@@ -1,3 +1,3 @@
 # @jgengine/react
 
-React UI layer for [JGengine](https://github.com/Noisemaker111/jgengine): `GameProvider`, hooks, and headless primitives over `@jgengine/core`. AGPL-3.0-only.
+React UI layer for [JGengine](https://github.com/Noisemaker111/jgengine): `GameProvider`, hooks, and headless primitives over `@jgengine/core`. Apache-2.0.

package/dist/actionHud.d.ts

@@ -0,0 +1,174 @@
+import { type CSSProperties, type ReactNode } from "react";
+import type { AbilitySlotSnapshot } from "@jgengine/core/combat/abilityKit";
+import { type ActionDef, type ResolvedAction } from "@jgengine/core/ui/actionModel";
+import { type PopoverSide, type TooltipContent } from "@jgengine/core/ui/tooltipModel";
+/**
+ * Composable React renderers over the headless action view model (`@jgengine/core/ui/actionModel`) —
+ * the data/renderer/chrome split for an RTS command card, an ability action bar, a build menu, or a
+ * radial. `useActionBar` is the DATA/HOOK layer (resolution + focus/hover/keyboard/hotkey), `ActionBarChrome`
+ * is the composable RENDERER (swap `renderItem` for custom chrome, or ignore it and consume the model
+ * directly for a radial), and `ActionBar` is the batteries-included default. A game swaps renderer or
+ * chrome without forking the logic. Layout, dimensions, hotkeys, and catalog-id mapping stay caller-owned.
+ */
+/**
+ * Adapt a combat {@link AbilitySlotSnapshot} into an {@link ActionDef} — the glue that binds an
+ * `AbilityKit` (via `useAbilitySlots`) to the action renderers without the game re-deriving cooldown
+ * and cost shapes. `extra` supplies the caller-owned bits the snapshot cannot know (label, icon,
+ * hotkey, description, resource name). Pure, so it is unit-testable.
+ *
+ * @capability action-from-ability-slot adapt a combat ability-kit snapshot into an action-bar action def
+ */
+export declare function actionFromAbilitySlot(slot: AbilitySlotSnapshot, extra?: Partial<ActionDef> & {
+    resourceId?: string;
+}): ActionDef;
+/** The intent a key press resolves to over an action bar: move focus, activate, or ignore. */
+export interface ActionBarKeyResult {
+    handled: boolean;
+    focusId?: string;
+    activateId?: string;
+}
+/**
+ * Pure keyboard/controller resolver for an action bar: arrows/Home/End move grid focus, Enter/Space
+ * activate the focused action, and any other single key routes through {@link actionByHotkey}. Returns
+ * the resulting intent without touching the DOM, so it unit-tests headless and `useActionBar` is a
+ * thin shell over it.
+ */
+export declare function actionBarKeyAction(actions: readonly ResolvedAction[], focusedId: string | null, columns: number, key: string, options?: {
+    wrap?: boolean;
+}): ActionBarKeyResult;
+/** A minimal keyboard-event shape — a real `KeyboardEvent`/React synthetic satisfies it. */
+export interface ActionKeyEvent {
+    key: string;
+    preventDefault(): void;
+}
+/** Options for {@link useActionBar}. */
+export interface UseActionBarOptions {
+    /** Grid width for keyboard focus math and the default grid renderer (default: number of actions). */
+    columns?: number;
+    /** Wrap focus at the grid edges (default false). */
+    wrap?: boolean;
+    /** Fired when an action is activated by click, Enter/Space, or its hotkey. */
+    onActivate?: (id: string) => void;
+    /** Set false to ignore single-key hotkeys (default true). */
+    hotkeys?: boolean;
+}
+/** The live action-bar model returned by {@link useActionBar}. */
+export interface ActionBarModel {
+    actions: readonly ResolvedAction[];
+    columns: number;
+    focusedId: string | null;
+    hoveredId: string | null;
+    setFocus: (id: string | null) => void;
+    setHover: (id: string | null) => void;
+    activate: (id: string) => void;
+    onKeyDown: (event: ActionKeyEvent) => void;
+}
+/**
+ * The DATA/HOOK layer: resolve `defs` into a live view model with focus, hover, keyboard grid
+ * navigation, and hotkey activation. Rendering-agnostic — feed the returned model to
+ * {@link ActionBarChrome}, or read it directly to lay out a radial or a bespoke card.
+ *
+ * @capability action-bar-model headless action-collection model with focus, hover, keyboard, and hotkey routing
+ */
+export declare function useActionBar(defs: readonly ActionDef[], options?: UseActionBarOptions): ActionBarModel;
+/** Render context passed to a custom {@link ActionBarChrome} item renderer. */
+export interface ActionItemContext {
+    focused: boolean;
+    hovered: boolean;
+    model: ActionBarModel;
+}
+/**
+ * The default per-item chrome — a cooldown-aware action button with hotkey cap, cost line, radial
+ * cooldown wipe, and full rest/hover/focus/pressed/active/disabled states. Accessible: it is a real
+ * `<button>` with `aria-disabled`, `aria-pressed` for toggles, `aria-keyshortcuts`, and a native
+ * `title` describing why it is blocked. Swap it via `ActionBarChrome`'s `renderItem`, or drop it into
+ * a radial layout yourself.
+ *
+ * @capability action-button cooldown/cost/hotkey action button with complete interaction states
+ */
+export declare function ActionButton({ action, focused, hovered, size, showHotkey, tabIndex, buttonRef, onActivate, onFocus, onHover, renderIcon, className, style, }: {
+    action: ResolvedAction;
+    focused?: boolean;
+    hovered?: boolean;
+    size?: number;
+    showHotkey?: boolean;
+    tabIndex?: number;
+    buttonRef?: (node: HTMLButtonElement | null) => void;
+    onActivate?: (id: string) => void;
+    onFocus?: (id: string) => void;
+    onHover?: (id: string | null) => void;
+    renderIcon?: (action: ResolvedAction) => ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}): import("react").JSX.Element;
+/**
+ * The composable RENDERER: lay the model's actions out as a `grid` or `list` toolbar with roving
+ * tabindex, arrow-key navigation, and a moved DOM focus. `renderItem` swaps per-item chrome; omit it
+ * for {@link ActionButton}. A radial or bespoke UI can skip this entirely and read the model. Purely
+ * a wiring/behavior layer — no panel skin — so a game art-directs freely.
+ *
+ * @capability action-bar-chrome accessible grid/list toolbar renderer over an action-bar model with swappable item chrome
+ */
+export declare function ActionBarChrome({ model, layout, itemSize, gap, ariaLabel, renderItem, className, style, }: {
+    model: ActionBarModel;
+    layout?: "grid" | "list";
+    itemSize?: number;
+    gap?: number;
+    ariaLabel?: string;
+    renderItem?: (action: ResolvedAction, ctx: ActionItemContext) => ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}): import("react").JSX.Element;
+/**
+ * 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 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[];
+    columns?: number;
+    layout?: "grid" | "list";
+    wrap?: boolean;
+    hotkeys?: boolean;
+    itemSize?: number;
+    ariaLabel?: string;
+    onActivate?: (id: string) => void;
+    renderItem?: (action: ResolvedAction, ctx: ActionItemContext) => ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}): import("react").JSX.Element;
+/**
+ * An accessible popover shell positioned by the pure {@link placePopover} math — flips and clamps
+ * against the viewport, renders nothing while closed, and defaults to `role="tooltip"`. Reuse it for
+ * an action's hover/focus description or any anchored panel.
+ *
+ * @capability popover viewport-flipping, viewport-clamped anchored popover/tooltip shell
+ */
+export declare function Popover({ open, anchorRef, side, gap, role, id, children, className, style, }: {
+    open: boolean;
+    anchorRef: {
+        current: HTMLElement | null;
+    };
+    side?: PopoverSide;
+    gap?: number;
+    role?: string;
+    id?: string;
+    children: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}): import("react").JSX.Element | null;
+/**
+ * Render {@link TooltipContent} (from `actionTooltip`) as a styled block: title, subtitle, body,
+ * hotkey, cost lines, cooldown, and a warning footer of blocking notes. Drop it inside a
+ * {@link Popover} for an action's hover/focus description.
+ *
+ * @capability action-tooltip structured action tooltip body (title, cost, cooldown, blocking notes)
+ */
+export declare function ActionTooltip({ content, className, style, }: {
+    content: TooltipContent;
+    className?: string;
+    style?: CSSProperties;
+}): import("react").JSX.Element;

package/dist/actionHud.js

@@ -0,0 +1,294 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useMemo, useRef, useState, } from "react";
+import { actionByHotkey, actionCooldownFromFraction, actionCost, moveGridFocus, resolveActionCollection, } from "@jgengine/core/ui/actionModel";
+import { actionTooltip, placePopover } from "@jgengine/core/ui/tooltipModel";
+import { Keycap } from "./keyHint.js";
+/**
+ * Composable React renderers over the headless action view model (`@jgengine/core/ui/actionModel`) —
+ * the data/renderer/chrome split for an RTS command card, an ability action bar, a build menu, or a
+ * radial. `useActionBar` is the DATA/HOOK layer (resolution + focus/hover/keyboard/hotkey), `ActionBarChrome`
+ * is the composable RENDERER (swap `renderItem` for custom chrome, or ignore it and consume the model
+ * directly for a radial), and `ActionBar` is the batteries-included default. A game swaps renderer or
+ * chrome without forking the logic. Layout, dimensions, hotkeys, and catalog-id mapping stay caller-owned.
+ */
+/**
+ * Adapt a combat {@link AbilitySlotSnapshot} into an {@link ActionDef} — the glue that binds an
+ * `AbilityKit` (via `useAbilitySlots`) to the action renderers without the game re-deriving cooldown
+ * and cost shapes. `extra` supplies the caller-owned bits the snapshot cannot know (label, icon,
+ * hotkey, description, resource name). Pure, so it is unit-testable.
+ *
+ * @capability action-from-ability-slot adapt a combat ability-kit snapshot into an action-bar action def
+ */
+export function actionFromAbilitySlot(slot, extra) {
+    const def = { id: slot.id };
+    if (slot.cooldownRemainingMs > 0) {
+        def.cooldown = actionCooldownFromFraction(slot.cooldownRemainingMs, slot.cooldownFraction);
+    }
+    if (slot.resourceCost > 0) {
+        const available = slot.state === "no-resource" ? 0 : slot.resourceCost;
+        def.costs = [actionCost(extra?.resourceId ?? "resource", slot.resourceCost, available)];
+    }
+    if (extra?.label !== undefined)
+        def.label = extra.label;
+    if (extra?.description !== undefined)
+        def.description = extra.description;
+    if (extra?.icon !== undefined)
+        def.icon = extra.icon;
+    if (extra?.hotkey !== undefined)
+        def.hotkey = extra.hotkey;
+    if (extra?.group !== undefined)
+        def.group = extra.group;
+    if (extra?.active !== undefined)
+        def.active = extra.active;
+    if (extra?.disabled !== undefined)
+        def.disabled = extra.disabled;
+    if (extra?.reasons !== undefined)
+        def.reasons = extra.reasons;
+    return def;
+}
+const ARROW_DIRECTIONS = {
+    ArrowRight: "right",
+    ArrowLeft: "left",
+    ArrowUp: "up",
+    ArrowDown: "down",
+    Home: "first",
+    End: "last",
+};
+/**
+ * Pure keyboard/controller resolver for an action bar: arrows/Home/End move grid focus, Enter/Space
+ * activate the focused action, and any other single key routes through {@link actionByHotkey}. Returns
+ * the resulting intent without touching the DOM, so it unit-tests headless and `useActionBar` is a
+ * thin shell over it.
+ */
+export function actionBarKeyAction(actions, focusedId, columns, key, options) {
+    const index = focusedId === null ? -1 : actions.findIndex((a) => a.id === focusedId);
+    const dir = ARROW_DIRECTIONS[key];
+    if (dir !== undefined) {
+        const next = moveGridFocus(index, actions.length, columns, dir, { wrap: options?.wrap === true });
+        const nextId = actions[next]?.id;
+        return nextId === undefined ? { handled: false } : { handled: true, focusId: nextId };
+    }
+    if (key === "Enter" || key === " " || key === "Spacebar") {
+        return focusedId === null ? { handled: false } : { handled: true, activateId: focusedId };
+    }
+    const hotkeyId = actionByHotkey(actions, key);
+    return hotkeyId === null ? { handled: false } : { handled: true, focusId: hotkeyId, activateId: hotkeyId };
+}
+/**
+ * The DATA/HOOK layer: resolve `defs` into a live view model with focus, hover, keyboard grid
+ * navigation, and hotkey activation. Rendering-agnostic — feed the returned model to
+ * {@link ActionBarChrome}, or read it directly to lay out a radial or a bespoke card.
+ *
+ * @capability action-bar-model headless action-collection model with focus, hover, keyboard, and hotkey routing
+ */
+export function useActionBar(defs, options) {
+    const [focusedId, setFocusedId] = useState(null);
+    const [hoveredId, setHoveredId] = useState(null);
+    const actions = useMemo(() => resolveActionCollection(defs), [defs]);
+    const columns = options?.columns ?? Math.max(1, actions.length);
+    const activate = useCallback((id) => options?.onActivate?.(id), [options]);
+    const onKeyDown = useCallback((event) => {
+        const result = actionBarKeyAction(actions, focusedId, columns, event.key, { wrap: options?.wrap === true });
+        if (!result.handled)
+            return;
+        if (result.activateId !== undefined && options?.hotkeys === false && result.focusId === result.activateId) {
+            // hotkey routing suppressed
+        }
+        else {
+            if (result.focusId !== undefined)
+                setFocusedId(result.focusId);
+            if (result.activateId !== undefined)
+                activate(result.activateId);
+        }
+        event.preventDefault();
+    }, [actions, focusedId, columns, options, activate]);
+    return {
+        actions,
+        columns,
+        focusedId,
+        hoveredId,
+        setFocus: setFocusedId,
+        setHover: setHoveredId,
+        activate,
+        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",
+    display: "flex",
+    flexDirection: "column",
+    alignItems: "center",
+    justifyContent: "center",
+    gap: 2,
+    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",
+    userSelect: "none",
+    overflow: "hidden",
+};
+/**
+ * The default per-item chrome — a cooldown-aware action button with hotkey cap, cost line, radial
+ * cooldown wipe, and full rest/hover/focus/pressed/active/disabled states. Accessible: it is a real
+ * `<button>` with `aria-disabled`, `aria-pressed` for toggles, `aria-keyshortcuts`, and a native
+ * `title` describing why it is blocked. Swap it via `ActionBarChrome`'s `renderItem`, or drop it into
+ * a radial layout yourself.
+ *
+ * @capability action-button cooldown/cost/hotkey action button with complete interaction states
+ */
+export function ActionButton({ action, focused = false, hovered = false, size = 52, showHotkey = true, tabIndex, buttonRef, onActivate, onFocus, onHover, renderIcon, className, style, }) {
+    const tip = actionTooltip(action);
+    const title = [tip.title, ...(tip.notes ?? [])].join("\n");
+    const cooldown = action.cooldown;
+    const wipeDeg = cooldown !== null && !cooldown.ready ? Math.round(cooldown.fraction * 360) : 0;
+    return (_jsxs("button", { type: "button", ref: buttonRef, className: className, "data-action-id": action.id, "data-active": action.active ? "" : undefined, "data-enabled": action.enabled ? "" : undefined, "data-focused": focused ? "" : undefined, "aria-disabled": !action.enabled, "aria-pressed": action.active, "aria-keyshortcuts": action.hotkey, "aria-label": action.label, title: title, tabIndex: tabIndex, onClick: () => onActivate?.(action.id), onFocus: () => onFocus?.(action.id), onPointerEnter: () => onHover?.(action.id), onPointerLeave: () => onHover?.(null), style: {
+            ...ITEM_BASE,
+            width: size,
+            height: size,
+            opacity: action.enabled ? 1 : 0.5,
+            borderColor: action.active
+                ? "rgba(56,189,248,0.95)"
+                : focused
+                    ? "rgba(148,197,255,0.9)"
+                    : hovered
+                        ? "rgba(255,255,255,0.3)"
+                        : "rgba(255,255,255,0.14)",
+            boxShadow: focused
+                ? "0 0 0 2px rgba(96,165,250,0.7)"
+                : action.active
+                    ? "0 0 0 1px rgba(56,189,248,0.6)"
+                    : "none",
+            transform: hovered && action.enabled ? "translateY(-1px)" : "none",
+            transition: "transform 120ms ease, border-color 120ms ease, box-shadow 120ms ease",
+            ...style,
+        }, children: [showHotkey && action.hotkey !== undefined ? (_jsx("span", { style: { position: "absolute", top: 2, left: 3 }, "aria-hidden": true, children: _jsx(Keycap, { style: { fontSize: 9, padding: "0 3px", opacity: 0.85 }, children: action.hotkey }) })) : null, _jsx("span", { style: { fontSize: renderIcon ? undefined : 18, lineHeight: 1 }, "data-action-icon": true, "aria-hidden": true, children: renderIcon ? renderIcon(action) : (action.icon ?? action.label.slice(0, 2)) }), action.costs.length > 0 ? (_jsx("span", { "data-action-costs": true, style: { display: "flex", gap: 4, fontSize: 9 }, children: action.costs.map((cost) => (_jsx("span", { style: { color: cost.met ? "rgba(147,197,253,0.9)" : "#f87171" }, children: cost.amount }, cost.resourceId))) })) : null, wipeDeg > 0 ? (_jsx("span", { "data-action-cooldown": true, "aria-hidden": true, style: {
+                    position: "absolute",
+                    inset: 0,
+                    pointerEvents: "none",
+                    background: `conic-gradient(rgba(4,6,10,0.62) ${wipeDeg}deg, transparent 0deg)`,
+                }, children: _jsx("span", { style: {
+                        position: "absolute",
+                        inset: 0,
+                        display: "flex",
+                        alignItems: "center",
+                        justifyContent: "center",
+                        fontSize: 13,
+                        fontWeight: 700,
+                        fontVariantNumeric: "tabular-nums",
+                    }, children: (action.cooldown.remainingMs / 1000).toFixed(action.cooldown.remainingMs < 10000 ? 1 : 0) }) })) : null] }));
+}
+/**
+ * The composable RENDERER: lay the model's actions out as a `grid` or `list` toolbar with roving
+ * tabindex, arrow-key navigation, and a moved DOM focus. `renderItem` swaps per-item chrome; omit it
+ * for {@link ActionButton}. A radial or bespoke UI can skip this entirely and read the model. Purely
+ * a wiring/behavior layer — no panel skin — so a game art-directs freely.
+ *
+ * @capability action-bar-chrome accessible grid/list toolbar renderer over an action-bar model with swappable item chrome
+ */
+export function ActionBarChrome({ model, layout = "grid", itemSize = 52, gap = 6, ariaLabel = "Actions", renderItem, className, style, }) {
+    const refs = useRef(new Map());
+    const { actions, focusedId, hoveredId, columns } = model;
+    const rovingId = focusedId ?? actions[0]?.id ?? null;
+    useEffect(() => {
+        if (focusedId === null)
+            return;
+        refs.current.get(focusedId)?.focus();
+    }, [focusedId]);
+    const containerStyle = layout === "grid"
+        ? { display: "grid", gridTemplateColumns: `repeat(${Math.max(1, columns)}, ${itemSize}px)`, gap }
+        : { display: "flex", flexDirection: "column", gap };
+    return (_jsx("div", { role: "toolbar", "aria-label": ariaLabel, "aria-orientation": layout === "list" ? "vertical" : "horizontal", className: className, "data-action-bar": "", onKeyDown: model.onKeyDown, style: { ...containerStyle, ...style }, children: actions.map((action) => {
+            const ctx = {
+                focused: focusedId === action.id,
+                hovered: hoveredId === action.id,
+                model,
+            };
+            if (renderItem !== undefined)
+                return _jsx("div", { children: renderItem(action, ctx) }, action.id);
+            return (_jsx(ActionButton, { action: action, focused: ctx.focused, hovered: ctx.hovered, size: itemSize, tabIndex: rovingId === action.id ? 0 : -1, buttonRef: (node) => {
+                    if (node === null)
+                        refs.current.delete(action.id);
+                    else
+                        refs.current.set(action.id, node);
+                }, onActivate: model.activate, onFocus: model.setFocus, onHover: model.setHover }, action.id));
+        }) }));
+}
+const PANEL = {
+    padding: 8,
+    borderRadius: "var(--jg-frame-radius, 12px)",
+    background: "var(--jg-frame-bg, rgba(10,12,16,0.6))",
+    backdropFilter: "blur(6px)",
+    WebkitBackdropFilter: "blur(6px)",
+    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))",
+};
+/**
+ * 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 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 });
+    return (_jsx("div", { className: className, "data-action-panel": "", style: { ...PANEL, display: "inline-block", ...style }, children: _jsx(ActionBarChrome, { model: model, layout: layout, itemSize: itemSize, ariaLabel: ariaLabel, renderItem: renderItem }) }));
+}
+/**
+ * An accessible popover shell positioned by the pure {@link placePopover} math — flips and clamps
+ * against the viewport, renders nothing while closed, and defaults to `role="tooltip"`. Reuse it for
+ * an action's hover/focus description or any anchored panel.
+ *
+ * @capability popover viewport-flipping, viewport-clamped anchored popover/tooltip shell
+ */
+export function Popover({ open, anchorRef, side = "top", gap = 8, role = "tooltip", id, children, className, style, }) {
+    const ref = useRef(null);
+    const [pos, setPos] = useState(null);
+    useEffect(() => {
+        if (!open || typeof window === "undefined")
+            return;
+        const anchor = anchorRef.current;
+        const node = ref.current;
+        if (anchor === null || node === null)
+            return;
+        const a = anchor.getBoundingClientRect();
+        const c = node.getBoundingClientRect();
+        const placement = placePopover({ x: a.left, y: a.top, width: a.width, height: a.height }, { width: c.width, height: c.height }, { width: window.innerWidth, height: window.innerHeight }, { preferred: side, gap });
+        setPos({ left: placement.left, top: placement.top });
+    }, [open, side, gap, anchorRef]);
+    if (!open)
+        return null;
+    return (_jsx("div", { ref: ref, role: role, id: id, "data-popover": "", className: className, style: {
+            position: "fixed",
+            left: pos?.left ?? -9999,
+            top: pos?.top ?? -9999,
+            zIndex: 1000,
+            pointerEvents: "none",
+            ...style,
+        }, children: children }));
+}
+/**
+ * Render {@link TooltipContent} (from `actionTooltip`) as a styled block: title, subtitle, body,
+ * hotkey, cost lines, cooldown, and a warning footer of blocking notes. Drop it inside a
+ * {@link Popover} for an action's hover/focus description.
+ *
+ * @capability action-tooltip structured action tooltip body (title, cost, cooldown, blocking notes)
+ */
+export function ActionTooltip({ content, className, style, }) {
+    return (_jsxs("div", { className: className, "data-action-tooltip": "", style: {
+            maxWidth: 240,
+            padding: "8px 10px",
+            borderRadius: 8,
+            background: "rgba(8,10,14,0.95)",
+            border: "1px solid rgba(255,255,255,0.14)",
+            color: "#eef2f8",
+            font: "500 12px/1.35 ui-sans-serif, system-ui, sans-serif",
+            boxShadow: "0 8px 24px rgba(0,0,0,0.5)",
+            ...style,
+        }, children: [_jsxs("div", { style: { display: "flex", alignItems: "baseline", gap: 8 }, children: [_jsx("strong", { style: { fontSize: 13 }, children: content.title }), content.hotkey !== undefined ? (_jsx(Keycap, { style: { marginLeft: "auto", fontSize: 10 }, children: content.hotkey })) : null] }), content.subtitle !== undefined ? (_jsx("div", { style: { fontSize: 10, textTransform: "uppercase", letterSpacing: 0.4, opacity: 0.6 }, children: content.subtitle })) : null, content.body !== undefined ? _jsx("div", { style: { marginTop: 4, opacity: 0.9 }, children: content.body }) : null, content.costs !== undefined && content.costs.length > 0 ? (_jsx("div", { style: { marginTop: 4, display: "flex", gap: 8, fontSize: 11 }, children: content.costs.map((cost) => (_jsxs("span", { style: { color: cost.met ? "rgba(147,197,253,0.95)" : "#f87171" }, children: [cost.amount, " ", cost.resourceId] }, cost.resourceId))) })) : null, content.cooldown != null ? (_jsxs("div", { style: { marginTop: 4, fontSize: 11, opacity: 0.8 }, children: [(content.cooldown.remainingMs / 1000).toFixed(1), "s cooldown"] })) : null, content.notes !== undefined && content.notes.length > 0 ? (_jsx("div", { style: { marginTop: 6, paddingTop: 4, borderTop: "1px solid rgba(255,255,255,0.1)", fontSize: 11, color: "#fca5a5" }, children: content.notes.map((note) => (_jsx("div", { children: note }, note))) })) : null] }));
+}

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;