@jgengine/react 0.18.1 → 0.21.0

package/dist/hooks.js

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { AxisChannel } from "@jgengine/core/input/axisInput";
 import { createMarkerSet } from "@jgengine/core/world/markers";
+import { dispatchCommand } from "@jgengine/core/runtime/commandDispatch";
 import { browseSessions, } from "@jgengine/core/multiplayer/matchmaking";
 import { resolveActivePrompt, } from "@jgengine/core/interaction/proximityPrompt";
 import { gamePhase, setGamePhase } from "@jgengine/core/game/gamePhase";
@@ -21,9 +22,10 @@ export function useGameStore(selector, isEqual = Object.is) {
 export function useGameStoreValue(key, fallback) {
     return useGameStore((ctx) => ctx.game.store.get(key) ?? fallback);
 }
+/** UI command surface. Hosted commands return a promise; await it to display acknowledgement or rejection. Registration and runAs remain trusted local APIs. */
 export function useGame() {
     const ctx = useGameContext();
-    return useMemo(() => ({ commands: ctx.game.commands, events: ctx.game.events }), [ctx]);
+    return useMemo(() => ({ commands: { ...ctx.game.commands, run: (name, input) => dispatchCommand(ctx, name, input) }, events: ctx.game.events }), [ctx]);
 }
 export function usePlayer() {
     const ctx = useGameContext();
@@ -81,6 +83,11 @@ export function useNearestWorldItem(radius) {
 export function useEntityStat(instanceId, statId) {
     return useGameStore((ctx) => ctx.scene.entity.stats.get(instanceId, statId));
 }
+/**
+ * The entity `fromInstanceId` currently targets (set by `ctx.scene.entity.setTarget` or `cycleTarget`), for a target frame.
+ *
+ * @capability current-target read the player's selected target (click or tab target) to drive a target frame
+ */
 export function useTarget(fromInstanceId) {
     return useGameStore((ctx) => ctx.scene.entity.getTarget(fromInstanceId));
 }

package/dist/hudTheme.d.ts

@@ -110,7 +110,7 @@ export interface HudTheme {
     ring: string;
     skin?: HudSkin;
 }
-/** Emits the CSS custom properties for a theme — spread onto any HUD ancestor to re-skin the subtree. */
+/** Emits theme CSS properties, resetting inherited bar fills when absent. Spread onto a HUD ancestor. */
 export declare function hudThemeVars(theme: HudTheme): CSSProperties;
 /** Default theme tokens for previews/scaffold — not a finished game look; author a custom theme. */
 export declare const defaultHudTheme: HudTheme;

package/dist/hudTheme.js

@@ -1,7 +1,7 @@
 import {} from "react";
 import { hudSkinVars } from "./hudSkin.js";
 export { hudSkinVars } from "./hudSkin.js";
-/** Emits the CSS custom properties for a theme — spread onto any HUD ancestor to re-skin the subtree. */
+/** Emits theme CSS properties, resetting inherited bar fills when absent. Spread onto a HUD ancestor. */
 export function hudThemeVars(theme) {
     const { palette, surface, status, font, rarity, frame, bar, slot } = theme;
     return {
@@ -13,7 +13,8 @@ export function hudThemeVars(theme) {
         "--jg-slot-slice": "0",
         "--jg-slot-scale": "1",
         "--jg-bar-skin-track": "none",
-        "--jg-bar-skin-fill": "none",
+        // `initial` clears inherited skins and lets var() fall back to the bar's palette color.
+        "--jg-bar-skin-fill": "initial",
         "--jg-skin-cursor": "auto",
         ...hudSkinVars(theme.skin),
         // atomic-bar tokens (same names the bars read — #1033)

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export * from "./chatBubbles.js";
 export * from "./voice.js";
 export * from "./social.js";
 export * from "./hooks.js";
+export * from "./browserLifecycle.js";
 export * from "./useDebouncedCommit.js";
 export * from "./store.js";
 export * from "./settings.js";
@@ -72,3 +73,5 @@ export * from "./previewFixtures.js";
 export * from "./streetGeometryPreview.js";
 export * from "./saveSlots.js";
 export * from "./cameraShake.js";
+export * from "./dialogBehavior.js";
+export * from "./scrollRail.js";

package/dist/index.js

@@ -5,6 +5,7 @@ export * from "./chatBubbles.js";
 export * from "./voice.js";
 export * from "./social.js";
 export * from "./hooks.js";
+export * from "./browserLifecycle.js";
 export * from "./useDebouncedCommit.js";
 export * from "./store.js";
 export * from "./settings.js";
@@ -72,3 +73,5 @@ export * from "./previewFixtures.js";
 export * from "./streetGeometryPreview.js";
 export * from "./saveSlots.js";
 export * from "./cameraShake.js";
+export * from "./dialogBehavior.js";
+export * from "./scrollRail.js";

package/dist/map.js

@@ -1,5 +1,5 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { DEFAULT_MARKER_KINDS, markerKindStyle, } from "@jgengine/core/world/markers";
 import { bearingToCardinal, clampToMinimapEdge, compassBearing, headingToBearing, projectToMinimap, relativeBearing, unprojectFromMinimap, } from "@jgengine/core/world/minimap";
 import { mapLayerColor, } from "@jgengine/core/world/mapLayers";
@@ -457,6 +457,15 @@ export function WorldMap({ markers, bounds, player, facingYaw = 0, fog, backgrou
 function clampScale(value, min, max) {
     return Math.max(min, Math.min(max, value));
 }
+function mapControlEvent(event) {
+    for (const target of event.nativeEvent.composedPath()) {
+        if (target === event.currentTarget)
+            break;
+        if (target instanceof Element && target.matches('button, a[href], input, textarea, select, label, [role="button"], [role="link"], [role="slider"], [role="switch"], [role="checkbox"], [contenteditable]:not([contenteditable=false])'))
+            return true;
+    }
+    return false;
+}
 /**
  * Fullscreen pan/zoom world-map overlay — the enlarged "press M" map. Wheel to
  * zoom (toward the cursor), drag to pan, and click to place (wire `onWorldClick`
@@ -477,8 +486,28 @@ export function FullscreenMap({ open = true, bounds, contentWidth = 900, minScal
     const moved = useRef(false);
     const draftRef = useRef(null);
     const [draft, setDraft] = useState(null);
+    const [panning, setPanning] = useState(false);
+    const ownerRef = useRef(null);
+    const gestureRef = useRef(null);
     const drawing = tool === "draw";
     const minSpacing = (worldW + worldD) / 400;
+    const retireGesture = (notify = true) => {
+        const owner = ownerRef.current;
+        ownerRef.current = null;
+        owner?.detach();
+        drag.current = null;
+        draftRef.current = null;
+        if (notify) {
+            setDraft(null);
+            setPanning(false);
+        }
+        if (owner?.source.hasPointerCapture(owner.pointerId))
+            owner.source.releasePointerCapture(owner.pointerId);
+    };
+    const cancelGesture = () => { if (ownerRef.current !== null)
+        moved.current = true; retireGesture(); };
+    useEffect(() => { cancelGesture(); }, [open, tool]);
+    useEffect(() => () => retireGesture(false), []);
     if (!open)
         return null;
     const zoomBy = (factor, sx, sy) => {
@@ -508,12 +537,43 @@ export function FullscreenMap({ open = true, bounds, contentWidth = 900, minScal
         draftRef.current = [...points, point];
         setDraft(draftRef.current);
     };
-    const commitDraft = () => {
-        const points = draftRef.current;
-        draftRef.current = null;
-        setDraft(null);
-        if (points !== null && points.length >= 2)
-            onStrokeComplete?.(points);
+    gestureRef.current = {
+        move: (event) => {
+            const owner = ownerRef.current;
+            if (owner === null || event.pointerId !== owner.pointerId)
+                return;
+            if (!owner.source.isConnected) {
+                cancelGesture();
+                return;
+            }
+            if (owner.tool === "draw") {
+                if (draftRef.current !== null)
+                    pushDraftPoint(screenToWorld({ currentTarget: owner.source, clientX: event.clientX, clientY: event.clientY }));
+                return;
+            }
+            const state = drag.current;
+            if (state === null)
+                return;
+            const rect = owner.source.getBoundingClientRect();
+            const dx = (event.clientX - state.x) * contentWidth / rect.width;
+            const dy = (event.clientY - state.y) * contentHeight / rect.height;
+            if (Math.abs(dx) + Math.abs(dy) > 3)
+                moved.current = true;
+            setViewport({ scale: state.vp.scale, tx: state.vp.tx + dx, ty: state.vp.ty + dy });
+        },
+        finish: (event) => {
+            const owner = ownerRef.current;
+            if (owner === null || event.pointerId !== owner.pointerId)
+                return;
+            if (!owner.source.isConnected) {
+                cancelGesture();
+                return;
+            }
+            const points = owner.tool === "draw" ? draftRef.current : null;
+            retireGesture();
+            if (points !== null && points.length >= 2)
+                onStrokeComplete?.(points);
+        },
     };
     const draftRoute = draft !== null && draft.length >= 2 ? { id: "__draft-stroke", points: draft, tone: drawTone, width: drawWidth } : null;
     const forwardedRoutes = draftRoute === null ? surfaceProps.routes : [...(surfaceProps.routes ?? []), draftRoute];
@@ -551,55 +611,59 @@ export function FullscreenMap({ open = true, bounds, contentWidth = 900, minScal
                     minHeight: 0,
                     overflow: "hidden",
                     touchAction: "none",
-                    cursor: drawing ? "crosshair" : drag.current !== null ? "grabbing" : "grab",
+                    cursor: drawing ? "crosshair" : panning ? "grabbing" : "grab",
                 }, onWheel: (event) => {
                     const at = canvasPoint(event);
                     zoomBy(event.deltaY < 0 ? 1.15 : 1 / 1.15, at.x, at.y);
                 }, onPointerDown: (event) => {
-                    if (event.button !== 0)
+                    if (event.button !== 0 || !event.isPrimary || ownerRef.current !== null || mapControlEvent(event))
                         return;
-                    event.currentTarget.setPointerCapture(event.pointerId);
-                    if (drawing) {
-                        draftRef.current = [screenToWorld(event)];
-                        setDraft(draftRef.current);
+                    const source = event.currentTarget;
+                    const view = source.ownerDocument.defaultView;
+                    if (view === null)
                         return;
+                    const onMove = (move) => gestureRef.current?.move(move);
+                    const onUp = (up) => { if (up.button === 0)
+                        gestureRef.current?.finish({ pointerId: event.pointerId }); };
+                    const onCancel = (cancel) => { if (cancel.pointerId === ownerRef.current?.pointerId)
+                        cancelGesture(); };
+                    const mouse = event.pointerType === "mouse";
+                    ownerRef.current = { pointerId: event.pointerId, pointerType: event.pointerType, source, tool, detach: () => {
+                            if (!mouse)
+                                return;
+                            view.removeEventListener("pointermove", onMove);
+                            view.removeEventListener("mouseup", onUp);
+                            view.removeEventListener("pointercancel", onCancel);
+                        } };
+                    if (mouse) {
+                        // Mouse capture can be dropped on an auxiliary release while the primary button is still held.
+                        view.addEventListener("pointermove", onMove);
+                        view.addEventListener("mouseup", onUp);
+                        view.addEventListener("pointercancel", onCancel);
                     }
-                    drag.current = { x: event.clientX, y: event.clientY, vp: viewport };
+                    else
+                        source.setPointerCapture(event.pointerId);
                     moved.current = false;
-                }, onPointerMove: (event) => {
                     if (drawing) {
-                        if (draftRef.current !== null)
-                            pushDraftPoint(screenToWorld(event));
+                        draftRef.current = [screenToWorld(event)];
+                        setDraft(draftRef.current);
                         return;
                     }
-                    const state = drag.current;
-                    if (state === null)
+                    drag.current = { x: event.clientX, y: event.clientY, vp: viewport };
+                    setPanning(true);
+                }, onPointerMove: (event) => { if (ownerRef.current?.pointerType !== "mouse")
+                    gestureRef.current?.move(event); }, onPointerUp: (event) => { if (ownerRef.current?.pointerType !== "mouse")
+                    gestureRef.current?.finish(event); }, onPointerCancel: (event) => { if (event.pointerId === ownerRef.current?.pointerId)
+                    cancelGesture(); }, onLostPointerCapture: (event) => { if (event.pointerId === ownerRef.current?.pointerId)
+                    cancelGesture(); }, onClick: (event) => {
+                    if (ownerRef.current !== null || onWorldClick === undefined || drawing || mapControlEvent(event))
                         return;
-                    const rect = event.currentTarget.getBoundingClientRect();
-                    const kx = contentWidth / rect.width;
-                    const ky = contentHeight / rect.height;
-                    const dx = (event.clientX - state.x) * kx;
-                    const dy = (event.clientY - state.y) * ky;
-                    if (Math.abs(dx) + Math.abs(dy) > 3)
-                        moved.current = true;
-                    setViewport({ scale: state.vp.scale, tx: state.vp.tx + dx, ty: state.vp.ty + dy });
-                }, onPointerUp: (event) => {
-                    if (event.currentTarget.hasPointerCapture(event.pointerId))
-                        event.currentTarget.releasePointerCapture(event.pointerId);
-                    if (drawing) {
-                        commitDraft();
+                    if (moved.current) {
+                        moved.current = false;
                         return;
                     }
-                    drag.current = null;
-                }, children: [_jsx(WorldMapSurface, { ...surfaceProps, routes: forwardedRoutes, bounds: bounds, width: contentWidth, height: contentHeight, canvasWidth: contentWidth, canvasHeight: contentHeight, viewport: viewport, style: { width: "100%", height: "100%", borderRadius: 0, display: "block" }, onWorldClick: onWorldClick === undefined || drawing
-                            ? undefined
-                            : (world) => {
-                                if (moved.current) {
-                                    moved.current = false;
-                                    return;
-                                }
-                                onWorldClick(world);
-                            } }), children] })] }));
+                    onWorldClick(screenToWorld(event));
+                }, children: [_jsx(WorldMapSurface, { ...surfaceProps, routes: forwardedRoutes, bounds: bounds, width: contentWidth, height: contentHeight, canvasWidth: contentWidth, canvasHeight: contentHeight, viewport: viewport, style: { width: "100%", height: "100%", borderRadius: 0, display: "block", ...(onWorldClick === undefined || drawing ? {} : { cursor: "crosshair" }) } }), children] })] }));
 }
 /**
  * Marker-kind key for a map/minimap — glyph + color swatch per kind, labelled.

package/dist/modals.js

@@ -1,7 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, useEffect, useReducer, useRef, } from "react";
+import { useCallback, useEffect, useReducer, } from "react";
 import { MODAL_CANCEL, MODAL_CONFIRM, } from "@jgengine/core/ui/modalStack";
 import { HudFrame } from "./hudFrame.js";
+import { useDialogBehavior } from "./dialogBehavior.js";
 /**
  * Subscribe to a modal stack and re-render on every change, returning the active modal and depth.
  *
@@ -12,11 +13,6 @@ export function useModalStack(stack) {
     useEffect(() => stack.subscribe(bump), [stack]);
     return { top: stack.top(), depth: stack.depth() };
 }
-/** @internal Focusable descendants of `root`, in DOM order, skipping disabled/hidden ones. */
-function focusableWithin(root) {
-    const selector = 'a[href],button:not([disabled]),textarea:not([disabled]),input:not([disabled]),select:not([disabled]),[tabindex]:not([tabindex="-1"])';
-    return Array.from(root.querySelectorAll(selector)).filter((el) => el.offsetParent !== null || el === document.activeElement);
-}
 /**
  * Full-screen modal host: watches a stack, renders only the topmost modal centered over a dimmed
  * backdrop, and manages accessibility — the panel is a `role="dialog" aria-modal`, focus moves into
@@ -28,60 +24,20 @@ function focusableWithin(root) {
  */
 export function ModalHost({ stack, children, showBackdrop = true, backdrop, closeOnBackdrop = true, closeOnEsc = true, zIndexBase = 80, className, style, }) {
     const { top } = useModalStack(stack);
-    const panelRef = useRef(null);
-    const restoreRef = useRef(null);
-    const stepId = top?.id ?? null;
     const controls = {
         resolve: useCallback((result, payload) => stack.resolve(result, payload !== undefined ? { payload } : undefined), [stack]),
         confirm: useCallback((payload) => stack.resolve(MODAL_CONFIRM, payload !== undefined ? { payload } : undefined), [stack]),
         cancel: useCallback(() => stack.resolve(MODAL_CANCEL), [stack]),
     };
-    // Move focus into the dialog on open; restore it on close.
-    useEffect(() => {
-        if (stepId === null || typeof document === "undefined")
-            return undefined;
-        restoreRef.current = document.activeElement;
-        const panel = panelRef.current;
-        if (panel !== null) {
-            const first = focusableWithin(panel)[0] ?? panel;
-            first.focus();
-        }
-        return () => {
-            restoreRef.current?.focus?.();
-        };
-    }, [stepId]);
+    const panelRef = useDialogBehavior({
+        open: top !== null,
+        focusKey: top?.id,
+        onClose: closeOnEsc ? controls.cancel : undefined,
+    });
     if (top === null)
         return null;
     const dim = backdrop ?? "var(--jg-backdrop, rgba(4,7,12,0.62))";
-    const onKeyDown = (event) => {
-        if (closeOnEsc && event.key === "Escape") {
-            event.stopPropagation();
-            controls.cancel();
-            return;
-        }
-        if (event.key !== "Tab")
-            return;
-        const panel = panelRef.current;
-        if (panel === null)
-            return;
-        const focusable = focusableWithin(panel);
-        if (focusable.length === 0) {
-            event.preventDefault();
-            return;
-        }
-        const first = focusable[0];
-        const last = focusable[focusable.length - 1];
-        const active = document.activeElement;
-        if (event.shiftKey && active === first) {
-            event.preventDefault();
-            last.focus();
-        }
-        else if (!event.shiftKey && active === last) {
-            event.preventDefault();
-            first.focus();
-        }
-    };
-    return (_jsxs("div", { "data-modal-host": "", className: className, onKeyDown: onKeyDown, style: {
+    return (_jsxs("div", { "data-modal-host": "", className: className, style: {
             position: "fixed",
             inset: 0,
             zIndex: zIndexBase,

package/dist/panels.js

@@ -2,6 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useRef, useState, } from "react";
 import { closePanel, closeTopPanel, createPanelState, focusPanel, isOpen as isPanelOpen, movePanel, openPanel, orderedOpen, panelByHotkey, } from "@jgengine/core/ui/panelModel";
 import { HudFrame } from "./hudFrame.js";
+import { observeBrowserSuspension } from "./browserLifecycle.js";
 /**
  * Pure keybind resolver for a panel set: ESC resolves to `closeTop` when a closable window is open, and
  * any other key routes through {@link panelByHotkey} (trying `code` then `key`) to a `toggle`. Returns
@@ -116,24 +117,51 @@ function topClosableOpen(state) {
     return null;
 }
 // ---- Window chrome ---------------------------------------------------------
-/** @internal Begin a pointer drag from the title bar, streaming new positions to `onMove` until release. */
-function beginWindowDrag(event, origin, onMove) {
-    if (typeof window === "undefined")
-        return;
+/** @internal Own a title-bar pointer until release or interruption, streaming positions to `onMove`. */
+function beginWindowDrag(event, origin, onMove, onRetire) {
+    const source = event.currentTarget;
+    const view = source.ownerDocument.defaultView;
+    if (view === null)
+        return null;
+    const pointerId = event.pointerId;
     const startX = event.clientX;
     const startY = event.clientY;
     const base = { x: origin.x, y: origin.y };
+    let active = true;
+    const retire = () => {
+        if (!active)
+            return;
+        active = false;
+        view.removeEventListener("pointermove", onPointerMove);
+        view.removeEventListener("pointerup", onEnd);
+        view.removeEventListener("pointercancel", onEnd);
+        detachSuspension();
+        source.removeEventListener("lostpointercapture", onEnd);
+        onRetire();
+        if (source.hasPointerCapture(pointerId))
+            source.releasePointerCapture(pointerId);
+    };
     const onPointerMove = (moveEvent) => {
+        if (moveEvent.pointerId !== pointerId)
+            return;
+        if (!source.isConnected) {
+            retire();
+            return;
+        }
         onMove({ x: base.x + (moveEvent.clientX - startX), y: base.y + (moveEvent.clientY - startY) });
     };
-    const onPointerUp = () => {
-        window.removeEventListener("pointermove", onPointerMove);
-        window.removeEventListener("pointerup", onPointerUp);
-        window.removeEventListener("pointercancel", onPointerUp);
+    const onEnd = (endEvent) => {
+        if (endEvent.pointerId !== pointerId || (endEvent.type === "pointerup" && endEvent.button !== 0))
+            return;
+        retire();
     };
-    window.addEventListener("pointermove", onPointerMove);
-    window.addEventListener("pointerup", onPointerUp);
-    window.addEventListener("pointercancel", onPointerUp);
+    view.addEventListener("pointermove", onPointerMove);
+    view.addEventListener("pointerup", onEnd);
+    view.addEventListener("pointercancel", onEnd);
+    const detachSuspension = observeBrowserSuspension(retire, { hidden: false, pointerLockLost: false }, { window: view, document: source.ownerDocument });
+    source.addEventListener("lostpointercapture", onEnd);
+    source.setPointerCapture(pointerId);
+    return retire;
 }
 const TITLEBAR_STYLE = {
     display: "flex",
@@ -167,12 +195,15 @@ const CLOSE_BUTTON_STYLE = {
 };
 /** @internal Shared, fully-controlled window view — title bar (drag + close) plus a HudFrame body. */
 function WindowView({ title, ariaLabel, closable, onClose, onFocus, onMove, pos, z, width, variation, shape, className, style, bodyStyle, children, }) {
+    const retireDrag = useRef(null);
+    useEffect(() => () => retireDrag.current?.(), []);
     return (_jsx("div", { role: "dialog", "aria-label": ariaLabel, "data-jg-window": "", className: className, onPointerDown: () => onFocus?.(), style: { position: "absolute", left: pos.x, top: pos.y, zIndex: z, pointerEvents: "auto", ...style }, children: _jsxs(HudFrame, { variation: variation, shape: shape, width: width, padding: 0, interactive: true, children: [_jsxs("div", { "data-jg-window-titlebar": "", onPointerDown: (event) => {
-                        if (event.button !== 0)
+                        if (event.button !== 0 || !event.isPrimary || retireDrag.current !== null)
                             return;
                         onFocus?.();
-                        if (onMove !== undefined)
-                            beginWindowDrag(event, pos, onMove);
+                        if (onMove !== undefined) {
+                            retireDrag.current = beginWindowDrag(event, pos, onMove, () => { retireDrag.current = null; });
+                        }
                     }, style: TITLEBAR_STYLE, children: [_jsx("span", { "data-jg-window-title": "", children: title }), closable ? (_jsx("button", { type: "button", "data-jg-window-close": "", "aria-label": "Close", onClick: onClose, onPointerDown: (event) => event.stopPropagation(), style: CLOSE_BUTTON_STYLE, children: "\u2715" })) : null] }), _jsx("div", { "data-jg-window-body": "", style: { padding: 10, ...bodyStyle }, children: children })] }) }));
 }
 /** @internal Fallback cascade position for a window whose state has no override yet. */

package/dist/previewFixtures.js

@@ -5,6 +5,7 @@ import { StreetGeometryPreview } from "./streetGeometryPreview.js";
 import { SpriteClipPreview } from "./spriteClipPreview.js";
 import { TileLayerPreview } from "./tileLayerPreview.js";
 import { HudSkinPreview } from "./hudSkinPreview.js";
+import { ScrollRailPreview } from "./scrollRailPreview.js";
 /**
  * Registry of deterministic, engine-level preview fixtures — the *real* exported
  * `@jgengine/react` components (`HudThemePreview`, `BarsPreview`, `IconsPreview`, …) that render
@@ -18,6 +19,7 @@ import { HudSkinPreview } from "./hudSkinPreview.js";
  * declares.
  */
 export const PREVIEW_FIXTURES = {
+    ScrollRailPreview: { name: "ScrollRailPreview", description: "Reachable caller-owned settings categories in shared scrolling chrome.", component: ScrollRailPreview },
     HudThemePreview: {
         name: "HudThemePreview",
         description: "Every HudTheme genre preset × atomic bars + a themed frame + a slot row.",
@@ -25,7 +27,7 @@ export const PREVIEW_FIXTURES = {
     },
     BarsPreview: {
         name: "BarsPreview",
-        description: "Every atomic vitals bar rendered twice under different BarTokens blocks.",
+        description: "Atomic vitals under BarTokens blocks, explicit fills, skins, and nested theme resets.",
         component: BarsPreview,
     },
     IconsPreview: {

package/dist/scrollRail.d.ts

@@ -0,0 +1,18 @@
+import { type CSSProperties, type ReactNode } from "react";
+/** Props for caller-composed horizontally scrolling controls. */
+export interface ScrollRailProps {
+    children: ReactNode;
+    /** Accessible name for the rail and its overflow navigation. */
+    label: string;
+    className?: string;
+    style?: CSSProperties;
+    /** Spacing between caller-owned items. Default 6 pixels. */
+    gap?: number;
+}
+/**
+ * Native horizontal scrolling with overflow-only navigation and automatic focus reveal.
+ * Callers own item markup, selection, keyboard semantics, and skin through HudTheme or style.
+ *
+ * @capability scroll-rail reachable horizontal controls with visible overflow navigation and keyboard focus reveal
+ */
+export declare function ScrollRail({ children, label, className, style, gap }: ScrollRailProps): import("react").JSX.Element;

package/dist/scrollRail.js

@@ -0,0 +1,55 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useId, useRef, useState } from "react";
+/**
+ * Native horizontal scrolling with overflow-only navigation and automatic focus reveal.
+ * Callers own item markup, selection, keyboard semantics, and skin through HudTheme or style.
+ *
+ * @capability scroll-rail reachable horizontal controls with visible overflow navigation and keyboard focus reveal
+ */
+export function ScrollRail({ children, label, className, style, gap = 6 }) {
+    const id = useId();
+    const ref = useRef(null);
+    const [edges, setEdges] = useState({ start: true, end: true });
+    const measure = () => {
+        const rail = ref.current;
+        if (rail === null)
+            return;
+        const next = { start: rail.scrollLeft <= 1, end: rail.scrollWidth - rail.clientWidth - rail.scrollLeft <= 1 };
+        setEdges(current => current.start === next.start && current.end === next.end ? current : next);
+    };
+    useEffect(() => {
+        const rail = ref.current;
+        if (rail === null)
+            return;
+        const observer = new ResizeObserver(measure);
+        observer.observe(rail);
+        for (const child of rail.children)
+            observer.observe(child);
+        measure();
+        return () => observer.disconnect();
+    }, [children]);
+    const scroll = (direction) => {
+        const rail = ref.current;
+        if (rail === null)
+            return;
+        rail.scrollBy({ left: direction * Math.max(44, rail.clientWidth * 0.8), behavior: "instant" });
+        measure();
+    };
+    const overflow = !edges.start || !edges.end;
+    const buttonStyle = {
+        flex: "0 0 44px", minHeight: 44, border: "1px solid var(--jg-edge, #454550)",
+        borderRadius: "var(--jg-slot-radius, 6px)", background: "var(--jg-surface-deep, #15151d)",
+        color: "var(--jg-text, #ececef)", font: "inherit", cursor: "pointer",
+    };
+    return _jsxs("div", { className: className, "data-scroll-rail": "", style: { display: "flex", minWidth: 0, flexShrink: 0, gap, ...style }, children: [overflow && _jsx("button", { type: "button", "aria-label": `Show earlier ${label}`, "aria-controls": id, disabled: edges.start, onClick: () => scroll(-1), style: { ...buttonStyle, opacity: edges.start ? 0.45 : 1 }, children: "\u2190" }), _jsx("div", { ref: ref, id: id, role: "group", "aria-label": label, onScroll: measure, onFocusCapture: event => {
+                    const rail = ref.current;
+                    if (rail === null || event.target === rail)
+                        return;
+                    const bounds = rail.getBoundingClientRect(), target = event.target.getBoundingClientRect();
+                    if (target.left < bounds.left)
+                        rail.scrollLeft += target.left - bounds.left;
+                    else if (target.right > bounds.right)
+                        rail.scrollLeft += target.right - bounds.right;
+                    measure();
+                }, style: { display: "flex", flex: "1 1 auto", minWidth: 0, overflowX: "auto", gap }, children: children }), overflow && _jsx("button", { type: "button", "aria-label": `Show later ${label}`, "aria-controls": id, disabled: edges.end, onClick: () => scroll(1), style: { ...buttonStyle, opacity: edges.end ? 0.45 : 1 }, children: "\u2192" })] });
+}

package/dist/scrollRailPreview.d.ts

@@ -0,0 +1,4 @@
+/** Deterministic preview of caller-owned controls in the shared scrolling chrome. @internal */
+export declare function ScrollRailPreview({ className }: {
+    className?: string;
+}): import("react").JSX.Element;

package/dist/scrollRailPreview.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { ScrollRail } from "./scrollRail.js";
+/** Deterministic preview of caller-owned controls in the shared scrolling chrome. @internal */
+export function ScrollRailPreview({ className }) {
+    const [selected, setSelected] = useState("Game");
+    return _jsxs("div", { className: className, style: { padding: 24, boxSizing: "border-box", background: "#18252b", color: "#f2e6c9", font: "16px system-ui" }, children: [_jsx("h1", { style: { fontSize: 20 }, children: "Scrolling controls" }), _jsx("div", { style: { width: "min(100%, 340px)" }, children: _jsx(ScrollRail, { label: "settings categories", children: ["Game", "Graphics", "Audio", "Accessibility", "Controls"].map(label => _jsx("button", { type: "button", onClick: () => setSelected(label), "aria-pressed": selected === label, style: { flexShrink: 0, minHeight: 44, padding: "0 16px", font: "inherit", color: "inherit", border: "1px solid #b2a27e", borderRadius: 2, background: selected === label ? "#526951" : "#20363c" }, children: label }, label)) }) }), _jsxs("p", { "aria-live": "polite", children: ["Selected: ", selected] })] });
+}

package/dist/useServerSession.d.ts

@@ -1,4 +1,4 @@
-import type { GameRuntimeTransport } from "@jgengine/core/runtime/transport";
+import { type GameRuntimeTransport } from "@jgengine/core/runtime/transport";
 /**
  * Joins a host and exposes a retryable blocking state until membership is confirmed.
  * @capability server-session join a multiplayer host with status, retry, and teardown

package/dist/useServerSession.js

@@ -1,4 +1,5 @@
 import { useCallback, useEffect, useState } from "react";
+import { createTransportSessionId } from "@jgengine/core/runtime/transport";
 /**
  * Joins a host and exposes a retryable blocking state until membership is confirmed.
  * @capability server-session join a multiplayer host with status, retry, and teardown
@@ -10,15 +11,16 @@ export function useServerSession(transport, gameId, preferredServerId) {
     useEffect(() => {
         let disposed = false;
         let serverId = null;
+        const sessionId = createTransportSessionId();
         setSession({ serverId: null, status: "joining", failureReason: null });
-        void transport.joinServer({ gameId, serverId: preferredServerId }).then((result) => {
+        void transport.joinServer({ gameId, serverId: preferredServerId, sessionId }).then((result) => {
             if (!result.ok) {
                 if (!disposed)
                     setSession({ serverId: null, status: "failed", failureReason: result.reason });
                 return;
             }
             if (disposed) {
-                void transport.leaveServer({ serverId: result.serverId }).catch(() => undefined);
+                void transport.leaveServer({ serverId: result.serverId, sessionId }).catch(() => undefined);
                 return;
             }
             serverId = result.serverId;
@@ -30,7 +32,7 @@ export function useServerSession(transport, gameId, preferredServerId) {
         return () => {
             disposed = true;
             if (serverId !== null)
-                void transport.leaveServer({ serverId }).catch(() => undefined);
+                void transport.leaveServer({ serverId, sessionId }).catch(() => undefined);
         };
     }, [transport, gameId, preferredServerId, attempt]);
     return { ...session, retry };