@jgengine/react 0.27.0 → 0.28.0

package/dist/settingsBlocks.js

@@ -0,0 +1,204 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { hudSpace, hudType, hudTransition } from "./hudTokens.js";
+import { ScrollRail } from "./scrollRail.js";
+import { useDebouncedCommit } from "./useDebouncedCommit.js";
+const rowStyle = {
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "space-between",
+    gap: hudSpace("md"),
+    padding: `${hudSpace("sm")} ${hudSpace("md")}`,
+    borderRadius: 10,
+    background: "var(--jg-surface-deep, rgba(255,255,255,0.04))",
+    border: "1px solid var(--jg-edge, rgba(255,255,255,0.08))",
+};
+const labelStyle = {
+    fontSize: hudType("sm"),
+    color: "var(--jg-text, #ececef)",
+};
+const valueStyle = {
+    fontSize: hudType("sm"),
+    color: "var(--jg-text, #ececef)",
+    fontVariantNumeric: "tabular-nums",
+    minWidth: 48,
+    textAlign: "right",
+};
+function RowShell({ label, children }) {
+    return (_jsxs("div", { "data-settings-row": "", style: rowStyle, children: [_jsx("span", { style: labelStyle, children: label }), _jsx("div", { style: { display: "flex", alignItems: "center", gap: hudSpace("sm"), minWidth: 0 }, children: children })] }));
+}
+/**
+ * One slider row from a {@link SettingsRow}: mirrors the thumb locally and commits on release, so a
+ * drag never storms the settings store or the graphics rebuild it drives.
+ *
+ * @capability settings-slider a settings slider row that mirrors locally and persists on release
+ */
+export function SettingsSlider({ row }) {
+    const { value, onInput, flush } = useDebouncedCommit(Number(row.value), (next) => row.set(next));
+    return (_jsxs(RowShell, { label: row.label, children: [_jsx("input", { type: "range", min: row.min, max: row.max, step: row.step, value: value, "aria-label": row.label, onChange: (event) => onInput(Number(event.target.value)), onPointerUp: flush, onKeyUp: flush, onBlur: flush, style: { flex: 1, minWidth: 120, accentColor: "var(--jg-accent, #6ee7a8)" } }), _jsx("span", { style: valueStyle, children: row.format?.(value) ?? String(value) })] }));
+}
+/** One on/off row from a {@link SettingsRow}. */
+export function SettingsToggle({ row }) {
+    const on = Boolean(row.value);
+    return (_jsx(RowShell, { label: row.label, children: _jsx("button", { type: "button", role: "switch", "aria-checked": on, "aria-label": row.label, onClick: () => row.set(!on), style: {
+                position: "relative",
+                width: 48,
+                height: 26,
+                borderRadius: 999,
+                border: "1px solid var(--jg-edge-bright, rgba(255,255,255,0.16))",
+                background: on ? "var(--jg-accent, #6ee7a8)" : "var(--jg-surface-deep, rgba(15,18,24,0.9))",
+                boxShadow: on ? "0 0 12px var(--jg-accent-glow, rgba(110,231,168,0.35))" : "none",
+                cursor: "pointer",
+                transition: hudTransition(["background", "box-shadow"]),
+            }, children: _jsx("span", { style: {
+                    position: "absolute",
+                    top: 3,
+                    left: on ? 25 : 3,
+                    width: 18,
+                    height: 18,
+                    borderRadius: 999,
+                    background: "var(--jg-text, #fff)",
+                    transition: hudTransition("left"),
+                } }) }) }));
+}
+/** One choice row from a {@link SettingsRow}, rendered as a pressed-state option group. */
+export function SettingsSelect({ row }) {
+    const current = String(row.value);
+    return (_jsx(RowShell, { label: row.label, children: _jsx("div", { role: "group", "aria-label": row.label, style: { display: "flex", flexWrap: "wrap", justifyContent: "flex-end", gap: 4 }, children: (row.options ?? []).map((option) => {
+                const selected = option.value === current;
+                return (_jsx("button", { type: "button", "aria-pressed": selected, onClick: () => row.set(option.value), style: {
+                        minHeight: 30,
+                        padding: `0 ${hudSpace("sm")}`,
+                        borderRadius: 7,
+                        border: "1px solid transparent",
+                        background: selected ? "var(--jg-accent, #6ee7a8)" : "transparent",
+                        color: selected ? "var(--jg-surface-deep, #0b0b0f)" : "var(--jg-text-dim, #94a3a0)",
+                        fontSize: hudType("sm"),
+                        fontWeight: 600,
+                        cursor: "pointer",
+                        transition: hudTransition(["background", "color"]),
+                    }, children: option.label }, option.value));
+            }) }) }));
+}
+/** Render the control a {@link SettingsRow} kind asks for. */
+export function SettingsRowControl({ row }) {
+    if (row.kind === "slider")
+        return _jsx(SettingsSlider, { row: row });
+    if (row.kind === "toggle")
+        return _jsx(SettingsToggle, { row: row });
+    return _jsx(SettingsSelect, { row: row });
+}
+/**
+ * A controls row for one action: its label, the bound key (click to rebind), a conflict/armed state
+ * and reset. The caller owns capture; this is the row's presentation.
+ *
+ * @capability settings-keybind-row one rebindable controls row — key glyph, armed state and reset
+ */
+export function SettingsKeybindControl({ row, armed = false, onArm, buttonProps }) {
+    return (_jsxs("div", { "data-settings-keybind": row.action, "data-armed": armed ? "" : undefined, style: rowStyle, children: [_jsx("span", { style: labelStyle, children: row.label }), _jsxs("div", { style: { display: "flex", alignItems: "center", gap: hudSpace("xs") }, children: [_jsx("button", { type: "button", "data-settings-capture": "", ...buttonProps, onClick: onArm, disabled: armed, title: "Click, then press a key \u2014 Escape cancels", style: {
+                            minWidth: 84,
+                            minHeight: 30,
+                            padding: `0 ${hudSpace("sm")}`,
+                            borderRadius: 7,
+                            border: `1px solid ${armed ? "var(--jg-accent, #6ee7a8)" : "var(--jg-edge-bright, rgba(255,255,255,0.14))"}`,
+                            background: armed ? "var(--jg-accent-glow, rgba(110,231,168,0.25))" : "var(--jg-surface-deep, rgba(15,18,24,0.9))",
+                            color: armed ? "var(--jg-accent, #6ee7a8)" : "var(--jg-text, #ececef)",
+                            fontFamily: "var(--jg-font-numeric, monospace)",
+                            fontSize: hudType("sm"),
+                            cursor: "pointer",
+                        }, children: armed ? "Press…" : row.bindingLabel }), _jsx("button", { type: "button", "data-settings-reset": "", onClick: () => row.reset(), "aria-label": `Reset ${row.label}`, tabIndex: row.isDefault ? -1 : 0, style: {
+                            width: 30,
+                            height: 30,
+                            borderRadius: 7,
+                            border: "none",
+                            background: "transparent",
+                            color: "var(--jg-text-dim, #94a3a0)",
+                            visibility: row.isDefault ? "hidden" : "visible",
+                            cursor: "pointer",
+                        }, children: "\u21BA" })] })] }));
+}
+/**
+ * One settings category as a block: its rows, then its rebindable actions with click-to-capture. The
+ * game picks where it sits and how wide it is; the block reads HudTheme tokens and the live rows the
+ * settings controller hands it, and writes every change straight back to that controller's store.
+ *
+ * @capability settings-section settings category block — rows plus click-to-capture keybind rows, HudTheme-styled, store-backed
+ */
+export function SettingsSection({ category, heading = true, capture = true, className, style, onCaptureChange, }) {
+    const [armed, setArmed] = useState(null);
+    const callbacks = useRef({ onCaptureChange });
+    callbacks.current = { onCaptureChange };
+    useEffect(() => {
+        callbacks.current.onCaptureChange?.(armed);
+    }, [armed]);
+    useEffect(() => {
+        if (armed === null)
+            return;
+        const row = category.keybinds.find((candidate) => candidate.action === armed);
+        if (row === undefined) {
+            setArmed(null);
+            return;
+        }
+        const onKey = (event) => {
+            event.preventDefault();
+            event.stopPropagation();
+            if (event.code === "Escape") {
+                setArmed(null);
+                return;
+            }
+            row.rebind(event.code);
+            setArmed(null);
+        };
+        const onPointer = (event) => {
+            event.preventDefault();
+            event.stopPropagation();
+            row.rebind(`mouse${event.button}`);
+            setArmed(null);
+        };
+        const onContext = (event) => event.preventDefault();
+        window.addEventListener("keydown", onKey, true);
+        window.addEventListener("pointerdown", onPointer, true);
+        window.addEventListener("contextmenu", onContext, true);
+        return () => {
+            window.removeEventListener("keydown", onKey, true);
+            window.removeEventListener("pointerdown", onPointer, true);
+            window.removeEventListener("contextmenu", onContext, true);
+        };
+    }, [armed, category.keybinds]);
+    return (_jsxs("section", { "data-settings-section": category.id, className: className, style: { display: "flex", flexDirection: "column", gap: hudSpace("xs"), ...style }, children: [heading ? (_jsx("h3", { style: {
+                    margin: 0,
+                    marginBottom: hudSpace("xs"),
+                    fontFamily: "var(--jg-font-display, inherit)",
+                    fontSize: hudType("xs"),
+                    fontWeight: 700,
+                    letterSpacing: "0.18em",
+                    textTransform: "uppercase",
+                    color: "var(--jg-accent, #6ee7a8)",
+                }, children: category.label })) : null, category.rows.map((row) => (_jsx(SettingsRowControl, { row: row }, row.id))), category.keybinds.map((row) => (_jsx(SettingsKeybindControl, { row: row, armed: armed === row.action, onArm: capture ? () => setArmed(row.action) : undefined }, row.action)))] }));
+}
+/**
+ * The category tab rail for a settings screen: a scrollable row of buttons with pressed state. The
+ * game owns the surrounding layout; this block keeps every category reachable on narrow screens.
+ *
+ * @capability settings-tabs scrollable settings category tabs with pressed state
+ */
+export function SettingsTabs({ categories, activeId, onSelect, leading, tabProps, className, style }) {
+    const tabs = leading === undefined ? categories : [{ id: leading.id, label: leading.label }, ...categories];
+    return (_jsx("div", { className: className, style: style, children: _jsx(ScrollRail, { label: "settings categories", children: tabs.map((tab) => {
+                const selected = tab.id === activeId;
+                return (_jsx("button", { type: "button", "data-settings-tab": tab.id, ...(tabProps === undefined ? {} : tabProps(tab.id)), "aria-pressed": selected, onClick: () => onSelect(tab.id), style: {
+                        flexShrink: 0,
+                        minHeight: 34,
+                        padding: `0 ${hudSpace("md")}`,
+                        marginRight: hudSpace("xs"),
+                        borderRadius: 8,
+                        border: "1px solid transparent",
+                        background: selected ? "var(--jg-accent, #6ee7a8)" : "transparent",
+                        color: selected ? "var(--jg-surface-deep, #0b0b0f)" : "var(--jg-text-dim, #94a3a0)",
+                        fontSize: hudType("sm"),
+                        fontWeight: 600,
+                        whiteSpace: "nowrap",
+                        cursor: "pointer",
+                    }, children: tab.label }, tab.id));
+            }) }) }));
+}

