@jgengine/react 0.14.0 → 0.15.0

package/dist/photoMode.d.ts

@@ -0,0 +1,21 @@
+import { type CSSProperties, type ReactNode } from "react";
+import type { PhotoModeState, PhotoModeStore } from "@jgengine/core/ui/photoMode";
+/** Subscribe to a photo-mode store's live state. */
+export declare function usePhotoMode(store: PhotoModeStore): PhotoModeState;
+/** Props for {@link PhotoModeControls}. */
+export interface PhotoModeControlsProps {
+    store: PhotoModeStore;
+    /** Take the shot — wire to shell `captureCanvas` + `downloadImage`. */
+    onCapture?: () => void;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Photo-mode toolbar — a hide/show-HUD toggle, a capture button, and an exit
+ * button, bound to a `createPhotoModeStore`. Presentation-only: the game wires
+ * `onCapture` to shell `captureCanvas`/`downloadImage` and reads `hideHud` to
+ * drop its gameplay HUD.
+ *
+ * @capability photo-mode-controls photo-mode toolbar (hide-HUD toggle, capture, exit) bound to a photo-mode store
+ */
+export declare function PhotoModeControls({ store, onCapture, className, style }: PhotoModeControlsProps): ReactNode;

package/dist/photoMode.js

@@ -0,0 +1,39 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useSyncExternalStore } from "react";
+/** Subscribe to a photo-mode store's live state. */
+export function usePhotoMode(store) {
+    return useSyncExternalStore(store.subscribe, store.get, store.get);
+}
+const BTN = {
+    borderRadius: 8,
+    border: "1px solid rgba(148,163,184,0.4)",
+    background: "rgba(17,22,30,0.85)",
+    color: "#e2e8f0",
+    fontSize: 12,
+    fontWeight: 600,
+    padding: "6px 12px",
+    cursor: "pointer",
+};
+/**
+ * Photo-mode toolbar — a hide/show-HUD toggle, a capture button, and an exit
+ * button, bound to a `createPhotoModeStore`. Presentation-only: the game wires
+ * `onCapture` to shell `captureCanvas`/`downloadImage` and reads `hideHud` to
+ * drop its gameplay HUD.
+ *
+ * @capability photo-mode-controls photo-mode toolbar (hide-HUD toggle, capture, exit) bound to a photo-mode store
+ */
+export function PhotoModeControls({ store, onCapture, className, style }) {
+    const state = usePhotoMode(store);
+    return (_jsxs("div", { className: className, "data-photo-mode-controls": true, style: {
+            display: "inline-flex",
+            alignItems: "center",
+            gap: 8,
+            padding: 8,
+            borderRadius: 12,
+            background: "rgba(6,9,14,0.86)",
+            border: "1px solid var(--jg-ring, rgba(148,163,184,0.3))",
+            color: "#e2e8f0",
+            fontFamily: "ui-sans-serif, system-ui, sans-serif",
+            ...style,
+        }, children: [_jsx("span", { style: { fontSize: 11, letterSpacing: 1.4, textTransform: "uppercase", color: "rgba(203,213,225,0.75)", padding: "0 4px" }, children: "\uD83D\uDCF7 Photo" }), _jsx("button", { type: "button", "data-photo-hide-hud": true, "aria-pressed": state.hideHud, onClick: () => store.setHideHud(!state.hideHud), style: { ...BTN, ...(state.hideHud ? { borderColor: "rgba(56,189,248,0.6)", color: "#bae6fd" } : {}) }, children: state.hideHud ? "HUD hidden" : "HUD shown" }), onCapture !== undefined ? (_jsx("button", { type: "button", "data-photo-capture": true, onClick: onCapture, style: { ...BTN, borderColor: "rgba(74,222,128,0.6)", color: "#bbf7d0" }, children: "Capture" })) : null, _jsx("button", { type: "button", "data-photo-exit": true, onClick: () => store.exit(), style: BTN, children: "Exit" })] }));
+}

package/dist/previewFixtures.d.ts

