@jgengine/react 0.19.0 → 0.21.0

package/dist/dialogBehavior.js

@@ -0,0 +1,109 @@
+import { useEffect, useRef } from "react";
+const owners = new WeakMap();
+function focusableWithin(root) {
+    return Array.from(root.querySelectorAll('a[href],button,textarea,input,select,[tabindex]')).filter((element) => {
+        if (element.tabIndex < 0 || element.matches(":disabled") || element.closest("[hidden],[inert]"))
+            return false;
+        const style = element.ownerDocument.defaultView?.getComputedStyle(element);
+        return style?.visibility !== "hidden" && style?.visibility !== "collapse" && element.getClientRects().length > 0;
+    });
+}
+function focusInitial(root, options) {
+    const controls = focusableWithin(root);
+    const preferred = options.initialFocus === "root" ? root : options.initialFocus?.();
+    (preferred !== null && preferred !== undefined && (preferred === root || controls.includes(preferred))
+        ? preferred : controls[0] ?? root).focus();
+}
+/**
+ * Focus entry, Tab trapping, Escape requests, and focus restoration for a caller-owned dialog.
+ * Attach the returned ref to the dialog root and supply `role="dialog"`, `aria-modal`, an accessible
+ * name, and `tabIndex={-1}`. The most recently opened dialog handles keys, including portal roots.
+ * Closing an inner dialog restores its opener; cleanup never steals focus from another active dialog.
+ * Replacing the root while open keeps its position and original return target.
+ *
+ * @capability dialog-behavior controlled dialog focus and keyboard behavior without owning markup or screen state
+ */
+export function useDialogBehavior(options) {
+    const ref = useRef(null);
+    const activeOwner = useRef(null);
+    const latest = useRef(options);
+    latest.current = options;
+    useEffect(() => {
+        const root = ref.current;
+        if (!options.open || root === null)
+            return;
+        const document = root.ownerDocument;
+        const stack = owners.get(document) ?? [];
+        owners.set(document, stack);
+        const owner = { root, restore: document.activeElement };
+        activeOwner.current = owner;
+        const child = stack.findIndex((entry) => root.contains(entry.root));
+        if (child < 0)
+            stack.push(owner);
+        else
+            stack.splice(child, 0, owner);
+        const keydown = (event) => {
+            if (stack.at(-1) !== owner || event.defaultPrevented)
+                return;
+            if (event.key === "Escape" && latest.current.onClose !== undefined) {
+                event.preventDefault();
+                event.stopPropagation();
+                latest.current.onClose();
+                return;
+            }
+            if (event.key !== "Tab")
+                return;
+            const root = owner.root;
+            const controls = focusableWithin(root);
+            const first = controls[0], last = controls.at(-1);
+            const active = document.activeElement;
+            if (first === undefined || !root.contains(active) || active === root ||
+                (event.shiftKey ? active === first : active === last)) {
+                event.preventDefault();
+                event.stopPropagation();
+                (event.shiftKey ? last : first)?.focus();
+                if (first === undefined)
+                    root.focus();
+            }
+        };
+        document.addEventListener("keydown", keydown, true);
+        return () => {
+            document.removeEventListener("keydown", keydown, true);
+            const wasTop = stack.at(-1) === owner;
+            const index = stack.indexOf(owner);
+            if (index >= 0)
+                stack.splice(index, 1);
+            for (const entry of stack) {
+                if (entry.restore !== null && owner.root.contains(entry.restore))
+                    entry.restore = owner.restore;
+            }
+            if (wasTop && owner.restore?.isConnected && !owner.restore.closest("[hidden],[inert]")) {
+                owner.restore.focus();
+            }
+            if (stack.length === 0)
+                owners.delete(document);
+            activeOwner.current = null;
+        };
+    }, [options.open]);
+    useEffect(() => {
+        const root = ref.current;
+        const owner = activeOwner.current;
+        if (!options.open || root === null || owner === null || owner.root === root)
+            return;
+        const stack = owners.get(owner.root.ownerDocument);
+        for (const entry of stack ?? []) {
+            if (entry !== owner && entry.restore !== null && owner.root.contains(entry.restore))
+                entry.restore = root;
+        }
+        owner.root = root;
+        if (stack?.at(-1) === owner)
+            focusInitial(root, latest.current);
+    });
+    useEffect(() => {
+        const root = ref.current;
+        if (!options.open || root === null || owners.get(root.ownerDocument)?.at(-1)?.root !== root)
+            return;
+        focusInitial(root, latest.current);
+    }, [options.open, options.focusKey]);
+    return ref;
+}

