@jgengine/react 0.18.1 → 0.21.0

package/dist/actionHud.js

@@ -193,7 +193,7 @@ export function ActionButton({ action, focused = false, hovered = false, size =
 export function ActionBarChrome({ model, layout = "grid", itemSize = 52, gap = 6, ariaLabel = "Actions", renderItem, className, style, }) {
     const refs = useRef(new Map());
     const { actions, focusedId, hoveredId, columns } = model;
-    const rovingId = focusedId ?? actions[0]?.id ?? null;
+    const rovingId = actions.some(action => action.id === focusedId) ? focusedId : actions[0]?.id ?? null;
     useEffect(() => {
         if (focusedId === null)
             return;

package/dist/bars.d.ts

@@ -49,7 +49,7 @@ export type BarShape = "rect" | "pill" | "skew" | "chamfer";
 export interface AtomicBarProps {
     /** Trough shape language. Default `rect`. */
     shape?: BarShape;
-    /** Explicit fill color, overriding the token (and the low-threshold swap) — for per-instance
+    /** Explicit fill color, overriding the skin, token, and low-threshold swap — for per-instance
      * colors a token can't express (e.g. a class-colored resource bar). Caller overrides win. */
     fill?: string;
     /** Explicit current value; when set the bar is pure and needs no game provider. */

package/dist/bars.js

@@ -96,7 +96,7 @@ function BarView({ fraction, valueText, config, label, width = 200, segments, en
                     position: "absolute",
                     inset: 0,
                     width: `${fraction * 100}%`,
-                    background: "var(--jg-bar-skin-fill, " + fill + ")",
+                    background: fillOverride ?? `var(--jg-bar-skin-fill, ${fill})`,
                     transition: "width 160ms ease",
                 } }), _jsx("div", { style: {
                     position: "absolute",

package/dist/barsPreview.d.ts

@@ -1,4 +1,4 @@
-/** Renders the atomic bar matrix twice under different token blocks to prove global re-theming. */
+/** Renders atomic bars under token blocks and nested themes to prove fill and skin precedence. */
 export declare function BarsPreview({ className }: {
     className?: string;
 }): import("react").JSX.Element;

package/dist/barsPreview.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import {} from "react";
 import { AmmoCounter, barTokens, BossBar, ExperienceBar, HealthBar, ManaBar, ShieldBar, SoulBar, StaminaBar, } from "./bars.js";
+import { hudTheme, hudThemeVars } from "./hudTheme.js";
 /**
  * A deterministic preview of every atomic vitals bar plus a composed example — the fixture behind
  * #1033's visual evidence. All values are static (no game provider), so it renders identically every
@@ -29,7 +30,13 @@ function Portrait({ color }) {
 function AtomicMatrix({ label, tokens }) {
     return (_jsxs("div", { style: { ...PANEL, ...(tokens === undefined ? {} : barTokens(tokens)) }, children: [_jsx("span", { style: { fontSize: 11, fontWeight: 700, letterSpacing: 0.6, textTransform: "uppercase", color: "rgba(255,255,255,0.6)" }, children: label }), _jsx(HealthBar, { value: 82, max: 100, label: "HP" }), _jsx(HealthBar, { value: 14, max: 100, label: "HP" }), _jsx(ShieldBar, { value: 40, max: 60, label: "SH" }), _jsx(ManaBar, { value: 55, max: 80, label: "MP" }), _jsx(StaminaBar, { value: 90, max: 100, label: "ST" }), _jsx(ExperienceBar, { value: 3, max: 10, segments: 10, showValue: false, label: "XP" }), _jsx(SoulBar, { value: 3, max: 5, segments: 5, showValue: false, label: "SOUL" }), _jsx(AmmoCounter, { loaded: 17, reserve: 90, magazine: 30 }), _jsx(BossBar, { value: 640, max: 1000, name: "Ancient Wyrm", width: "100%" }), _jsxs("div", { style: { display: "flex", alignItems: "center", gap: 8, marginTop: 4 }, children: [_jsx(Portrait, { color: tokens?.health ?? "#e5484d" }), _jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 4, flex: "1 1 auto" }, children: [_jsx(HealthBar, { value: 82, max: 100, width: "100%", showValue: false }), _jsx(ShieldBar, { value: 40, max: 60, width: "100%", showValue: false })] })] })] }));
 }
-/** Renders the atomic bar matrix twice under different token blocks to prove global re-theming. */
+function ThemeFills() {
+    const themed = hudTheme({ palette: { health: "#7fb06d", healthLow: "#d89b38" } });
+    const skinned = hudTheme({ skin: { bar: { fill: "linear-gradient(90deg, #136fbc, #68c9ee)", track: "none" } } });
+    const nestedSkin = hudTheme({ skin: { bar: { fill: "#a855f7", track: "none" } } });
+    return (_jsxs("div", { style: { ...PANEL, ...hudThemeVars(themed) }, children: [_jsx("span", { children: "Theme fill precedence" }), _jsx(HealthBar, { value: 270, max: 270, fill: "#7fb06d", label: "Explicit" }), _jsx(HealthBar, { value: 80, max: 100, label: "Palette" }), _jsx(HealthBar, { value: 15, max: 100, label: "Low palette" }), _jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 8, ...hudThemeVars(skinned) }, children: [_jsx(HealthBar, { value: 80, max: 100, label: "Skin" }), _jsx(HealthBar, { value: 80, max: 100, fill: "#7fb06d", label: "Explicit over skin" }), _jsx("div", { style: hudThemeVars(themed), children: _jsx(HealthBar, { value: 80, max: 100, label: "Nested reset" }) }), _jsx("div", { style: hudThemeVars(nestedSkin), children: _jsx(HealthBar, { value: 80, max: 100, label: "Nested skin" }) })] })] }));
+}
+/** Renders atomic bars under token blocks and nested themes to prove fill and skin precedence. */
 export function BarsPreview({ className }) {
     return (_jsxs("div", { "data-bars-preview": true, className: className, style: { display: "flex", gap: 16, flexWrap: "wrap", padding: 20, fontFamily: "system-ui, sans-serif", color: "#f5f7fa" }, children: [_jsx(AtomicMatrix, { label: "default tokens" }), _jsx(AtomicMatrix, { label: "restyled tokens", tokens: {
                     health: "#2fbf71",
@@ -43,5 +50,5 @@ export function BarsPreview({ className }) {
                     frame: "#0a0a0a",
                     radius: "2px",
                     height: "20px",
-                } })] }));
+                } }), _jsx(ThemeFills, {})] }));
 }

