@jgengine/react 0.11.0 → 0.13.0

package/dist/inventoryGrid.js

@@ -0,0 +1,135 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useMemo, useRef, useState, } from "react";
+import { moveGridFocus } from "@jgengine/core/ui/actionModel";
+import { DragGhost, DraggableCard, DropZone, useDragLayer } from "./dragLayer.js";
+import { iconForItemId } from "./gameIcons.js";
+import { IconTreatment, schoolForItem } from "./iconTreatment.js";
+import { useInventoryGrid } from "./hooks.js";
+/**
+ * A drop-in NxN inventory grid bound to a live inventory: `<InventoryGrid inventoryId="bag" columns={4} />`
+ * renders every slot (painted {@link IconTreatment} tile + count badge for filled, a themed `--jg-slot-*`
+ * placeholder for empty), and wires the real mechanics on top of the engine's inventory model —
+ * drag-to-move, swap, stack-merge with remainder (all via the `inventory.move` command), and stack-split
+ * (shift/right-click a stack, via `inventory.split`). Fully keyboard-accessible: `role="grid"`, arrow-key
+ * roving focus, Enter/Space to pick up and drop. Games own placement, skin, and terminology; the engine
+ * ships the working grid.
+ *
+ * @capability inventory-grid-hud drop-in NxN inventory grid with drag/swap/stack/split bound to a live inventory
+ */
+const ARROW_DIRECTIONS = {
+    ArrowRight: "right",
+    ArrowLeft: "left",
+    ArrowUp: "up",
+    ArrowDown: "down",
+    Home: "first",
+    End: "last",
+};
+function EmptySlot({ size, picked }) {
+    return (_jsx("div", { "data-slot-empty": "", style: {
+            width: size,
+            height: size,
+            borderRadius: "var(--jg-slot-radius, 9px)",
+            background: "var(--jg-slot-bg, rgba(12,14,20,0.5))",
+            border: picked
+                ? "1px solid var(--jg-accent, #38bdf8)"
+                : "var(--jg-slot-border, 1px solid rgba(255,255,255,0.1))",
+            boxShadow: "inset 0 2px 6px rgba(0,0,0,0.45)",
+            boxSizing: "border-box",
+        } }));
+}
+/** A drop-in inventory grid with drag/swap/stack-merge/split and full keyboard control, bound to `inventoryId`. */
+export function InventoryGrid({ inventoryId, columns, size = 44, gap = 6, itemIcon, onActivate, className, style, }) {
+    const { slots, move, split } = useInventoryGrid(inventoryId);
+    const cols = columns ?? Math.max(1, Math.ceil(Math.sqrt(slots.length)));
+    const [focus, setFocus] = useState(0);
+    const [picked, setPicked] = useState(null);
+    const cellRefs = useRef(new Map());
+    const layer = useDragLayer({
+        onDrop: (info) => {
+            const target = info.target === null ? null : Number(info.target);
+            if (target !== null && Number.isInteger(target) && target !== info.payload.value) {
+                move(info.payload.value, target);
+            }
+        },
+    });
+    useEffect(() => {
+        if (focus < slots.length)
+            cellRefs.current.get(focus)?.focus();
+    }, [focus, slots.length]);
+    const splitHalf = useCallback((index) => {
+        const slot = slots[index];
+        if (slot !== null && slot !== undefined && slot.count > 1)
+            split(index, Math.floor(slot.count / 2));
+    }, [slots, split]);
+    const onKeyDown = useCallback((event) => {
+        const dir = ARROW_DIRECTIONS[event.key];
+        if (dir !== undefined) {
+            const next = moveGridFocus(focus, slots.length, cols, dir);
+            if (next >= 0) {
+                event.preventDefault();
+                setFocus(next);
+            }
+            return;
+        }
+        if (event.key === "Enter" || event.key === " " || event.key === "Spacebar") {
+            event.preventDefault();
+            if (picked === null) {
+                if (slots[focus] !== null && slots[focus] !== undefined)
+                    setPicked(focus);
+            }
+            else {
+                if (picked !== focus)
+                    move(picked, focus);
+                setPicked(null);
+            }
+            return;
+        }
+        if (event.key === "Escape" && picked !== null) {
+            event.preventDefault();
+            setPicked(null);
+        }
+    }, [focus, slots, cols, picked, move]);
+    const rows = useMemo(() => {
+        const out = [];
+        for (let i = 0; i < slots.length; i += cols) {
+            out.push(Array.from({ length: Math.min(cols, slots.length - i) }, (_, k) => i + k));
+        }
+        return out;
+    }, [slots.length, cols]);
+    const renderTile = (index) => {
+        const slot = slots[index] ?? null;
+        const isPicked = picked === index;
+        const label = slot === null
+            ? `Empty slot ${index + 1}`
+            : `${slot.itemId}${slot.count > 1 ? ` (${slot.count})` : ""}, slot ${index + 1}`;
+        const custom = slot !== null ? itemIcon?.(slot.itemId) : undefined;
+        const named = slot !== null ? iconForItemId(slot.itemId) : null;
+        return (_jsx(DropZone, { id: String(index), layer: layer, children: _jsx("div", { role: "gridcell", "aria-label": label, "aria-selected": isPicked, tabIndex: focus === index ? 0 : -1, "data-slot": index, ref: (node) => {
+                    if (node === null)
+                        cellRefs.current.delete(index);
+                    else
+                        cellRefs.current.set(index, node);
+                }, onFocus: () => setFocus(index), onKeyDown: onKeyDown, onDoubleClick: () => {
+                    if (slot !== null)
+                        onActivate?.(index);
+                }, onClick: (event) => {
+                    if (event.shiftKey) {
+                        event.preventDefault();
+                        splitHalf(index);
+                    }
+                }, onContextMenu: (event) => {
+                    if (slot !== null && slot.count > 1) {
+                        event.preventDefault();
+                        splitHalf(index);
+                    }
+                }, style: { width: size, height: size, position: "relative", cursor: slot !== null ? "grab" : "default" }, children: slot !== null ? (_jsx(DraggableCard, { id: String(index), value: index, layer: layer, onRotate: false, children: custom !== undefined && custom !== null ? (_jsx(IconTreatment, { glyph: custom, size: size, count: slot.count, active: isPicked })) : (_jsx(IconTreatment, { ...(named === null ? {} : { icon: named }), school: schoolForItem(slot.itemId), size: size, count: slot.count, active: isPicked })) })) : (_jsx(EmptySlot, { size: size, picked: isPicked })) }) }, index));
+    };
+    return (_jsxs("div", { role: "grid", "aria-label": `${inventoryId} inventory`, "aria-colcount": cols, className: className, "data-inventory-grid": inventoryId, style: { display: "grid", gap, ...style }, children: [rows.map((row, r) => (_jsx("div", { role: "row", style: { display: "grid", gridTemplateColumns: `repeat(${cols}, ${size}px)`, gap }, children: row.map(renderTile) }, r))), _jsx(DragGhost, { layer: layer, children: (payload) => {
+                    const slot = slots[payload.value] ?? null;
+                    if (slot === null)
+                        return null;
+                    const named = iconForItemId(slot.itemId);
+                    const custom = itemIcon?.(slot.itemId);
+                    return custom !== undefined && custom !== null ? (_jsx(IconTreatment, { glyph: custom, size: size, count: slot.count })) : (_jsx(IconTreatment, { ...(named === null ? {} : { icon: named }), school: schoolForItem(slot.itemId), size: size, count: slot.count }));
+                } })] }));
+}

