@jgengine/react 0.28.0 → 0.30.0

package/CHANGELOG.md

@@ -26,6 +26,37 @@ At publish, rename this heading to the new version and mirror the entries into
 `packages/core/src/meta/changelog.ts` (the typed `CHANGELOG` export).
 -->
 
+## 0.30.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.30.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.27.0`; `@jgengine/github` is `0.17.0`.
+
+### Added
+
+- `ColorblindFrame` (`@jgengine/react/accessibility`) wraps the 3D canvas and applies the player's colour-vision mode to that box alone, so HUD, menu and caption text keep their own contrast. `colorblindFrameFilter` (`@jgengine/core/ui/accessibility`) resolves a mode to the CSS filter, and `useColorblindMode` reads the mode from the settings store the settings rows write; the 3D shell does both for the mounted game.
+- `SettingsSection` (`@jgengine/react/settingsBlocks`) is one `useMenuNav` menu: a d-pad or left stick moves between rows and left/right steps the focused value — slider by its step, toggle flipped, select to the next option, confirm arms a keybind — through the same `onAdjust` path the arrow keys use. `onAdjust` (`@jgengine/react/menuNav`) is the option that makes left/right adjust instead of move.
+- `createStanding` (`@jgengine/core/progression/standing`) holds per-faction or per-district standing over authored tracks and moves it from named outcomes, so an outcome that resolves to nothing throws at the call instead of silently moving nothing.
+- `createGateSet` (`@jgengine/core/progression/gates`) evaluates authored milestones against standing and money, and refuses to load when a gate's unlock id resolves to nothing.
+- `createCareerBank` (`@jgengine/core/progression/careerBank`) keeps persistent career money apart from a run's haul, so a failed run loses the haul and keeps the bank.
+- `createUpgradeTree` (`@jgengine/core/progression/upgrades`) prices each rank from the shared curve primitive and gates purchases on prerequisites and standing.
+
+### Changed
+
+- `AccessibilityProvider` (`@jgengine/react/accessibility`) sets its data attributes and text-scale var without filtering its own subtree. A colour matrix over the HUD and menu root recoloured the text the rest of the UI assumes, so wrap the game canvas in `ColorblindFrame` instead; a custom root can still offset it with its own `ColorblindFilters` and `filter: url(#jg-cb-<mode>)`.
+- World health bars and nameplates derive their range from the render camera and the target height when a game sets no `maxDistance`: an overhead camera reaches the units it looks down at, and a bar is kept while the target it annotates still covers 18 px, instead of hiding every target past a fixed 60 units.
+- A configured `worldHealthBars.maxDistance` or `nameplates.maxDistance` that hides every target in view now warns once with the nearest measured distance and the prop to raise, instead of rendering nothing.
+
+## 0.29.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.29.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.26.0`; `@jgengine/github` is `0.16.0`.
+
+### Fixed
+
+- `MissionView.remaining` (`@jgengine/core/gameplay`) now counts down from a `survive` objective's own `duration`, not only from a `timeout`. A defend or hold objective reports the seconds it still has to run, which is the one number its HUD needs; a completed run still reports null.
+
 ## 0.28.0
 
 ### Migrate

package/dist/accessibility.d.ts

@@ -1,5 +1,6 @@
 import { type CSSProperties, type ReactNode } from "react";
