@jgengine/react 0.13.0 → 0.15.0-next.0

package/dist/map.js

@@ -1,5 +1,5 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useMemo, useSyncExternalStore } from "react";
+import { useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { DEFAULT_MARKER_KINDS, markerKindStyle, } from "@jgengine/core/world/markers";
 import { bearingToCardinal, clampToMinimapEdge, compassBearing, headingToBearing, projectToMinimap, relativeBearing, unprojectFromMinimap, } from "@jgengine/core/world/minimap";
 import { mapLayerColor, } from "@jgengine/core/world/mapLayers";
@@ -376,21 +376,66 @@ function WorldMapFogImage({ fogCells, project, worldW, worldD, width, mapH, }) {
         return null;
     return _jsx("image", { href: fogImage, x: 0, y: 0, width: width, height: mapH, preserveAspectRatio: "none" });
 }
+const IDENTITY_VIEWPORT = { scale: 1, tx: 0, ty: 0 };
 /**
- * Full-bounds top-down world map (the "press M" overlay): baked terrain
- * background, reveal-on-event fog, all markers with labels, and the player.
- * Rectangular linear projection over the supplied world `bounds`.
+ * The bare top-down map `<svg>` shared by {@link WorldMap} (framed panel) and
+ * {@link FullscreenMap} (pan/zoom overlay): baked terrain background, fog, map
+ * layers, markers with labels, and the player arrow, drawn under an optional
+ * viewport transform. Rectangular linear projection over the world `bounds`.
  */
-export function WorldMap({ markers, bounds, player, facingYaw = 0, fog, background, width = 520, height, kindStyles = DEFAULT_MARKER_KINDS, routes, zones, cellStates, onWorldClick, className, title = "World Map", onClose, }) {
+export function WorldMapSurface({ markers, bounds, player, facingYaw = 0, fog, background, width = 520, height, kindStyles = DEFAULT_MARKER_KINDS, routes, zones, cellStates, onWorldClick, canvasWidth, canvasHeight, viewport = IDENTITY_VIEWPORT, style, }) {
     const markerList = useMarkers(markers);
     const fogCells = useSyncExternalStore(fog?.subscribe ?? NO_SUBSCRIBE, fog?.cells ?? NULL_CELLS, fog?.cells ?? NULL_CELLS);
     const worldW = bounds.maxX - bounds.minX;
     const worldD = bounds.maxZ - bounds.minZ;
     const mapH = height ?? Math.round((width * worldD) / worldW);
+    const svgW = canvasWidth ?? width;
+    const svgH = canvasHeight ?? mapH;
     const project = (x, z) => ({
         x: ((x - bounds.minX) / worldW) * width,
         y: ((z - bounds.minZ) / worldD) * mapH,
     });
+    return (_jsx("svg", { width: svgW, height: svgH, viewBox: `0 0 ${svgW} ${svgH}`, "data-world-map-canvas": true, style: { borderRadius: 10, ...(onWorldClick === undefined ? {} : { cursor: "crosshair" }), ...style }, ...(onWorldClick === undefined
+            ? {}
+            : {
+                onClick: (event) => {
+                    const rect = event.currentTarget.getBoundingClientRect();
+                    const sx = ((event.clientX - rect.left) / rect.width) * svgW;
+                    const sy = ((event.clientY - rect.top) / rect.height) * svgH;
+                    const px = (sx - viewport.tx) / viewport.scale;
+                    const py = (sy - viewport.ty) / viewport.scale;
+                    onWorldClick([bounds.minX + (px / width) * worldW, bounds.minZ + (py / mapH) * worldD]);
+                },
+            }), children: _jsxs("g", { transform: `translate(${viewport.tx} ${viewport.ty}) scale(${viewport.scale})`, "data-world-map-content": true, children: [_jsx("rect", { x: 0, y: 0, width: width, height: mapH, fill: "#16202b" }), background !== undefined ? (_jsx("image", { href: background, x: 0, y: 0, width: width, height: mapH, preserveAspectRatio: "none", opacity: 0.95 })) : null, _jsx(WorldMapFogImage, { fogCells: fogCells, project: project, worldW: worldW, worldD: worldD, width: width, mapH: mapH }), (() => {
+                    const projectXZ = (x, z) => project(x, z);
+                    const layerScale = {
+                        x: (units) => (units / worldW) * width,
+                        y: (units) => (units / worldD) * mapH,
+                    };
+                    return [
+                        ...cellStateNodes(cellStates, projectXZ, layerScale, "wm"),
+                        ...zoneNodes(zones, projectXZ, layerScale, "wm"),
+                        ...routeNodes(routes, projectXZ, "wm"),
+                    ];
+                })(), markerList.map((marker) => {
+                    const at = project(marker.position[0], marker.position[2]);
+                    const kind = marker.kind ?? "marker";
+                    const markerStyle = 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: markerStyle.color, strokeWidth: 1.2 }), _jsx("text", { x: at.x, y: at.y + 4, textAnchor: "middle", fontSize: 12, fill: markerStyle.color, style: { fontWeight: 700 }, children: markerStyle.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]);
+                        return (_jsx("g", { transform: `translate(${at.x} ${at.y}) rotate(${headingToBearing(facingYaw) * (180 / Math.PI)})`, children: _jsx("path", { d: "M0,-11 L7,9 L0,4 L-7,9 Z", fill: "#4ade80", stroke: "#052e16", strokeWidth: 1 }) }));
+                    })()
+                    : null] }) }));
+}
+/**
+ * Full-bounds top-down world map (the "press M" overlay): baked terrain
+ * background, reveal-on-event fog, all markers with labels, and the player.
+ * Rectangular linear projection over the supplied world `bounds`. Framed panel
+ * wrapper over {@link WorldMapSurface}.
+ */
+export function WorldMap({ markers, bounds, player, facingYaw = 0, fog, background, width = 520, height, kindStyles = DEFAULT_MARKER_KINDS, routes, zones, cellStates, onWorldClick, className, title = "World Map", onClose, }) {
     return (_jsxs("div", { className: className, "data-world-map": true, style: {
             borderRadius: 16,
             padding: 14,
@@ -407,35 +452,193 @@ export function WorldMap({ markers, bounds, player, facingYaw = 0, fog, backgrou
                             fontSize: 11,
                             padding: "3px 9px",
                             cursor: "pointer",
-                        }, children: "Close" })) : null] }), _jsxs("svg", { width: width, height: mapH, viewBox: `0 0 ${width} ${mapH}`, "data-world-map-canvas": true, style: { borderRadius: 10, ...(onWorldClick === undefined ? {} : { cursor: "crosshair" }) }, ...(onWorldClick === undefined
-                    ? {}
-                    : {
-                        onClick: (event) => {
-                            const rect = event.currentTarget.getBoundingClientRect();
-                            const px = ((event.clientX - rect.left) / rect.width) * width;
-                            const py = ((event.clientY - rect.top) / rect.height) * mapH;
-                            onWorldClick([bounds.minX + (px / width) * worldW, bounds.minZ + (py / mapH) * worldD]);
-                        },
-                    }), children: [_jsx("rect", { x: 0, y: 0, width: width, height: mapH, fill: "#16202b" }), background !== undefined ? (_jsx("image", { href: background, x: 0, y: 0, width: width, height: mapH, preserveAspectRatio: "none", opacity: 0.95 })) : null, _jsx(WorldMapFogImage, { fogCells: fogCells, project: project, worldW: worldW, worldD: worldD, width: width, mapH: mapH }), (() => {
-                        const projectXZ = (x, z) => project(x, z);
-                        const layerScale = {
-                            x: (units) => (units / worldW) * width,
-                            y: (units) => (units / worldD) * mapH,
-                        };
-                        return [
-                            ...cellStateNodes(cellStates, projectXZ, layerScale, "wm"),
-                            ...zoneNodes(zones, projectXZ, layerScale, "wm"),
-                            ...routeNodes(routes, projectXZ, "wm"),
-                        ];
-                    })(), markerList.map((marker) => {
-                        const at = project(marker.position[0], marker.position[2]);
-                        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]);
-                            return (_jsx("g", { transform: `translate(${at.x} ${at.y}) rotate(${headingToBearing(facingYaw) * (180 / Math.PI)})`, children: _jsx("path", { d: "M0,-11 L7,9 L0,4 L-7,9 Z", fill: "#4ade80", stroke: "#052e16", strokeWidth: 1 }) }));
-                        })()
-                        : null] })] }));
+                        }, children: "Close" })) : null] }), _jsx(WorldMapSurface, { markers: markers, bounds: bounds, player: player, facingYaw: facingYaw, fog: fog, background: background, width: width, height: height, kindStyles: kindStyles, routes: routes, zones: zones, cellStates: cellStates, onWorldClick: onWorldClick })] }));
+}
+function clampScale(value, min, max) {
+    return Math.max(min, Math.min(max, value));
+}
+/**
+ * Fullscreen pan/zoom world-map overlay — the enlarged "press M" map. Wheel to
+ * zoom (toward the cursor), drag to pan, and click to place (wire `onWorldClick`
+ * to a waypoint/annotation store). Switch `tool` to `"draw"` to freehand-draw
+ * strokes committed to `onStrokeComplete` (wire to `createAnnotationLayer`).
+ * Reuses {@link WorldMapSurface} for rendering, so terrain bake, fog, routes,
+ * zones, markers, and the player arrow all appear; a drag never fires
+ * `onWorldClick`. Compose a {@link MapLegend} or tool palette via `children`.
+ *
+ * @capability fullscreen-map fullscreen pan/zoom world-map overlay over WorldMapSurface — wheel-zoom, drag-pan, click-to-place, and a freehand draw tool (onStrokeComplete)
+ */
+export function FullscreenMap({ open = true, bounds, contentWidth = 900, minScale = 0.5, maxScale = 8, title = "Map", onClose, onWorldClick, tool = "pan", onStrokeComplete, drawTone = "info", drawWidth = 3, children, overlayClassName, overlayStyle, ...surfaceProps }) {
+    const worldW = bounds.maxX - bounds.minX;
+    const worldD = bounds.maxZ - bounds.minZ;
+    const contentHeight = Math.round((contentWidth * worldD) / worldW);
+    const [viewport, setViewport] = useState(IDENTITY_VIEWPORT);
+    const drag = useRef(null);
+    const moved = useRef(false);
+    const draftRef = useRef(null);
+    const [draft, setDraft] = useState(null);
+    const drawing = tool === "draw";
+    const minSpacing = (worldW + worldD) / 400;
+    if (!open)
+        return null;
+    const zoomBy = (factor, sx, sy) => {
+        setViewport((prev) => {
+            const next = clampScale(prev.scale * factor, minScale, maxScale);
+            const k = next / prev.scale;
+            return { scale: next, tx: sx - k * (sx - prev.tx), ty: sy - k * (sy - prev.ty) };
+        });
+    };
+    const canvasPoint = (event) => {
+        const rect = event.currentTarget.getBoundingClientRect();
+        const kx = contentWidth / rect.width;
+        const ky = contentHeight / rect.height;
+        return { x: (event.clientX - rect.left) * kx, y: (event.clientY - rect.top) * ky, kx, ky };
+    };
+    const screenToWorld = (event) => {
+        const at = canvasPoint(event);
+        const cx = (at.x - viewport.tx) / viewport.scale;
+        const cy = (at.y - viewport.ty) / viewport.scale;
+        return [bounds.minX + (cx / contentWidth) * worldW, bounds.minZ + (cy / contentHeight) * worldD];
+    };
+    const pushDraftPoint = (point) => {
+        const points = draftRef.current ?? [];
+        const last = points[points.length - 1];
+        if (last !== undefined && Math.hypot(last[0] - point[0], last[1] - point[1]) < minSpacing)
+            return;
+        draftRef.current = [...points, point];
+        setDraft(draftRef.current);
+    };
+    const commitDraft = () => {
+        const points = draftRef.current;
+        draftRef.current = null;
+        setDraft(null);
+        if (points !== null && points.length >= 2)
+            onStrokeComplete?.(points);
+    };
+    const draftRoute = draft !== null && draft.length >= 2 ? { id: "__draft-stroke", points: draft, tone: drawTone, width: drawWidth } : null;
+    const forwardedRoutes = draftRoute === null ? surfaceProps.routes : [...(surfaceProps.routes ?? []), draftRoute];
+    const controlButton = {
+        width: 30,
+        height: 30,
+        borderRadius: 8,
+        border: "1px solid rgba(148,163,184,0.4)",
+        background: "rgba(17,22,30,0.85)",
+        color: "#e2e8f0",
+        fontSize: 16,
+        lineHeight: "1",
+        cursor: "pointer",
+    };
+    return (_jsxs("div", { className: overlayClassName, "data-fullscreen-map": true, style: {
+            position: "fixed",
+            inset: 0,
+            zIndex: 40,
+            display: "flex",
+            flexDirection: "column",
+            background: "rgba(6,9,14,0.82)",
+            backdropFilter: "blur(2px)",
+            color: "#e2e8f0",
+            fontFamily: "ui-sans-serif, system-ui, sans-serif",
+            ...overlayStyle,
+        }, children: [_jsxs("div", { style: {
+                    display: "flex",
+                    alignItems: "center",
+                    justifyContent: "space-between",
+                    padding: "10px 16px",
+                    borderBottom: "1px solid rgba(148,163,184,0.2)",
+                }, children: [_jsx("span", { style: { fontSize: 13, fontWeight: 700, letterSpacing: 1.6, textTransform: "uppercase" }, children: title }), _jsxs("div", { style: { display: "flex", gap: 8, alignItems: "center" }, children: [_jsx("button", { type: "button", "aria-label": "Zoom out", style: controlButton, onClick: () => zoomBy(1 / 1.2, contentWidth / 2, contentHeight / 2), children: "\u2212" }), _jsx("button", { type: "button", "aria-label": "Zoom in", style: controlButton, onClick: () => zoomBy(1.2, contentWidth / 2, contentHeight / 2), children: "+" }), _jsx("button", { type: "button", "aria-label": "Reset view", style: { ...controlButton, width: "auto", padding: "0 10px", fontSize: 11 }, onClick: () => setViewport(IDENTITY_VIEWPORT), children: "Reset" }), onClose !== undefined ? (_jsx("button", { type: "button", "aria-label": "Close map", style: { ...controlButton, width: "auto", padding: "0 12px", fontSize: 11 }, onClick: onClose, children: "Close" })) : null] })] }), _jsxs("div", { "data-fullscreen-map-viewport": true, "data-map-tool": tool, style: {
+                    position: "relative",
+                    flex: 1,
+                    minHeight: 0,
+                    overflow: "hidden",
+                    touchAction: "none",
+                    cursor: drawing ? "crosshair" : drag.current !== null ? "grabbing" : "grab",
+                }, onWheel: (event) => {
+                    const at = canvasPoint(event);
+                    zoomBy(event.deltaY < 0 ? 1.15 : 1 / 1.15, at.x, at.y);
+                }, onPointerDown: (event) => {
+                    if (event.button !== 0)
+                        return;
+                    event.currentTarget.setPointerCapture(event.pointerId);
+                    if (drawing) {
+                        draftRef.current = [screenToWorld(event)];
+                        setDraft(draftRef.current);
+                        return;
+                    }
+                    drag.current = { x: event.clientX, y: event.clientY, vp: viewport };
+                    moved.current = false;
+                }, onPointerMove: (event) => {
+                    if (drawing) {
+                        if (draftRef.current !== null)
+                            pushDraftPoint(screenToWorld(event));
+                        return;
+                    }
+                    const state = drag.current;
+                    if (state === null)
+                        return;
+                    const rect = event.currentTarget.getBoundingClientRect();
+                    const kx = contentWidth / rect.width;
+                    const ky = contentHeight / rect.height;
+                    const dx = (event.clientX - state.x) * kx;
+                    const dy = (event.clientY - state.y) * ky;
+                    if (Math.abs(dx) + Math.abs(dy) > 3)
+                        moved.current = true;
+                    setViewport({ scale: state.vp.scale, tx: state.vp.tx + dx, ty: state.vp.ty + dy });
+                }, onPointerUp: (event) => {
+                    if (event.currentTarget.hasPointerCapture(event.pointerId))
+                        event.currentTarget.releasePointerCapture(event.pointerId);
+                    if (drawing) {
+                        commitDraft();
+                        return;
+                    }
+                    drag.current = null;
+                }, children: [_jsx(WorldMapSurface, { ...surfaceProps, routes: forwardedRoutes, bounds: bounds, width: contentWidth, height: contentHeight, canvasWidth: contentWidth, canvasHeight: contentHeight, viewport: viewport, style: { width: "100%", height: "100%", borderRadius: 0, display: "block" }, onWorldClick: onWorldClick === undefined || drawing
+                            ? undefined
+                            : (world) => {
+                                if (moved.current) {
+                                    moved.current = false;
+                                    return;
+                                }
+                                onWorldClick(world);
+                            } }), children] })] }));
+}
+/**
+ * Marker-kind key for a map/minimap — glyph + color swatch per kind, labelled.
+ * Reads the same `kindStyles` the map renders with, so the legend can never
+ * drift from the pins.
+ *
+ * @capability map-legend marker-kind key (glyph + color + label per kind) sharing the map's kindStyles
+ */
+export function MapLegend({ kinds, labels, kindStyles = DEFAULT_MARKER_KINDS, title = "Legend", className, style, }) {
+    return (_jsxs("div", { className: className, "data-map-legend": true, style: {
+            borderRadius: 10,
+            padding: "8px 10px",
+            background: "rgba(12,16,22,0.86)",
+            border: "1px solid rgba(148,163,184,0.28)",
+            color: "#e2e8f0",
+            fontFamily: "ui-sans-serif, system-ui, sans-serif",
+            fontSize: 11,
+            ...style,
+        }, children: [title !== "" ? (_jsx("div", { style: { fontSize: 9, letterSpacing: 1.4, textTransform: "uppercase", color: "rgba(203,213,225,0.7)", marginBottom: 5 }, children: title })) : null, _jsx("ul", { style: { listStyle: "none", margin: 0, padding: 0, display: "flex", flexDirection: "column", gap: 3 }, children: kinds.map((kind) => {
+                    const kindStyle = markerKindStyle(kind, kindStyles);
+                    return (_jsxs("li", { "data-legend-kind": kind, style: { display: "flex", alignItems: "center", gap: 7 }, children: [_jsx("span", { "aria-hidden": true, style: { width: 14, textAlign: "center", color: kindStyle.color, fontWeight: 700 }, children: kindStyle.glyph }), _jsx("span", { children: labels?.[kind] ?? kind })] }, kind));
+                }) })] }));
+}
+/**
+ * On-screen guide arrow to the tracked waypoint — a HUD compass needle rotated
+ * by the facing-relative bearing, with an optional label and distance readout.
+ * Pair with `WaypointStore.guidance(playerXZ, facingYaw)`.
+ *
+ * @capability waypoint-arrow on-screen HUD guide arrow to a tracked waypoint, rotated by facing-relative bearing with a distance readout
+ */
+export function WaypointArrow({ relative, distance, label, formatDistance = (value) => `${Math.round(value)}m`, size = 44, color = "#f59e0b", className, style, }) {
+    return (_jsxs("div", { className: className, "data-waypoint-arrow": true, style: {
+            display: "inline-flex",
+            flexDirection: "column",
+            alignItems: "center",
+            gap: 2,
+            color,
+            fontFamily: "ui-sans-serif, system-ui, sans-serif",
+            textShadow: "0 1px 2px rgba(0,0,0,0.9)",
+            ...style,
+        }, children: [_jsx("svg", { width: size, height: size, viewBox: "0 0 44 44", "aria-hidden": true, "data-waypoint-arrow-needle": true, children: _jsx("g", { transform: `rotate(${(relative * 180) / Math.PI} 22 22)`, children: _jsx("path", { d: "M22 6 L32 34 L22 27 L12 34 Z", fill: color, stroke: "rgba(0,0,0,0.7)", strokeWidth: 1.2, strokeLinejoin: "round" }) }) }), label !== undefined ? (_jsx("span", { style: { fontSize: 10, fontWeight: 700, letterSpacing: 0.6, textTransform: "uppercase" }, children: label })) : null, distance !== undefined ? (_jsx("span", { style: { fontSize: 11, fontVariantNumeric: "tabular-nums", color: "rgba(226,232,240,0.9)" }, children: formatDistance(distance) })) : null] }));
 }