package/dist/dragLayer.d.ts

@@ -45,6 +45,13 @@ export interface DragLayer<T> {
     cancel(): void;
     attachGhost(element: HTMLElement | null): void;
 }
+/**
+ * Pointer-owned drag state shared by cards and inventory grids. Registered DropZones are hit-tested
+ * through pointer capture; release finishes once, while cancellation, blur and unmount release ownership.
+ * Callers own drop policy, rotation and presentation; pointer movement paints the ghost without rerendering it.
+ *
+ * @capability drag-layer composable pointer-owned drag, drop targets and cancellation for custom cards and inventory UI
+ */
 export declare function useDragLayer<T>(options?: {
     onDrop?: (info: DropInfo<T>) => void;
 }): DragLayer<T>;

package/dist/dragLayer.js

@@ -2,25 +2,41 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState, } from "react";
 import { cellFromPoint, } from "@jgengine/core/inventory/shapedGrid";
 const EMPTY_POINT = { x: 0, y: 0 };
+const targetRegistries = new WeakMap();
+/**
+ * Pointer-owned drag state shared by cards and inventory grids. Registered DropZones are hit-tested
+ * through pointer capture; release finishes once, while cancellation, blur and unmount release ownership.
+ * Callers own drop policy, rotation and presentation; pointer movement paints the ghost without rerendering it.
+ *
+ * @capability drag-layer composable pointer-owned drag, drop targets and cancellation for custom cards and inventory UI
+ */
 export function useDragLayer(options) {
     const [state, setState] = useState({
-        payload: null,
-        point: EMPTY_POINT,
-        origin: EMPTY_POINT,
-        overTarget: null,
-        overCell: null,
+        payload: null, point: EMPTY_POINT, origin: EMPTY_POINT, overTarget: null, overCell: null,
     });
     const pointRef = useRef(EMPTY_POINT);
     const ghostRef = useRef(null);
-    const moveRef = useRef(null);
     const payloadRef = useRef(null);
     const overRef = useRef({ target: null, cell: null });
+    const overElement = useRef(null);
+    const targets = useRef(new Map());
+    const ownerRef = useRef(null);
+    const latest = useRef(options);
+    latest.current = options;
     const detach = useCallback(() => {
-        if (moveRef.current !== null) {
-            window.removeEventListener("pointermove", moveRef.current);
-            moveRef.current = null;
-        }
+        const owner = ownerRef.current;
+        ownerRef.current = null;
+        if (owner === null)
+            return;
+        owner.detach();
+        if (owner.source.hasPointerCapture(owner.pointerId))
+            owner.source.releasePointerCapture(owner.pointerId);
     }, []);
+    useEffect(() => () => {
+        detach();
+        payloadRef.current = null;
+        ghostRef.current = null;
+    }, [detach]);
     const writeGhost = useCallback((point, rotation) => {
         const el = ghostRef.current;
         if (el === null)
@@ -29,91 +45,139 @@ export function useDragLayer(options) {
         el.style.top = `${point.y}px`;
         el.style.transform = `translate(-50%, -50%) rotate(${rotation * 90}deg)`;
     }, []);
-    const beginDrag = useCallback((payload, event) => {
-        const point = { x: event.clientX, y: event.clientY };
-        const nextPayload = { id: payload.id, value: payload.value, rotation: payload.rotation ?? 0 };
-        payloadRef.current = nextPayload;
-        overRef.current = { target: null, cell: null };
-        pointRef.current = point;
-        setState({
-            payload: nextPayload,
-            point,
-            origin: point,
-            overTarget: null,
-            overCell: null,
-        });
-        writeGhost(point, nextPayload.rotation);
-        const onMove = (moveEvent) => {
-            if (payloadRef.current === null)
-                return;
-            const next = { x: moveEvent.clientX, y: moveEvent.clientY };
-            pointRef.current = next;
-            writeGhost(next, payloadRef.current.rotation);
-        };
-        detach();
-        moveRef.current = onMove;
-        window.addEventListener("pointermove", onMove);
-    }, [detach, writeGhost]);
-    const rotate = useCallback((quarterTurns = 1) => {
-        setState((prev) => {
-            if (prev.payload === null)
-                return prev;
-            const rotation = (((prev.payload.rotation + quarterTurns) % 4) + 4) % 4;
-            const payload = { ...prev.payload, rotation };
-            payloadRef.current = payload;
-            writeGhost(pointRef.current, rotation);
-            return { ...prev, payload, point: pointRef.current };
-        });
-    }, [writeGhost]);
     const setTarget = useCallback((target, cell = null) => {
+        const previous = overRef.current;
+        if (previous.target === target && previous.cell?.[0] === cell?.[0] && previous.cell?.[1] === cell?.[1])
+            return;
         overRef.current = { target, cell };
         setState((prev) => ({ ...prev, overTarget: target, overCell: cell, point: pointRef.current }));
     }, []);
+    const resolveTarget = useCallback((document, point) => {
+        if (targets.current.size === 0)
+            return;
+        let element = document.elementFromPoint(point.x, point.y);
+        while (element !== null) {
+            const target = targets.current.get(element);
+            if (target !== undefined) {
+                overElement.current = element;
+                const rect = element.getBoundingClientRect();
+                setTarget(target.id, target.cellSize === undefined ? null
+                    : cellFromPoint({ x: point.x - rect.left, y: point.y - rect.top }, target.cellSize));
+                return;
+            }
+            element = element.parentElement;
+        }
+        overElement.current = null;
+        setTarget(null);
+    }, [setTarget]);
     const reset = useCallback(() => {
         detach();
         payloadRef.current = null;
         overRef.current = { target: null, cell: null };
+        overElement.current = null;
         pointRef.current = EMPTY_POINT;
-        setState({
-            payload: null,
-            point: EMPTY_POINT,
-            origin: EMPTY_POINT,
-            overTarget: null,
-            overCell: null,
-        });
+        setState({ payload: null, point: EMPTY_POINT, origin: EMPTY_POINT, overTarget: null, overCell: null });
     }, [detach]);
     const endDrag = useCallback(() => {
         const payload = payloadRef.current;
-        let info = null;
-        if (payload !== null) {
-            info = {
-                payload,
-                target: overRef.current.target,
-                cell: overRef.current.cell,
-                point: pointRef.current,
-            };
-            options?.onDrop?.(info);
-        }
+        if (payload === null)
+            return null;
+        const info = {
+            payload, target: overRef.current.target, cell: overRef.current.cell, point: pointRef.current,
+        };
         reset();
+        latest.current?.onDrop?.(info);
         return info;
-    }, [options, reset]);
+    }, [reset]);
+    const beginDrag = useCallback((payload, event) => {
+        if (event.button !== 0 || !event.isPrimary || payloadRef.current !== null)
+            return;
+        const source = event.currentTarget;
+        const view = source.ownerDocument.defaultView;
+        if (view === null)
+            return;
+        const point = { x: event.clientX, y: event.clientY };
+        const nextPayload = { id: payload.id, value: payload.value, rotation: payload.rotation ?? 0 };
+        payloadRef.current = nextPayload;
+        overRef.current = { target: null, cell: null };
+        pointRef.current = point;
+        setState({ payload: nextPayload, point, origin: point, overTarget: null, overCell: null });
+        writeGhost(point, nextPayload.rotation);
+        resolveTarget(source.ownerDocument, point);
+        const onMove = (move) => {
+            if (move.pointerId !== ownerRef.current?.pointerId || payloadRef.current === null)
+                return;
+            if (!source.isConnected) {
+                reset();
+                return;
+            }
+            const next = { x: move.clientX, y: move.clientY };
+            pointRef.current = next;
+            writeGhost(next, payloadRef.current.rotation);
+            resolveTarget(source.ownerDocument, next);
+        };
+        const onUp = (up) => {
+            if (up.pointerId !== ownerRef.current?.pointerId || up.button !== 0)
+                return;
+            if (!source.isConnected) {
+                reset();
+                return;
+            }
+            pointRef.current = { x: up.clientX, y: up.clientY };
+            resolveTarget(source.ownerDocument, pointRef.current);
+            endDrag();
+        };
+        const onCancel = (cancel) => { if (cancel.pointerId === ownerRef.current?.pointerId)
+            reset(); };
+        const onKey = (key) => {
+            if (key.key !== "Escape" || key.defaultPrevented)
+                return;
+            key.preventDefault();
+            key.stopPropagation();
+            reset();
+        };
+        ownerRef.current = { source, pointerId: event.pointerId, detach: () => {
+                view.removeEventListener("pointermove", onMove, true);
+                view.removeEventListener("pointerup", onUp, true);
+                view.removeEventListener("pointercancel", onCancel, true);
+                view.removeEventListener("lostpointercapture", onCancel, true);
+                view.removeEventListener("blur", reset);
+                view.removeEventListener("keydown", onKey, true);
+            } };
+        view.addEventListener("pointermove", onMove, true);
+        view.addEventListener("pointerup", onUp, true);
+        view.addEventListener("pointercancel", onCancel, true);
+        view.addEventListener("lostpointercapture", onCancel, true);
+        view.addEventListener("blur", reset);
+        view.addEventListener("keydown", onKey, true);
+        source.setPointerCapture(event.pointerId);
+    }, [endDrag, reset, resolveTarget, writeGhost]);
+    targetRegistries.set(beginDrag, (element, id, cellSize) => {
+        targets.current.set(element, { id, cellSize });
+        return () => {
+            targets.current.delete(element);
+            if (overElement.current === element) {
+                overElement.current = null;
+                setTarget(null);
+            }
+        };
+    });
+    const rotate = useCallback((quarterTurns = 1) => {
+        const payload = payloadRef.current;
+        if (payload === null)
+            return;
+        const rotation = (((payload.rotation + quarterTurns) % 4) + 4) % 4;
+        const next = { ...payload, rotation };
+        payloadRef.current = next;
+        writeGhost(pointRef.current, rotation);
+        setState((prev) => ({ ...prev, payload: next, point: pointRef.current }));
+    }, [writeGhost]);
     const attachGhost = useCallback((element) => {
         ghostRef.current = element;
-        if (element !== null && payloadRef.current !== null) {
+        if (element !== null && payloadRef.current !== null)
             writeGhost(pointRef.current, payloadRef.current.rotation);
-        }
     }, [writeGhost]);
