@jgengine/react 0.10.0 → 0.12.0

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/cards.d.ts

@@ -0,0 +1,59 @@
+import type { CSSProperties, ReactNode } from "react";
+import type { CardPileState } from "@jgengine/core/cards/cardPile";
+import { type DragLayer } from "./dragLayer.js";
+/** The four French-deck suits. */
+export type Suit = "clubs" | "diamonds" | "hearts" | "spades";
+/** A playing-card rank, ace through king. */
+export type Rank = "A" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "10" | "J" | "Q" | "K";
+/** Suits in canonical order (clubs, diamonds, hearts, spades). */
+export declare const SUITS: readonly Suit[];
+/** Ranks in ascending order, ace low. */
+export declare const RANKS: readonly Rank[];
+/** True for the red suits (hearts, diamonds). */
+export declare function isRedSuit(suit: Suit): boolean;
+/** A single card in a stack: an id plus its face and orientation. */
+export interface PlayingCard {
+    id: string;
+    rank: Rank;
+    suit: Suit;
+    faceDown?: boolean;
+}
+/** A single playing-card face: rank + suit pips, or a patterned back when `faceDown`. */
+export declare function CardFace({ rank, suit, faceDown, width, height, className, style, children, }: {
+    rank: Rank;
+    suit: Suit;
+    faceDown?: boolean;
+    width?: number;
+    height?: number;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * An overlapping fan of `CardFace`s. Plain-props: pass `cards`. Optional drag: pass a `layer`
+ * to make each card a `DraggableCard`, and `dropId` to wrap the pile in a `DropZone`.
+ */
+export declare function StackedPile({ cards, faceDown, offsetX, offsetY, cardWidth, cardHeight, layer, dropId, draggableFrom, className, cardClassName, onCardClick, renderOverlay, }: {
+    cards: readonly PlayingCard[];
+    faceDown?: boolean;
+    offsetX?: number;
+    offsetY?: number;
+    cardWidth?: number;
+    cardHeight?: number;
+    layer?: DragLayer<PlayingCard>;
+    dropId?: string;
+    draggableFrom?: number;
+    className?: string;
+    cardClassName?: string;
+    onCardClick?: (card: PlayingCard, index: number) => void;
+    renderOverlay?: (card: PlayingCard, index: number) => ReactNode;
+}): import("react").JSX.Element;
+/**
+ * `StackedPile` bound to a headless `CardPileState` zone: reads the ordered card ids from
+ * `pile.zones[zone]` and resolves each to a `PlayingCard` via `cardOf`.
+ */
+export declare function CardStack({ pile, zone, cardOf, ...rest }: {
+    pile: CardPileState;
+    zone: string;
+    cardOf: (id: string) => PlayingCard;
+} & Omit<Parameters<typeof StackedPile>[0], "cards">): import("react").JSX.Element;

package/dist/cards.js

@@ -0,0 +1,116 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { DraggableCard, DropZone } from "./dragLayer.js";
+/** Suits in canonical order (clubs, diamonds, hearts, spades). */
+export const SUITS = ["clubs", "diamonds", "hearts", "spades"];
+/** Ranks in ascending order, ace low. */
+export const RANKS = ["A", "2", "3", "4", "5", "6", "7", "8", "9", "10", "J", "Q", "K"];
+/** True for the red suits (hearts, diamonds). */
+export function isRedSuit(suit) {
+    return suit === "hearts" || suit === "diamonds";
+}
+const SUIT_PATHS = {
+    hearts: _jsx("path", { d: "M12 21C7 17 3 13.5 3 9.5A4.5 4.5 0 0112 7a4.5 4.5 0 019 2.5C21 13.5 17 17 12 21z" }),
+    diamonds: _jsx("path", { d: "M12 2l7.5 10L12 22 4.5 12z" }),
+    spades: (_jsx("path", { d: "M12 2C8.5 6 3.5 8.5 3.5 13A4 4 0 0011 15.7C10.7 18 9.7 19.3 8 21h8c-1.7-1.7-2.7-3-3-5.3A4 4 0 0020.5 13C20.5 8.5 15.5 6 12 2z" })),
+    clubs: (_jsx("path", { d: "M12 2a3.6 3.6 0 00-2.9 5.7A3.6 3.6 0 108.4 14.6 3.6 3.6 0 0011 15.3C10.8 18 9.8 19.4 8 21h8c-1.8-1.6-2.8-3-3-5.7a3.6 3.6 0 102.6-6.9A3.6 3.6 0 0012 2z" })),
+};
+function SuitGlyph({ suit, size = 16 }) {
+    return (_jsx("svg", { viewBox: "0 0 24 24", width: size, height: size, fill: "currentColor", "aria-hidden": "true", "data-suit-glyph": suit, style: { display: "block" }, children: SUIT_PATHS[suit] }));
+}
+const SUIT_LABEL = {
+    clubs: "clubs",
+    diamonds: "diamonds",
+    hearts: "hearts",
+    spades: "spades",
+};
+/** A single playing-card face: rank + suit pips, or a patterned back when `faceDown`. */
+export function CardFace({ rank, suit, faceDown = false, width = 64, height = 90, className, style, children, }) {
+    const radius = Math.round(Math.min(width, height) * 0.11);
+    const base = {
+        width,
+        height,
+        borderRadius: radius,
+        boxSizing: "border-box",
+        position: "relative",
+        userSelect: "none",
+        ...style,
+    };
+    if (faceDown) {
+        return (_jsxs("div", { className: className, "data-card-face": "", "data-face-down": "", role: "img", "aria-label": "Face-down card", style: {
+                ...base,
+                border: "1px solid #1e2a52",
+                background: "repeating-linear-gradient(45deg, #2b3a72 0, #2b3a72 4px, #1b2650 4px, #1b2650 8px)",
+            }, children: [_jsx("div", { style: {
+                        position: "absolute",
+                        inset: Math.round(Math.min(width, height) * 0.09),
+                        borderRadius: Math.max(2, radius - 3),
+                        border: "1px solid rgba(255,255,255,0.35)",
+                    } }), children] }));
+    }
+    const color = isRedSuit(suit) ? "#c02434" : "#16181d";
+    const cornerFont = Math.round(height * 0.16);
+    const corner = (rotated) => ({
+        position: "absolute",
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "center",
+        lineHeight: 1,
+        color,
+        fontFamily: "Georgia, 'Times New Roman', serif",
+        fontWeight: 700,
+        fontSize: cornerFont,
+        ...(rotated
+            ? { right: Math.round(width * 0.06), bottom: Math.round(height * 0.05), transform: "rotate(180deg)" }
+            : { left: Math.round(width * 0.06), top: Math.round(height * 0.05) }),
+    });
+    return (_jsxs("div", { className: className, "data-card-face": "", "data-rank": rank, "data-suit": suit, role: "img", "aria-label": `${rank} of ${SUIT_LABEL[suit]}`, style: {
+            ...base,
+            border: "1px solid #c8ccd6",
+            background: "#ffffff",
+        }, children: [_jsxs("span", { "data-card-corner": "top", style: corner(false), children: [_jsx("span", { "data-card-rank": true, children: rank }), _jsx(SuitGlyph, { suit: suit, size: cornerFont })] }), _jsx("div", { style: {
+                    position: "absolute",
+                    inset: 0,
+                    display: "flex",
+                    alignItems: "center",
+                    justifyContent: "center",
+                    color,
+                }, children: _jsx(SuitGlyph, { suit: suit, size: Math.round(Math.min(width, height) * 0.5) }) }), _jsxs("span", { "data-card-corner": "bottom", style: corner(true), children: [_jsx("span", { "data-card-rank": true, children: rank }), _jsx(SuitGlyph, { suit: suit, size: cornerFont })] }), children] }));
+}
+/**
+ * An overlapping fan of `CardFace`s. Plain-props: pass `cards`. Optional drag: pass a `layer`
+ * to make each card a `DraggableCard`, and `dropId` to wrap the pile in a `DropZone`.
+ */
+export function StackedPile({ cards, faceDown, offsetX = 0, offsetY = 20, cardWidth = 64, cardHeight = 90, layer, dropId, draggableFrom = 0, className, cardClassName, onCardClick, renderOverlay, }) {
+    const last = Math.max(0, cards.length - 1);
+    const width = cardWidth + Math.abs(offsetX) * last;
+    const height = cardHeight + Math.abs(offsetY) * last;
+    const baseLeft = offsetX < 0 ? -offsetX * last : 0;
+    const baseTop = offsetY < 0 ? -offsetY * last : 0;
+    const body = (_jsx("div", { className: className, "data-card-stack": "", "data-count": cards.length, style: { position: "relative", width, height }, children: cards.map((card, index) => {
+            const positioned = {
+                position: "absolute",
+                left: baseLeft + offsetX * index,
+                top: baseTop + offsetY * index,
+                zIndex: index,
+            };
+            const face = (_jsx(CardFace, { rank: card.rank, suit: card.suit, faceDown: card.faceDown ?? faceDown, width: cardWidth, height: cardHeight, className: cardClassName, children: renderOverlay?.(card, index) }));
+            const clickable = onCardClick !== undefined;
+            if (layer !== undefined && index >= draggableFrom) {
+                return (_jsx("div", { style: positioned, children: _jsx(DraggableCard, { id: card.id, value: card, layer: layer, onRotate: false, children: face }) }, card.id));
+            }
+            return (_jsx("div", { "data-card-slot": index, style: { ...positioned, cursor: clickable ? "pointer" : undefined }, onClick: clickable ? () => onCardClick(card, index) : undefined, children: face }, card.id));
+        }) }));
+    if (layer !== undefined && dropId !== undefined) {
+        return (_jsx(DropZone, { id: dropId, layer: layer, children: body }));
+    }
+    return body;
+}
+/**
+ * `StackedPile` bound to a headless `CardPileState` zone: reads the ordered card ids from
+ * `pile.zones[zone]` and resolves each to a `PlayingCard` via `cardOf`.
+ */
+export function CardStack({ pile, zone, cardOf, ...rest }) {
+    const ids = pile.zones[zone] ?? [];
+    const cards = ids.map(cardOf);
+    return _jsx(StackedPile, { cards: cards, ...rest });
+}

package/dist/chat.d.ts

@@ -33,7 +33,7 @@ export declare function ChannelTabs({ channels, active, onSelect, className, tab
     activeTabClassName?: string;
     renderTab?: (channelId: string, isActive: boolean) => ReactNode;
 }): import("react").JSX.Element | null;
-export declare function ChatPanel({ channels, initialChannel, limit, className, tabsClassName, tabClassName, activeTabClassName, logClassName, messageClassName, inputClassName, inputFieldClassName, sendButtonClassName, placeholder, renderMessage, onRejected, }: {
+export declare function ChatPanel({ channels, initialChannel, limit, className, tabsClassName, tabClassName, activeTabClassName, logClassName, messageClassName, inputClassName, inputFieldClassName, sendButtonClassName, placeholder, renderMessage, renderTab, onRejected, }: {
     channels?: readonly string[];
     initialChannel?: string;
     limit?: number;
@@ -48,5 +48,7 @@ export declare function ChatPanel({ channels, initialChannel, limit, className,
     sendButtonClassName?: string;
     placeholder?: string;
     renderMessage?: (message: ChatMessage) => ReactNode;
+    /** Overrides a tab's label — e.g. render channel id `"proximity"` as "Nearby". */
+    renderTab?: (channelId: string, isActive: boolean) => ReactNode;
     onRejected?: (reason: string) => void;
 }): import("react").JSX.Element | null;

package/dist/chat.js

@@ -66,12 +66,12 @@ export function ChannelTabs({ channels, active, onSelect, className, tabClassNam
             return (_jsx("button", { type: "button", role: "tab", "aria-selected": isActive, className: classes.length > 0 ? classes : undefined, "data-channel": channelId, onClick: () => onSelect(channelId), children: renderTab !== undefined ? renderTab(channelId, isActive) : channelId }, channelId));
         }) }));
 }
-export function ChatPanel({ channels, initialChannel, limit, className, tabsClassName, tabClassName, activeTabClassName, logClassName, messageClassName, inputClassName, inputFieldClassName, sendButtonClassName, placeholder, renderMessage, onRejected, }) {
+export function ChatPanel({ channels, initialChannel, limit, className, tabsClassName, tabClassName, activeTabClassName, logClassName, messageClassName, inputClassName, inputFieldClassName, sendButtonClassName, placeholder, renderMessage, renderTab, onRejected, }) {
     const ctx = useGameContext();
     const chat = ctx.game.chat;
     const ids = channels ?? chat?.channels().map((def) => def.id) ?? [];
     const [active, setActive] = useState(initialChannel ?? ids[0] ?? "global");
     if (chat === undefined)
         return null;
-    return (_jsxs("section", { className: className, "data-chat-panel": true, children: [_jsx(ChannelTabs, { channels: ids, active: active, onSelect: setActive, className: tabsClassName, tabClassName: tabClassName, activeTabClassName: activeTabClassName }), _jsx(ChatLog, { channelId: active, limit: limit, className: logClassName, messageClassName: messageClassName, renderMessage: renderMessage }), _jsx(ChatInput, { channelId: active, className: inputClassName, inputClassName: inputFieldClassName, buttonClassName: sendButtonClassName, placeholder: placeholder, onRejected: onRejected })] }));
+    return (_jsxs("section", { className: className, "data-chat-panel": true, children: [_jsx(ChannelTabs, { channels: ids, active: active, onSelect: setActive, className: tabsClassName, tabClassName: tabClassName, activeTabClassName: activeTabClassName, renderTab: renderTab }), _jsx(ChatLog, { channelId: active, limit: limit, className: logClassName, messageClassName: messageClassName, renderMessage: renderMessage }), _jsx(ChatInput, { channelId: active, className: inputClassName, inputClassName: inputFieldClassName, buttonClassName: sendButtonClassName, placeholder: placeholder, onRejected: onRejected })] }));
 }

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;
@@ -84,6 +91,20 @@ export declare function DialogueBox({ dialogue, onChoice, rng, className, lineCl
     choiceClassName?: string;
     checkClassName?: string;
 }): import("react").JSX.Element;
+/**
+ * The id of the dialogue `ctx.game.dialogue` (or a `talkable(id)` prompt) currently has open, or `null`.
+ * The read side of the `features.dialogue` bridge — a panel looks the id up in its own dialogue catalog and
+ * renders {@link DialogueBox}, with no per-game open/close store.
+ */
+export declare function useOpenDialogueId(): string | null;
+/**
+ * Route a {@link DialogueBox} choice through the `features.dialogue` bridge: resolve the choice's invoke
+ * (honoring a skill-check `result`), run that command, and otherwise close the dialogue — the write side that
+ * replaces a per-game `onChoice` that hand-rolls `resolveDialogueInvoke` + `dialogue.close`.
+ */
+export declare function runDialogueChoice(commands: {
+    run(name: string, input?: unknown): unknown;
+}, choice: DialogueChoice, result: CheckResult | null): void;
 export declare function SkillCheckBar({ config, startedAt, className, trackClassName, zoneClassName, markerClassName, renderStatus, }: {
     config: SkillCheckConfig;
     startedAt: number;
@@ -106,6 +127,12 @@ export declare function CaptureOdds({ chance, className, fillClassName, }: {
     className?: string;
     fillClassName?: string;
 }): import("react").JSX.Element;
+/**
+ * Render `ctx.game.feed`'s entries for `action` as a newest-first toast stack — the feed-backed sibling of
+ * `@jgengine/core/game/toasts`' `createToastQueue`. Reach for this when the message source is already an engine
+ * event bound onto `ctx.game.feed` (kill feed, quest updates, loot log); reach for a `createToastQueue` when the
+ * game raises ad-hoc messages that need their own TTL independent of the feed's ring buffer.
+ */
 export declare function ToastStack({ action, limit, className, renderToast, }: {
     action: string;
     limit?: number;

package/dist/components.js

@@ -3,8 +3,10 @@ import { useEffect, useRef, useState } from "react";
 import { evaluateSkillCheck, } from "@jgengine/core/interaction/skillCheck";
 import { pendingQteStep } from "@jgengine/core/interaction/qte";
 import { rollCheck } from "@jgengine/core/stats/rollCheck";
+import { dialogueSlot } from "@jgengine/core/game/dialogue";
 import { useGameContext } from "./provider.js";
 import { useCurrency, useEntityStat, useFeed, useInventory, useLocalPlayerDead } from "./hooks.js";
+import { useStore } from "./store.js";
 import { paintQteStepDom, paintSkillCheckDom } from "./skillCheckPaint.js";
 export { paintQteStepDom, paintSkillCheckDom } from "./skillCheckPaint.js";
 export function SlotGrid({ inventoryId, className, renderSlot, }) {
@@ -15,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;
@@ -55,6 +64,26 @@ export function DialogueBox({ dialogue, onChoice, rng, className, lineClassName,
                                 ? ` (${choice.check.advantage})`
                                 : ""] }))] }, choice.label))) }, index)) : (_jsxs("p", { className: lineClassName, children: [_jsx("span", { className: speakerClassName, "data-speaker": true, children: line.speaker }), _jsx("span", { children: line.text })] }, index))) }));
 }