package/dist/menuRouter.d.ts

@@ -0,0 +1,51 @@
+/** A screen-stack transition. `reset` without an id collapses to the router's original root. */
+export type MenuStackAction<Id extends string> = {
+    type: "open";
+    id: Id;
+} | {
+    type: "back";
+} | {
+    type: "replace";
+    id: Id;
+} | {
+    type: "reset";
+    id?: Id;
+};
+/**
+ * The pure screen-stack transition behind {@link useMenuRouter}. Exported so a game can drive the
+ * same navigation from its own store or a replayable command log instead of React state.
+ *
+ * @capability menu-stack-reducer pure push/back/replace/reset transitions for a menu screen stack
+ */
+export declare function menuStackReducer<Id extends string>(path: readonly Id[], action: MenuStackAction<Id>, root: Id): readonly Id[];
+/** A menu screen stack: where you are, how you got there, and how to go back. */
+export interface MenuRouter<Id extends string> {
+    /** The screen on top of the stack. */
+    current: Id;
+    /** The whole stack, root first — render breadcrumbs from it, or check depth. */
+    path: readonly Id[];
+    /** True when `current` is the root screen, so Escape has nowhere to go. */
+    atRoot: boolean;
+    /** Push a screen. Pushing the current screen again is a no-op. */
+    open(id: Id): void;
+    /** Pop one screen. A no-op at the root. */
+    back(): void;
+    /** Replace the top of the stack without deepening it. */
+    replace(id: Id): void;
+    /** Collapse to a root — the one passed, or the original. Use it when a run starts or ends. */
+    reset(id?: Id): void;
+}
+/**
+ * The screen stack behind a game front-end: title → save select → settings → credits, and Escape
+ * back out. Every game menu needs this and none of it is game-specific, so it ships here rather
+ * than being re-derived per game. Holds no content and imposes no look — the game decides what each
+ * screen id renders.
+ *
+ * `escapeToBack` (default `true`) binds Escape to {@link MenuRouter.back}; pass `false` when the
+ * game already owns the Escape key (a pause menu that toggles rather than pops).
+ *
+ * @capability menu-router screen stack for a game front-end — push/back/replace/reset with optional Escape-to-back
+ */
+export declare function useMenuRouter<Id extends string>(root: Id, options?: {
+    escapeToBack?: boolean;
+}): MenuRouter<Id>;