@@ -0,0 +1,30 @@
+import type { GamePreviewComponent } from "./preview.js";
+/**
+ * One entry in the engine preview-fixture registry: a deterministic, engine-level
+ * preview component keyed by a stable id.
+ */
+export interface PreviewFixture {
+    /** Stable id used on the `?fixture=` capture route and `bun run shoot --fixture <name>`. */
+    readonly name: string;
+    /** One-line description of what the deterministic fixture renders. */
+    readonly description: string;
+    /** The real exported preview component, rendered from static values (screenshots identically). */
+    readonly component: GamePreviewComponent;
+}
+/**
+ * Registry of deterministic, engine-level preview fixtures — the *real* exported
+ * `@jgengine/react` components (`HudThemePreview`, `BarsPreview`, `IconsPreview`, …) that render
+ * identically every time from static values, so they can be screenshotted as regression evidence
+ * without booting a game.
+ *
+ * The dev runner's fixtures route (`?fixture=<name>`) and `bun run shoot --fixture <name>` mount
+ * these by name; `bun run shoot --list` (or `--fixture` with no name) prints the registered set.
+ * Register any additional deterministic preview component here — the route and `shoot` pick it up
+ * with no further wiring. Genre-agnostic: there is no hardcoded fixture set beyond what this record
+ * declares.
+ */
+export declare const PREVIEW_FIXTURES: Record<string, PreviewFixture>;
+/** Sorted list of registered fixture names, for discovery/listing. */
+export declare function previewFixtureNames(): string[];
+/** Resolve a fixture by name, or `undefined` when it is not registered. */
+export declare function resolvePreviewFixture(name: string): PreviewFixture | undefined;

package/dist/previewFixtures.js

@@ -0,0 +1,46 @@
+import { BarsPreview } from "./barsPreview.js";
+import { HudThemePreview } from "./hudThemePreview.js";
+import { IconsPreview } from "./iconsPreview.js";
+import { StreetGeometryPreview } from "./streetGeometryPreview.js";
+/**
+ * Registry of deterministic, engine-level preview fixtures — the *real* exported
+ * `@jgengine/react` components (`HudThemePreview`, `BarsPreview`, `IconsPreview`, …) that render
+ * identically every time from static values, so they can be screenshotted as regression evidence
+ * without booting a game.
+ *
+ * The dev runner's fixtures route (`?fixture=<name>`) and `bun run shoot --fixture <name>` mount
+ * these by name; `bun run shoot --list` (or `--fixture` with no name) prints the registered set.
+ * Register any additional deterministic preview component here — the route and `shoot` pick it up
+ * with no further wiring. Genre-agnostic: there is no hardcoded fixture set beyond what this record
+ * declares.
+ */
+export const PREVIEW_FIXTURES = {
+    HudThemePreview: {
+        name: "HudThemePreview",
+        description: "Every HudTheme genre preset × atomic bars + a themed frame + a slot row.",
+        component: HudThemePreview,
+    },
+    BarsPreview: {
+        name: "BarsPreview",
+        description: "Every atomic vitals bar rendered twice under different BarTokens blocks.",
+        component: BarsPreview,
+    },
+    IconsPreview: {
+        name: "IconsPreview",
+        description: "IconTreatment school-gradient row plus a treated-icon hotbar with badges.",
+        component: IconsPreview,
+    },
+    StreetGeometryPreview: {
+        name: "StreetGeometryPreview",
+        description: "Close-up welded road meshes for turns, unequal crossings, and five-way junctions.",
+        component: StreetGeometryPreview,
+    },
+};
+/** Sorted list of registered fixture names, for discovery/listing. */
+export function previewFixtureNames() {
+    return Object.keys(PREVIEW_FIXTURES).sort();
+}
+/** Resolve a fixture by name, or `undefined` when it is not registered. */
+export function resolvePreviewFixture(name) {
+    return PREVIEW_FIXTURES[name];
+}

package/dist/questTracker.d.ts