package/dist/map.d.ts

@@ -1,12 +1,16 @@
-import { type ReactNode } from "react";
+import { type CSSProperties, type ReactNode } from "react";
 import type { FogField } from "@jgengine/core/world/fog";
-import { type MapMarker, type MarkerKindStyle, type MarkerSet } from "@jgengine/core/world/markers";
+import { type MapMarker, type MarkerCollection, type MarkerKindStyle, type MarkerSource, type MarkerSet, type MarkerView } from "@jgengine/core/world/markers";
 import { type MinimapView, type WorldXZ } from "@jgengine/core/world/minimap";
 import { type MapCellStates, type MapRoute, type MapZone } from "@jgengine/core/world/mapLayers";
-export declare function useMarkers(markers: MarkerSet): readonly MapMarker[];
+/** Subscribe to a native marker set or external marker source, or read a static marker array. */
+export declare function useMarkers<TMeta = unknown>(markers: MarkerSet<TMeta>): readonly MapMarker<TMeta>[];
+export declare function useMarkers<TMarker extends MarkerView>(markers: readonly TMarker[] | MarkerSource<TMarker>): readonly TMarker[];
+export declare function useMarkers(markers: MarkerCollection): readonly MarkerView[];
 export declare function useFog(fog: FogField): ReturnType<FogField["cells"]>;
 export interface MinimapProps {
-    markers: MarkerSet;
+    /** Static views, an external marker source, or a native JGengine MarkerSet. */
+    markers: MarkerCollection;
     center: WorldXZ;
     worldRadius: number;
     fog?: FogField;
@@ -27,6 +31,8 @@ export interface MinimapProps {
     /** Click-to-pin seam (#285.6): receives the clicked world XZ via `unprojectFromMinimap`. */
     onWorldClick?: (world: WorldXZ) => void;
     className?: string;
+    /** Caller-owned outer chrome overrides, applied after the built-in defaults. */
+    style?: CSSProperties;
     title?: string;
     children?: ReactNode;
 }
@@ -38,12 +44,13 @@ export interface MapBounds {
 }
 /**
  * Framed circular minimap: optional baked terrain background, reveal-on-event
- * fog overlay, categorized marker icons, and a facing arrow. Reads a core
- * `MarkerSet` / `FogField`; supply your own `kindStyles` palette to reskin.
+ * fog overlay, categorized marker icons, and a facing arrow. Reads static
+ * marker views, an external marker source, or a native `MarkerSet`; supply
+ * your own `kindStyles` palette to reskin. Does not require `GameProvider`.
  *
  * @capability minimap framed circular minimap with terrain bake, fog, markers, and facing arrow
  */
-export declare function Minimap({ markers, center, worldRadius, fog, size, facingYaw, rotate, kindStyles, background, mapBounds, routes, zones, cellStates, onWorldClick, className, title, children, }: MinimapProps): ReactNode;
+export declare function Minimap({ markers, center, worldRadius, fog, size, facingYaw, rotate, kindStyles, background, mapBounds, routes, zones, cellStates, onWorldClick, className, style, title, children, }: MinimapProps): ReactNode;
 /** One dot (or, with `heading`, a rotated arrow) drawn by `MinimapChrome`. */
 export interface MinimapChromeMarker {
     id: string;
@@ -91,7 +98,7 @@ export interface CompassProps {
     /** Facing yaw (`rotationY`, forward = `(sin yaw, cos yaw)`) of the tracked entity — pass it raw, never pre-converted to a bearing. */
     facingYaw: number;
     center?: WorldXZ;
-    markers?: MarkerSet;
+    markers?: MarkerCollection;
     width?: number;
     fov?: number;
     kindStyles?: Record<string, MarkerKindStyle>;
@@ -99,7 +106,8 @@ export interface CompassProps {
 }
 /**
  * Horizontal compass strip centered on the player's facing direction, with the
- * eight cardinals and optional marker pips (bearing to each `MarkerSet` entry).
+ * eight cardinals and optional marker pips from static views, an external
+ * source, or a native `MarkerSet`.
  */
 export declare function Compass({ facingYaw, center, markers, width, fov, kindStyles, className, }: CompassProps): ReactNode;
 /** Props for `MinimapPanel` — all `MinimapProps` plus the zone-label/clock header and compass slots. */
@@ -125,8 +133,62 @@ export interface MinimapPanelProps extends MinimapProps {
  * @capability minimap-panel circular minimap with zone label, clock, and compass composed together
  */
 export declare function MinimapPanel({ zoneLabel, clock, showCompass, compassProps, headerClassName, zoneLabelClassName, clockClassName, compassClassName, children, ...minimapProps }: MinimapPanelProps): ReactNode;
+/** A colored span across the {@link MinimapTrack} rail, given by 0..1 `start`/`end` fractions (e.g. from core `trackFraction`). */
+export interface MinimapTrackSpan {
+    id: string;
+    /** 0..1 fraction where the span starts. */
+    start: number;
+    /** 0..1 fraction where the span ends. */
+    end: number;
+    /** Fill color; defaults to a translucent white. */
+    color?: string;
+    /** Tooltip / accessible label for the span. */
+    label?: string;
+}
+/** A point marker on the {@link MinimapTrack} rail at a 0..1 fraction (e.g. a gate, the exit, or the player). */
+export interface MinimapTrackPip {
+    id: string;
+    /** 0..1 fraction along the rail. */
+    at: number;
+    /** Marker color; defaults to the rail foreground. */
+    color?: string;
+    /** Accessible label for the marker. */
+    label?: string;
+    /** Tooltip text (rendered as the `title` attribute). */
+    title?: string;
+    /** Silhouette: `gate` (thin tall bar) or a `dot`/`exit`/`player` circle of increasing size (default `dot`). */
+    shape?: "gate" | "dot" | "exit" | "player";
+}
+/** Props for {@link MinimapTrack}. */
+export interface MinimapTrackProps {
+    /** Colored zone spans painted along the rail. */
+    spans?: readonly MinimapTrackSpan[];
+    /** Point markers (gates, exit, player) placed by 0..1 fraction. */
+    pips?: readonly MinimapTrackPip[];
+    /** Rail width (default `100%`). */
+    width?: number | string;
+    /** Rail thickness in px (default 12). */
+    height?: number;
+    /** Rail track color (default `rgba(255,255,255,0.10)`). */
+    railColor?: string;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+}
+/**
+ * Horizontal linear track minimap — a rounded progress rail with colored zone
+ * `spans` and gate/exit/player `pips` positioned by 0..1 fraction. The
+ * structural counterpart to the radial {@link Minimap} for corridor/route
+ * games: fractions are supplied by the caller (via core `trackFraction`), so it
+ * reads no store and stays presentation-only, sharing chrome with the radial
+ * minimap.
+ *
+ * @capability minimap-track-hud horizontal linear track minimap (corridor/route progress) — colored zone spans and gate/player pips positioned by 0..1 fraction, sharing chrome with the radial Minimap
+ */
+export declare function MinimapTrack({ spans, pips, width, height, railColor, className, style, children, }: MinimapTrackProps): ReactNode;
 export interface WorldMapProps {
-    markers: MarkerSet;
+    /** Static views, an external marker source, or a native JGengine MarkerSet. */
+    markers: MarkerCollection;
     bounds: MapBounds;
     player?: WorldXZ;
     /** Facing yaw (`rotationY`, forward = `(sin yaw, cos yaw)`) of the player — pass it raw, never pre-converted to a bearing. */

package/dist/map.js

@@ -68,20 +68,42 @@ function cellStateNodes(layers, project, scale, keyPrefix) {
     }
     return nodes;
 }
+function markerAccess(markers) {
+    if (Array.isArray(markers)) {
+        const snapshot = markers;
+        return { subscribe: NO_SUBSCRIBE, getSnapshot: () => snapshot, getServerSnapshot: () => snapshot };
+    }
+    if ("getSnapshot" in markers) {
+        const source = markers;
+        return {
+            subscribe: (listener) => source.subscribe(listener),
+            getSnapshot: () => source.getSnapshot(),
+            getServerSnapshot: () => (source.getServerSnapshot ?? source.getSnapshot).call(source),
+        };
+    }
+    const markerSet = markers;
+    return {
+        subscribe: (listener) => markerSet.subscribe(listener),
+        getSnapshot: () => markerSet.snapshot(),
+        getServerSnapshot: () => markerSet.snapshot(),
+    };
+}
 export function useMarkers(markers) {
-    return useSyncExternalStore(markers.subscribe, markers.snapshot, markers.snapshot);
+    const access = useMemo(() => markerAccess(markers), [markers]);
+    return useSyncExternalStore(access.subscribe, access.getSnapshot, access.getServerSnapshot);
 }
 export function useFog(fog) {
     return useSyncExternalStore(fog.subscribe, fog.cells, fog.cells);
 }
 /**
  * Framed circular minimap: optional baked terrain background, reveal-on-event
- * fog overlay, categorized marker icons, and a facing arrow. Reads a core
- * `MarkerSet` / `FogField`; supply your own `kindStyles` palette to reskin.
+ * fog overlay, categorized marker icons, and a facing arrow. Reads static
+ * marker views, an external marker source, or a native `MarkerSet`; supply
+ * your own `kindStyles` palette to reskin. Does not require `GameProvider`.
  *
  * @capability minimap framed circular minimap with terrain bake, fog, markers, and facing arrow
  */
-export function Minimap({ markers, center, worldRadius, fog, size = 176, facingYaw = 0, rotate = false, kindStyles = DEFAULT_MARKER_KINDS, background, mapBounds, routes, zones, cellStates, onWorldClick, className, title = "Map", children, }) {
+export function Minimap({ markers, center, worldRadius, fog, size = 176, facingYaw = 0, rotate = false, kindStyles = DEFAULT_MARKER_KINDS, background, mapBounds, routes, zones, cellStates, onWorldClick, className, style, title = "Map", children, }) {
     const markerList = useMarkers(markers);
     const fogCells = useSyncExternalStore(fog?.subscribe ?? NO_SUBSCRIBE, fog?.cells ?? NULL_CELLS, fog?.cells ?? NULL_CELLS);
     const bearing = headingToBearing(facingYaw);
@@ -93,7 +115,7 @@ export function Minimap({ markers, center, worldRadius, fog, size = 176, facingY
     };
     const half = size / 2;
     const clipId = `mm-clip-${size}`;
-    const sorted = [...markerList].sort((a, b) => markerKindStyle(a.kind, kindStyles).priority - markerKindStyle(b.kind, kindStyles).priority);
+    const sorted = useMemo(() => [...markerList].sort((a, b) => markerKindStyle(a.kind, kindStyles).priority - markerKindStyle(b.kind, kindStyles).priority), [markerList, kindStyles]);
     const fogImage = useMemo(() => {
         if (fogCells === null)
             return null;
@@ -117,10 +139,12 @@ export function Minimap({ markers, center, worldRadius, fog, size = 176, facingY
             borderRadius: 14,
             padding: 8,
             background: "linear-gradient(160deg, rgba(24,28,36,0.94), rgba(12,15,20,0.94))",
-            border: "1px solid rgba(148,163,184,0.28)",
+            // Ring color reads the shared HudTheme `--jg-ring` token (#1034); fallback = the built-in ring.
+            border: "1px solid var(--jg-ring, rgba(148,163,184,0.28))",
             boxShadow: "0 10px 30px rgba(0,0,0,0.45)",
             color: "#e2e8f0",
             fontFamily: "ui-sans-serif, system-ui, sans-serif",
+            ...style,
         }, children: [_jsxs("div", { style: {
                     display: "flex",
                     justifyContent: "space-between",
@@ -158,10 +182,11 @@ export function Minimap({ markers, center, worldRadius, fog, size = 176, facingY
                                     ...routeNodes(routes, projectXZ, "mm"),
                                 ];
                             })(), _jsx("circle", { cx: half, cy: half, r: half - 1, fill: "none", stroke: "rgba(148,163,184,0.12)" }), sorted.map((marker) => {
-                                const style = markerKindStyle(marker.kind, kindStyles);
+                                const kind = marker.kind ?? "marker";
+                                const style = markerKindStyle(kind, kindStyles);
                                 const projected = projectToMinimap(marker.position, view);
                                 const at = projected.inside ? projected : clampToMinimapEdge(projected, size);
-                                return (_jsxs("g", { "data-marker-kind": marker.kind, children: [_jsx("circle", { cx: at.x, cy: at.y, r: 7, fill: "rgba(2,6,12,0.55)" }), _jsx("text", { x: at.x, y: at.y + 3.5, textAnchor: "middle", fontSize: 10, fill: style.color, style: { fontWeight: 700 }, children: style.glyph })] }, marker.id));
+                                return (_jsxs("g", { "data-marker-kind": kind, children: [_jsx("circle", { cx: at.x, cy: at.y, r: 7, fill: "rgba(2,6,12,0.55)" }), _jsx("text", { x: at.x, y: at.y + 3.5, textAnchor: "middle", fontSize: 10, fill: style.color, style: { fontWeight: 700 }, children: style.glyph })] }, marker.id));
                             }), _jsx("g", { transform: `translate(${half} ${half}) rotate(${(rotate ? 0 : bearing) * (180 / Math.PI)})`, children: _jsx("path", { d: "M0,-9 L6,7 L0,3 L-6,7 Z", fill: "#4ade80", stroke: "#052e16", strokeWidth: 0.75 }) })] }), _jsx("circle", { cx: half, cy: half, r: half - 1, fill: "none", stroke: "rgba(148,163,184,0.4)", strokeWidth: 1.5 }), _jsx("text", { x: half, y: 13, textAnchor: "middle", fontSize: 11, fill: "rgba(226,232,240,0.9)", style: { fontWeight: 700 }, children: "N" })] }), children] }));
 }
 /**
@@ -197,7 +222,6 @@ export function MinimapChrome({ view, frame = false, frameColor = "rgba(148,163,
 const NO_SUBSCRIBE = () => () => undefined;
 const NULL_CELLS = () => null;
 const EMPTY_MARKERS_VALUE = [];
-const EMPTY_MARKERS = () => EMPTY_MARKERS_VALUE;
 const COMPASS_TICKS = [
     { cardinal: "N", bearing: 0 },
     { cardinal: "NE", bearing: Math.PI / 4 },
@@ -210,10 +234,11 @@ const COMPASS_TICKS = [
 ];
 /**
  * Horizontal compass strip centered on the player's facing direction, with the
- * eight cardinals and optional marker pips (bearing to each `MarkerSet` entry).
+ * eight cardinals and optional marker pips from static views, an external
+ * source, or a native `MarkerSet`.
  */
 export function Compass({ facingYaw, center, markers, width = 340, fov = (Math.PI * 2) / 3, kindStyles = DEFAULT_MARKER_KINDS, className, }) {
-    const markerList = useSyncExternalStore(markers?.subscribe ?? NO_SUBSCRIBE, markers?.snapshot ?? EMPTY_MARKERS, markers?.snapshot ?? EMPTY_MARKERS);
+    const markerList = useMarkers(markers ?? EMPTY_MARKERS_VALUE);
     const facingBearing = headingToBearing(facingYaw);
     const half = fov / 2;
     const toX = (bearing) => {
@@ -259,8 +284,9 @@ export function Compass({ facingYaw, center, markers, width = 340, fov = (Math.P
                     const x = toX(bearing);
                     if (x === null)
                         return null;
-                    const style = markerKindStyle(marker.kind, kindStyles);
-                    return (_jsx("span", { "data-compass-marker": marker.kind, style: {
+                    const kind = marker.kind ?? "marker";
+                    const style = markerKindStyle(kind, kindStyles);
+                    return (_jsx("span", { "data-compass-marker": kind, style: {
                             position: "absolute",
                             left: x,
                             bottom: 2,
@@ -293,6 +319,48 @@ export function MinimapPanel({ zoneLabel, clock, showCompass = true, compassProp
                     fontFamily: "ui-sans-serif, system-ui, sans-serif",
                 }, children: [zoneLabel !== undefined ? (_jsx("span", { className: zoneLabelClassName, "data-minimap-chrome-zone": true, style: { fontSize: 12, fontWeight: 700 }, children: zoneLabel })) : (_jsx("span", {})), clock !== undefined ? (_jsx("span", { className: clockClassName, "data-minimap-chrome-clock": true, style: { fontSize: 11, color: "rgba(226,232,240,0.75)" }, children: clock })) : null] })) : null, _jsx(Minimap, { ...minimapProps, children: children }), showCompass ? (_jsx("div", { className: compassClassName, "data-minimap-chrome-compass": true, style: { marginTop: 6 }, children: _jsx(Compass, { facingYaw: minimapProps.facingYaw ?? 0, center: minimapProps.center, markers: minimapProps.markers, width: minimapProps.size ?? 176, ...compassProps }) })) : null] }));
 }
+const TRACK_PIP_DIAMETER = {
+    dot: 6,
+    exit: 8,
+    player: 12,
+};
+/**
+ * Horizontal linear track minimap — a rounded progress rail with colored zone
+ * `spans` and gate/exit/player `pips` positioned by 0..1 fraction. The
+ * structural counterpart to the radial {@link Minimap} for corridor/route
+ * games: fractions are supplied by the caller (via core `trackFraction`), so it
+ * reads no store and stays presentation-only, sharing chrome with the radial
+ * minimap.
+ *
+ * @capability minimap-track-hud horizontal linear track minimap (corridor/route progress) — colored zone spans and gate/player pips positioned by 0..1 fraction, sharing chrome with the radial Minimap
+ */
+export function MinimapTrack({ spans = [], pips = [], width = "100%", height = 12, railColor = "rgba(255,255,255,0.10)", className, style, children, }) {
+    return (_jsxs("div", { className: className, "data-minimap-track": true, style: { position: "relative", width, height, borderRadius: 9999, background: railColor, ...style }, children: [spans.map((span) => (_jsx("div", { "data-track-span": span.id, title: span.label, style: {
+                    position: "absolute",
+                    top: 0,
+                    bottom: 0,
+                    left: `${span.start * 100}%`,
+                    width: `${(span.end - span.start) * 100}%`,
+                    background: span.color ?? "rgba(255,255,255,0.25)",
+                    opacity: 0.4,
+                    borderRadius: 9999,
+                } }, span.id))), pips.map((pip) => {
+                const shape = pip.shape ?? "dot";
+                const color = pip.color ?? "#f4f6fb";
+                const common = {
+                    position: "absolute",
+                    top: "50%",
+                    left: `${pip.at * 100}%`,
+                    transform: "translate(-50%, -50%)",
+                    background: color,
+                };
+                if (shape === "gate") {
+                    return (_jsx("div", { "data-track-pip": pip.id, "data-pip-shape": "gate", title: pip.title ?? pip.label, style: { ...common, width: 3, height: height + 6, borderRadius: 2 } }, pip.id));
+                }
+                const diameter = TRACK_PIP_DIAMETER[shape];
+                return (_jsx("div", { "data-track-pip": pip.id, "data-pip-shape": shape, title: pip.title ?? pip.label, style: { ...common, width: diameter, height: diameter, borderRadius: 9999, border: "1px solid rgba(0,0,0,0.6)" } }, pip.id));
+            }), children] }));
+}
 function WorldMapFogImage({ fogCells, project, worldW, worldD, width, mapH, }) {
     const fogImage = useMemo(() => {
         if (fogCells === null)
@@ -361,8 +429,9 @@ export function WorldMap({ markers, bounds, player, facingYaw = 0, fog, backgrou
                         ];
                     })(), markerList.map((marker) => {
                         const at = project(marker.position[0], marker.position[2]);
-                        const style = markerKindStyle(marker.kind, kindStyles);
-                        return (_jsxs("g", { "data-world-marker": marker.kind, children: [_jsx("circle", { cx: at.x, cy: at.y, r: 9, fill: "rgba(2,6,12,0.6)", stroke: style.color, strokeWidth: 1.2 }), _jsx("text", { x: at.x, y: at.y + 4, textAnchor: "middle", fontSize: 12, fill: style.color, style: { fontWeight: 700 }, children: style.glyph }), marker.label !== undefined ? (_jsx("text", { x: at.x + 12, y: at.y + 4, fontSize: 11, fill: "rgba(226,232,240,0.85)", children: marker.label })) : null] }, marker.id));
+                        const kind = marker.kind ?? "marker";
+                        const style = markerKindStyle(kind, kindStyles);
+                        return (_jsxs("g", { "data-world-marker": kind, children: [_jsx("circle", { cx: at.x, cy: at.y, r: 9, fill: "rgba(2,6,12,0.6)", stroke: style.color, strokeWidth: 1.2 }), _jsx("text", { x: at.x, y: at.y + 4, textAnchor: "middle", fontSize: 12, fill: style.color, style: { fontWeight: 700 }, children: style.glyph }), marker.label !== undefined ? (_jsx("text", { x: at.x + 12, y: at.y + 4, fontSize: 11, fill: "rgba(226,232,240,0.85)", children: marker.label })) : null] }, marker.id));
                     }), player !== undefined
                         ? (() => {
                             const at = project(player[0], player[1]);

package/dist/panels.d.ts

@@ -0,0 +1,107 @@
+import { type CSSProperties, type ReactNode } from "react";
+import { type PanelDef, type PanelPosition, type PanelState } from "@jgengine/core/ui/panelModel";
+import { type HudFrameShape, type HudFrameVariation } from "./hudFrame.js";
+/**
+ * React chrome over the headless panel/window model (`@jgengine/core/ui/panelModel`) — the toggleable,
+ * draggable, z-stacked windows a WoW-style UI is made of (B for bag, C for character, ESC to close).
+ * `usePanels` is the DATA/HOOK layer (open/close/toggle/focus + a keybind listener), `PanelHost` renders
+ * the open windows in z-order, and `Window` is a standalone one-off window. All unskinned and
+ * token-driven: games reskin via `HudTheme` tokens and by swapping the `HudFrame` variation.
+ */
+/** Intent a key press resolves to over a panel set: toggle a panel, close the top window, or ignore. */
+export interface PanelKeyResult {
+    handled: boolean;
+    type?: "toggle" | "closeTop";
+    id?: string;
+}
+/**
+ * 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
+ * the intent without touching the DOM, so it unit-tests headless and `usePanels` is a thin shell over it.
+ */
+export declare function panelKeyAction(defs: readonly PanelDef[], state: PanelState, event: {
+    code?: string;
+    key?: string;
+}): PanelKeyResult;
+/** Options for {@link usePanels}. */
+export interface UsePanelsOptions {
+    /** Fired when a panel transitions from closed to open (not on refocus of an already-open panel). */
+    onOpen?: (id: string) => void;
+    /** Fired when an open panel is closed. */
+    onClose?: (id: string) => void;
+    /** Set false to skip installing the window keybind/ESC listener (default true). */
+    hotkeys?: boolean;
+}
+/** The live panel manager returned by {@link usePanels} and consumed by {@link PanelHost}. */
+export interface PanelsManager {
+    state: PanelState;
+    defs: readonly PanelDef[];
+    isOpen: (id: string) => boolean;
+    open: (id: string) => void;
+    close: (id: string) => void;
+    toggle: (id: string) => void;
+    focus: (id: string) => void;
+    move: (id: string, pos: PanelPosition) => void;
+    byHotkey: (code: string) => string | null;
+}
+/**
+ * The DATA/HOOK layer: wrap the core panel model in state and install a window keybind listener —
+ * per-panel hotkeys toggle their window and ESC closes the topmost closable one. Hotkeys are ignored
+ * while the player is typing in an input/textarea/contenteditable. The listener is cleaned up on
+ * unmount and SSR-safe (armed in an effect). Feed the returned manager to {@link PanelHost}, or drive a
+ * bespoke window layout from it directly.
+ *
+ * @capability use-panels headless toggleable-window manager with keybind + ESC handling over the core panel model
+ */
+export declare function usePanels(defs: readonly PanelDef[], options?: UsePanelsOptions): PanelsManager;
+/**
+ * Renders the open panels of a {@link usePanels} manager as absolutely-positioned, draggable, closable
+ * windows in z-order — the WoW window layer. Each window uses {@link HudFrame} chrome, is dragged by its
+ * title bar, raises focus on pointer-down, and gets its content from the `render` prop (or a `panels`
+ * map). Accessible: every window is a `role="dialog"` with an `aria-label` and a focusable close button;
+ * ESC-close is wired by the manager. Unskinned — art-direct via `HudTheme` tokens and the `variation`.
+ *
+ * @capability panel-host render a manager's open windows as draggable, closable, z-stacked dialogs
+ */
+export declare function PanelHost({ manager, render, panels, variation, shape, width, className, windowClassName, windowStyle, bodyStyle, }: {
+    manager: PanelsManager;
+    /** Content for a panel by id. Takes precedence over `panels`. */
+    render?: (id: string) => ReactNode;
+    /** Static content map by panel id, used when `render` is omitted. */
+    panels?: Record<string, ReactNode>;
+    variation?: HudFrameVariation;
+    shape?: HudFrameShape;
+    /** Default window width (per-panel unless overridden by the panel content). */
+    width?: number | string;
+    className?: string;
+    windowClassName?: string;
+    windowStyle?: CSSProperties;
+    bodyStyle?: CSSProperties;
+}): import("react").JSX.Element;
+/**
+ * A single standalone window — title bar, close button, and title-bar drag over {@link HudFrame} chrome —
+ * usable without the {@link usePanels} manager for a one-off dialog. Position is uncontrolled (seeded by
+ * `x`/`y`) unless both `x`/`y` and `onMove` are supplied, in which case the caller owns placement.
+ * Accessible: `role="dialog"` with an `aria-label` and a focusable close button.
+ *
+ * @capability window standalone draggable, closable window primitive over HudFrame — no manager required
+ */
+export declare function Window({ title, ariaLabel, closable, onClose, x, y, onMove, z, width, variation, shape, className, style, bodyStyle, children, }: {
+    title: ReactNode;
+    ariaLabel?: string;
+    closable?: boolean;
+    onClose?: () => void;
+    /** Initial (uncontrolled) or current (controlled, with `onMove`) x position. Default 56. */
+    x?: number;
+    /** Initial (uncontrolled) or current (controlled, with `onMove`) y position. Default 56. */
+    y?: number;
+    onMove?: (pos: PanelPosition) => void;
+    z?: number;
+    width?: number | string;
+    variation?: HudFrameVariation;
+    shape?: HudFrameShape;
+    className?: string;
+    style?: CSSProperties;
+    bodyStyle?: CSSProperties;
+    children?: ReactNode;
+}): import("react").JSX.Element;