+/**
+ * The id of the dialogue `ctx.game.dialogue` (or a `talkable(id)` prompt) currently has open, or `null`.
+ * The read side of the `features.dialogue` bridge — a panel looks the id up in its own dialogue catalog and
+ * renders {@link DialogueBox}, with no per-game open/close store.
+ */
+export function useOpenDialogueId() {
+    return useStore(dialogueSlot, (value) => value ?? null);
+}
+/**
+ * Route a {@link DialogueBox} choice through the `features.dialogue` bridge: resolve the choice's invoke
+ * (honoring a skill-check `result`), run that command, and otherwise close the dialogue — the write side that
+ * replaces a per-game `onChoice` that hand-rolls `resolveDialogueInvoke` + `dialogue.close`.
+ */
+export function runDialogueChoice(commands, choice, result) {
+    const invoke = resolveDialogueInvoke(choice, result);
+    if (invoke !== null && invoke !== undefined)
+        commands.run(invoke.command, invoke.args ?? {});
+    else
+        commands.run("dialogue.close", {});
+}
 export function SkillCheckBar({ config, startedAt, className, trackClassName, zoneClassName, markerClassName, renderStatus, }) {
     const ctx = useGameContext();
     const rootRef = useRef(null);
@@ -119,6 +148,12 @@ function defaultToast(entry) {
     }
     return typeof entry.data === "string" ? entry.data : JSON.stringify(entry.data);
 }