package/dist/menuRouter.js

@@ -0,0 +1,49 @@
+import { useCallback, useEffect, useMemo, useReducer } from "react";
+/**
+ * The pure screen-stack transition behind {@link useMenuRouter}. Exported so a game can drive the
+ * same navigation from its own store or a replayable command log instead of React state.
+ *
+ * @capability menu-stack-reducer pure push/back/replace/reset transitions for a menu screen stack
+ */
+export function menuStackReducer(path, action, root) {
+    switch (action.type) {
+        case "open":
+            return path[path.length - 1] === action.id ? path : [...path, action.id];
+        case "back":
+            return path.length <= 1 ? path : path.slice(0, -1);
+        case "replace":
+            return [...path.slice(0, -1), action.id];
+        case "reset":
+            return [action.id ?? root];
+    }
+}
+/**
+ * The screen stack behind a game front-end: title → save select → settings → credits, and Escape
+ * back out. Every game menu needs this and none of it is game-specific, so it ships here rather
+ * than being re-derived per game. Holds no content and imposes no look — the game decides what each
+ * screen id renders.
+ *
+ * `escapeToBack` (default `true`) binds Escape to {@link MenuRouter.back}; pass `false` when the
+ * game already owns the Escape key (a pause menu that toggles rather than pops).
+ *
+ * @capability menu-router screen stack for a game front-end — push/back/replace/reset with optional Escape-to-back
+ */
+export function useMenuRouter(root, options = {}) {
+    const { escapeToBack = true } = options;
+    const [path, dispatch] = useReducer((state, action) => menuStackReducer(state, action, root), [root]);
+    const open = useCallback((id) => dispatch({ type: "open", id }), []);
+    const back = useCallback(() => dispatch({ type: "back" }), []);
+    const replace = useCallback((id) => dispatch({ type: "replace", id }), []);
+    const reset = useCallback((id) => dispatch({ type: "reset", id }), []);
+    useEffect(() => {
+        if (!escapeToBack)
+            return;
+        const onKeyDown = (event) => {
+            if (event.key === "Escape")
+                dispatch({ type: "back" });
+        };
+        window.addEventListener("keydown", onKeyDown);
+        return () => window.removeEventListener("keydown", onKeyDown);
+    }, [escapeToBack]);
+    return useMemo(() => ({ current: path[path.length - 1], path, atRoot: path.length <= 1, open, back, replace, reset }), [path, open, back, replace, reset]);
+}