package/dist/titleMenu.d.ts

@@ -0,0 +1,60 @@
+import type { CSSProperties, ReactNode } from "react";
+import { type MenuScreenScrim, type MenuScreenTransition } from "./menuScreen.js";
+/** One verb on a {@link TitleMenu}: New Game, Continue, Settings, Credits, Quit. */
+export interface TitleMenuItem {
+    /** Stable id the game routes on. */
+    id: string;
+    /** Player-facing label. */
+    label: string;
+    /** One line under the label (save summary, a "no save yet" note). */
+    hint?: string;
+    /** Render as the screen's primary action. */
+    primary?: boolean;
+    /** Show but skip it in navigation and clicks. */
+    disabled?: boolean;
+}
+/** Props for {@link TitleMenu}. */
+export interface TitleMenuProps {
+    /** The game's wordmark or title. Free markup, so a game can art-direct it. */
+    title: ReactNode;
+    /** Small line above the title (studio, genre, chapter). */
+    eyebrow?: ReactNode;
+    /** One line under the title. */
+    tagline?: ReactNode;
+    /** The front-end verbs, in focus order. */
+    items: readonly TitleMenuItem[];
+    /** A verb was chosen. */
+    onSelect: (id: string) => void;
+    /** Back/Escape. Omit at the root screen, where there is nowhere to go. */
+    onBack?: () => void;
+    /** Footer left slot — build version, copyright. */
+    footer?: ReactNode;
+    /** Footer right slot — replaces the default control hint. */
+    controlHint?: ReactNode;
+    /** Artwork, a poster, or a live 3D scene painted behind the menu. */
+    backdrop?: ReactNode;
+    /** Extra content under the verbs (a save summary, a control legend). */
+    children?: ReactNode;
+    open?: boolean;
+    transition?: MenuScreenTransition;
+    /** Dim/blur treatment over the scene behind. Default `"dim"`. */
+    scrim?: MenuScreenScrim;
+    enterMs?: number;
+    exitMs?: number;
+    reducedMotion?: boolean;
+    onClosed?: () => void;
+    className?: string;
+    style?: CSSProperties;
+    contentClassName?: string;
+    contentStyle?: CSSProperties;
+}
+/**
+ * A game front-end title screen: wordmark, tagline, the game's verbs in a keyboard/gamepad-navigable
+ * list, a footer and an optional backdrop. The engine owns navigation, focus and the enter/exit
+ * animation; the game owns the title markup, wording, verbs, art and every colour through HudTheme
+ * tokens. Pass the live scene (or artwork) as `backdrop` so the title renders over 3D instead of a
+ * blank page.
+ *
+ * @capability title-menu title-screen block — wordmark, tagline, navigable verb list, footer, backdrop slot, animated over a live scene
+ */
+export declare function TitleMenu({ title, eyebrow, tagline, items, onSelect, onBack, footer, controlHint, backdrop, children, open, transition, scrim, enterMs, exitMs, reducedMotion, onClosed, className, style, contentClassName, contentStyle, }: TitleMenuProps): ReactNode;