-    return {
-        state,
-        dragging: state.payload !== null,
-        pointRef,
-        beginDrag,
-        rotate,
-        setTarget,
-        endDrag,
-        cancel: reset,
-        attachGhost,
-    };
+    return { state, dragging: state.payload !== null, pointRef, beginDrag, rotate, setTarget, endDrag, cancel: reset, attachGhost };
 }
 export function DragGhost({ layer, className, style, children, }) {
     const ref = useRef(null);
@@ -136,12 +200,17 @@ export function DragGhost({ layer, className, style, children, }) {
 }
 export function DraggableCard({ id, value, layer, className, children, onRotate, }) {
     const isDragging = layer.state.payload?.id === id;
-    return (_jsx("div", { className: className, "data-card": id, "data-dragging": isDragging ? "" : undefined, onPointerDown: (event) => {
+    const latest = useRef(layer);
+    latest.current = layer;
+    useEffect(() => () => {
+        if (latest.current.state.payload?.id === id)
+            latest.current.cancel();
+    }, [id, layer.cancel]);
+    return (_jsx("div", { className: className, "data-card": id, "data-dragging": isDragging ? "" : undefined, style: { touchAction: "none" }, onPointerDown: (event) => {
+            if (event.button !== 0 || !event.isPrimary)
+                return;
             event.preventDefault();
             layer.beginDrag({ id, value }, event);
-        }, onPointerUp: () => {
-            if (layer.dragging)
-                layer.endDrag();
         }, onContextMenu: (event) => {
             if (onRotate === false)
                 return;
@@ -153,24 +222,11 @@ export function DraggableCard({ id, value, layer, className, children, onRotate,
 export function DropZone({ id, layer, className, activeClassName, cellSize, children, }) {
     const ref = useRef(null);
     const active = layer.state.overTarget === id && layer.dragging;
-    const resolveCell = useCallback((event) => {
-        if (cellSize === undefined || ref.current === null)
-            return null;
-        const rect = ref.current.getBoundingClientRect();
-        return cellFromPoint({ x: event.clientX - rect.left, y: event.clientY - rect.top }, cellSize);
-    }, [cellSize]);
+    useEffect(() => {
+        const element = ref.current;
+        if (element !== null)
+            return targetRegistries.get(layer.beginDrag)?.(element, id, cellSize);
+    }, [layer.beginDrag, id, cellSize]);
     const composed = useMemo(() => [className, active ? activeClassName : undefined].filter(Boolean).join(" ") || undefined, [className, active, activeClassName]);
-    return (_jsx("div", { ref: ref, className: composed, "data-dropzone": id, "data-active": active ? "" : undefined, onPointerEnter: (event) => {
-            if (layer.dragging)
-                layer.setTarget(id, resolveCell(event));
-        }, onPointerMove: (event) => {
-            if (layer.dragging && layer.state.overTarget === id)
-                layer.setTarget(id, resolveCell(event));
-        }, onPointerLeave: () => {
-            if (layer.dragging && layer.state.overTarget === id)
-                layer.setTarget(null, null);
-        }, onPointerUp: () => {
-            if (layer.dragging)
-                layer.endDrag();
-        }, children: children }));
+    return (_jsx("div", { ref: ref, className: composed, "data-dropzone": id, "data-active": active ? "" : undefined, children: children }));
 }

package/dist/hooks.d.ts

@@ -2,6 +2,7 @@ import { type DependencyList } from "react";
 import { AxisChannel, type AxisChannelConfig } from "@jgengine/core/input/axisInput";
 import { type MarkerSet } from "@jgengine/core/world/markers";
 import type { GameContext } from "@jgengine/core/runtime/gameContext";
+import { type DispatchedCommandResult } from "@jgengine/core/runtime/commandDispatch";
 import type { AbilityKit, AbilitySlotSnapshot } from "@jgengine/core/combat/abilityKit";
 import type { EventMeter } from "@jgengine/core/stats/eventMeter";
 import type { GameEvents } from "@jgengine/core/game/events";
@@ -23,8 +24,11 @@ import { type GamePhase } from "@jgengine/core/game/gamePhase";
 export declare function useGameStore<T>(selector: (ctx: GameContext) => T, isEqual?: (previous: T, next: T) => boolean): T;
 /** Subscribe to a single keyed slice of the game store, returning `fallback` until the key is set. */
 export declare function useGameStoreValue<T>(key: string, fallback: T): T;
+/** UI command surface. Hosted commands return a promise; await it to display acknowledgement or rejection. Registration and runAs remain trusted local APIs. */
 export declare function useGame(): {
-    commands: GameContext["game"]["commands"];
+    commands: Omit<GameContext["game"]["commands"], "run"> & {
+        run(name: string, input: unknown): DispatchedCommandResult;
+    };
     events: GameEvents;
 };
 export declare function usePlayer(): {

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();

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";