package/dist/browserLifecycle.d.ts

@@ -0,0 +1,26 @@
+/** Browser events that can interrupt active play. The caller decides whether to pause. */
+export type BrowserSuspensionReason = "blur" | "hidden" | "pointer-lock-lost";
+/** Select suspension events; all are observed by default. No callback runs on attachment. */
+export interface BrowserSuspensionOptions {
+    blur?: boolean;
+    hidden?: boolean;
+    pointerLockLost?: boolean;
+}
+/** Event sources for a browser window, an iframe, or a test. */
+export interface BrowserSuspensionSources {
+    window: Pick<EventTarget, "addEventListener" | "removeEventListener">;
+    document: Pick<EventTarget, "addEventListener" | "removeEventListener"> & {
+        readonly hidden: boolean;
+        readonly pointerLockElement: Element | null;
+    };
+}
+/**
+ * Observe interruption events until detached. Lock loss requires a preceding lock; SSR attaches nothing.
+ * @capability browser-suspension-observer observe browser interruptions outside React with caller-owned pause policy and event sources
+ */
+export declare function observeBrowserSuspension(onSuspend: (reason: BrowserSuspensionReason) => void, options?: BrowserSuspensionOptions, sources?: BrowserSuspensionSources | null): () => void;
+/**
+ * Observe browser interruptions while mounted, invoking the latest callback without replacing listeners.
+ * @capability browser-suspension observe blur, hidden-page and pointer-lock loss while the game owns pause and input policy
+ */
+export declare function useBrowserSuspension(onSuspend: (reason: BrowserSuspensionReason) => void, options?: BrowserSuspensionOptions): void;