-import { type AccessibilityState, type AccessibilityStore } from "@jgengine/core/ui/accessibility";
+import { type AccessibilityState, type AccessibilityStore, type ColorblindMode } from "@jgengine/core/ui/accessibility";
+import type { SettingsStore } from "@jgengine/core/settings/settingsModel";
 interface AccessibilityContextValue {
     state: AccessibilityState;
     store: AccessibilityStore;
@@ -8,21 +9,53 @@ interface AccessibilityContextValue {
 export declare function useAccessibility(): AccessibilityContextValue;
 /**
  * Hidden SVG `<defs>` holding the `feColorMatrix` colorblind filters that
- * `AccessibilityProvider` references by `filter: url(#jg-cb-<mode>)`. Rendered
- * automatically inside the provider; export standalone for custom roots.
+ * `filter: url(#jg-cb-<mode>)` references. Mounted by {@link ColorblindFrame};
+ * export it standalone for a root that applies the filter itself.
  *
  * @capability colorblind-filters SVG feColorMatrix defs (protanopia/deuteranopia/tritanopia/grayscale) referenced by the accessibility colorblind filter
  */
 export declare function ColorblindFilters(): ReactNode;
+/** Props for {@link ColorblindFrame}. */
+export interface ColorblindFrameProps {
+    /** The player's colour-vision mode. `none` (default) renders the frame untouched. */
+    mode?: ColorblindMode;
+    children?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Apply the player's colour-vision mode to one rendered frame: a box carrying
+ * `filter: url(#jg-cb-<mode>)` plus the filter defs it references. Put it around the canvas of a 3D
+ * game and nothing else — the filter is one compositor pass over that box's pixels, so HUD, menu and
+ * caption text outside it keep the contrast and hues the rest of the UI assumes.
+ *
+ * The filter needs no framebuffer copy and no extra WebGL draw: the browser filters the canvas layer
+ * as it composites, so switching modes costs nothing per frame beyond that pass. Gameplay stays
+ * unaffected; the cost is one full-screen colour-matrix pass while a mode other than `none` is set.
+ *
+ * @capability colorblind-frame apply the player's colour-vision mode to the 3D frame alone, leaving HUD and menu text unfiltered
+ */
+export declare function ColorblindFrame({ mode, children, className, style }: ColorblindFrameProps): ReactNode;
+/**
+ * The live colour-vision mode from a settings store — the same store the settings rows write, so the
+ * frame follows the player's choice the moment they pick it. Pass the store the shell owns; read
+ * `useAccessibilitySettings().colorblind` instead when a `SettingsProvider` is above the caller.
+ *
+ * @capability colorblind-frame-mode read the live colour-vision mode from the settings store that the settings rows write
+ */
+export declare function useColorblindMode(store: SettingsStore): ColorblindMode;
 /**
  * Apply accessibility preferences to a subtree: exposes `--jg-text-scale` for
- * text to scale off, sets `data-reduced-motion` / `data-high-contrast` /
- * `data-colorblind` / `data-captions` for CSS to respond to, and wraps the tree
- * in the selected colorblind `feColorMatrix` filter. Reads a
+ * text to scale off, and sets `data-reduced-motion` / `data-high-contrast` /
+ * `data-colorblind` / `data-captions` for CSS to respond to. Reads a
  * `createAccessibilityStore` and re-renders on change; provides the state to
  * `useAccessibility`.
  *
- * @capability accessibility-provider apply accessibility preferences to a subtree — text-scale CSS var, reduced-motion/high-contrast/colorblind/captions data attrs, and the colorblind color-matrix filter
+ * It deliberately does not filter its own subtree: this is the HUD and menu root, and a colour matrix
+ * over text costs the contrast the rest of the UI was designed around. Wrap the 3D canvas in
+ * {@link ColorblindFrame} instead.
+ *
+ * @capability accessibility-provider apply accessibility preferences to a subtree — text-scale CSS var and reduced-motion/high-contrast/colorblind/captions data attrs
  */
 export declare function AccessibilityProvider({ store, children, className, style, }: {
     store: AccessibilityStore;

package/dist/accessibility.js

@@ -1,6 +1,7 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { createContext, useContext, useSyncExternalStore } from "react";
-import { COLORBLIND_MATRICES, } from "@jgengine/core/ui/accessibility";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useContext, useSyncExternalStore, } from "react";
+import { COLORBLIND_MATRICES, colorblindFrameFilter, } from "@jgengine/core/ui/accessibility";
+import { readColorblind } from "@jgengine/core/settings/accessibilitySettings";
 const AccessibilityContext = createContext(null);
 const FILTER_MODES = [
     "protanopia",
@@ -17,31 +18,58 @@ export function useAccessibility() {
 }
 /**
  * Hidden SVG `<defs>` holding the `feColorMatrix` colorblind filters that
- * `AccessibilityProvider` references by `filter: url(#jg-cb-<mode>)`. Rendered
- * automatically inside the provider; export standalone for custom roots.
+ * `filter: url(#jg-cb-<mode>)` references. Mounted by {@link ColorblindFrame};
+ * export it standalone for a root that applies the filter itself.
  *
  * @capability colorblind-filters SVG feColorMatrix defs (protanopia/deuteranopia/tritanopia/grayscale) referenced by the accessibility colorblind filter
  */
 export function ColorblindFilters() {
     return (_jsx("svg", { "aria-hidden": true, width: 0, height: 0, style: { position: "absolute" }, "data-colorblind-filters": true, children: _jsx("defs", { children: FILTER_MODES.map((mode) => (_jsx("filter", { id: `jg-cb-${mode}`, colorInterpolationFilters: "sRGB", children: _jsx("feColorMatrix", { type: "matrix", values: COLORBLIND_MATRICES[mode] ?? "" }) }, mode))) }) }));
 }
+/**
+ * Apply the player's colour-vision mode to one rendered frame: a box carrying
+ * `filter: url(#jg-cb-<mode>)` plus the filter defs it references. Put it around the canvas of a 3D
+ * game and nothing else — the filter is one compositor pass over that box's pixels, so HUD, menu and
+ * caption text outside it keep the contrast and hues the rest of the UI assumes.
+ *
+ * The filter needs no framebuffer copy and no extra WebGL draw: the browser filters the canvas layer
+ * as it composites, so switching modes costs nothing per frame beyond that pass. Gameplay stays
+ * unaffected; the cost is one full-screen colour-matrix pass while a mode other than `none` is set.
+ *
+ * @capability colorblind-frame apply the player's colour-vision mode to the 3D frame alone, leaving HUD and menu text unfiltered
+ */
+export function ColorblindFrame({ mode = "none", children, className, style }) {
+    const filter = colorblindFrameFilter(mode);
+    return (_jsxs(_Fragment, { children: [_jsx(ColorblindFilters, {}), _jsx("div", { className: className, "data-colorblind-frame": mode, style: filter === null ? style : { ...style, filter }, children: children })] }));
+}
+/**
+ * The live colour-vision mode from a settings store — the same store the settings rows write, so the
+ * frame follows the player's choice the moment they pick it. Pass the store the shell owns; read
+ * `useAccessibilitySettings().colorblind` instead when a `SettingsProvider` is above the caller.
+ *
+ * @capability colorblind-frame-mode read the live colour-vision mode from the settings store that the settings rows write
+ */
+export function useColorblindMode(store) {
+    return useSyncExternalStore(store.subscribe, () => readColorblind(store), () => readColorblind(store));
+}
 /**
  * Apply accessibility preferences to a subtree: exposes `--jg-text-scale` for
- * text to scale off, sets `data-reduced-motion` / `data-high-contrast` /
- * `data-colorblind` / `data-captions` for CSS to respond to, and wraps the tree
- * in the selected colorblind `feColorMatrix` filter. Reads a
+ * text to scale off, and sets `data-reduced-motion` / `data-high-contrast` /
+ * `data-colorblind` / `data-captions` for CSS to respond to. Reads a
  * `createAccessibilityStore` and re-renders on change; provides the state to
  * `useAccessibility`.
  *
- * @capability accessibility-provider apply accessibility preferences to a subtree — text-scale CSS var, reduced-motion/high-contrast/colorblind/captions data attrs, and the colorblind color-matrix filter
+ * It deliberately does not filter its own subtree: this is the HUD and menu root, and a colour matrix
+ * over text costs the contrast the rest of the UI was designed around. Wrap the 3D canvas in
+ * {@link ColorblindFrame} instead.
+ *
+ * @capability accessibility-provider apply accessibility preferences to a subtree — text-scale CSS var and reduced-motion/high-contrast/colorblind/captions data attrs
  */
 export function AccessibilityProvider({ store, children, className, style, }) {
     const state = useSyncExternalStore(store.subscribe, store.get, store.get);
     const rootStyle = { ...style };
     rootStyle["--jg-text-scale"] = String(state.textScale);
-    if (state.colorblind !== "none")
-        rootStyle.filter = `url(#jg-cb-${state.colorblind})`;
-    return (_jsx(AccessibilityContext.Provider, { value: { state, store }, children: _jsxs("div", { className: className, "data-accessibility": true, "data-reduced-motion": state.reducedMotion, "data-high-contrast": state.highContrast, "data-colorblind": state.colorblind, "data-captions": state.captions, style: rootStyle, children: [_jsx(ColorblindFilters, {}), children] }) }));
+    return (_jsx(AccessibilityContext.Provider, { value: { state, store }, children: _jsx("div", { className: className, "data-accessibility": true, "data-reduced-motion": state.reducedMotion, "data-high-contrast": state.highContrast, "data-colorblind": state.colorblind, "data-captions": state.captions, style: rootStyle, children: children }) }));
 }
 /**
  * OS "reduce motion" preference (`prefers-reduced-motion: reduce`) as a live

package/dist/menuNav.d.ts

@@ -43,6 +43,12 @@ export interface UseMenuNavOptions {
     enabled?: boolean;
     /** Confirm (Enter/Space/A). Called with the focused id. */
     onConfirm?: (id: string) => void;
+    /**
+     * Left/right (arrow keys, d-pad, left stick) change the focused item's value by one step instead of
+     * moving focus. Give it to a menu whose items are settings rows; hold-to-repeat applies, so a held
+     * direction steps repeatedly. Up/down and confirm/back are unchanged.
+     */
+    onAdjust?: (id: string, delta: -1 | 1) => void;
     /** Back (Escape/Backspace/B/Start). */
     onBack?: () => void;
     /** Poll a connected gamepad for menu intents. Default true. */
@@ -58,6 +64,6 @@ export interface UseMenuNavOptions {
  *
  * @capability use-menu-nav keyboard and gamepad focus navigation for a menu — roving focus order, confirm/back, disabled-item skipping, no focus trap
  */
-export declare function useMenuNav({ ids, columns, wrap, disabled, initialId, enabled, onConfirm, onBack, gamepad, repeat, }: UseMenuNavOptions): MenuNavController;
+export declare function useMenuNav({ ids, columns, wrap, disabled, initialId, enabled, onConfirm, onBack, onAdjust, gamepad, repeat, }: UseMenuNavOptions): MenuNavController;
 /** Render prop for a menu whose items come from {@link useMenuNav}. */
 export type MenuNavRender = (nav: MenuNavController) => ReactNode;

package/dist/menuNav.js

@@ -14,7 +14,7 @@ function isTextEntry(target) {
  *
  * @capability use-menu-nav keyboard and gamepad focus navigation for a menu — roving focus order, confirm/back, disabled-item skipping, no focus trap
  */
-export function useMenuNav({ ids, columns = 1, wrap = true, disabled, initialId, enabled = true, onConfirm, onBack, gamepad = true, repeat, }) {
+export function useMenuNav({ ids, columns = 1, wrap = true, disabled, initialId, enabled = true, onConfirm, onBack, onAdjust, gamepad = true, repeat, }) {
     const disabledIndices = useMemo(() => {
         if (disabled === undefined || disabled.length === 0)
             return undefined;
@@ -36,16 +36,28 @@ export function useMenuNav({ ids, columns = 1, wrap = true, disabled, initialId,
     idsRef.current = ids;
     const activeIndexRef = useRef(activeIndex);
     activeIndexRef.current = activeIndex;
-    const callbacks = useRef({ onConfirm, onBack });
-    callbacks.current = { onConfirm, onBack };
+    const callbacks = useRef({ onConfirm, onBack, onAdjust });
+    callbacks.current = { onConfirm, onBack, onAdjust };
     const elements = useRef(new Map());
     const pendingFocus = useRef(true);
+    // The first pass claims focus only when nothing else owns it; later moves focus the new item.
+    const claimed = useRef(false);
+    const firstEnablePass = useRef(true);
     const focusActive = useCallback(() => {
         const id = menuNavIdAt(idsRef.current, activeIndexRef.current);
         if (id === null)
             return;
         elements.current.get(id)?.focus({ preventScroll: true });
     }, []);
+    // A control or dialog that already owns focus keeps it; the first move brings focus into the menu. Without
+    // this a menu mounted inside a dialog takes focus from the dialog's own initial control, and the dialog's
+    // opener is never restored on close.
+    const claimFocus = useCallback(() => {
+        const active = typeof document === "undefined" ? null : document.activeElement;
+        if (active !== null && active !== document.body && active !== document.documentElement)
+            return;
+        focusActive();
+    }, [focusActive]);
     const move = useCallback((direction) => {
         const layout = {
             count: idsRef.current.length,
@@ -75,11 +87,19 @@ export function useMenuNav({ ids, columns = 1, wrap = true, disabled, initialId,
             activate(menuNavIdAt(idsRef.current, activeIndexRef.current));
         else if (intent === "back")
             callbacks.current.onBack?.();
+        else if (intent === "left" || intent === "right") {
+            const adjust = callbacks.current.onAdjust;
+            if (adjust === undefined) {
+                move(intent);
+                return;
+            }
+            const id = menuNavIdAt(idsRef.current, activeIndexRef.current);
+            if (id !== null)
+                adjust(id, intent === "right" ? 1 : -1);
+        }
         else
             move(intent);
     }, [activate, move]);
-    const moveRef = useRef(move);
-    moveRef.current = move;
     const runIntentRef = useRef(runIntent);
     runIntentRef.current = runIntent;
     const repeatRef = useRef(repeat);
@@ -88,14 +108,24 @@ export function useMenuNav({ ids, columns = 1, wrap = true, disabled, initialId,
         if (!pendingFocus.current)
             return;
         pendingFocus.current = false;
-        focusActive();
-    }, [activeIndex, focusActive]);
+        if (claimed.current) {
+            focusActive();
+            return;
+        }
+        claimed.current = true;
+        claimFocus();
+    }, [activeIndex, claimFocus, focusActive]);
     useEffect(() => {
         if (!enabled)
             return;
         pendingFocus.current = true;
+        if (firstEnablePass.current) {
+            firstEnablePass.current = false;
+            claimFocus();
+            return;
+        }
         focusActive();
-    }, [enabled, focusActive]);
+    }, [enabled, claimFocus, focusActive]);
     useEffect(() => {
         const index = ids.indexOf(activeId ?? "");
         if (activeId !== null && index >= 0)
@@ -201,12 +231,12 @@ export function useMenuNav({ ids, columns = 1, wrap = true, disabled, initialId,
                 }
                 if (isNew) {
                     held.set(button, { pressedAt: now, lastFiredAt: now });
-                    moveRef.current(intent);
+                    runIntentRef.current(intent);
                     continue;
                 }
                 if (record !== undefined && shouldRepeatMenuNav(now, record, repeatRef.current)) {
                     record.lastFiredAt = now;
-                    moveRef.current(intent);
+                    runIntentRef.current(intent);
                 }
             }
             for (const button of [...held.keys()])
@@ -222,12 +252,12 @@ export function useMenuNav({ ids, columns = 1, wrap = true, disabled, initialId,
             }
             if (stick === null || stick.intent !== axisIntent) {
                 stick = { intent: axisIntent, pressedAt: now, lastFiredAt: now };
-                moveRef.current(axisIntent);
+                runIntentRef.current(axisIntent);
                 return;
             }
             if (shouldRepeatMenuNav(now, stick, repeatRef.current)) {
                 stick.lastFiredAt = now;
-                moveRef.current(axisIntent);
+                runIntentRef.current(axisIntent);
             }
         };
         frame = requestAnimationFrame(poll);

package/dist/settingsBlocks.d.ts

@@ -1,25 +1,39 @@
 import { type CSSProperties, type ReactNode } from "react";
+import type { SettingValue } from "@jgengine/core/settings/settingsModel";
+import { type MenuNavItemProps } from "./menuNav.js";
 import type { SettingsCategoryView, SettingsKeybindRow, SettingsRow } from "./settings.js";
+/**
+ * One adjustment of a settings row: a slider moves by its step inside its bounds, a toggle flips, a
+ * select moves one option (wrapping at both ends). Returns the value to write, or `undefined` when the
+ * kind has nothing to step. Shared by the keyboard and the gamepad so both change a row the same way.
+ *
+ * @capability adjust-setting-row step a settings row value once, for keyboard and gamepad alike
+ */
+export declare function adjustSettingRow(row: SettingsRow, delta: -1 | 1): SettingValue | undefined;
 /**
  * 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 declare function SettingsSlider({ row }: {
+export declare function SettingsSlider({ row, itemProps }: {
     row: SettingsRow;
+    itemProps?: MenuNavItemProps;
 }): ReactNode;
 /** One on/off row from a {@link SettingsRow}. */
-export declare function SettingsToggle({ row }: {
+export declare function SettingsToggle({ row, itemProps }: {
     row: SettingsRow;
+    itemProps?: MenuNavItemProps;
 }): ReactNode;
 /** One choice row from a {@link SettingsRow}, rendered as a pressed-state option group. */
-export declare function SettingsSelect({ row }: {
+export declare function SettingsSelect({ row, itemProps }: {
     row: SettingsRow;
+    itemProps?: MenuNavItemProps;
 }): ReactNode;
-/** Render the control a {@link SettingsRow} kind asks for. */
-export declare function SettingsRowControl({ row }: {
+/** Render the control a {@link SettingsRow} kind asks for. `itemProps` carries `useMenuNav` focus tracking from {@link SettingsSection}. */
+export declare function SettingsRowControl({ row, itemProps }: {
     row: SettingsRow;
+    itemProps?: MenuNavItemProps;
 }): ReactNode;
 /** One rebindable action row: current key glyph, armed-capture state and a reset button. */
 export interface SettingsKeybindControlProps {
@@ -30,6 +44,8 @@ export interface SettingsKeybindControlProps {
     onArm?: () => void;
     /** Props the caller can spread onto the binding button for focus tracking. */
     buttonProps?: Record<string, unknown>;
+    /** Props for the row element (a `useMenuNav` item). */
+    rowProps?: MenuNavItemProps;
 }
 /**
  * A controls row for one action: its label, the bound key (click to rebind), a conflict/armed state
@@ -37,7 +53,7 @@ export interface SettingsKeybindControlProps {
  *
  * @capability settings-keybind-row one rebindable controls row — key glyph, armed state and reset
  */
-export declare function SettingsKeybindControl({ row, armed, onArm, buttonProps }: SettingsKeybindControlProps): ReactNode;
+export declare function SettingsKeybindControl({ row, armed, onArm, buttonProps, rowProps }: SettingsKeybindControlProps): ReactNode;
 /** How a {@link SettingsSection} handles a rebind capture. */
 export interface SettingsSectionProps {
     /** The category to render: its rows and its rebindable actions. */
@@ -46,6 +62,10 @@ export interface SettingsSectionProps {
     heading?: boolean;
     /** Allow click-to-rebind on the controls rows. Default true. */
     capture?: boolean;
+    /** Take arrow keys, the d-pad and the left stick for row navigation and value edits. Default true. */
+    enabled?: boolean;
+    /** Row focused on mount. Default the first row. */
+    initialId?: string;
     className?: string;
     style?: CSSProperties;
     /** Called with the armed action id (or `null`) so a game can suspend its own keys. */
@@ -56,9 +76,15 @@ export interface SettingsSectionProps {
  * 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
+ * The rows are one `useMenuNav` menu: up/down (or the d-pad/stick) move between them, left/right step
+ * the focused value — a slider by its step, a toggle flipped, a select to the next/previous option —
+ * and Enter/Space/A confirms, which flips a toggle, steps a select forward or arms a keybind.
+ * Keyboard and gamepad share that one mapping, so a held direction repeats at the same rate for both,
+ * and no row carries its own key handling.
+ *
+ * @capability settings-section settings category block — rows plus click-to-capture keybind rows, HudTheme-styled, store-backed, keyboard and gamepad navigable
  */
-export declare function SettingsSection({ category, heading, capture, className, style, onCaptureChange, }: SettingsSectionProps): ReactNode;
+export declare function SettingsSection({ category, heading, capture, enabled, initialId, className, style, onCaptureChange, }: SettingsSectionProps): ReactNode;
 /** The live category tabs for a settings screen: a scrollable rail with pressed state. */
 export interface SettingsTabsProps {
     /** The live categories from the settings controller. */

package/dist/settingsBlocks.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { hudSpace, hudType, hudTransition } from "./hudTokens.js";
+import { useMenuNav } from "./menuNav.js";
 import { ScrollRail } from "./scrollRail.js";
 import { useDebouncedCommit } from "./useDebouncedCommit.js";
 const rowStyle = {
@@ -24,8 +25,35 @@ const valueStyle = {
     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 })] }));
+function RowShell({ label, children, itemProps }) {
+    return (_jsxs("div", { "data-settings-row": "", style: rowStyle, ...itemProps, children: [_jsx("span", { style: labelStyle, children: label }), _jsx("div", { style: { display: "flex", alignItems: "center", gap: hudSpace("sm"), minWidth: 0 }, children: children })] }));
+}
+/**
+ * One adjustment of a settings row: a slider moves by its step inside its bounds, a toggle flips, a
+ * select moves one option (wrapping at both ends). Returns the value to write, or `undefined` when the
+ * kind has nothing to step. Shared by the keyboard and the gamepad so both change a row the same way.
+ *
+ * @capability adjust-setting-row step a settings row value once, for keyboard and gamepad alike
+ */
+export function adjustSettingRow(row, delta) {
+    if (row.kind === "toggle")
+        return !Boolean(row.value);
+    if (row.kind === "select") {
+        const options = row.options ?? [];
+        if (options.length === 0)
+            return undefined;
+        const current = options.findIndex((option) => option.value === String(row.value));
+        const base = current < 0 ? (delta > 0 ? -1 : 0) : current;
+        return options[(base + delta + options.length) % options.length]?.value;
+    }
+    if (row.kind !== "slider")
+        return undefined;
+    const step = row.step ?? 1;
+    const min = row.min ?? Number.NEGATIVE_INFINITY;
+    const max = row.max ?? Number.POSITIVE_INFINITY;
+    const next = Math.min(max, Math.max(min, Number(row.value) + step * delta));
+    // Settings persist as plain numbers, so keep float noise out of values like 0.30000000000000004.
+    return Math.round(next * 1e6) / 1e6;
 }
 /**
  * One slider row from a {@link SettingsRow}: mirrors the thumb locally and commits on release, so a
@@ -33,14 +61,14 @@ function RowShell({ label, children }) {
  *
  * @capability settings-slider a settings slider row that mirrors locally and persists on release
  */
-export function SettingsSlider({ row }) {
+export function SettingsSlider({ row, itemProps }) {
     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) })] }));
+    return (_jsxs(RowShell, { label: row.label, itemProps: itemProps, 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 }) {
+export function SettingsToggle({ row, itemProps }) {
     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: {
+    return (_jsx(RowShell, { label: row.label, itemProps: itemProps, 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,
@@ -62,9 +90,9 @@ export function SettingsToggle({ row }) {
                 } }) }) }));
 }
 /** One choice row from a {@link SettingsRow}, rendered as a pressed-state option group. */
-export function SettingsSelect({ row }) {
+export function SettingsSelect({ row, itemProps }) {
     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) => {
+    return (_jsx(RowShell, { label: row.label, itemProps: itemProps, 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,
@@ -80,13 +108,13 @@ export function SettingsSelect({ row }) {
                     }, children: option.label }, option.value));
             }) }) }));
 }
-/** Render the control a {@link SettingsRow} kind asks for. */
-export function SettingsRowControl({ row }) {
+/** Render the control a {@link SettingsRow} kind asks for. `itemProps` carries `useMenuNav` focus tracking from {@link SettingsSection}. */
+export function SettingsRowControl({ row, itemProps }) {
     if (row.kind === "slider")
-        return _jsx(SettingsSlider, { row: row });
+        return _jsx(SettingsSlider, { row: row, itemProps: itemProps });
     if (row.kind === "toggle")
-        return _jsx(SettingsToggle, { row: row });
-    return _jsx(SettingsSelect, { row: row });
+        return _jsx(SettingsToggle, { row: row, itemProps: itemProps });
+    return _jsx(SettingsSelect, { row: row, itemProps: itemProps });
 }
 /**
  * A controls row for one action: its label, the bound key (click to rebind), a conflict/armed state
@@ -94,8 +122,8 @@ export function SettingsRowControl({ row }) {
  *
  * @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: {
+export function SettingsKeybindControl({ row, armed = false, onArm, buttonProps, rowProps }) {
+    return (_jsxs("div", { "data-settings-keybind": row.action, "data-armed": armed ? "" : undefined, style: rowStyle, ...rowProps, 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")}`,
@@ -117,43 +145,95 @@ export function SettingsKeybindControl({ row, armed = false, onArm, buttonProps
                             cursor: "pointer",
                         }, children: "\u21BA" })] })] }));
 }
+const ROW_ITEM_PREFIX = "row:";
+const KEY_ITEM_PREFIX = "key:";
 /**
  * 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
+ * The rows are one `useMenuNav` menu: up/down (or the d-pad/stick) move between them, left/right step
+ * the focused value — a slider by its step, a toggle flipped, a select to the next/previous option —
+ * and Enter/Space/A confirms, which flips a toggle, steps a select forward or arms a keybind.
+ * Keyboard and gamepad share that one mapping, so a held direction repeats at the same rate for both,
+ * and no row carries its own key handling.
+ *
+ * @capability settings-section settings category block — rows plus click-to-capture keybind rows, HudTheme-styled, store-backed, keyboard and gamepad navigable
  */
-export function SettingsSection({ category, heading = true, capture = true, className, style, onCaptureChange, }) {
+export function SettingsSection({ category, heading = true, capture = true, enabled = true, initialId, className, style, onCaptureChange, }) {
     const [armed, setArmed] = useState(null);
+    // Mirrors `armed` synchronously. Two key events in one tick — Escape then the key after it — would both
+    // see the pre-render state without it, and the second would rebind what Escape just cancelled.
+    const armedRef = useRef(null);
+    const arm = useCallback((action) => {
+        armedRef.current = action;
+        setArmed(action);
+    }, []);
     const callbacks = useRef({ onCaptureChange });
     callbacks.current = { onCaptureChange };
     useEffect(() => {
         callbacks.current.onCaptureChange?.(armed);
     }, [armed]);
+    const rows = category.rows;
+    const keybinds = category.keybinds;
+    const ids = useMemo(() => [...rows.map((row) => `${ROW_ITEM_PREFIX}${row.id}`), ...keybinds.map((row) => `${KEY_ITEM_PREFIX}${row.action}`)], [rows, keybinds]);
+    const adjust = useCallback((id, delta) => {
+        // A keybind row has no value to step; confirming it is what arms the capture.
+        if (id.startsWith(KEY_ITEM_PREFIX))
+            return;
+        const row = rows.find((candidate) => `${ROW_ITEM_PREFIX}${candidate.id}` === id);
+        if (row === undefined)
+            return;
+        const next = adjustSettingRow(row, delta);
+        if (next !== undefined)
+            row.set(next);
+    }, [rows]);
+    const confirm = useCallback((id) => {
+        if (id.startsWith(ROW_ITEM_PREFIX)) {
+            const row = rows.find((candidate) => `${ROW_ITEM_PREFIX}${candidate.id}` === id);
+            // A slider's value belongs to left/right; confirming it would jump the thumb for a keyboard user.
+            if (row === undefined || row.kind === "slider")
+                return;
+            const next = adjustSettingRow(row, 1);
+            if (next !== undefined)
+                row.set(next);
+            return;
+        }
+        if (!capture)
+            return;
+        arm(id.slice(KEY_ITEM_PREFIX.length));
+    }, [arm, capture, rows]);
+    const nav = useMenuNav({
+        ids,
+        ...(initialId === undefined ? {} : { initialId: `${ROW_ITEM_PREFIX}${initialId}` }),
+        enabled: enabled && armed === null,
+        onAdjust: adjust,
+        onConfirm: confirm,
+    });
     useEffect(() => {
         if (armed === null)
             return;
-        const row = category.keybinds.find((candidate) => candidate.action === armed);
+        const row = keybinds.find((candidate) => candidate.action === armed);
         if (row === undefined) {
-            setArmed(null);
+            arm(null);
             return;
         }
         const onKey = (event) => {
             event.preventDefault();
             event.stopPropagation();
-            if (event.code === "Escape") {
-                setArmed(null);
+            if (armedRef.current !== row.action)
                 return;
-            }
-            row.rebind(event.code);
-            setArmed(null);
+            arm(null);
+            if (event.code !== "Escape")
+                row.rebind(event.code);
         };
         const onPointer = (event) => {
             event.preventDefault();
             event.stopPropagation();
+            if (armedRef.current !== row.action)
+                return;
+            arm(null);
             row.rebind(`mouse${event.button}`);
-            setArmed(null);
         };
         const onContext = (event) => event.preventDefault();
         window.addEventListener("keydown", onKey, true);
@@ -164,8 +244,8 @@ export function SettingsSection({ category, heading = true, capture = true, clas
             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: {
+    }, [armed, arm, keybinds]);
+    return (_jsxs("section", { ...nav.containerProps, "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)",
@@ -174,7 +254,7 @@ export function SettingsSection({ category, heading = true, capture = true, clas
                     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)))] }));
+                }, children: category.label })) : null, rows.map((row) => (_jsx(SettingsRowControl, { row: row, itemProps: nav.itemProps(`${ROW_ITEM_PREFIX}${row.id}`) }, row.id))), keybinds.map((row) => (_jsx(SettingsKeybindControl, { row: row, armed: armed === row.action, onArm: capture ? () => arm(row.action) : undefined, rowProps: nav.itemProps(`${KEY_ITEM_PREFIX}${row.action}`) }, row.action)))] }));
 }
 /**
  * The category tab rail for a settings screen: a scrollable row of buttons with pressed state. The

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/react",
-  "version": "0.28.0",
+  "version": "0.30.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.28.0"
+    "@jgengine/core": "^0.30.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.28.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.30.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.28.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.30.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 

package/skills/jgengine-ui/api.md

@@ -407,6 +407,7 @@
 - `TEXT_SCALE_MAX` (const): const TEXT_SCALE_MAX: 2 — Maximum UI text scale.
 - `TEXT_SCALE_MIN` (const): const TEXT_SCALE_MIN: 0.75 — Minimum UI text scale.
 - `clampTextScale` (function): function clampTextScale(scale: number): number — Clamp a text-scale multiplier into the supported `[TEXT_SCALE_MIN, TEXT_SCALE_MAX]` range.
+- `colorblindFrameFilter` (function): function colorblindFrameFilter(mode: ColorblindMode): string | null — The CSS filter that applies `mode` to one rendered frame — a `url(#jg-cb-<mode>)` reference to the `feColorMatrix` defs {@link COLORBLIND_MATRICES} drives. `"none"` maps to `null` (no filter), so a caller can spread it onto the canvas alone and leave HUD and menu text at its own contrast.
 - `createAccessibilityStore` (function): function createAccessibilityStore(initial: Partial<AccessibilityState> = {}): AccessibilityStore — Serializable, observable store of accessibility preferences (reduced motion, high contrast, text scale, colorblind mode, captions). Genre-agnostic plumbing like input rebinding — a game binds these to its settings UI and adapts its presentation; `snapshot`/`restore` round-trip through a save or settings blob.
 - `reducedMotionDuration` (function): function reducedMotionDuration(state: AccessibilityState, ms: number, reduced = 0): number — Return `ms` when motion is allowed, or `reduced` (default 0) when `reducedMotion` is set — the animation-duration gate.
 
@@ -652,7 +653,7 @@
 ## @jgengine/react
 
 - `AbilitySlotBindingOptions` (interface): interface AbilitySlotBindingOptions { intervalMs?: number } — ⚠ undocumented · used by `useEventMeter`: Bind a `createEventMeter` (`@jgengine/core/stats/eventMeter`) heat/streak gauge to a component — the react-render half of the ult/adrenaline…
-- `AccessibilityProvider` (function): function AccessibilityProvider({ store, children, className, style, }: { store: AccessibilityStore; children: ReactNode; className?: string; style?: CSSProperties; }): ReactNode — Apply accessibility preferences to a subtree: exposes `--jg-text-scale` for text to scale off, sets `data-reduced-motion` / `data-high-contrast` / `data-colorblind` / `data-captions` for CSS to respond to, and wraps the tree in the selected colorblind `feColorMatrix` filter. Reads a `createAccessibilityStore` and re-renders on change; provides the state to `useAccessibility`.
+- `AccessibilityProvider` (function): function AccessibilityProvider({ store, children, className, style, }: { store: AccessibilityStore; children: ReactNode; className?: string; style?: CSSProperties; }): ReactNode — Apply accessibility preferences to a subtree: exposes `--jg-text-scale` for text to scale off, and sets `data-reduced-motion` / `data-high-contrast` / `data-colorblind` / `data-captions` for CSS to respond to. Reads a `createAccessibilityStore` and re-renders on change; provides the state to `useAccessibility`.
 - `AchievementGallery` (function): function AchievementGallery({ achievements, title = "Achievements", maskSecrets = true, renderIcon, columns = 2, emptyLabel = "No achievements yet.", className, style, }: AchievementGalleryProps): ReactNode — Achievement/trophy gallery — a responsive grid of cards showing unlocked vs. locked state, a progress bar for counter achievements, and a header summary of completion and score. Secret+locked entries mask their name/description. Feed it `useAchievements(tracker)`.
 - `AchievementGalleryProps` (interface): interface AchievementGalleryProps — Props for {@link AchievementGallery}.
 - `AchievementToast` (function): function AchievementToast({ name, description, icon, points, heading = "Achievement Unlocked", className, style, }: AchievementToastProps): ReactNode — The unlock-moment banner — icon, "Achievement Unlocked" heading, name, and optional points. Purely presentational; pair the game's `onUnlock` seam with a toast queue and render one of these per entry.
@@ -703,7 +704,9 @@
 - `Codex` (function): function Codex({ entries, title = "Codex", columns = 3, maskSecrets = true, renderIcon, onSelect, emptyLabel = "Nothing discovered yet.", className, style, }: CodexProps): ReactNode — Codex / bestiary gallery — category tabs, a responsive grid of entry cards (discovered vs. locked, secret entries masked until found), and a header summarizing completion. Feed it `codex.list()`; wire `onSelect` to a detail pane.
 - `CodexProps` (interface): interface CodexProps — Props for {@link Codex}.
 - `Coins` (function): function Coins({ currencyId, icon = "🪙", style, className, }: { currencyId: string; icon?: ReactNode; style?: CSSProperties; className?: string; }): React.JSX.Element — A currency counter — an icon (emoji/char, default a coin) plus the live amount for `currencyId`. *
-- `ColorblindFilters` (function): function ColorblindFilters(): ReactNode — Hidden SVG `<defs>` holding the `feColorMatrix` colorblind filters that `AccessibilityProvider` references by `filter: url(#jg-cb-<mode>)`. Rendered automatically inside the provider; export standalone for custom roots.
+- `ColorblindFilters` (function): function ColorblindFilters(): ReactNode — Hidden SVG `<defs>` holding the `feColorMatrix` colorblind filters that `filter: url(#jg-cb-<mode>)` references. Mounted by {@link ColorblindFrame}; export it standalone for a root that applies the filter itself.
+- `ColorblindFrame` (function): function ColorblindFrame({ mode = "none", children, className, style }: ColorblindFrameProps): ReactNode — Apply the player's colour-vision mode to one rendered frame: a box carrying `filter: url(#jg-cb-<mode>)` plus the filter defs it references. Put it around the canvas of a 3D game and nothing else — the filter is one compositor pass over that box's pixels, so HUD, menu and caption text outside it keep the contrast and hues the rest of the UI assumes.
+- `ColorblindFrameProps` (interface): interface ColorblindFrameProps — Props for {@link ColorblindFrame}.
 - `ComboMeterHud` (function): function ComboMeterHud({ meter, tierColors, theme, animate = true, hideWhenEmpty = true, barWidth = 220, className, style, }: ComboMeterHudProps): ReactNode — A drop-in HUD for a core {@link ComboMeter}: the big live combo count ("×12"), the current free-string tier label, the derived score multiplier, and a draining window bar (reusing the shared atomic bar) that empties as the decay window runs out and re-fills on every hit. The active tier's color — supplied by the game via `tierColors`, keyed on the free-string tier id the model never interprets — drives the count glow, the label, and the bar fill, so a game reskins the escalation ("good" → "great" → "savage") without the engine hardcoding any tier meaning. Presentation only: all counting, timing, tiers, and the multiplier live in the core model.
 - `ComboMeterHudProps` (interface): interface ComboMeterHudProps — Props for {@link ComboMeterHud}.
 - `ComboMeterTheme` (interface): interface ComboMeterTheme — Reskin tokens for {@link ComboMeterHud}.
@@ -1067,6 +1070,7 @@
 - `useChat` (function): function useChat(channelId: string, options?: { limit?: number }): ChatMessage[] — ⚠ undocumented
 - `useChatBubbles` (function): function useChatBubbles(options?: ChatBubblesOptions): readonly ChatBubble[] — ⚠ undocumented
 - `useCoachMarks` (function): function useCoachMarks(sequence: CoachMarkSequence): CoachMarkView | null — Subscribe to a coach-mark sequence and re-render on every change, returning the current step view (or `null` when the tour is complete or waiting on a gate).
+- `useColorblindMode` (function): function useColorblindMode(store: SettingsStore): ColorblindMode — The live colour-vision mode from a settings store — the same store the settings rows write, so the frame follows the player's choice the moment they pick it. Pass the store the shell owns; read `useAccessibilitySettings().colorblind` instead when a `SettingsProvider` is above the caller.
 - `useComboMeter` (function): function useComboMeter(meter: ComboMeter, animate = true): ComboMeterView — Subscribe to a combo meter and re-render it each animation frame so the decay window bar drains live, returning the pooled view to draw right now. Reading the view each frame advances the meter's clock and fires window expiry, so a combo that times out visibly drops even with no further hits. The returned object is the model's pooled view — read its fields immediately, do not retain it.
 - `useCurrency` (function): function useCurrency(currencyId: string): number — ⚠ undocumented
 - `useDamageDirection` (function): function useDamageDirection(tracker: DamageDirectionTracker): readonly DamageIndicator[] — Subscribe to a damage-direction tracker and animate. Because indicators fade continuously on a clock (not just on discrete events), this drives a `requestAnimationFrame` loop while any indicator is live and stops when the screen is clear, then wakes again on the next hit. Returns the tracker's current `active()` array (reused between frames — copy if you retain it).
@@ -1110,7 +1114,7 @@
 - `useLocalPlayerDead` (function): function useLocalPlayerDead(healthStatId = "health"): boolean — ⚠ undocumented
 - `useLocale` (function): function useLocale(): Locale — Subscribe to the active locale — re-renders on `setLocale`.
 - `useMarkers` (function): function useMarkers<TMeta = unknown>(markers: MarkerSet<TMeta>): readonly MapMarker<TMeta>[] — Subscribe to a native marker set or external marker source, or read a static marker array.
-- `useMenuNav` (function): function useMenuNav({ ids, columns = 1, wrap = true, disabled, initialId, enabled = true, onConfirm, onBack, gamepad = true, repeat, }: UseMenuNavOptions): MenuNavController — Bind a menu's focus order to the DOM: arrow keys, WASD, Home/End and a standard gamepad move a roving focus, Enter/Space/A confirm, Escape/Backspace/B/Start go back. Tab is left to the browser, so a menu never traps focus, and typing in a text field is never intercepted. The menu is pure state + listeners — it unmounts with the screen, so it costs nothing during play.
+- `useMenuNav` (function): function useMenuNav({ ids, columns = 1, wrap = true, disabled, initialId, enabled = true, onConfirm, onBack, onAdjust, gamepad = true, repeat, }: UseMenuNavOptions): MenuNavController — Bind a menu's focus order to the DOM: arrow keys, WASD, Home/End and a standard gamepad move a roving focus, Enter/Space/A confirm, Escape/Backspace/B/Start go back. Tab is left to the browser, so a menu never traps focus, and typing in a text field is never intercepted. The menu is pure state + listeners — it unmounts with the screen, so it costs nothing during play.
 - `useModalStack` (function): function useModalStack(stack: ModalStack): ModalStackView — Subscribe to a modal stack and re-render on every change, returning the active modal and depth.
 - `useNearestWorldItem` (function): function useNearestWorldItem(radius: number): WorldItemRecord | null — Nearest ground item within `radius` of the local player — drives a pickup prompt/highlight.
 - `useNotifications` (function): function useNotifications<TMeta = unknown>(store: NotificationStore<TMeta>): readonly NotificationEntry<TMeta>[] — Subscribe to a notification store's live list.
@@ -1161,9 +1165,12 @@
 
 ## @jgengine/react/accessibility
 
-- `AccessibilityProvider` (function): function AccessibilityProvider({ store, children, className, style, }: { store: AccessibilityStore; children: ReactNode; className?: string; style?: CSSProperties; }): ReactNode — Apply accessibility preferences to a subtree: exposes `--jg-text-scale` for text to scale off, sets `data-reduced-motion` / `data-high-contrast` / `data-colorblind` / `data-captions` for CSS to respond to, and wraps the tree in the selected colorblind `feColorMatrix` filter. Reads a `createAccessibilityStore` and re-renders on change; provides the state to `useAccessibility`.
-- `ColorblindFilters` (function): function ColorblindFilters(): ReactNode — Hidden SVG `<defs>` holding the `feColorMatrix` colorblind filters that `AccessibilityProvider` references by `filter: url(#jg-cb-<mode>)`. Rendered automatically inside the provider; export standalone for custom roots.
+- `AccessibilityProvider` (function): function AccessibilityProvider({ store, children, className, style, }: { store: AccessibilityStore; children: ReactNode; className?: string; style?: CSSProperties; }): ReactNode — Apply accessibility preferences to a subtree: exposes `--jg-text-scale` for text to scale off, and sets `data-reduced-motion` / `data-high-contrast` / `data-colorblind` / `data-captions` for CSS to respond to. Reads a `createAccessibilityStore` and re-renders on change; provides the state to `useAccessibility`.
+- `ColorblindFilters` (function): function ColorblindFilters(): ReactNode — Hidden SVG `<defs>` holding the `feColorMatrix` colorblind filters that `filter: url(#jg-cb-<mode>)` references. Mounted by {@link ColorblindFrame}; export it standalone for a root that applies the filter itself.
+- `ColorblindFrame` (function): function ColorblindFrame({ mode = "none", children, className, style }: ColorblindFrameProps): ReactNode — Apply the player's colour-vision mode to one rendered frame: a box carrying `filter: url(#jg-cb-<mode>)` plus the filter defs it references. Put it around the canvas of a 3D game and nothing else — the filter is one compositor pass over that box's pixels, so HUD, menu and caption text outside it keep the contrast and hues the rest of the UI assumes.
+- `ColorblindFrameProps` (interface): interface ColorblindFrameProps — Props for {@link ColorblindFrame}.
 - `useAccessibility` (function): function useAccessibility(): AccessibilityContextValue — Read the live accessibility state + its store; throws without an {@link AccessibilityProvider} above.
+- `useColorblindMode` (function): function useColorblindMode(store: SettingsStore): ColorblindMode — The live colour-vision mode from a settings store — the same store the settings rows write, so the frame follows the player's choice the moment they pick it. Pass the store the shell owns; read `useAccessibilitySettings().colorblind` instead when a `SettingsProvider` is above the caller.
 - `usePrefersReducedMotion` (function): function usePrefersReducedMotion(): boolean — OS "reduce motion" preference (`prefers-reduced-motion: reduce`) as a live boolean — SSR-safe (defaults false). Use it to seed an accessibility store's `reducedMotion` default.
 - `useReducedMotion` (function): function useReducedMotion(): boolean — True when motion should be skipped: the OS `prefers-reduced-motion` preference, or the nearest {@link AccessibilityProvider}'s `reducedMotion` setting. Works without a provider.
 
@@ -1746,7 +1753,7 @@
 - `MenuNavItemProps` (interface): interface MenuNavItemProps — Props a menu item needs so {@link useMenuNav} can focus it and track pointer/focus.
 - `MenuNavRender` (type): type MenuNavRender = (nav: MenuNavController) => ReactNode — Render prop for a menu whose items come from {@link useMenuNav}.
 - `UseMenuNavOptions` (interface): interface UseMenuNavOptions — How {@link useMenuNav} is wired.
-- `useMenuNav` (function): function useMenuNav({ ids, columns = 1, wrap = true, disabled, initialId, enabled = true, onConfirm, onBack, gamepad = true, repeat, }: UseMenuNavOptions): MenuNavController — Bind a menu's focus order to the DOM: arrow keys, WASD, Home/End and a standard gamepad move a roving focus, Enter/Space/A confirm, Escape/Backspace/B/Start go back. Tab is left to the browser, so a menu never traps focus, and typing in a text field is never intercepted. The menu is pure state + listeners — it unmounts with the screen, so it costs nothing during play.
+- `useMenuNav` (function): function useMenuNav({ ids, columns = 1, wrap = true, disabled, initialId, enabled = true, onConfirm, onBack, onAdjust, gamepad = true, repeat, }: UseMenuNavOptions): MenuNavController — Bind a menu's focus order to the DOM: arrow keys, WASD, Home/End and a standard gamepad move a roving focus, Enter/Space/A confirm, Escape/Backspace/B/Start go back. Tab is left to the browser, so a menu never traps focus, and typing in a text field is never intercepted. The menu is pure state + listeners — it unmounts with the screen, so it costs nothing during play.
 
 ## @jgengine/react/menuRouter
 
@@ -1921,16 +1928,17 @@
 
 ## @jgengine/react/settingsBlocks
 
-- `SettingsKeybindControl` (function): function SettingsKeybindControl({ row, armed = false, onArm, buttonProps }: SettingsKeybindControlProps): ReactNode — 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.
+- `SettingsKeybindControl` (function): function SettingsKeybindControl({ row, armed = false, onArm, buttonProps, rowProps }: SettingsKeybindControlProps): ReactNode — 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.
 - `SettingsKeybindControlProps` (interface): interface SettingsKeybindControlProps — One rebindable action row: current key glyph, armed-capture state and a reset button.
-- `SettingsRowControl` (function): function SettingsRowControl({ row }: { row: SettingsRow }): ReactNode — Render the control a {@link SettingsRow} kind asks for.
-- `SettingsSection` (function): function SettingsSection({ category, heading = true, capture = true, className, style, onCaptureChange, }: SettingsSectionProps): ReactNode — 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.
+- `SettingsRowControl` (function): function SettingsRowControl({ row, itemProps }: { row: SettingsRow; itemProps?: MenuNavItemProps }): ReactNode — Render the control a {@link SettingsRow} kind asks for. `itemProps` carries `useMenuNav` focus tracking from {@link SettingsSection}.
+- `SettingsSection` (function): function SettingsSection({ category, heading = true, capture = true, enabled = true, initialId, className, style, onCaptureChange, }: SettingsSectionProps): ReactNode — 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.
 - `SettingsSectionProps` (interface): interface SettingsSectionProps — How a {@link SettingsSection} handles a rebind capture.
-- `SettingsSelect` (function): function SettingsSelect({ row }: { row: SettingsRow }): ReactNode — One choice row from a {@link SettingsRow}, rendered as a pressed-state option group.
-- `SettingsSlider` (function): function SettingsSlider({ row }: { row: SettingsRow }): ReactNode — 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.
+- `SettingsSelect` (function): function SettingsSelect({ row, itemProps }: { row: SettingsRow; itemProps?: MenuNavItemProps }): ReactNode — One choice row from a {@link SettingsRow}, rendered as a pressed-state option group.
+- `SettingsSlider` (function): function SettingsSlider({ row, itemProps }: { row: SettingsRow; itemProps?: MenuNavItemProps }): ReactNode — 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.
 - `SettingsTabs` (function): function SettingsTabs({ categories, activeId, onSelect, leading, tabProps, className, style }: SettingsTabsProps): ReactNode — 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.
 - `SettingsTabsProps` (interface): interface SettingsTabsProps — The live category tabs for a settings screen: a scrollable rail with pressed state.
-- `SettingsToggle` (function): function SettingsToggle({ row }: { row: SettingsRow }): ReactNode — One on/off row from a {@link SettingsRow}.
+- `SettingsToggle` (function): function SettingsToggle({ row, itemProps }: { row: SettingsRow; itemProps?: MenuNavItemProps }): ReactNode — One on/off row from a {@link SettingsRow}.
+- `adjustSettingRow` (function): function adjustSettingRow(row: SettingsRow, delta: -1 | 1): SettingValue | undefined — One adjustment of a settings row: a slider moves by its step inside its bounds, a toggle flips, a select moves one option (wrapping at both ends). Returns the value to write, or `undefined` when the kind has nothing to step. Shared by the keyboard and the gamepad so both change a row the same way.
 
 ## @jgengine/react/shopGrid
 
@@ -3654,9 +3662,9 @@
 - `ProjectileTracers` (function): function ProjectileTracers({ lifeMs = 130 }: { lifeMs?: number }): React.JSX.Element — ⚠ undocumented
 - `Reticle` (function): function Reticle({ className }: { className?: string }): React.JSX.Element — ⚠ undocumented
 - `WorldBarSample` (interface): interface WorldBarSample { entityId?: string; x: number; y: number; percent: number; pxPerMeter?: number } — ⚠ undocumented
-- `WorldEntityBars` (function): function WorldEntityBars({ statId, height = 2.2, roles, resolveRole, maxDistance = 60, occlude = true, tickMs = 80, maxSamples = 64, }: { statId: string; height?: number; roles?: readonly CatalogEntityRole[]; resolveRole?: (entity: SceneEntity) => CatalogEntityRole | undefined; /** Hide bars beyond … — ⚠ undocumented
+- `WorldEntityBars` (function): function WorldEntityBars({ statId, height = 2.2, roles, resolveRole, maxDistance, occlude = true, tickMs = 80, maxSamples = 64, }: { statId: string; height?: number; roles?: readonly CatalogEntityRole[]; resolveRole?: (entity: SceneEntity) => CatalogEntityRole | undefined; /** Hide bars beyond this … — ⚠ undocumented
 - `WorldFloatText` (function): function WorldFloatText({ height = 1.9, lifeMs = 950 }: { height?: number; lifeMs?: number }): React.JSX.Element — ⚠ undocumented
-- `WorldNameplates` (function): function WorldNameplates({ statId = "health", height = 2.3, roles, resolveRole, maxDistance = 40, occlude = true, tickMs = 120, maxSamples = 64, resolveName, showHealth = true, className, nameplateClassName, nameClassName, barClassName, fillClassName, renderNameplate, }: WorldNameplatesProps): React… — Billboarded name + 78×6px HP bar over every nearby non-local entity that passes `roles`/`maxDistance` — headless (className/data-* slots on every part, `renderNameplate` for a full swap), turned on declaratively via `defineGame({ nameplates })` rather than mounted by hand.
+- `WorldNameplates` (function): function WorldNameplates({ statId = "health", height = 2.3, roles, resolveRole, maxDistance, occlude = true, tickMs = 120, maxSamples = 64, resolveName, showHealth = true, className, nameplateClassName, nameClassName, barClassName, fillClassName, renderNameplate, }: WorldNameplatesProps): React.JSX.… — Billboarded name + 78×6px HP bar over every nearby non-local entity that passes `roles`/`maxDistance` — headless (className/data-* slots on every part, `renderNameplate` for a full swap), turned on declaratively via `defineGame({ nameplates })` rather than mounted by hand.
 - `WorldNameplatesProps` (interface): interface WorldNameplatesProps — Props for `WorldNameplates` — entity filter, refresh rate, and headless className/render hooks.
 - `WorldObjectHighlights` (function): function WorldObjectHighlights({ color = "#facc15", radius, y = 0.05 }: WorldObjectHighlightsProps): React.JSX.Element — Ground ring over every `ctx.scene.object.selection`-ed placed object — the object-layer counterpart to `WorldEntityBars`/`WorldNameplates`. Mount it once in the game's scene (headless: no defaults are imposed beyond a visible ring) instead of hand-rolling a selection highlight through `WorldOverlay` against external state.
 - `WorldObjectHighlightsProps` (interface): interface WorldObjectHighlightsProps — Props for {@link WorldObjectHighlights}.

package/skills/jgengine-ui/capabilities.md

@@ -4,7 +4,7 @@
 
 Reach for these before hand-rolling. Each row is *the thing you need* → *the primitive that already does it*.
 
-## accessibility-provider — apply accessibility preferences to a subtree — text-scale CSS var, reduced-motion/high-contrast/colorblind/captions data attrs, and the colorblind color-matrix filter
+## accessibility-provider — apply accessibility preferences to a subtree — text-scale CSS var and reduced-motion/high-contrast/colorblind/captions data attrs
 
 - `AccessibilityProvider` (function) · `import { AccessibilityProvider } from "@jgengine/react"`
 
@@ -52,6 +52,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `ActionTooltip` (function) · `import { ActionTooltip } from "@jgengine/react"`
 
+## adjust-setting-row — step a settings row value once, for keyboard and gamepad alike
+
+- `adjustSettingRow` (function) · `import { adjustSettingRow } from "@jgengine/react/settingsBlocks"`
+
 ## animation — turn a killed rigged character into a physics ragdoll on death
 
 - `useRagdoll` (function) · `import { useRagdoll } from "@jgengine/shell/render/useRagdoll"`
@@ -159,6 +163,18 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `ColorblindFilters` (function) · `import { ColorblindFilters } from "@jgengine/react"`
 
+## colorblind-frame — apply the player's colour-vision mode to the 3D frame alone, leaving HUD and menu text unfiltered
+
+- `ColorblindFrame` (function) · `import { ColorblindFrame } from "@jgengine/react"`
+
+## colorblind-frame-filter — resolve a colorblind mode to the CSS filter for the 3D frame alone
+
+- `colorblindFrameFilter` (function) · `import { colorblindFrameFilter } from "@jgengine/core/ui/accessibility"`
+
+## colorblind-frame-mode — read the live colour-vision mode from the settings store that the settings rows write
+
+- `useColorblindMode` (function) · `import { useColorblindMode } from "@jgengine/react"`
+
 ## combo-meter-hud — drop-in HUD for a core combo meter — big live count, free-string tier label, derived multiplier, and a draining decay-window bar, per-tier colored from a caller map and HudTheme-token skinnable
 
 - `ComboMeterHud` (function) · `import { ComboMeterHud } from "@jgengine/react"`
@@ -758,7 +774,7 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `SettingsKeybindControl` (function) · `import { SettingsKeybindControl } from "@jgengine/react/settingsBlocks"`
 
-## settings-section — settings category block — rows plus click-to-capture keybind rows, HudTheme-styled, store-backed
+## settings-section — settings category block — rows plus click-to-capture keybind rows, HudTheme-styled, store-backed, keyboard and gamepad navigable
 
 - `SettingsSection` (function) · `import { SettingsSection } from "@jgengine/react/settingsBlocks"`
 

package/skills/jgengine-ui/reference.md

@@ -279,9 +279,9 @@ HUD-only games (`presentation: "hud"` or a camera with rig `"none"`) use the sam
 
 **Present it any way you want.** `useSettings()` (`@jgengine/react`) returns the live controller — `{ categories, actions, variant, surface, isOpen, open, close, setOpen }` — so a game can drive its own pause-menu button, or render `categories`/`actions` (rows carry `value`/`set`/bounds, keybinds carry `rebind`/`reset`) entirely inside its own HUD. `useHasSettings()` gates a custom entry; `useSetting(id, fallback)` reads/writes one value. Set a slider's `min`/`max` explicitly — an omitted range collapses the thumb to 0/1.
 
-**Composing your own settings layout.** `SettingsSection` (`@jgengine/react/settingsBlocks`) renders one controller category — its rows, then its click-to-capture keybind rows — and `SettingsTabs` renders the category rail (pass `tabProps` from `useMenuNav` so a gamepad can switch categories). `SettingsRowControl`, `SettingsSlider`, `SettingsToggle`, `SettingsSelect` and `SettingsKeybindControl` are the individual rows if the layout is not a list. All of them read `--jg-*` tokens and write through the controller, so the game's rebinds land in the same keybinding store as the stock menu. The stock menu uses these same blocks, so a game-composed screen and the engine dialog cannot drift.
+**Composing your own settings layout.** `SettingsSection` (`@jgengine/react/settingsBlocks`) renders one controller category - its rows, then its click-to-capture keybind rows - as one `useMenuNav` menu: the d-pad and left stick move between rows, left/right step the focused value (slider by its step, toggle flipped, select to the next option), and confirm arms a keybind. Arrow keys take the same `onAdjust` path, so a keyboard and a pad cannot diverge. `SettingsTabs` renders the category rail (pass `tabProps` from `useMenuNav` so a gamepad can switch categories). `SettingsRowControl`, `SettingsSlider`, `SettingsToggle`, `SettingsSelect` and `SettingsKeybindControl` are the individual rows if the layout is not a list; pass the `itemProps` they accept so focus tracking still works. All of them read `--jg-*` tokens and write through the controller, so the game's rebinds land in the same keybinding store as the stock menu. The stock menu uses these same blocks, so a game-composed screen and the engine dialog cannot drift.
 
-**Accessibility is a shipped category.** The settings menu includes `accessibility` — text size, colourblind palette, reduce motion, high contrast, captions and hold-or-toggle — unless the game hides it. Text size multiplies every `--jg-type-*` token through `--jg-text-scale`, reduce motion zeroes `--jg-motion-scale`, and high contrast/colourblind/captions set `data-*` hooks on the HUD root; read them with `useAccessibilitySettings()` and `useHoldVsToggle()` for a custom layout. Apply the colourblind matrix (`ColorblindFilters`, `@jgengine/react/accessibility`) around the surface that should be daltonized — the shell sets the hook but does not wrap the 3D canvas.
+**Accessibility is a shipped category.** The settings menu includes `accessibility` — text size, colourblind palette, reduce motion, high contrast, captions and hold-or-toggle — unless the game hides it. Text size multiplies every `--jg-type-*` token through `--jg-text-scale`, reduce motion zeroes `--jg-motion-scale`, and high contrast/colourblind/captions set `data-*` hooks on the HUD root; read them with `useAccessibilitySettings()` and `useHoldVsToggle()` for a custom layout. The 3D shell applies the colourblind matrix to its canvas alone with `ColorblindFrame` (`@jgengine/react/accessibility`), so HUD and menu text keep the contrast the rest of the UI assumes. A custom presentation wraps its own canvas in `ColorblindFrame` with `useColorblindMode(store)`; wrapping the HUD or menu root instead recolours the text, which is why `AccessibilityProvider` sets `data-colorblind` and leaves the filtering to the frame.
 
 ## 8. Motion and game feel