@jgengine/react 0.13.0 → 0.15.0-next.0

package/dist/saveSlots.js

@@ -0,0 +1,138 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useReducer, useEffect } from "react";
+import { GameIcon } from "./gameIcons.js";
+import { HudFrame } from "./hudFrame.js";
+/**
+ * Subscribe to a {@link SaveSlots} index and re-render on any change (write,
+ * clear, rename, restore). Returns the live list of slots in menu order. Wire it
+ * into a save-select screen and mutate the model in event handlers — the menu
+ * re-renders itself.
+ *
+ * @capability use-save-slots React hook binding a save-slots metadata index — re-renders on change and returns the ordered slot list
+ */
+export function useSaveSlots(model) {
+    const [, bump] = useReducer((n) => n + 1, 0);
+    useEffect(() => model.subscribe(bump), [model]);
+    return model.list();
+}
+function resolveTheme(theme) {
+    return {
+        accent: theme?.accent ?? "var(--jg-accent, #38bdf8)",
+        cardBg: theme?.cardBg ?? "var(--jg-frame-bg, linear-gradient(180deg, rgba(20,24,32,0.86), rgba(10,12,16,0.9)))",
+        cardBorder: theme?.cardBorder ?? "var(--jg-frame-border, 1px solid rgba(255,255,255,0.12))",
+        text: theme?.text ?? "#f1f5f9",
+        muted: theme?.muted ?? "rgba(203,213,225,0.72)",
+        chipBg: theme?.chipBg ?? "rgba(148,163,184,0.16)",
+        fontFamily: theme?.fontFamily ?? "ui-sans-serif, system-ui, sans-serif",
+        radius: theme?.radius ?? "var(--jg-frame-radius, 12px)",
+    };
+}
+/**
+ * Turn a `savedAt` timestamp into a compact relative label ("just now", "4m ago",
+ * "2d ago"). Presentation-only helper — the model stores raw ms.
+ */
+export function relativeSavedAt(savedAt, nowMs = Date.now()) {
+    const delta = Math.max(0, nowMs - savedAt);
+    const s = Math.floor(delta / 1000);
+    if (s < 45)
+        return "just now";
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m ago`;
+    const h = Math.floor(m / 60);
+    if (h < 24)
+        return `${h}h ago`;
+    const d = Math.floor(h / 24);
+    return `${d}d ago`;
+}
+const rowButton = (accent, primary) => ({
+    pointerEvents: "auto",
+    cursor: "pointer",
+    borderRadius: 8,
+    border: primary ? "none" : "1px solid rgba(148,163,184,0.28)",
+    background: primary ? accent : "rgba(15,20,28,0.6)",
+    color: primary ? "#0b1220" : "#e2e8f0",
+    fontSize: 12,
+    fontWeight: 700,
+    letterSpacing: 0.4,
+    padding: "7px 12px",
+    display: "inline-flex",
+    alignItems: "center",
+    gap: 6,
+});
+/** One filled slot's meta rendered as chips. */
+function MetaChips({ slot, t, metaIcons, }) {
+    const entries = Object.entries(slot.meta);
+    if (entries.length === 0)
+        return null;
+    return (_jsx("div", { style: { display: "flex", flexWrap: "wrap", gap: 6, marginTop: 8 }, children: entries.map(([key, value]) => {
+            const icon = metaIcons?.[key];
+            return (_jsxs("span", { "data-save-slot-chip": key, style: {
+                    display: "inline-flex",
+                    alignItems: "center",
+                    gap: 5,
+                    background: t.chipBg,
+                    color: t.muted,
+                    borderRadius: 999,
+                    padding: "3px 9px",
+                    fontSize: 11,
+                    fontWeight: 600,
+                    lineHeight: 1.3,
+                }, children: [icon !== undefined ? _jsx(GameIcon, { name: icon, size: 12, color: t.accent }) : null, _jsx("span", { style: { opacity: 0.7, textTransform: "uppercase", letterSpacing: 0.6, fontSize: 9 }, children: key }), _jsx("span", { style: { color: t.text }, children: String(value) })] }, key));
+        }) }));
+}
+/**
+ * A drop-in save-select / profile menu that renders a {@link SaveSlots} index as
+ * a column of cards. A filled slot shows its name, the free-string `meta` the
+ * game supplied as chips, and a relative "saved" time, with Load and Delete
+ * actions; an empty slot shows a "New Game" affordance. A top-level Continue
+ * button targets the newest save (`model.mostRecent()`). This is a starting-point
+ * game-front-end building block — the game owns final art, wording, and layout;
+ * reskin it with {@link SaveSlotMenuTheme} or HudTheme CSS vars. Presentation
+ * only: all state lives in the core model, and `meta` keys are never interpreted.
+ *
+ * @capability save-slot-menu drop-in save-select / profile menu that renders a core save-slots index as New / Continue / Load / Delete cards with free-string meta chips and relative save times, theme-skinnable
+ */
+export function SaveSlotMenu({ model, onLoad, onNew, onDelete, onContinue, title = "Select Save", theme, now = Date.now, metaIcons, className, style, }) {
+    const slots = useSaveSlots(model);
+    const t = resolveTheme(theme);
+    const nowMs = now();
+    const recent = model.mostRecent();
+    return (_jsxs("div", { className: className, "data-save-slot-menu": "", style: {
+            display: "flex",
+            flexDirection: "column",
+            gap: 12,
+            width: "min(92vw, 460px)",
+            fontFamily: t.fontFamily,
+            color: t.text,
+            ...style,
+        }, children: [_jsxs("div", { style: { display: "flex", alignItems: "center", justifyContent: "space-between", gap: 12 }, children: [_jsx("div", { style: { fontSize: 20, fontWeight: 800, letterSpacing: 0.4 }, children: title }), onContinue !== undefined && recent !== null ? (_jsxs("button", { type: "button", "data-save-slot-continue": "", style: rowButton(t.accent, true), onClick: () => onContinue(recent), children: [_jsx(GameIcon, { name: "skip", size: 14, color: "#0b1220" }), "Continue"] })) : null] }), slots.map((slot) => {
+                const isRecent = recent !== null && slot.id === recent.id;
+                return (_jsx(HudFrame, { interactive: true, variation: "glass", padding: 14, style: {
+                        background: t.cardBg,
+                        border: isRecent ? `1px solid ${t.accent}` : t.cardBorder,
+                        borderRadius: t.radius,
+                        boxShadow: isRecent ? `0 0 0 1px ${t.accent}, 0 8px 26px rgba(0,0,0,0.4)` : "0 6px 20px rgba(0,0,0,0.35)",
+                    }, children: slot.empty ? (_jsxs("button", { type: "button", "data-save-slot-new": "", onClick: () => onNew?.(slot), style: {
+                            pointerEvents: "auto",
+                            cursor: "pointer",
+                            width: "100%",
+                            display: "flex",
+                            alignItems: "center",
+                            gap: 12,
+                            background: "transparent",
+                            border: "none",
+                            color: t.muted,
+                            padding: "6px 2px",
+                            textAlign: "left",
+                        }, children: [_jsx("span", { style: {
+                                    display: "inline-flex",
+                                    alignItems: "center",
+                                    justifyContent: "center",
+                                    width: 40,
+                                    height: 40,
+                                    borderRadius: 10,
+                                    border: `1px dashed ${t.muted}`,
+                                }, children: _jsx(GameIcon, { name: "star", size: 18, color: t.muted }) }), _jsxs("span", { children: [_jsx("span", { style: { display: "block", fontSize: 15, fontWeight: 700, color: t.text }, children: "New Game" }), _jsxs("span", { style: { fontSize: 11 }, children: ["Empty slot \u00B7 ", slot.id] })] })] })) : (_jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 4 }, children: [_jsxs("div", { style: { display: "flex", alignItems: "baseline", justifyContent: "space-between", gap: 10 }, children: [_jsx("span", { "data-save-slot-name": "", style: { fontSize: 16, fontWeight: 800 }, children: slot.name ?? slot.id }), slot.savedAt !== undefined ? (_jsx("span", { style: { fontSize: 11, fontWeight: 600, color: t.accent, whiteSpace: "nowrap" }, children: relativeSavedAt(slot.savedAt, nowMs) })) : null] }), _jsx(MetaChips, { slot: slot, t: t, metaIcons: metaIcons }), _jsxs("div", { style: { display: "flex", gap: 8, marginTop: 12 }, children: [_jsxs("button", { type: "button", "data-save-slot-load": "", style: { ...rowButton(t.accent, true), flex: 1, justifyContent: "center" }, onClick: () => onLoad?.(slot), children: [_jsx(GameIcon, { name: "chest", size: 14, color: "#0b1220" }), "Load"] }), _jsxs("button", { type: "button", "data-save-slot-delete": "", style: rowButton(t.accent, false), onClick: () => onDelete?.(slot), "aria-label": `Delete ${slot.name ?? slot.id}`, children: [_jsx(GameIcon, { name: "cross", size: 14 }), "Delete"] })] })] })) }, slot.id));
+            })] }));
+}

package/dist/scoreboard.d.ts

@@ -0,0 +1,67 @@
+import { type CSSProperties, type ReactNode } from "react";
+import { type RankableRow, type RankedEntry, type RankLeaderboardOptions } from "@jgengine/core/game/leaderboardRank";
+import { type GameIconName } from "./gameIcons.js";
+/** The medal tokens {@link medalFor} emits for the podium. */
+export type MedalToken = "gold" | "silver" | "bronze";
+/** Reskin tokens for {@link Scoreboard}. Every color/spacing value reads a `--jg-*` token first. */
+export interface ScoreboardTheme {
+    /** Panel background. Default reads `--jg-frame-bg`. */
+    bg?: string;
+    /** Panel border. Default reads `--jg-frame-border`. */
+    border?: string;
+    /** Panel corner radius. Default reads `--jg-frame-radius`. */
+    radius?: string;
+    /** Row / header text color. */
+    text?: string;
+    /** Muted text (rank column, header labels). */
+    muted?: string;
+    /** Accent used for the local-row highlight. Default reads `--jg-accent`. */
+    accent?: string;
+    /** Background wash behind the local ("you") row. */
+    localBg?: string;
+    /** Font family. */
+    fontFamily?: string;
+    /** Podium medal colors keyed by token. */
+    medals?: Record<MedalToken, string>;
+}
+/** Props for {@link Scoreboard}. Pass either `entries` (already ranked) or `rows` + `options`. */
+export interface ScoreboardProps {
+    /** Already-ranked entries from {@link rankLeaderboard}. Takes precedence over `rows`. */
+    entries?: readonly RankedEntry[];
+    /** Raw rows to rank in-component. Ignored when `entries` is given. */
+    rows?: readonly RankableRow[];
+    /** Ranking options applied to `rows`. Ignored when `entries` is given. */
+    options?: RankLeaderboardOptions;
+    /** Optional heading rendered above the table (e.g. "TOP RUNNERS"). */
+    title?: ReactNode;
+    /** Label for the score column header. Default `"Score"`. */
+    scoreLabel?: string;
+    /**
+     * Map a `userId` to a display name. Falls back to the entry's `label`, then the
+     * raw `userId`. The model never carries display names it does not own.
+     */
+    nameFor?: (entry: RankedEntry) => ReactNode;
+    /** Format a raw score for display. Default `String(value)`. */
+    formatScore?: (value: number) => ReactNode;
+    /**
+     * Podium icon for a medal token. Default: a filled star tinted by the medal
+     * color. Return `null` to render just the numeric rank.
+     */
+    medalIcon?: (medal: MedalToken) => GameIconName | null;
+    /** Reskin tokens. */
+    theme?: ScoreboardTheme;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * A reskinnable ranked-score table for the {@link rankLeaderboard} selector: a rank
+ * column (medal icon/color for the top three via {@link medalFor}, otherwise the
+ * number), a name column, and a score column. The local player's row (`isLocal`) is
+ * washed and accented so "you" stands out. Feed it already-ranked `entries`, or raw
+ * `rows` plus `options` and it ranks them for you. All colors and spacing come from
+ * {@link ScoreboardTheme} / HudTheme `--jg-*` tokens — the component reads the model
+ * and never styles by game meaning.
+ *
+ * @capability scoreboard-table reskinnable ranked-score / leaderboard table over the rankLeaderboard selector — medal-colored podium, local-row highlight, HudTheme-token driven
+ */
+export declare function Scoreboard({ entries, rows, options, title, scoreLabel, nameFor, formatScore, medalIcon, theme, className, style, }: ScoreboardProps): ReactNode;

package/dist/scoreboard.js

@@ -0,0 +1,71 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import {} from "react";
+import { medalFor, rankLeaderboard, } from "@jgengine/core/game/leaderboardRank";
+import { GameIcon } from "./gameIcons.js";
+function resolveTheme(theme) {
+    return {
+        bg: theme?.bg ?? "var(--jg-frame-bg, linear-gradient(180deg, rgba(20,24,32,0.92), rgba(10,12,16,0.95)))",
+        border: theme?.border ?? "var(--jg-frame-border, 1px solid rgba(255,255,255,0.12))",
+        radius: theme?.radius ?? "var(--jg-frame-radius, 12px)",
+        text: theme?.text ?? "#f1f5f9",
+        muted: theme?.muted ?? "rgba(203,213,225,0.65)",
+        accent: theme?.accent ?? "var(--jg-accent, #38bdf8)",
+        localBg: theme?.localBg ?? "rgba(56,189,248,0.16)",
+        fontFamily: theme?.fontFamily ?? "ui-sans-serif, system-ui, sans-serif",
+        medals: theme?.medals ?? { gold: "#f5c542", silver: "#cbd5e1", bronze: "#cd7f32" },
+    };
+}
+/**
+ * A reskinnable ranked-score table for the {@link rankLeaderboard} selector: a rank
+ * column (medal icon/color for the top three via {@link medalFor}, otherwise the
+ * number), a name column, and a score column. The local player's row (`isLocal`) is
+ * washed and accented so "you" stands out. Feed it already-ranked `entries`, or raw
+ * `rows` plus `options` and it ranks them for you. All colors and spacing come from
+ * {@link ScoreboardTheme} / HudTheme `--jg-*` tokens — the component reads the model
+ * and never styles by game meaning.
+ *
+ * @capability scoreboard-table reskinnable ranked-score / leaderboard table over the rankLeaderboard selector — medal-colored podium, local-row highlight, HudTheme-token driven
+ */
+export function Scoreboard({ entries, rows, options, title, scoreLabel = "Score", nameFor, formatScore, medalIcon, theme, className, style, }) {
+    const t = resolveTheme(theme);
+    const ranked = entries ?? rankLeaderboard(rows ?? [], options ?? {});
+    const cell = { padding: "0.5em 0.75em", textAlign: "left", whiteSpace: "nowrap" };
+    const headCell = {
+        ...cell,
+        fontSize: "0.72em",
+        fontWeight: 700,
+        letterSpacing: "0.08em",
+        textTransform: "uppercase",
+        color: t.muted,
+    };
+    return (_jsxs("div", { className: className, "data-jgui": "scoreboard", style: {
+            display: "inline-flex",
+            flexDirection: "column",
+            gap: "0.5em",
+            background: t.bg,
+            border: t.border,
+            borderRadius: t.radius,
+            padding: "0.75em",
+            color: t.text,
+            fontFamily: t.fontFamily,
+            minWidth: 280,
+            ...style,
+        }, children: [title !== undefined ? (_jsx("div", { "data-jgui": "scoreboard-title", style: { fontSize: "0.95em", fontWeight: 800, letterSpacing: "0.06em", textTransform: "uppercase", padding: "0 0.25em" }, children: title })) : null, _jsxs("table", { style: { borderCollapse: "collapse", width: "100%", fontSize: "0.95em" }, children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { style: { ...headCell, textAlign: "center", width: "3em" }, children: "#" }), _jsx("th", { style: headCell, children: "Name" }), _jsx("th", { style: { ...headCell, textAlign: "right" }, children: scoreLabel })] }) }), _jsx("tbody", { children: ranked.map((entry, index) => {
+                            const medal = medalFor(entry.rank);
+                            const medalColor = medal !== null ? t.medals[medal] : undefined;
+                            const icon = medal !== null ? (medalIcon ? medalIcon(medal) : "star") : null;
+                            const name = nameFor ? nameFor(entry) : entry.label ?? entry.userId;
+                            const rowKey = `${entry.userId}:${index}`;
+                            return (_jsxs("tr", { "data-scoreboard-row": entry.userId, "data-rank": entry.rank, "data-local": entry.isLocal ? "" : undefined, "data-tie": entry.isTie ? "" : undefined, style: {
+                                    background: entry.isLocal ? t.localBg : "transparent",
+                                    boxShadow: entry.isLocal ? `inset 3px 0 0 ${t.accent}` : undefined,
+                                }, children: [_jsx("td", { style: { ...cell, textAlign: "center" }, children: _jsxs("span", { style: {
+                                                display: "inline-flex",
+                                                alignItems: "center",
+                                                justifyContent: "center",
+                                                gap: "0.25em",
+                                                color: medalColor ?? t.muted,
+                                                fontWeight: medal !== null ? 800 : 600,
+                                            }, children: [icon !== null ? _jsx(GameIcon, { name: icon, size: 16, color: medalColor }) : null, entry.rank] }) }), _jsx("td", { style: { ...cell, color: entry.isLocal ? t.accent : t.text, fontWeight: entry.isLocal ? 700 : 500 }, children: name }), _jsx("td", { style: { ...cell, textAlign: "right", fontVariantNumeric: "tabular-nums", fontWeight: 600 }, children: formatScore ? formatScore(entry.value) : entry.value })] }, rowKey));
+                        }) })] })] }));
+}

package/dist/settings.d.ts

@@ -65,11 +65,17 @@ export declare function SettingsControllerProvider({ controller, children, }: {
 export declare function useSettings(): SettingsController;
 /** True when the game has any setting or game-action to show — gate your own settings entry on it. */
 export declare function useHasSettings(): boolean;
+/**
+ * Default HudTheme-token skin for {@link SettingsTrigger} — the 8×8 chrome button
+ * games re-authored seven times. Pass your own `className` only to override placement
+ * or brand chrome; the gear glyph already scales with `text-base` / `1em`.
+ */
+export declare const SETTINGS_TRIGGER_CLASSNAME = "pointer-events-auto flex h-8 w-8 items-center justify-center rounded-md border border-[var(--jg-edge-bright)] bg-[var(--jg-surface)]/80 text-base text-[var(--jg-text-dim)] shadow-[0_1px_2px_rgba(0,0,0,0.6)] transition hover:bg-[var(--jg-surface-deep)] hover:text-[var(--jg-accent)]";
 /**
  * Inline settings entry — drop it anywhere in your game's menu or HUD; it opens
- * the themed settings menu. Headless: pass `className` for placement/skin and
- * `children` to replace the default gear glyph. Renders nothing when the game
- * has no settings to show, so it never leaves a dead button behind.
+ * the themed settings menu. Headless: pass `className` only when overriding the
+ * default HudTheme skin; pass `children` to replace the gear glyph. Renders nothing
+ * when the game has no settings to show, so it never leaves a dead button behind.
  */
 export declare function SettingsTrigger({ className, children, label, }: {
     className?: string;

package/dist/settings.js

@@ -47,13 +47,19 @@ export function useHasSettings() {
     const s = useSettings();
     return s.categories.length > 0 || s.actions.length > 0;
 }
+/**
+ * Default HudTheme-token skin for {@link SettingsTrigger} — the 8×8 chrome button
+ * games re-authored seven times. Pass your own `className` only to override placement
+ * or brand chrome; the gear glyph already scales with `text-base` / `1em`.
+ */
+export const SETTINGS_TRIGGER_CLASSNAME = "pointer-events-auto flex h-8 w-8 items-center justify-center rounded-md border border-[var(--jg-edge-bright)] bg-[var(--jg-surface)]/80 text-base text-[var(--jg-text-dim)] shadow-[0_1px_2px_rgba(0,0,0,0.6)] transition hover:bg-[var(--jg-surface-deep)] hover:text-[var(--jg-accent)]";
 /**
  * Inline settings entry — drop it anywhere in your game's menu or HUD; it opens
- * the themed settings menu. Headless: pass `className` for placement/skin and
- * `children` to replace the default gear glyph. Renders nothing when the game
- * has no settings to show, so it never leaves a dead button behind.
+ * the themed settings menu. Headless: pass `className` only when overriding the
+ * default HudTheme skin; pass `children` to replace the gear glyph. Renders nothing
+ * when the game has no settings to show, so it never leaves a dead button behind.
  */
-export function SettingsTrigger({ className, children, label = "Settings", }) {
+export function SettingsTrigger({ className = SETTINGS_TRIGGER_CLASSNAME, children, label = "Settings", }) {
     const settings = useSettings();
     if (settings.categories.length === 0 && settings.actions.length === 0)
         return null;

package/dist/shopGrid.d.ts

@@ -0,0 +1,70 @@
+import { type CSSProperties, type ReactNode } from "react";
+import { type WalletState } from "@jgengine/core/economy/wallet";
+import type { ShopStock, ShopStockEntry } from "@jgengine/core/economy/shopStock";
+import { type GameIconName } from "./gameIcons.js";
+/**
+ * Subscribe to a shop's stock and re-render whenever it changes (buy, sell, restock, price, add,
+ * remove, restore). Returns the current entry list — a detached snapshot safe to map over.
+ *
+ * @capability use-shop-stock React hook binding a shop-stock model — re-renders on any stock change and returns the entry list
+ */
+export declare function useShopStock(shop: ShopStock): ShopStockEntry[];
+/** Reskin tokens for {@link ShopGrid}. Falls back to shared `--jg-*` HudTheme tokens, then neutral defaults. */
+export interface ShopGridTheme {
+    /** Card background. Default reads `--jg-slot-bg`. */
+    cardBg?: string;
+    /** Card border. Default reads `--jg-slot-border`. */
+    cardBorder?: string;
+    /** Card corner radius. Default reads `--jg-slot-radius`. */
+    cardRadius?: string;
+    /** Accent for icons/prices/Buy button. Default reads `--jg-accent`. */
+    accent?: string;
+    /** Primary text color. */
+    text?: string;
+    /** Muted/secondary text color. */
+    muted?: string;
+    /** Font family. */
+    fontFamily?: string;
+}
+/** Props for {@link ShopGrid}. */
+export interface ShopGridProps {
+    /** The vendor stock model to render. */
+    shop: ShopStock;
+    /** The caller-owned wallet the grid buys/sells against. The shop never owns it. */
+    wallet: WalletState;
+    /** Called with the new wallet after a successful buy or sell — the caller adopts it. */
+    onWalletChange: (wallet: WalletState) => void;
+    /** Reskin tokens. */
+    theme?: ShopGridTheme;
+    /** Optional per-currency icon overrides, keyed by the free-string currency. */
+    currencyIcons?: Record<string, GameIconName>;
+    /** Optional entry→icon picker. Defaults to keyword matching on `kind`/`id`. */
+    iconFor?: (entry: ShopStockEntry) => GameIconName;
+    /** Show a Sell button on entries that carry a `sellPrice`. Default `false`. */
+    showSell?: boolean;
+    /**
+     * Currencies to show in the wallet readout, in order. Default: every currency referenced by the
+     * stock (prices + sell prices), in first-seen order.
+     */
+    walletCurrencies?: readonly string[];
+    /** Panel header label. Default `"Shop"`. */
+    title?: ReactNode;
+    /** Human label for an entry — default is the capitalized `kind`. */
+    labelFor?: (entry: ShopStockEntry) => ReactNode;
+    /** Minimum card width (CSS length) for the responsive grid. Default `"140px"`. */
+    minCardWidth?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * A drop-in vendor/shop grid: item cards (icon, name, price with a currency glyph, stock count or
+ * "∞") over a caller-owned wallet, plus a wallet balance readout. Each card's Buy button disables
+ * when the wallet cannot afford it (`shop.canAfford`) or the item is sold out; an optional Sell
+ * button appears for entries with a `sellPrice`. Buying/selling routes through the core shop model
+ * and hands the debited/credited wallet back via `onWalletChange` — the component never owns the
+ * wallet. Purely token-driven presentation (shared `--jg-*` HudTheme tokens, reskinnable via
+ * {@link ShopGridTheme}); `kind` and `currency` are free strings the game styles, never interpreted.
+ *
+ * @capability shop-grid-host drop-in vendor/shop grid over a caller-owned wallet — item cards with icon/price/stock, afford-aware Buy, optional Sell, and a balance readout, token-themed
+ */
+export declare function ShopGrid({ shop, wallet, onWalletChange, theme, currencyIcons, iconFor, showSell, walletCurrencies, title, labelFor, minCardWidth, className, style, }: ShopGridProps): ReactNode;

package/dist/shopGrid.js

@@ -0,0 +1,129 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useReducer } from "react";
+import { balance } from "@jgengine/core/economy/wallet";
+import { GameIcon, iconForItemId } from "./gameIcons.js";
+import { HudFrame } from "./hudFrame.js";
+/**
+ * Subscribe to a shop's stock and re-render whenever it changes (buy, sell, restock, price, add,
+ * remove, restore). Returns the current entry list — a detached snapshot safe to map over.
+ *
+ * @capability use-shop-stock React hook binding a shop-stock model — re-renders on any stock change and returns the entry list
+ */
+export function useShopStock(shop) {
+    const [, bump] = useReducer((n) => n + 1, 0);
+    useEffect(() => shop.subscribe(bump), [shop]);
+    return shop.list();
+}
+function resolveTheme(theme) {
+    return {
+        cardBg: theme?.cardBg ?? "var(--jg-slot-bg, rgba(12,14,20,0.72))",
+        cardBorder: theme?.cardBorder ?? "var(--jg-slot-border, 1px solid rgba(255,255,255,0.12))",
+        cardRadius: theme?.cardRadius ?? "var(--jg-slot-radius, 10px)",
+        accent: theme?.accent ?? "var(--jg-accent, #38bdf8)",
+        text: theme?.text ?? "#f1f5f9",
+        muted: theme?.muted ?? "rgba(203,213,225,0.72)",
+        fontFamily: theme?.fontFamily ?? "ui-sans-serif, system-ui, sans-serif",
+    };
+}
+/** Default currency → icon mapping via {@link iconForItemId} (which knows "gold"/"gem"/… keywords). */
+function currencyIcon(currency, override) {
+    return override?.[currency] ?? iconForItemId(currency) ?? "coin";
+}
+/** Default entry → icon mapping from the free-string `kind`, falling back to a chest. */
+function entryIcon(entry, iconFor) {
+    if (iconFor !== undefined)
+        return iconFor(entry);
+    return iconForItemId(entry.kind) ?? iconForItemId(entry.id) ?? "chest";
+}
+function capitalize(value) {
+    return value.length === 0 ? value : value[0].toUpperCase() + value.slice(1);
+}
+function referencedCurrencies(entries) {
+    const seen = [];
+    const add = (currency) => {
+        if (!seen.includes(currency))
+            seen.push(currency);
+    };
+    for (const entry of entries) {
+        add(entry.price.currency);
+        if (entry.sellPrice !== undefined)
+            add(entry.sellPrice.currency);
+    }
+    return seen;
+}
+function PriceTag({ price, icon, accent, muted, }) {
+    return (_jsxs("span", { style: { display: "inline-flex", alignItems: "center", gap: 4, color: muted, fontVariantNumeric: "tabular-nums" }, children: [_jsx(GameIcon, { name: icon, size: 15, color: accent }), _jsx("span", { style: { fontWeight: 700, color: "inherit" }, children: price.amount })] }));
+}
+/**
+ * A drop-in vendor/shop grid: item cards (icon, name, price with a currency glyph, stock count or
+ * "∞") over a caller-owned wallet, plus a wallet balance readout. Each card's Buy button disables
+ * when the wallet cannot afford it (`shop.canAfford`) or the item is sold out; an optional Sell
+ * button appears for entries with a `sellPrice`. Buying/selling routes through the core shop model
+ * and hands the debited/credited wallet back via `onWalletChange` — the component never owns the
+ * wallet. Purely token-driven presentation (shared `--jg-*` HudTheme tokens, reskinnable via
+ * {@link ShopGridTheme}); `kind` and `currency` are free strings the game styles, never interpreted.
+ *
+ * @capability shop-grid-host drop-in vendor/shop grid over a caller-owned wallet — item cards with icon/price/stock, afford-aware Buy, optional Sell, and a balance readout, token-themed
+ */
+export function ShopGrid({ shop, wallet, onWalletChange, theme, currencyIcons, iconFor, showSell = false, walletCurrencies, title = "Shop", labelFor, minCardWidth = "140px", className, style, }) {
+    const entries = useShopStock(shop);
+    const t = resolveTheme(theme);
+    const currencies = walletCurrencies ?? referencedCurrencies(entries);
+    const onBuy = (entry) => {
+        const result = shop.buy(entry.id, wallet);
+        if (result.ok)
+            onWalletChange(result.wallet);
+    };
+    const onSell = (entry) => {
+        const result = shop.sell(entry.id, wallet);
+        if (result.ok)
+            onWalletChange(result.wallet);
+    };
+    const walletReadout = (_jsx("div", { "data-shop-grid-wallet": true, style: { display: "flex", flexWrap: "wrap", gap: 12, alignItems: "center" }, children: currencies.map((currency) => (_jsxs("span", { "data-shop-grid-balance": currency, style: { display: "inline-flex", alignItems: "center", gap: 5, color: t.text, fontVariantNumeric: "tabular-nums", fontWeight: 700 }, children: [_jsx(GameIcon, { name: currencyIcon(currency, currencyIcons), size: 18, color: t.accent }), balance(wallet, currency)] }, currency))) }));
+    return (_jsx(HudFrame, { variation: "themed", title: title, aside: walletReadout, interactive: true, className: className, style: { fontFamily: t.fontFamily, color: t.text, ...style }, children: _jsx("div", { "data-shop-grid": true, style: {
+                display: "grid",
+                gridTemplateColumns: `repeat(auto-fill, minmax(${minCardWidth}, 1fr))`,
+                gap: 10,
+            }, children: entries.map((entry) => {
+                const soldOut = entry.qty !== null && entry.qty <= 0;
+                const affordable = shop.canAfford(entry.id, wallet);
+                const buyDisabled = soldOut || !affordable;
+                return (_jsxs("div", { "data-shop-item": entry.id, "data-kind": entry.kind, style: {
+                        display: "flex",
+                        flexDirection: "column",
+                        gap: 6,
+                        padding: 10,
+                        background: t.cardBg,
+                        border: t.cardBorder,
+                        borderRadius: t.cardRadius,
+                        opacity: soldOut ? 0.55 : 1,
+                    }, children: [_jsxs("div", { style: { display: "flex", alignItems: "center", justifyContent: "space-between", gap: 6 }, children: [_jsx("div", { style: {
+                                        display: "grid",
+                                        placeItems: "center",
+                                        width: 40,
+                                        height: 40,
+                                        borderRadius: 8,
+                                        background: "rgba(0,0,0,0.28)",
+                                    }, children: _jsx(GameIcon, { name: entryIcon(entry, iconFor), size: 28, color: t.accent }) }), _jsx("span", { "data-shop-item-qty": true, style: { fontSize: 12, fontWeight: 700, color: t.muted, fontVariantNumeric: "tabular-nums" }, children: entry.qty === null ? "∞" : `x${entry.qty}` })] }), _jsx("div", { style: { fontSize: 13, fontWeight: 700, color: t.text, lineHeight: 1.2 }, children: labelFor?.(entry) ?? capitalize(entry.kind) }), _jsxs("div", { style: { display: "flex", alignItems: "center", justifyContent: "space-between", gap: 6 }, children: [_jsx(PriceTag, { price: entry.price, icon: currencyIcon(entry.price.currency, currencyIcons), accent: t.accent, muted: t.text }), entry.sellPrice !== undefined ? (_jsxs("span", { style: { display: "inline-flex", alignItems: "center", gap: 3, fontSize: 11, color: t.muted }, children: ["sell", _jsx(PriceTag, { price: entry.sellPrice, icon: currencyIcon(entry.sellPrice.currency, currencyIcons), accent: t.muted, muted: t.muted })] })) : null] }), _jsxs("div", { style: { display: "flex", gap: 6 }, children: [_jsx("button", { type: "button", "data-shop-buy": entry.id, disabled: buyDisabled, onClick: () => onBuy(entry), style: {
+                                        flex: 1,
+                                        padding: "7px 8px",
+                                        borderRadius: 8,
+                                        border: "none",
+                                        fontWeight: 800,
+                                        fontSize: 12,
+                                        letterSpacing: "0.03em",
+                                        cursor: buyDisabled ? "not-allowed" : "pointer",
+                                        color: buyDisabled ? t.muted : "#0b1017",
+                                        background: buyDisabled ? "rgba(255,255,255,0.08)" : t.accent,
+                                    }, children: soldOut ? "Sold Out" : "Buy" }), showSell && entry.sellPrice !== undefined ? (_jsx("button", { type: "button", "data-shop-sell": entry.id, onClick: () => onSell(entry), style: {
+                                        padding: "7px 10px",
+                                        borderRadius: 8,
+                                        border: t.cardBorder,
+                                        fontWeight: 700,
+                                        fontSize: 12,
+                                        cursor: "pointer",
+                                        color: t.text,
+                                        background: "transparent",
+                                    }, children: "Sell" })) : null] })] }, entry.id));
+            }) }) }));
+}

package/dist/statusEffectBar.d.ts

@@ -0,0 +1,52 @@
+import { type CSSProperties, type ReactNode } from "react";
+import { type StatusEffectView } from "@jgengine/core/combat";
+import { type GameIconName } from "./gameIcons.js";
+import { type IconSchool } from "./iconTreatment.js";
+/**
+ * `StatusEffectBar` (#status-effect-hud): a drop-in timeline HUD row that renders active
+ * buffs/debuffs as painted icons, each wrapped in a radial countdown ring and a stack-count badge,
+ * driven straight off the engine's existing status model (`StatusInstance` → `StatusEffectView`).
+ * A game passes its live effect views and gets a polished, reskinnable effect bar — no re-deriving
+ * ring math or timers. `kind` is a free string the game styles: the component never interprets
+ * buff-vs-debuff semantics, it only maps `kind` to an icon/color/label the game can fully override.
+ * Ring, track, and frame read `HudTheme` tokens (`--jg-accent`, `--jg-slot-*`), so a theme change
+ * reskins the whole row.
+ */
+/** How a `kind` resolves to a glyph: a `GameIcon` name, an explicit node, or `null` for the fallback. */
+export type StatusIconResolver = (kind: string) => GameIconName | ReactNode | null;
+/** Props for {@link StatusEffectBar}. */
+export interface StatusEffectBarProps {
+    /** Live effect views from the status model (`toStatusEffectViews(...)`). Rendered in order. */
+    effects: readonly StatusEffectView[];
+    /** Icon face size in px. Default 44. */
+    size?: number;
+    /** Gap between icons in px. Default 8. */
+    gap?: number;
+    /**
+     * Resolve a `kind` to its glyph. Default: the matching `GameIcon` keyword, else an hourglass.
+     * Return a `GameIconName`, any `ReactNode`, or `null` to fall through to the default.
+     */
+    iconFor?: StatusIconResolver;
+    /** Ring color per `kind`. Default reads `--jg-accent`. Style debuffs red / buffs green here. */
+    colorFor?: (kind: string) => string;
+    /** School gradient behind the glyph per `kind`. Default inferred from the `kind` keyword. */
+    schoolFor?: (kind: string) => IconSchool;
+    /** Tooltip/`aria-label` per effect. Default: the `kind`, with a `xN` suffix when stacked. */
+    labelFor?: (effect: StatusEffectView) => string;
+    /** Show the remaining-seconds readout under each icon. Default true. */
+    showTimer?: boolean;
+    /** Ring stroke width in px. Default 3. */
+    ringWidth?: number;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * A horizontal timeline of active status effects — one countdown-ring icon per effect. Presentation
+ * only and pure over its `effects` prop, so it renders straight off the status model's snapshot.
+ * `kind` is a free string the game styles (icon / color / label); the component never interprets
+ * buff-vs-debuff semantics. Ring, track, and frame read `HudTheme` tokens, so a theme change reskins
+ * the whole row.
+ *
+ * @capability status-effect-bar timeline HUD row of active statuses — icon + radial countdown ring + stack badge, driven off the status model, HudTheme-skinned
+ */
+export declare function StatusEffectBar({ effects, size, gap, iconFor, colorFor, schoolFor, labelFor, showTimer, ringWidth, className, style, }: StatusEffectBarProps): ReactNode;

package/dist/statusEffectBar.js

@@ -0,0 +1,57 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import {} from "react";
+import { statusEffectRemainingFraction } from "@jgengine/core/combat";
+import { iconForItemId, isGameIconName } from "./gameIcons.js";
+import { IconTreatment, schoolForItem } from "./iconTreatment.js";
+const FALLBACK_ICON = "hourglass";
+function defaultIcon(kind) {
+    return iconForItemId(kind) ?? FALLBACK_ICON;
+}
+function resolveGlyph(kind, iconFor) {
+    const custom = iconFor?.(kind) ?? null;
+    if (custom === null)
+        return { icon: defaultIcon(kind) };
+    if (typeof custom === "string")
+        return isGameIconName(custom) ? { icon: custom } : { icon: defaultIcon(kind) };
+    return { node: custom };
+}
+function defaultLabel(effect) {
+    return effect.stacks > 1 ? `${effect.kind} x${effect.stacks}` : effect.kind;
+}
+function remainingSeconds(remainingMs) {
+    const seconds = remainingMs / 1000;
+    if (seconds >= 10)
+        return `${Math.ceil(seconds)}`;
+    if (seconds >= 1)
+        return seconds.toFixed(1);
+    return remainingMs > 0 ? "<1" : "0";
+}
+/** A single effect icon: painted face + stack badge, overlaid with its radial countdown ring. */
+function StatusEffectIcon({ effect, size, ringColor, school, glyph, label, showTimer, ringWidth, }) {
+    const fraction = statusEffectRemainingFraction(effect);
+    const radius = (size - ringWidth) / 2;
+    const circumference = 2 * Math.PI * radius;
+    const dashOffset = circumference * (1 - fraction);
+    return (_jsxs("div", { "data-status-effect": effect.kind, "data-remaining-fraction": fraction.toFixed(4), title: label, "aria-label": label, style: { display: "flex", flexDirection: "column", alignItems: "center", gap: 3 }, children: [_jsxs("div", { style: { position: "relative", width: size, height: size }, children: [_jsx(IconTreatment, { ...(glyph.node !== undefined ? { glyph: glyph.node } : glyph.icon !== undefined ? { icon: glyph.icon } : {}), school: school, size: size, count: effect.stacks }), _jsxs("svg", { width: size, height: size, viewBox: `0 0 ${size} ${size}`, "aria-hidden": "true", style: { position: "absolute", inset: 0, transform: "rotate(-90deg)", pointerEvents: "none", overflow: "visible" }, children: [_jsx("circle", { cx: size / 2, cy: size / 2, r: radius, fill: "none", stroke: "rgba(0,0,0,0.55)", strokeWidth: ringWidth }), _jsx("circle", { "data-countdown-ring": "", cx: size / 2, cy: size / 2, r: radius, fill: "none", stroke: ringColor, strokeWidth: ringWidth, strokeLinecap: "round", strokeDasharray: circumference, strokeDashoffset: dashOffset, style: { transition: "stroke-dashoffset 200ms linear" } })] })] }), showTimer ? (_jsx("span", { "data-status-timer": "", style: {
+                    fontSize: 10,
+                    fontWeight: 700,
+                    fontVariantNumeric: "tabular-nums",
+                    color: "var(--jg-bar-text, #f5f7fa)",
+                    textShadow: "0 1px 2px rgba(0,0,0,0.9)",
+                    lineHeight: 1,
+                }, children: remainingSeconds(effect.remainingMs) })) : null] }));
+}
+/**
+ * A horizontal timeline of active status effects — one countdown-ring icon per effect. Presentation
+ * only and pure over its `effects` prop, so it renders straight off the status model's snapshot.
+ * `kind` is a free string the game styles (icon / color / label); the component never interprets
+ * buff-vs-debuff semantics. Ring, track, and frame read `HudTheme` tokens, so a theme change reskins
+ * the whole row.
+ *
+ * @capability status-effect-bar timeline HUD row of active statuses — icon + radial countdown ring + stack badge, driven off the status model, HudTheme-skinned
+ */
+export function StatusEffectBar({ effects, size = 44, gap = 8, iconFor, colorFor, schoolFor, labelFor, showTimer = true, ringWidth = 3, className, style, }) {
+    if (effects.length === 0)
+        return null;
+    return (_jsx("div", { className: className, "data-status-effect-bar": "", style: { display: "flex", alignItems: "flex-start", gap, ...style }, children: effects.map((effect) => (_jsx(StatusEffectIcon, { effect: effect, size: size, ringColor: colorFor?.(effect.kind) ?? "var(--jg-accent, #38bdf8)", school: schoolFor?.(effect.kind) ?? schoolForItem(effect.kind), glyph: resolveGlyph(effect.kind, iconFor), label: labelFor?.(effect) ?? defaultLabel(effect), showTimer: showTimer, ringWidth: ringWidth }, effect.id))) }));
+}