@jgengine/react 0.29.0 → 0.31.0

package/dist/hudLayout.js

@@ -1,5 +1,5 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { createContext, useContext, useEffect, useMemo, useRef, useState, } from "react";
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, } from "react";
 import { createPortal } from "react-dom";
 import { HUD_ANCHOR_FRACTIONS, anchoredPlacement, createHudLayout, isPanelDraggable, registerActiveHudLayout, } from "@jgengine/core/ui/hudLayout";
 import { resizePanelSize, resolvePanelResize, } from "@jgengine/core/ui/hudDocument";
@@ -9,6 +9,7 @@ import { useDisplayProfile } from "./display.js";
 import { useEngineState } from "./engineStore.js";
 import { useGameLayoutMode, useRegisterLayoutRegion } from "./gameViewport.js";
 import { useOptionalGamePhase } from "./hooks.js";
+import { formatHudOverlapReport, hudBlockOverlaps, resolveHudLanes } from "./hudLanes.js";
 import { useHudLayoutPersist } from "./hudLayoutPersist.js";
 import { useHudViewport } from "./hudViewport.js";
 import { hudFont, hudType } from "./hudTokens.js";
@@ -34,13 +35,21 @@ const WINDOW_ATTR = "data-hud-window";
 /**
  * Dev-only, prod-safe. The on-screen boundary overlay must never reach players,
  * so anything we cannot positively identify as a dev build resolves to `false`.
+ *
+ * `import.meta.env.DEV` is read as a literal member chain because Vite replaces
+ * exactly those words at transform time; reading `env` off a cast `import.meta`
+ * survives to the browser as `undefined` and every dev-only report stays dark.
  */
 function isDevBuild() {
     try {
-        const meta = import.meta;
-        if (meta.env?.DEV === true)
+        // Literal members on purpose: Vite replaces exactly `import.meta.env.DEV`.
+        // Inlined as plain `@ts-ignore` because a workspace-wide type program that
+        // includes `vite/client` would otherwise fail an unused-directive check.
+        // @ts-ignore -- `vite/client` types are not part of this package's own tsconfig
+        if (import.meta.env.DEV === true)
             return true;
-        if (meta.env?.PROD === true)
+        // @ts-ignore -- `vite/client` types are not part of this package's own tsconfig
+        if (import.meta.env.PROD === true)
             return false;
     }
     catch {
@@ -108,6 +117,21 @@ function collectBoundarySurfaces(canvas) {
     }
     return out;
 }
+/**
+ * The nearest ancestor that actually has a box. `HudThemeRoot` is
+ * `display: contents`, so `canvas.parentElement` can be a layout-free element
+ * whose rect is 0x0 — measuring it would silently disable every check below.
+ */
+function measurableHost(canvas) {
+    let element = canvas.parentElement;
+    while (element !== null) {
+        const rect = element.getBoundingClientRect();
+        if (rect.width > 0 && rect.height > 0)
+            return element;
+        element = element.parentElement;
+    }
+    return canvas;
+}
 function sizeStyle(panel) {
     if (panel === undefined)
         return {};
@@ -197,6 +221,7 @@ export function useHudLayout(options) {
     }, [layout, storageKey, documentUi]);
     return layout;
 }