package/dist/modals.d.ts

@@ -0,0 +1,131 @@
+import { type CSSProperties, type ReactNode } from "react";
+import { type ModalRecord, type ModalStack } from "@jgengine/core/ui/modalStack";
+/**
+ * React chrome over the headless modal stack (`@jgengine/core/ui/modalStack`) — the blocking-overlay
+ * layer a game raises over its scene: a pause menu, a "quit to menu?" confirm, a reward popup.
+ * {@link useModalStack} is the DATA/HOOK layer (subscribe + the active record), {@link ModalHost}
+ * renders the top modal with a backdrop, focus trap, and Esc-to-cancel, and {@link ConfirmDialog} /
+ * {@link PauseMenu} are ready-to-wire, HudTheme-token-driven building blocks. All unskinned and
+ * game-owned: the model never interprets a modal's `kind`, so a game switches on it to pick which of
+ * these (or its own) content to show, and reskins everything via `HudTheme` tokens and the frame.
+ */
+/** The live modal view returned by {@link useModalStack}: the active record (or `null`) plus the stack depth. */
+export interface ModalStackView {
+    /** The topmost open modal, or `null` when nothing is open. */
+    top: ModalRecord | null;
+    /** Number of stacked modals (for a "2 of 3"-style affordance or a dim-per-layer backdrop). */
+    depth: number;
+}
+/**
+ * Subscribe to a modal stack and re-render on every change, returning the active modal and depth.
+ *
+ * @capability use-modal-stack React hook binding a modal stack to a component — re-renders on push/pop/resolve
+ */
+export declare function useModalStack(stack: ModalStack): ModalStackView;
+/** Props for {@link ModalHost}. */
+export interface ModalHostProps {
+    /** The stack to render the top of. */
+    stack: ModalStack;
+    /**
+     * Render the active modal's content. Receives the record and controls bound to the stack —
+     * `resolve(result)` closes it with a free-form outcome, `cancel()` is the Esc/backdrop shortcut
+     * (`resolve(MODAL_CANCEL)`). Switch on `record.kind` to pick a {@link ConfirmDialog}, a
+     * {@link PauseMenu}, or your own content.
+     */
+    children: (record: ModalRecord, controls: ModalControls) => ReactNode;
+    /** Dim the scene behind the modal. Default `true`. */
+    showBackdrop?: boolean;
+    /** Backdrop color (default `rgba(4,7,12,0.62)`, or the `--jg-backdrop` token). */
+    backdrop?: string;
+    /** Close the top modal (cancel) on backdrop click. Default `true`. */
+    closeOnBackdrop?: boolean;
+    /** Close the top modal (cancel) on Escape. Default `true`. */
+    closeOnEsc?: boolean;
+    /** z-index of the host's stacking context — sits above the HUD/windows. Default 80. */
+    zIndexBase?: number;
+    className?: string;
+    style?: CSSProperties;
+}
+/** Stack-bound controls handed to a {@link ModalHost} render callback. */
+export interface ModalControls {
+    /** Resolve the active modal with a free-form result and close it. */
+    resolve: (result: string, payload?: unknown) => void;
+    /** Resolve the active modal with {@link MODAL_CONFIRM}. */
+    confirm: (payload?: unknown) => void;
+    /** Resolve the active modal with {@link MODAL_CANCEL} — the Esc / backdrop behavior. */
+    cancel: () => void;
+}
+/**
+ * Full-screen modal host: watches a stack, renders only the topmost modal centered over a dimmed
+ * backdrop, and manages accessibility — the panel is a `role="dialog" aria-modal`, focus moves into
+ * it on open and is trapped with Tab/Shift+Tab cycling, Escape and (optionally) a backdrop click
+ * cancel the top modal, and focus returns to the previously focused element on close. It renders
+ * nothing when the stack is empty. Skin the panel and backdrop via `HudTheme` tokens.
+ *
+ * @capability modal-host full-screen modal/dialog host over a modal stack — dimmed backdrop, focus trap, Esc/backdrop-to-cancel, aria-modal dialog
+ */
+export declare function ModalHost({ stack, children, showBackdrop, backdrop, closeOnBackdrop, closeOnEsc, zIndexBase, className, style, }: ModalHostProps): ReactNode;
+/** Props for {@link ConfirmDialog}. */
+export interface ConfirmDialogProps {
+    title: ReactNode;
+    /** Explanatory body copy under the title. */
+    body?: ReactNode;
+    /** Confirm button label (default `"Confirm"`). */
+    confirmLabel?: ReactNode;
+    /** Cancel button label (default `"Cancel"`). */
+    cancelLabel?: ReactNode;
+    onConfirm: () => void;
+    onCancel: () => void;
+    /** Style the confirm button as destructive (red). Default `false`. */
+    danger?: boolean;
+    /** Fixed dialog width (default 360). */
+    width?: number | string;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * A generic two-button confirmation dialog — title, optional body, and Cancel / Confirm buttons over
+ * a `HudTheme`-token-driven {@link HudFrame}. Presentation-only: wire `onConfirm`/`onCancel` to a
+ * modal stack's `resolve` (typically inside a {@link ModalHost} render callback) and reskin via
+ * `HudTheme` tokens or `danger` for a destructive action. It interprets nothing — the game supplies
+ * the copy.
+ *
+ * @capability confirm-dialog generic themeable confirm/cancel dialog — title, body, two buttons, danger styling
+ */
+export declare function ConfirmDialog({ title, body, confirmLabel, cancelLabel, onConfirm, onCancel, danger, width, className, style, }: ConfirmDialogProps): ReactNode;
+/** One selectable row in a {@link PauseMenu}'s slot list (Settings, Save, Quit, …). */
+export interface PauseMenuItem {
+    /** Stable id (also the `data-pause-item` value). */
+    id: string;
+    label: ReactNode;
+    onSelect: () => void;
+    /** Render as destructive (e.g. Quit). Default `false`. */
+    danger?: boolean;
+    /** Disable the row. Default `false`. */
+    disabled?: boolean;
+}
+/** Props for {@link PauseMenu}. */
+export interface PauseMenuProps {
+    /** Menu heading (default `"Paused"`). */
+    title?: ReactNode;
+    /** Resume/close-the-menu action, wired to the primary Resume button. */
+    onResume: () => void;
+    /** Resume button label (default `"Resume"`). */
+    resumeLabel?: ReactNode;
+    /** The game-filled slot list beneath Resume (Settings, Save, Quit, …). */
+    items?: readonly PauseMenuItem[];
+    /** Fixed menu width (default 300). */
+    width?: number | string;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * A reskinnable pause-menu building block: a primary Resume button plus a game-filled list of slot
+ * items (Settings, Save, Quit, …), stacked in a `HudTheme`-token-driven {@link HudFrame}. It ships
+ * the common shape every game's pause screen needs and nothing genre-specific — the game supplies the
+ * title, item labels/order, and destructive styling, and reskins with `HudTheme` tokens. Drop it into
+ * a {@link ModalHost} keyed on a `"pause"` modal, or render it standalone.
+ *
+ * @capability pause-menu reskinnable pause-menu building block — Resume plus a game-filled Settings/Quit slot list, HudTheme-driven
+ */
+export declare function PauseMenu({ title, onResume, resumeLabel, items, width, className, style, }: PauseMenuProps): ReactNode;