+/**
+ * Render `ctx.game.feed`'s entries for `action` as a newest-first toast stack — the feed-backed sibling of
+ * `@jgengine/core/game/toasts`' `createToastQueue`. Reach for this when the message source is already an engine
+ * event bound onto `ctx.game.feed` (kill feed, quest updates, loot log); reach for a `createToastQueue` when the
+ * game raises ad-hoc messages that need their own TTL independent of the feed's ring buffer.
+ */
 export function ToastStack({ action, limit = 4, className, renderToast, }) {
     const entries = useFeed({ action, limit });
     if (entries.length === 0)

package/dist/display.d.ts

@@ -11,4 +11,5 @@ export interface DisplayProfile {
     compact: boolean;
     portrait: boolean;
 }
+/** @internal */
 export declare function useDisplayProfile(): DisplayProfile;

package/dist/display.js

@@ -40,6 +40,7 @@ function subscribe(onChange) {
             list.removeEventListener("change", onChange);
     };
 }
+/** @internal */
 export function useDisplayProfile() {
     return useSyncExternalStore(subscribe, readProfile, () => SERVER_PROFILE);
 }

package/dist/engineStore.d.ts

@@ -5,6 +5,9 @@ export interface ReadableEngineStore<TState> {
 export interface EventfulEngineStore<TEventMap extends object> {
     on<K extends keyof TEventMap>(eventName: K, listener: (payload: TEventMap[K]) => void): () => void;
 }
+/** @internal */
 export declare function useEngineState<TState>(store: ReadableEngineStore<TState>): TState;
+/** @internal */
 export declare function useEngineStore<TState, TSelected>(store: ReadableEngineStore<TState>, selector: (state: TState) => TSelected, isEqual?: (previous: TSelected, next: TSelected) => boolean): TSelected;
+/** @internal */
 export declare function useEngineEvent<TEventMap extends object, K extends keyof TEventMap>(store: EventfulEngineStore<TEventMap>, eventName: K, handler: (payload: TEventMap[K]) => void): void;

package/dist/engineStore.js

@@ -1,10 +1,12 @@
 import { useCallback, useEffect, useRef, useSyncExternalStore } from "react";
 import { createSelectCache, readSelectSnapshot } from "./selectSnapshot.js";
+/** @internal */
 export function useEngineState(store) {
     const subscribe = useCallback((onChange) => store.subscribe(() => onChange()), [store]);
     const getSnapshot = useCallback(() => store.getState(), [store]);
     return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
 }
+/** @internal */
 export function useEngineStore(store, selector, isEqual = Object.is) {
     const selectorRef = useRef(selector);
     selectorRef.current = selector;
@@ -15,6 +17,7 @@ export function useEngineStore(store, selector, isEqual = Object.is) {
     const getSnapshot = useCallback(() => readSelectSnapshot(cacheRef.current, store.getState(), (state) => selectorRef.current(state), (previous, next) => isEqualRef.current(previous, next)), [store]);
     return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
 }
+/** @internal */
 export function useEngineEvent(store, eventName, handler) {
     const handlerRef = useRef(handler);
     handlerRef.current = handler;

package/dist/fogOverlay.d.ts

@@ -10,11 +10,14 @@ export interface FogPaintSurface {
     fillRect(x: number, y: number, width: number, height: number): void;
     clearRect(x: number, y: number, width: number, height: number): void;
 }
+/** @internal */
 export declare function forEachUnrevealedFogCell(fog: FogCells, visit: (col: number, row: number) => void): number;
+/** @internal */
 export declare function paintFogOverlay(surface: FogPaintSurface, canvasSize: {
     width: number;
     height: number;
 }, fog: FogCells, cellRect: (col: number, row: number) => FogCellRect | null, fill?: string): number;
+/** @internal */
 export declare function createFogDataUrl(fog: FogCells, canvasSize: {
     width: number;
     height: number;