package/dist/browserLifecycle.js

@@ -0,0 +1,42 @@
+import { useEffect, useRef } from "react";
+/**
+ * Observe interruption events until detached. Lock loss requires a preceding lock; SSR attaches nothing.
+ * @capability browser-suspension-observer observe browser interruptions outside React with caller-owned pause policy and event sources
+ */
+export function observeBrowserSuspension(onSuspend, options = {}, sources = typeof window === "undefined" || typeof document === "undefined" ? null : { window, document }) {
+    if (sources === null)
+        return () => { };
+    const { window: win, document: doc } = sources;
+    let locked = doc.pointerLockElement !== null;
+    const blur = () => onSuspend("blur");
+    const visibility = () => { if (doc.hidden)
+        onSuspend("hidden"); };
+    const lock = () => {
+        const next = doc.pointerLockElement !== null;
+        const lost = locked && !next;
+        locked = next;
+        if (lost)
+            onSuspend("pointer-lock-lost");
+    };
+    if (options.blur !== false)
+        win.addEventListener("blur", blur);
+    if (options.hidden !== false)
+        doc.addEventListener("visibilitychange", visibility);
+    if (options.pointerLockLost !== false)
+        doc.addEventListener("pointerlockchange", lock);
+    return () => {
+        win.removeEventListener("blur", blur);
+        doc.removeEventListener("visibilitychange", visibility);
+        doc.removeEventListener("pointerlockchange", lock);
+    };
+}
+/**
+ * Observe browser interruptions while mounted, invoking the latest callback without replacing listeners.
+ * @capability browser-suspension observe blur, hidden-page and pointer-lock loss while the game owns pause and input policy
+ */
+export function useBrowserSuspension(onSuspend, options = {}) {
+    const callback = useRef(onSuspend);
+    useEffect(() => { callback.current = onSuspend; }, [onSuspend]);
+    const { blur, hidden, pointerLockLost } = options;
+    useEffect(() => observeBrowserSuspension((reason) => callback.current(reason), { blur, hidden, pointerLockLost }), [blur, hidden, pointerLockLost]);
+}

package/dist/dialogBehavior.d.ts

@@ -0,0 +1,22 @@
+import { type RefObject } from "react";
+/** Options for controlled dialog focus behavior; callers own markup, state, and close policy. */
+export interface DialogBehaviorOptions {
+    /** Whether the dialog is mounted and open. */
+    open: boolean;
+    /** Escape requests a close; leaving `open` true keeps the dialog active. Omit to disable Escape. */
+    onClose?: () => void;
+    /** Preferred initial focus, falling back to the first available control or the dialog root. */
+    initialFocus?: "root" | (() => HTMLElement | null);
+    /** Refocus when the content identity changes, without replacing the original return target. */
+    focusKey?: unknown;
+}
+/**
+ * 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 declare function useDialogBehavior<T extends HTMLElement = HTMLDivElement>(options: DialogBehaviorOptions): RefObject<T | null>;

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(): {
@@ -53,6 +57,11 @@ export declare function useWorldItems(): readonly WorldItemRecord[];
 /** Nearest ground item within `radius` of the local player — drives a pickup prompt/highlight. */
 export declare function useNearestWorldItem(radius: number): WorldItemRecord | null;
 export declare function useEntityStat(instanceId: string, statId: string): StatValue | null;
+/**
+ * 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 declare function useTarget(fromInstanceId: string): string | null;
 export declare function useInventory(inventoryId: string): readonly InventorySlot[];
 /** Live slots plus `move`/`split` actions bound to `inventoryId`, routed through the notifying `inventory.move`/`inventory.split` commands so React re-renders. */