package/dist/titleMenu.js

@@ -0,0 +1,66 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { hudSpace, hudType } from "./hudTokens.js";
+import { HudButton } from "./hudButton.js";
+import { useMenuNav } from "./menuNav.js";
+import { MenuScreen } from "./menuScreen.js";
+const column = {
+    display: "flex",
+    flexDirection: "column",
+    gap: hudSpace("md"),
+    width: "min(92vw, 460px)",
+};
+const itemButton = {
+    display: "flex",
+    flexDirection: "column",
+    alignItems: "flex-start",
+    gap: 2,
+    textAlign: "left",
+};
+/**
+ * A game front-end title screen: wordmark, tagline, the game's verbs in a keyboard/gamepad-navigable
+ * list, a footer and an optional backdrop. The engine owns navigation, focus and the enter/exit
+ * animation; the game owns the title markup, wording, verbs, art and every colour through HudTheme
+ * tokens. Pass the live scene (or artwork) as `backdrop` so the title renders over 3D instead of a
+ * blank page.
+ *
+ * @capability title-menu title-screen block — wordmark, tagline, navigable verb list, footer, backdrop slot, animated over a live scene
+ */
+export function TitleMenu({ title, eyebrow, tagline, items, onSelect, onBack, footer, controlHint, backdrop, children, open = true, transition = "slide", scrim = "dim", enterMs, exitMs, reducedMotion, onClosed, className, style, contentClassName, contentStyle, }) {
+    const disabled = items.filter((item) => item.disabled === true).map((item) => item.id);
+    const nav = useMenuNav({
+        ids: items.map((item) => item.id),
+        disabled,
+        enabled: open,
+        onConfirm: onSelect,
+        ...(onBack === undefined ? {} : { onBack }),
+    });
+    return (_jsx(MenuScreen, { open: open, transition: transition, scrim: scrim, ...(enterMs === undefined ? {} : { enterMs }), ...(exitMs === undefined ? {} : { exitMs }), ...(reducedMotion === undefined ? {} : { reducedMotion }), ...(onClosed === undefined ? {} : { onClosed }), label: "Title menu", ...(backdrop === undefined ? {} : { backdrop }), className: className, style: style, contentClassName: contentClassName, contentStyle: contentStyle, children: _jsxs("div", { "data-title-menu": "", style: column, ...nav.containerProps, children: [eyebrow === undefined ? null : (_jsx("p", { "data-title-eyebrow": "", style: {
+                        margin: 0,
+                        fontSize: hudType("xs"),
+                        letterSpacing: "0.24em",
+                        textTransform: "uppercase",
+                        color: "var(--jg-accent, #6ee7a8)",
+                    }, children: eyebrow })), _jsx("div", { "data-title-wordmark": "", style: {
+                        fontFamily: "var(--jg-font-display, inherit)",
+                        fontSize: hudType("display"),
+                        fontWeight: 800,
+                        lineHeight: 1.02,
+                        letterSpacing: "-0.01em",
+                        color: "var(--jg-text, #f5f7fa)",
+                        textShadow: "0 2px 18px rgba(0,0,0,0.55)",
+                    }, children: title }), tagline === undefined ? null : (_jsx("p", { style: { margin: 0, fontSize: hudType("sm"), color: "var(--jg-text-dim, #94a3a0)", maxWidth: "34ch" }, children: tagline })), _jsx("nav", { "data-title-items": "", style: { display: "flex", flexDirection: "column", gap: hudSpace("xs"), marginTop: hudSpace("sm") }, children: items.map((item) => {
+                        const props = nav.itemProps(item.id);
+                        return (_jsxs(HudButton, { ...props, variant: item.primary === true ? "primary" : "secondary", size: "lg", block: true, disabled: item.disabled === true, "data-title-item": item.id, onClick: () => {
+                                if (item.disabled !== true)
+                                    onSelect(item.id);
+                            }, style: itemButton, children: [_jsx("span", { style: { fontSize: hudType("md"), fontWeight: 700 }, children: item.label }), item.hint === undefined ? null : (_jsx("span", { style: { fontSize: hudType("xs"), fontWeight: 500, opacity: 0.78 }, children: item.hint }))] }, item.id));
+                    }) }), children, _jsxs("footer", { "data-title-footer": "", style: {
+                        display: "flex",
+                        alignItems: "center",
+                        justifyContent: "space-between",
+                        gap: hudSpace("md"),
+                        marginTop: hudSpace("md"),
+                        fontSize: hudType("xs"),
+                        color: "var(--jg-text-dim, #94a3a0)",
+                    }, children: [_jsx("span", { children: footer }), _jsx("span", { "data-jg-kbd-hint": controlHint === undefined ? "" : undefined, children: controlHint ?? "↑↓ move · Enter select · Esc back" })] })] }) }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/react",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "React UI layer for JGengine: GameProvider, hooks, and headless primitives over @jgengine/core.",
   "license": "Apache-2.0",
   "type": "module",
@@ -35,7 +35,7 @@
     "styles": "bun scripts/styles.ts"
   },
   "dependencies": {
-    "@jgengine/core": "^0.27.0"
+    "@jgengine/core": "^0.28.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/skills/jgengine/api.md

@@ -6,7 +6,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.27.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.28.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -285,7 +285,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.27.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.28.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 

package/skills/jgengine-ui/SKILL.md

@@ -29,6 +29,7 @@ Existing React games keep their entity store and use the focused
 
 - **Every game owns its UI end-to-end.** Custom composition, skin, placement, terminology, motion, and one main menu. The website/runner is a bare loader. Composing and reskinning the shipped blocks is correct use; a genre HUD kit, theme preset, or unarranged default stack dropped in as the game's identity is not.
 - **The main menu is a game front-end, not marketing.** The runner loads straight into the game's own menu; it offers the real front-end verbs the game supports — New Game, Continue/Load (save slots), Create/Choose character or class, Settings, Credits — each an authored screen in the game's art direction, not a landing page or raw scaffold. See [reference.md](reference.md#main-menu).
+- **Menus come from the shipped blocks, navigated by `useMenuNav`.** `TitleMenu`/`MenuScreen` (`@jgengine/react`) give the animated screen over the live scene (transform/opacity only, reduced-motion aware, unmounted after exit), `PauseMenu` the pause shape, `SettingsSection`/`SettingsTabs` the settings surface, `SaveSlotMenu` the slot list, `CreditsPanel` the credits screen, `LoadingScreen` the boot screen with rotating tips. `useMenuNav` (`@jgengine/react/menuNav`) is the one keyboard + gamepad focus model for any menu: roving focus, confirm/back, disabled rows skipped, no focus trap. Games keep wording, layout, art and terminology.
 - **Settings is game-owned and reachable from a sensible place.** Every game ships settings as *its* settings — skinned and placed inline with its UI (main menu and pause), never the engine's stock face floated into a corner. Credits are a reachable in-game screen, not attribution buried in a build artifact.
 - **Route the front-end with `useMenuRouter`, and generate the credits.** `useMenuRouter(root)` is the screen stack behind title → save select → settings → credits: `open`/`back`/`replace`/`reset`, `path` for depth, and Escape-to-back bound by default (`escapeToBack: false` when the game owns Escape). `menuStackReducer` is the same transition as a pure function. For credits, `creditsForSourceIds(ids)` (`@jgengine/assets/credits`) turns the pack ids a game declares to `buildCatalog` into licensed, attributed sections, `mergeCredits` folds them into hand-authored lines, and `CreditsScreen` renders the result HudTheme-skinned.
 - **Skin the shared chrome with one `HudTheme` token object.** `hudThemeVars(theme)` emits the whole `--jg-*` vocabulary — bar fills and troughs, `HudFrame variation="themed"`, painted slots, the minimap ring, plus surfaces, edges, text, status colors, fonts, and rarity — so one theme spread on any HUD ancestor reskins the `@jgengine/react` primitives and the `registry/jgengine` blocks together. Author your own with `deriveHudTheme({ accent, surface })` or `hudTheme({ ... })`; `HUD_THEME_PRESETS` / `resolveHudTheme("<preset>")` are demo/scaffold starting points, never a game's identity. A component that needs a token no theme emits fails `check-hud-tokens` — add it to `HudTheme` rather than inventing a second vocabulary. Caller `style`/`renderItem` overrides still win.