+const EMPTY_LANE_RECTS = {};
 const HudCanvasContext = createContext(null);
 function HudEditBar({ layout }) {
     return (_jsxs("div", { "data-hud-edit-bar": "", style: {
@@ -305,7 +330,82 @@ export function HudCanvas({ layout, editChord, compactScale, showDuring, classNa
         }
         return refs;
     }, []);
-    const value = useMemo(() => ({ layout, canvasRef, regions, compact }), [layout, regions, compact]);
+    const [laneLayer, setLaneLayer] = useState(null);
+    const [laneFrame, setLaneFrame] = useState(null);
+    const [laneRevision, setLaneRevision] = useState(0);
+    const laneSlots = useRef(new Map());
+    const laneSizes = useRef(new Map());
+    const declareLane = useCallback((slot) => {
+        const previous = laneSlots.current.get(slot.id);
+        if (previous !== undefined &&
+            previous.anchor === slot.anchor &&
+            previous.lane === slot.lane &&
+            previous.order === slot.order &&
+            previous.width === slot.width &&
+            previous.height === slot.height &&
+            previous.rect === slot.rect) {
+            return;
+        }
+        laneSlots.current.set(slot.id, slot);
+        setLaneRevision((value) => value + 1);
+    }, []);
+    const removeLane = useCallback((id) => {
+        if (!laneSlots.current.delete(id))
+            return;
+        laneSizes.current.delete(id);
+        setLaneRevision((value) => value + 1);
+    }, []);
+    const reportLaneSize = useCallback((id, size) => {
+        const previous = laneSizes.current.get(id);
+        if (previous !== undefined &&
+            Math.abs(previous.width - size.width) < 0.5 &&
+            Math.abs(previous.height - size.height) < 0.5) {
+            return;
+        }
+        laneSizes.current.set(id, size);
+        setLaneRevision((value) => value + 1);
+    }, []);
+    const laneRects = useMemo(() => {
+        if (laneFrame === null || laneSlots.current.size === 0)
+            return EMPTY_LANE_RECTS;
+        const slots = [];
+        for (const slot of laneSlots.current.values()) {
+            const measured = laneSizes.current.get(slot.id);
+            slots.push(measured === undefined
+                ? slot
+                : { ...slot, width: slot.width ?? measured.width, height: slot.height ?? measured.height });
+        }
+        return resolveHudLanes(slots, laneFrame, { gap: REGION_GAP }).rects;
+    }, [laneFrame, laneRevision]);
+    useEffect(() => {
+        if (laneLayer === null)
+            return;
+        const measure = () => {
+            const rect = laneLayer.getBoundingClientRect();
+            if (rect.width <= 0 || rect.height <= 0)
+                return;
+            setLaneFrame((prev) => prev !== null && Math.abs(prev.width - rect.width) < 0.5 && Math.abs(prev.height - rect.height) < 0.5
+                ? prev
+                : { width: rect.width, height: rect.height });
+        };
+        measure();
+        if (typeof ResizeObserver === "undefined")
+            return;
+        const observer = new ResizeObserver(measure);
+        observer.observe(laneLayer);
+        return () => observer.disconnect();
+    }, [laneLayer]);
+    const value = useMemo(() => ({
+        layout,
+        canvasRef,
+        regions,
+        compact,
+        laneLayer,
+        laneRects,
+        declareLane,
+        removeLane,
+        reportLaneSize,
+    }), [layout, regions, compact, laneLayer, laneRects, declareLane, removeLane, reportLaneSize]);
     const editing = useEngineState(layout).editing;
     useEffect(() => registerActiveHudLayout(layout), [layout]);
     const chordEnabled = editChord !== false;
@@ -350,7 +450,7 @@ export function HudCanvas({ layout, editChord, compactScale, showDuring, classNa
     useEffect(() => {
         if (!fitEnabled)
             return;
-        const host = canvasRef.current?.parentElement;
+        const host = canvasRef.current === null ? null : measurableHost(canvasRef.current);
         if (host === undefined || host === null || typeof ResizeObserver === "undefined")
             return;
         const measure = () => {
@@ -365,13 +465,14 @@ export function HudCanvas({ layout, editChord, compactScale, showDuring, classNa
     }, [fitEnabled]);
     useEffect(() => {
         const canvas = canvasRef.current;
-        const host = canvas?.parentElement;
-        if (canvas === null || canvas === undefined || host === undefined || host === null)
+        if (canvas === null)
             return;
+        const host = measurableHost(canvas);
         if (typeof requestAnimationFrame !== "function")
             return;
         let frame = 0;
         let lastReport = "";
+        let lastOverlapReport = "";
         const dev = isDevBuild();
         const check = () => {
             frame = 0;
@@ -398,21 +499,46 @@ export function HudCanvas({ layout, editChord, compactScale, showDuring, classNa
             // cross an edge — a closed/parked/off-screen menu is never an offender.
             const escaped = overflowingPanels(surfaces, viewportSize);
             const report = escaped.length === 0 ? "" : JSON.stringify(escaped);
-            if (report === lastReport)
-                return;
-            lastReport = report;
-            if (report === "") {
-                canvas.removeAttribute("data-hud-overflow");
-            }
-            else {
-                canvas.setAttribute("data-hud-overflow", report);
-                console.warn(`[jgengine] HUD UI escapes the ${Math.round(hostRect.width)}x${Math.round(hostRect.height)} viewport: ${report}`);
+            if (report !== lastReport) {
+                lastReport = report;
+                if (report === "") {
+                    canvas.removeAttribute("data-hud-overflow");
+                }
+                else {
+                    canvas.setAttribute("data-hud-overflow", report);
+                    console.warn(`[jgengine] HUD UI escapes the ${Math.round(hostRect.width)}x${Math.round(hostRect.height)} viewport: ${report}`);
+                }
+                if (dev) {
+                    setOffenders(escaped.map((overflow) => {
+                        const rect = surfaces.find((s) => s.id === overflow.id)?.rect;
+                        return { ...overflow, x: rect?.x ?? 0, y: rect?.y ?? 0, width: rect?.width ?? 0, height: rect?.height ?? 0 };
+                    }));
+                }
             }
-            if (dev) {
-                setOffenders(escaped.map((overflow) => {
-                    const rect = surfaces.find((s) => s.id === overflow.id)?.rect;
-                    return { ...overflow, x: rect?.x ?? 0, y: rect?.y ?? 0, width: rect?.width ?? 0, height: rect?.height ?? 0 };
-                }));
+            const blocks = [...canvas.querySelectorAll("[data-hud-panel]")]
+                .filter((el) => isSurfaceShown(el))
+                .map((el) => {
+                const rect = el.getBoundingClientRect();
+                return {
+                    id: surfaceId(el),
+                    rect: {
+                        x: rect.left - hostRect.left,
+                        y: rect.top - hostRect.top,
+                        width: rect.width,
+                        height: rect.height,
+                    },
+                };
+            });
+            const overlapReport = dev ? formatHudOverlapReport(hudBlockOverlaps(blocks), viewportSize) : "";
+            if (overlapReport !== lastOverlapReport) {
+                lastOverlapReport = overlapReport;
+                if (overlapReport === "") {
+                    canvas.removeAttribute("data-hud-overlap");
+                }
+                else {
+                    canvas.setAttribute("data-hud-overlap", overlapReport);
+                    console.warn(`[jgengine] ${overlapReport}`);
+                }
             }
         };
         const schedule = () => {
@@ -462,7 +588,14 @@ export function HudCanvas({ layout, editChord, compactScale, showDuring, classNa
                         pointerEvents: "none",
                         zIndex: 1,
                         ...REGION_LAYOUT[anchor],
-                    } }, anchor))), children, offenders.length > 0 ? (_jsx("div", { "data-hud-overflow-overlay": "", style: { position: "absolute", inset: 0, pointerEvents: "none", zIndex: EDIT_BAR_Z - 1 }, children: offenders.map((o) => (_jsx("div", { style: {
+                    } }, anchor))), _jsx("div", { "data-hud-lane-layer": "", style: {
+                        position: "absolute",
+                        inset: 0,
+                        padding: `${PAD_TOP} ${PAD_RIGHT} ${PAD_BOTTOM} ${PAD_LEFT}`,
+                        boxSizing: "border-box",
+                        pointerEvents: "none",
+                        zIndex: 1,
+                    }, children: _jsx("div", { ref: setLaneLayer, style: { position: "relative", width: "100%", height: "100%" } }) }), children, offenders.length > 0 ? (_jsx("div", { "data-hud-overflow-overlay": "", style: { position: "absolute", inset: 0, pointerEvents: "none", zIndex: EDIT_BAR_Z - 1 }, children: offenders.map((o) => (_jsx("div", { style: {
                             position: "absolute",
                             left: o.x / scale,
                             top: o.y / scale,
@@ -537,13 +670,13 @@ function HudChip({ label, anchor, children, }) {
   *
  * @capability hud-panel anchored HUD slot — drop any widget in a named, player-movable panel
  */
-export function HudPanel({ id, anchor = "top-left", order, compact: compactMode = "keep", chip, interactive, inset, locked, showDuring, priority, mobileBehavior, allowOverlapWith, collisionGroup, region = true, width, height, type, className, style, children, }) {
+export function HudPanel({ id, anchor = "top-left", lane, order, compact: compactMode = "keep", chip, interactive, inset, locked, showDuring, priority, mobileBehavior, allowOverlapWith, collisionGroup, region = true, width, height, type, className, style, children, }) {
     const ctx = useContext(HudCanvasContext);
     const phase = useOptionalGamePhase();
     const layoutMode = useGameLayoutMode();
     if (ctx === null)
         throw new Error("HudPanel must be rendered inside a HudCanvas");
-    const { layout, canvasRef, regions, compact } = ctx;
+    const { layout, canvasRef, regions, compact, laneLayer, laneRects, declareLane, removeLane, reportLaneSize } = ctx;
     const onMobile = isMobileMode(layoutMode);
     const registeredOnRef = useRef(null);
     if (registeredOnRef.current !== layout) {
@@ -582,6 +715,59 @@ export function HudPanel({ id, anchor = "top-left", order, compact: compactMode
     // A flowing panel portals into its anchor region, which HudCanvas only provides after its first commit.
     const awaitingRegion = panel !== undefined && (compact || !panel.moved) && regions[compact ? anchor : panel.placement.anchor] === undefined;
     useRegisterLayoutRegion(regionSpec, rootRef, region && !regionHidden && !awaitingRegion);
+    const laneActive = lane !== undefined && !regionHidden && !(panel !== undefined && panel.moved);
+    const laneRect = lane === undefined ? undefined : laneRects[id];
+    const [laneSize, setLaneSize] = useState(null);
+    useEffect(() => {
+        if (!laneActive)
+            return;
+        declareLane({
+            id,
+            anchor: panel?.placement.anchor ?? anchor,
+            lane,
+            order,
+            width: panel?.width ?? width,
+            height: panel?.height ?? height,
+        });
+        return () => removeLane(id);
+    }, [
+        laneActive,
+        declareLane,
+        removeLane,
+        id,
+        panel?.placement.anchor,
+        lane,
+        order,
+        panel?.width,
+        width,
+        panel?.height,
+        height,
+    ]);
+    const laneMounted = laneRect !== undefined;
+    useEffect(() => {
+        if (!laneActive || !laneMounted)
+            return;
+        const element = rootRef.current;
+        if (element === null)
+            return;
+        const measure = () => {
+            const rect = element.getBoundingClientRect();
+            if (rect.width <= 0 && rect.height <= 0)
+                return;
+            setLaneSize((previous) => previous !== null &&
+                Math.abs(previous.width - rect.width) < 0.5 &&
+                Math.abs(previous.height - rect.height) < 0.5
+                ? previous
+                : { width: rect.width, height: rect.height });
+            reportLaneSize(id, { width: rect.width, height: rect.height });
+        };
+        measure();
+        if (typeof ResizeObserver === "undefined")
+            return;
+        const observer = new ResizeObserver(measure);
+        observer.observe(element);
+        return () => observer.disconnect();
+    }, [laneActive, laneMounted, id, reportLaneSize]);
     const onPointerDown = (event) => {
         if (!draggable || event.button !== 0)
             return;
@@ -712,6 +898,31 @@ export function HudPanel({ id, anchor = "top-left", order, compact: compactMode
     if (!hudVisibleInPhase(showDuring, phase))
         return null;
     const authoredSize = sizeStyle(panel);
+    if (laneActive) {
+        if (laneRect === undefined || laneLayer === null)
+            return null;
+        const declaredWidth = panel.width ?? width;
+        const declaredHeight = panel.height ?? height;
+        const settled = laneSize !== null || declaredWidth !== undefined || declaredHeight !== undefined;
+        const chipped = compact && compactMode === "chip";
+        const passThrough = interactive === false && !editing && !chipped;
+        return createPortal(_jsxs("div", { ref: rootRef, "data-hud-panel": id, "data-hud-lane": lane, "data-dragging": dragging ? "" : undefined, "data-hud-priority": priority, "data-hud-mobile-behavior": mobileBehavior, "data-hud-type": panel.type ?? type, className: className, onPointerDown: onPointerDown, onClickCapture: onClickCapture, style: {
+                position: "absolute",
+                left: laneRect.x,
+                top: laneRect.y,
+                ...(declaredWidth === undefined ? {} : { width: declaredWidth }),
+                ...(declaredHeight === undefined ? {} : { height: declaredHeight }),
+                visibility: settled ? undefined : "hidden",
+                pointerEvents: passThrough ? "none" : "auto",
+                touchAction: draggable ? "none" : undefined,
+                userSelect: editing || dragging ? "none" : undefined,
+                cursor: dragging ? "grabbing" : editing ? "grab" : undefined,
+                outline: editing ? "1px dashed rgba(255, 255, 255, 0.6)" : undefined,
+                outlineOffset: editing ? 2 : undefined,
+                boxSizing: "border-box",
+                ...style,
+            }, children: [chipped ? (_jsx(HudChip, { label: chip ?? id, anchor: anchor, children: children })) : (children), editingChrome] }), laneLayer);
+    }
     const flow = compact || !panel.moved;
     if (flow) {
         const regionEl = regions[compact ? anchor : panel.placement.anchor];

package/dist/index.d.ts

@@ -67,6 +67,7 @@ export * from "./cards.js";
 export * from "./actionHud.js";
 export * from "./selectionHud.js";
 export * from "./hudLayout.js";
+export * from "./hudLanes.js";
 export * from "./hudLayoutPersist.js";
 export * from "./hudViewport.js";
 export * from "./gameViewport.js";

package/dist/index.js

@@ -67,6 +67,7 @@ export * from "./cards.js";
 export * from "./actionHud.js";
 export * from "./selectionHud.js";
 export * from "./hudLayout.js";
+export * from "./hudLanes.js";
 export * from "./hudLayoutPersist.js";
 export * from "./hudViewport.js";
 export * from "./gameViewport.js";

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/previewFixtures.js

@@ -1,5 +1,6 @@
 import { BarsPreview } from "./barsPreview.js";
 import { HudChromePreview } from "./hudChromePreview.js";
+import { HudLanesPreview } from "./hudLanesPreview.js";
 import { HudThemePreview } from "./hudThemePreview.js";
 import { IconsPreview } from "./iconsPreview.js";
 import { StreetGeometryPreview } from "./streetGeometryPreview.js";
@@ -20,6 +21,11 @@ import { ScrollRailPreview } from "./scrollRailPreview.js";
  * declares.
  */
 export const PREVIEW_FIXTURES = {
+    HudLanesPreview: {
+        name: "HudLanesPreview",
+        description: "Two HUD blocks stacked in one lane, a second lane beside it, and the mirrored right-hand lane.",
+        component: HudLanesPreview,
+    },
     ScrollRailPreview: { name: "ScrollRailPreview", description: "Reachable caller-owned settings categories in shared scrolling chrome.", component: ScrollRailPreview },
     HudChromePreview: {
         name: "HudChromePreview",

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. */