@@ -0,0 +1,24 @@
+import type { CSSProperties, ReactNode } from "react";
+import type { TrackedQuestView } from "@jgengine/core/game/quest";
+/** Props for {@link QuestTracker}. */
+export interface QuestTrackerProps {
+    /** Quests to show, e.g. `journal.list(userId).map((q) => describeTrackedQuest(defs[q.questId], q))`. */
+    quests: readonly TrackedQuestView[];
+    title?: string;
+    emptyLabel?: string;
+    /** Max objectives shown per quest before a "+N more" line. Default: all. */
+    maxObjectives?: number;
+    /** Accent color for the completion tick / progress fill. Reads a HudTheme token by default. */
+    accent?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Quest / objective tracker HUD — a compact panel of active quests with a title
+ * and labelled, progress-barred objectives (checked + struck when complete).
+ * Presentation-only over `describeTrackedQuest(def, instance)` views, so it stays
+ * decoupled from the `QuestJournal` runtime.
+ *
+ * @capability quest-tracker compact quest/objective HUD tracker — titles + labelled objective progress from describeTrackedQuest views
+ */
+export declare function QuestTracker({ quests, title, emptyLabel, maxObjectives, accent, className, style, }: QuestTrackerProps): ReactNode;

package/dist/questTracker.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+function ObjectiveRow({ label, progress, count, complete, accent }) {
+    const fraction = count > 0 ? Math.min(1, progress / count) : complete ? 1 : 0;
+    return (_jsxs("li", { "data-quest-objective": true, "data-complete": complete, style: { display: "flex", flexDirection: "column", gap: 3, listStyle: "none" }, children: [_jsxs("div", { style: { display: "flex", alignItems: "baseline", justifyContent: "space-between", gap: 8 }, children: [_jsxs("span", { style: { display: "flex", alignItems: "baseline", gap: 6, opacity: complete ? 0.65 : 1 }, children: [_jsx("span", { "aria-hidden": true, style: { color: complete ? accent : "rgba(148,163,184,0.7)" }, children: complete ? "✓" : "○" }), _jsx("span", { style: { textDecoration: complete ? "line-through" : "none" }, children: label })] }), count > 1 ? (_jsxs("span", { style: { fontVariantNumeric: "tabular-nums", color: "rgba(203,213,225,0.7)", fontSize: "0.9em" }, children: [Math.min(progress, count), "/", count] })) : null] }), count > 1 && !complete ? (_jsx("div", { style: { height: 3, borderRadius: 9999, background: "rgba(148,163,184,0.2)", overflow: "hidden" }, children: _jsx("div", { style: { width: `${Math.round(fraction * 100)}%`, height: "100%", background: accent } }) })) : null] }));
+}
+/**
+ * Quest / objective tracker HUD — a compact panel of active quests with a title
+ * and labelled, progress-barred objectives (checked + struck when complete).
+ * Presentation-only over `describeTrackedQuest(def, instance)` views, so it stays
+ * decoupled from the `QuestJournal` runtime.
+ *
+ * @capability quest-tracker compact quest/objective HUD tracker — titles + labelled objective progress from describeTrackedQuest views
+ */
+export function QuestTracker({ quests, title = "Quests", emptyLabel = "No active quests.", maxObjectives, accent = "var(--jg-accent, #facc15)", className, style, }) {
+    return (_jsxs("div", { className: className, "data-quest-tracker": true, style: {
+            width: 260,
+            borderRadius: 12,
+            padding: 12,
+            background: "linear-gradient(160deg, rgba(20,24,32,0.92), rgba(11,14,19,0.92))",
+            border: "1px solid var(--jg-ring, rgba(148,163,184,0.28))",
+            color: "#e2e8f0",
+            fontFamily: "ui-sans-serif, system-ui, sans-serif",
+            fontSize: 12,
+            ...style,
+        }, children: [title !== "" ? (_jsx("div", { style: { fontSize: 10, letterSpacing: 1.4, textTransform: "uppercase", color: "rgba(203,213,225,0.7)", marginBottom: 8 }, children: title })) : null, quests.length === 0 ? (_jsx("p", { style: { margin: 0, color: "rgba(148,163,184,0.8)" }, children: emptyLabel })) : (_jsx("ul", { style: { margin: 0, padding: 0, listStyle: "none", display: "flex", flexDirection: "column", gap: 10 }, children: quests.map((quest) => {
+                    const shown = maxObjectives === undefined ? quest.objectives : quest.objectives.slice(0, maxObjectives);
+                    const hidden = quest.objectives.length - shown.length;
+                    const done = quest.status === "completed";
+                    return (_jsxs("li", { "data-quest": quest.id, "data-status": quest.status, style: { listStyle: "none" }, children: [_jsxs("div", { style: { display: "flex", alignItems: "baseline", gap: 6, marginBottom: 4 }, children: [_jsx("span", { style: { fontWeight: 700, color: done ? accent : "#f8fafc" }, children: quest.title }), done ? _jsx("span", { style: { fontSize: 10, color: accent }, children: "DONE" }) : null] }), _jsx("ul", { style: { margin: 0, padding: 0, display: "flex", flexDirection: "column", gap: 5 }, children: shown.map((objective) => (_jsx(ObjectiveRow, { label: objective.label, progress: objective.progress, count: objective.count, complete: objective.complete, accent: accent }, objective.id))) }), hidden > 0 ? (_jsxs("div", { style: { marginTop: 4, fontSize: 11, color: "rgba(148,163,184,0.75)" }, children: ["+", hidden, " more"] })) : null] }, quest.id));
+                }) }))] }));
+}

package/dist/quickMenu.d.ts

@@ -0,0 +1,39 @@
+import { type CSSProperties, type ReactNode } from "react";
+import type { RadialArc } from "@jgengine/core/ui/radialMenu";
+import { type RadialMenuOption } from "./radialMenu.js";
+/** An entry on a {@link QuickMenu}: a leaf action, or (with `children`) a submenu. */
+export interface QuickMenuItem extends RadialMenuOption {
+    /** Nested items; selecting this entry drills into them instead of firing `onSelect`. */
+    children?: readonly QuickMenuItem[];
+    /** Optional group heading (list/grid layouts). */
+    section?: string;
+}
+/** The forms a {@link QuickMenu} can take. */
+export type QuickMenuLayout = "radial" | "arc" | "list" | "grid";
+/** Props for {@link QuickMenu}. */
+export interface QuickMenuProps {
+    items: readonly QuickMenuItem[];
+    layout?: QuickMenuLayout;
+    onSelect: (id: string) => void;
+    onClose?: () => void;
+    title?: string;
+    /** Grid columns. Default 3. */
+    columns?: number;
+    /** Arc span for `layout="arc"`. Default a bottom half. */
+    arc?: RadialArc;
+    /** Diameter for radial/arc forms. Default 300. */
+    radialSize?: number;
+    accent?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Versatile quick menu that takes many forms — a `radial` wheel, a partial
+ * `arc`, a vertical `list`, or a `grid` — over one item model with icons,
+ * labels, hotkeys, count badges, cooldowns, section headers, and nested
+ * submenus (drill in / back). Radial and arc forms reuse {@link RadialMenu};
+ * list and grid render sectioned rows/tiles. The game supplies content and skin.
+ *
+ * @capability quick-menu multi-form quick menu (radial / arc / list / grid) over one item model with hotkeys, badges, cooldowns, sections, and nested submenus
+ */
+export declare function QuickMenu({ items, layout, onSelect, onClose, title, columns, arc, radialSize, accent, className, style, }: QuickMenuProps): ReactNode;

package/dist/quickMenu.js

@@ -0,0 +1,79 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo, useState } from "react";
+import { RadialMenu } from "./radialMenu.js";
+const PANEL = {
+    borderRadius: 14,
+    padding: 12,
+    background: "linear-gradient(160deg, rgba(20,24,32,0.94), rgba(11,14,19,0.94))",
+    border: "1px solid var(--jg-ring, rgba(148,163,184,0.3))",
+    color: "#e2e8f0",
+    fontFamily: "ui-sans-serif, system-ui, sans-serif",
+};
+function groupBySection(items) {
+    const groups = [];
+    for (const item of items) {
+        const last = groups[groups.length - 1];
+        if (last !== undefined && last.section === item.section)
+            last.items.push(item);
+        else
+            groups.push({ section: item.section, items: [item] });
+    }
+    return groups;
+}
+function Badges({ item, accent }) {
+    return (_jsxs("span", { style: { display: "inline-flex", alignItems: "center", gap: 6 }, children: [item.cooldown !== undefined && item.cooldown > 0 ? (_jsxs("span", { style: { fontSize: 10, color: "rgba(148,163,184,0.85)" }, children: [Math.ceil(item.cooldown * 100), "%"] })) : null, item.badge !== undefined ? (_jsx("span", { style: { fontSize: 11, fontWeight: 700, color: accent, fontVariantNumeric: "tabular-nums" }, children: item.badge })) : null, item.hotkey !== undefined ? (_jsx("kbd", { style: { fontSize: 10, padding: "1px 5px", borderRadius: 4, border: "1px solid rgba(148,163,184,0.4)", color: "rgba(226,232,240,0.85)" }, children: item.hotkey })) : null, item.children !== undefined ? _jsx("span", { style: { color: "rgba(226,232,240,0.7)" }, children: "\u25B8" }) : null] }));
+}
+/**
+ * Versatile quick menu that takes many forms — a `radial` wheel, a partial
+ * `arc`, a vertical `list`, or a `grid` — over one item model with icons,
+ * labels, hotkeys, count badges, cooldowns, section headers, and nested
+ * submenus (drill in / back). Radial and arc forms reuse {@link RadialMenu};
+ * list and grid render sectioned rows/tiles. The game supplies content and skin.
+ *
+ * @capability quick-menu multi-form quick menu (radial / arc / list / grid) over one item model with hotkeys, badges, cooldowns, sections, and nested submenus
+ */
+export function QuickMenu({ items, layout = "list", onSelect, onClose, title, columns = 3, arc = { startAngle: Math.PI / 2, sweep: Math.PI }, radialSize = 300, accent = "var(--jg-accent, #38bdf8)", className, style, }) {
+    const [path, setPath] = useState([]);
+    const current = useMemo(() => {
+        let level = items;
+        for (const id of path) {
+            const next = level.find((item) => item.id === id)?.children;
+            if (next === undefined)
+                return level;
+            level = next;
+        }
+        return level;
+    }, [items, path]);
+    const activate = (item) => {
+        if (item.disabled === true)
+            return;
+        if (item.children !== undefined && item.children.length > 0)
+            setPath((p) => [...p, item.id]);
+        else
+            onSelect(item.id);
+    };
+    const back = () => setPath((p) => p.slice(0, -1));
+    const header = title !== undefined || path.length > 0 ? (_jsxs("div", { "data-quick-header": true, style: { display: "flex", alignItems: "center", gap: 8, marginBottom: 8 }, children: [path.length > 0 ? (_jsx("button", { type: "button", "data-quick-back": true, onClick: back, style: { border: "1px solid rgba(148,163,184,0.4)", borderRadius: 6, background: "transparent", color: "#e2e8f0", fontSize: 11, padding: "2px 8px", cursor: "pointer" }, children: "\u2039 Back" })) : null, title !== undefined ? (_jsx("span", { style: { fontSize: 11, letterSpacing: 1.2, textTransform: "uppercase", color: "rgba(203,213,225,0.75)" }, children: title })) : null] })) : null;
+    if (layout === "radial" || layout === "arc") {
+        const options = current.map((item) => ({ ...item, hasSubmenu: item.children !== undefined && item.children.length > 0 }));
+        return (_jsxs("div", { className: className, "data-quick-menu": true, "data-layout": layout, style: { position: "relative", ...style }, children: [header, _jsx(RadialMenu, { options: options, size: radialSize, accent: accent, ...(layout === "arc" ? { arc } : {}), onSelect: (id) => {
+                        const item = current.find((entry) => entry.id === id);
+                        if (item !== undefined)
+                            activate(item);
+                    }, onClose: onClose })] }));
+    }
+    const groups = groupBySection(current);
+    if (layout === "grid") {
+        return (_jsxs("div", { className: className, "data-quick-menu": true, "data-layout": "grid", style: { ...PANEL, width: columns * 92 + 24, ...style }, children: [header, groups.map((group, gi) => (_jsxs("div", { "data-section": group.section, children: [group.section !== undefined ? (_jsx("div", { style: { fontSize: 10, textTransform: "uppercase", letterSpacing: 1.2, color: "rgba(148,163,184,0.75)", margin: "6px 0 4px" }, children: group.section })) : null, _jsx("div", { style: { display: "grid", gridTemplateColumns: `repeat(${columns}, 1fr)`, gap: 6 }, children: group.items.map((item) => (_jsxs("button", { type: "button", "data-quick-item": item.id, "data-disabled": item.disabled === true, onClick: () => activate(item), disabled: item.disabled === true, style: {
+                                    position: "relative", display: "flex", flexDirection: "column", alignItems: "center", gap: 3, padding: "10px 4px",
+                                    borderRadius: 10, border: "1px solid rgba(148,163,184,0.25)", background: "rgba(17,22,30,0.7)", color: "#e2e8f0",
+                                    cursor: item.disabled === true ? "default" : "pointer", opacity: item.disabled === true ? 0.4 : 1,
+                                }, children: [_jsx("span", { style: { fontSize: 22 }, children: item.icon }), item.label !== undefined ? _jsx("span", { style: { fontSize: 10 }, children: item.label }) : null, item.badge !== undefined ? (_jsx("span", { style: { position: "absolute", top: 3, right: 5, fontSize: 10, fontWeight: 700, color: accent }, children: item.badge })) : null, item.children !== undefined ? _jsx("span", { style: { position: "absolute", bottom: 3, right: 5, fontSize: 10 }, children: "\u25B8" }) : null] }, item.id))) })] }, group.section ?? gi)))] }));
+    }
+    // list
+    return (_jsxs("div", { className: className, "data-quick-menu": true, "data-layout": "list", style: { ...PANEL, width: 240, ...style }, children: [header, groups.map((group, gi) => (_jsxs("div", { "data-section": group.section, children: [group.section !== undefined ? (_jsx("div", { style: { fontSize: 10, textTransform: "uppercase", letterSpacing: 1.2, color: "rgba(148,163,184,0.75)", margin: "6px 0 4px" }, children: group.section })) : null, _jsx("ul", { style: { listStyle: "none", margin: 0, padding: 0, display: "flex", flexDirection: "column", gap: 2 }, children: group.items.map((item) => (_jsx("li", { children: _jsxs("button", { type: "button", "data-quick-item": item.id, "data-disabled": item.disabled === true, onClick: () => activate(item), disabled: item.disabled === true, style: {
+                                    width: "100%", display: "flex", alignItems: "center", gap: 8, padding: "7px 9px", borderRadius: 8,
+                                    border: "1px solid transparent", background: "transparent", color: "#e2e8f0", fontSize: 13, textAlign: "left",
+                                    cursor: item.disabled === true ? "default" : "pointer", opacity: item.disabled === true ? 0.45 : 1,
+                                }, children: [item.icon !== undefined ? _jsx("span", { style: { width: 22, textAlign: "center", fontSize: 17 }, children: item.icon }) : null, _jsx("span", { style: { flex: 1 }, children: item.label ?? item.id }), _jsx(Badges, { item: item, accent: accent })] }) }, item.id))) })] }, group.section ?? gi)))] }));
+}

package/dist/radialMenu.d.ts

@@ -0,0 +1,50 @@
+import { type CSSProperties, type ReactNode } from "react";
+import { type RadialArc } from "@jgengine/core/ui/radialMenu";
+/** One selectable entry on a radial/quick menu (weapon or emote wheel). */
+export interface RadialMenuOption {
+    id: string;
+    label?: string;
+    /** Glyph/icon node the game supplies. */
+    icon?: ReactNode;
+    disabled?: boolean;
+    /** Per-slice accent; falls back to the menu `accent`. */
+    color?: string;
+    /** Keybind hint drawn on the slice (e.g. "1", "Q"). */
+    hotkey?: string;
+    /** Count/quantity badge (ammo, stack size). */
+    badge?: string | number;
+    /** Cooldown remaining as `0..1` — dims the slice and shows the fraction. */
+    cooldown?: number;
+    /** Draw a ► marker to signal the slice opens a submenu. */
+    hasSubmenu?: boolean;
+}
+/** Props for {@link RadialMenu}. */
+export interface RadialMenuProps {
+    options: readonly RadialMenuOption[];
+    /** Render nothing when false. Default true. */
+    open?: boolean;
+    onSelect: (id: string) => void;
+    onClose?: () => void;
+    /** Diameter in px. Default 300. */
+    size?: number;
+    /** Neutral inner-hub radius (dead zone) in px. Default 52. */
+    innerRadius?: number;
+    /** Partial arc instead of a full wheel (e.g. a bottom half or quarter). */
+    arc?: RadialArc;
+    /** Force a highlighted slice (also the initial hover) — for controllers/tests. */
+    highlightIndex?: number | null;
+    accent?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Radial / quick menu (weapon or emote wheel) — a ring or partial `arc` of
+ * selectable wedges the player points at with the mouse (or a stick). Pointer
+ * angle drives the highlight via core `radialIndexFromVector`; click/confirm
+ * fires `onSelect`, the neutral hub closes. Options carry optional hotkeys,
+ * count badges, cooldowns, and submenu markers. The game supplies icons/labels
+ * and skins it.
+ *
+ * @capability radial-menu pointer/stick-driven radial or arc quick menu (weapon/emote wheel) — angular slice selection with hotkeys, badges, cooldowns, and a neutral hub
+ */
+export declare function RadialMenu({ options, open, onSelect, onClose, size, innerRadius, arc, highlightIndex, accent, className, style, }: RadialMenuProps): ReactNode;

package/dist/radialMenu.js

@@ -0,0 +1,69 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo, useState } from "react";
+import { radialIndexFromVector, radialSlicePosition, radialSlices, } from "@jgengine/core/ui/radialMenu";
+const TWO_PI = Math.PI * 2;
+function wedgePath(cx, cy, innerR, outerR, center, half) {
+    const point = (r, a) => [cx + Math.sin(a) * r, cy - Math.cos(a) * r];
+    const start = center - half;
+    const end = center + half;
+    const [x0, y0] = point(outerR, start);
+    const [x1, y1] = point(outerR, end);
+    const [x2, y2] = point(innerR, end);
+    const [x3, y3] = point(innerR, start);
+    const large = half * 2 > Math.PI ? 1 : 0;
+    return `M${x0},${y0} A${outerR},${outerR} 0 ${large} 1 ${x1},${y1} L${x2},${y2} A${innerR},${innerR} 0 ${large} 0 ${x3},${y3} Z`;
+}
+/**
+ * Radial / quick menu (weapon or emote wheel) — a ring or partial `arc` of
+ * selectable wedges the player points at with the mouse (or a stick). Pointer
+ * angle drives the highlight via core `radialIndexFromVector`; click/confirm
+ * fires `onSelect`, the neutral hub closes. Options carry optional hotkeys,
+ * count badges, cooldowns, and submenu markers. The game supplies icons/labels
+ * and skins it.
+ *
+ * @capability radial-menu pointer/stick-driven radial or arc quick menu (weapon/emote wheel) — angular slice selection with hotkeys, badges, cooldowns, and a neutral hub
+ */
+export function RadialMenu({ options, open = true, onSelect, onClose, size = 300, innerRadius = 52, arc, highlightIndex, accent = "var(--jg-accent, #38bdf8)", className, style, }) {
+    const count = options.length;
+    const [hovered, setHovered] = useState(highlightIndex ?? null);
+    const active = highlightIndex !== undefined ? highlightIndex : hovered;
+    const cx = size / 2;
+    const cy = size / 2;
+    const outerR = size / 2 - 3;
+    const labelRadius = (innerRadius + outerR) / 2;
+    const sweep = arc?.sweep ?? TWO_PI;
+    const half = count > 0 ? (sweep >= TWO_PI - 1e-6 ? Math.PI / count : sweep / count / 2) : 0;
+    const centers = useMemo(() => radialSlices(count, arc).map((slice) => slice.centerAngle), [count, arc]);
+    if (!open || count === 0)
+        return null;
+    const commit = () => {
+        if (active === null) {
+            onClose?.();
+            return;
+        }
+        const option = options[active];
+        if (option !== undefined && option.disabled !== true)
+            onSelect(option.id);
+    };
+    return (_jsx("div", { className: className, "data-radial-menu": true, style: { position: "relative", width: size, height: size, userSelect: "none", ...style }, children: _jsxs("svg", { width: size, height: size, viewBox: `0 0 ${size} ${size}`, style: { display: "block", cursor: "pointer" }, onPointerMove: (event) => {
+                if (highlightIndex !== undefined)
+                    return;
+                const rect = event.currentTarget.getBoundingClientRect();
+                const px = ((event.clientX - rect.left) / rect.width) * size;
+                const py = ((event.clientY - rect.top) / rect.height) * size;
+                setHovered(radialIndexFromVector(px - cx, py - cy, count, { deadZone: innerRadius, ...arc }));
+            }, onClick: commit, children: [centers.map((center, index) => {
+                    const option = options[index];
+                    const isActive = index === active;
+                    const color = option.color ?? accent;
+                    const onCooldown = option.cooldown !== undefined && option.cooldown > 0;
+                    return (_jsx("path", { "data-radial-option": option.id, "data-highlighted": isActive, "data-disabled": option.disabled === true, d: wedgePath(cx, cy, innerRadius, outerR, center, half * 0.92), fill: isActive ? color : "rgba(17,22,30,0.82)", fillOpacity: option.disabled === true ? 0.3 : onCooldown ? 0.5 : isActive ? 0.9 : 0.82, stroke: "rgba(148,163,184,0.35)", strokeWidth: 1 }, option.id));
+                }), _jsx("circle", { cx: cx, cy: cy, r: innerRadius - 6, fill: "rgba(8,11,16,0.9)", stroke: "rgba(148,163,184,0.3)" }), centers.map((_, index) => {
+                    const option = options[index];
+                    const at = radialSlicePosition(index, count, labelRadius, arc);
+                    const isActive = index === active;
+                    const x = cx + at.x;
+                    const y = cy + at.y;
+                    return (_jsxs("g", { transform: `translate(${x} ${y})`, style: { pointerEvents: "none" }, children: [option.icon !== undefined ? (_jsx("foreignObject", { x: -18, y: -26, width: 36, height: 30, style: { overflow: "visible" }, children: _jsx("div", { style: { display: "flex", justifyContent: "center", fontSize: 20 }, children: option.icon }) })) : null, option.label !== undefined ? (_jsx("text", { y: option.icon !== undefined ? 14 : 4, textAnchor: "middle", fontSize: 11, fontWeight: 700, fill: isActive ? "#f8fafc" : "rgba(226,232,240,0.8)", fontFamily: "ui-sans-serif, system-ui, sans-serif", children: option.label })) : null, option.hotkey !== undefined ? (_jsxs("text", { y: -20, textAnchor: "middle", fontSize: 9, fontWeight: 700, fill: "rgba(148,163,184,0.9)", children: ["[", option.hotkey, "]"] })) : null, option.badge !== undefined ? (_jsx("text", { x: 16, y: -8, textAnchor: "middle", fontSize: 10, fontWeight: 700, fill: accent, children: option.badge })) : null, option.cooldown !== undefined && option.cooldown > 0 ? (_jsxs("text", { y: 28, textAnchor: "middle", fontSize: 9, fill: "rgba(148,163,184,0.85)", children: [Math.ceil(option.cooldown * 100), "%"] })) : null, option.hasSubmenu === true ? (_jsx("text", { x: 22, y: 4, textAnchor: "middle", fontSize: 11, fill: "rgba(226,232,240,0.75)", children: "\u25B8" })) : null] }, option.id));
+                }), _jsx("text", { x: cx, y: cy + 4, textAnchor: "middle", fontSize: 12, fontWeight: 700, fill: "rgba(226,232,240,0.9)", fontFamily: "ui-sans-serif, system-ui, sans-serif", style: { pointerEvents: "none" }, children: active !== null && options[active] !== undefined ? options[active].label ?? "" : "" })] }) }));
+}

package/dist/saveSlots.d.ts

@@ -0,0 +1,81 @@
+import { type CSSProperties, type ReactNode } from "react";
+import type { SaveSlotMeta, SaveSlots } from "@jgengine/core/game/saveSlots";
+import { type GameIconName } from "./gameIcons.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 declare function useSaveSlots(model: SaveSlots): SaveSlotMeta[];
+/** Reskin tokens for {@link SaveSlotMenu}. All optional — each falls back to a HudTheme var then a neutral default. */
+export interface SaveSlotMenuTheme {
+    /** Accent for the Continue action, savedAt time, and focus glow. Default reads `--jg-accent`. */
+    accent?: string;
+    /** Card background. */
+    cardBg?: string;
+    /** Card border. */
+    cardBorder?: string;
+    /** Primary text color (slot name). */
+    text?: string;
+    /** Muted text color (meta chips, empty label). */
+    muted?: string;
+    /** Meta-chip background. */
+    chipBg?: string;
+    /** Font family. */
+    fontFamily?: string;
+    /** Card corner radius (CSS length). */
+    radius?: string;
+}
+/**
+ * Turn a `savedAt` timestamp into a compact relative label ("just now", "4m ago",
+ * "2d ago"). Presentation-only helper — the model stores raw ms.
+ */
+export declare function relativeSavedAt(savedAt: number, nowMs?: number): string;
+/** Props for {@link SaveSlotMenu}. */
+export interface SaveSlotMenuProps {
+    /** The metadata index to render. */
+    model: SaveSlots;
+    /**
+     * Load an existing save. Given the filled slot the player chose. Wire this to
+     * your `createSaveStore.switchSlot(id)` + scene load.
+     */
+    onLoad?: (slot: SaveSlotMeta) => void;
+    /** Start a new game in an empty slot. Given the empty slot chosen. */
+    onNew?: (slot: SaveSlotMeta) => void;
+    /**
+     * Delete a save. Given the filled slot. A game typically clears both this index
+     * (`model.clear(id)`) and the matching `createSaveStore` slot.
+     */
+    onDelete?: (slot: SaveSlotMeta) => void;
+    /**
+     * Continue the most recent save (the Continue button targets `model.mostRecent()`).
+     * Omit to hide the Continue button.
+     */
+    onContinue?: (slot: SaveSlotMeta) => void;
+    /** Menu heading. Default `"Select Save"`. */
+    title?: ReactNode;
+    /** Reskin tokens. */
+    theme?: SaveSlotMenuTheme;
+    /** Wall clock (ms) for relative times — inject in tests/screenshots. Default `Date.now`. */
+    now?: () => number;
+    /** Optional per-`meta`-key icon, so a game can prefix chips (e.g. `{ level: "star", playtime: "hourglass" }`). */
+    metaIcons?: Record<string, GameIconName>;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * 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 declare function SaveSlotMenu({ model, onLoad, onNew, onDelete, onContinue, title, theme, now, metaIcons, className, style, }: SaveSlotMenuProps): ReactNode;