@jgengine/react 0.14.0 → 0.15.0-next.0

package/dist/killFeed.js

@@ -0,0 +1,88 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useReducer, useRef } from "react";
+import { GameIcon, isGameIconName } from "./gameIcons.js";
+/**
+ * Subscribe to an event ticker and re-render it on an animation frame (unless the game
+ * already ticks it), returning the live entries newest-first with `fade` applied. Driving
+ * the frame loop is what makes entries visibly fade and drop as they age out.
+ *
+ * @capability use-event-ticker React hook binding an event-ticker — re-renders per frame so entries fade and drop live, returning the current newest-first views
+ */
+export function useEventTicker(ticker, animate = true) {
+    const [, bump] = useReducer((n) => n + 1, 0);
+    const rafRef = useRef(0);
+    useEffect(() => ticker.subscribe(bump), [ticker]);
+    useEffect(() => {
+        if (!animate)
+            return;
+        let running = true;
+        const loop = () => {
+            if (!running)
+                return;
+            bump();
+            rafRef.current = requestAnimationFrame(loop);
+        };
+        rafRef.current = requestAnimationFrame(loop);
+        return () => {
+            running = false;
+            cancelAnimationFrame(rafRef.current);
+        };
+    }, [ticker, animate]);
+    return ticker.recent();
+}
+function resolveTheme(theme) {
+    return {
+        rowBg: theme?.rowBg ?? "var(--jg-frame-bg, rgba(12,16,22,0.82))",
+        text: theme?.text ?? "#f1f5f9",
+        accent: theme?.accent ?? "var(--jg-accent, #38bdf8)",
+        fontFamily: theme?.fontFamily ?? "ui-sans-serif, system-ui, sans-serif",
+        radius: theme?.radius ?? "var(--jg-frame-radius, 8px)",
+    };
+}
+/**
+ * A vertical event/kill-feed ticker: renders an {@link EventTicker}'s recent entries as a
+ * stack of rows, newest on top, each with its `fade` `0..1` mapped to opacity so entries dim
+ * and drop as they age out. Each row shows an optional per-kind (or per-entry) {@link GameIcon}
+ * and a per-kind accent color from `kindStyles`, styled with HudTheme tokens. Presentation
+ * only: all capping/timing lives in the core ticker, and the free-string `kind`/`text`/`icon`
+ * are never interpreted here — a game colors and icons each variant via `kindStyles`.
+ *
+ * @capability kill-feed vertical event/kill-feed ticker rendering a core event-ticker as a fading, newest-on-top stack of per-kind iconned, accent-colored rows over HudTheme tokens
+ */
+export function KillFeed({ ticker, kindStyles, theme, iconSize = 18, animate = true, zIndex = 40, className, style, }) {
+    const entries = useEventTicker(ticker, animate);
+    const t = resolveTheme(theme);
+    return (_jsx("div", { className: className, "data-kill-feed": "", style: {
+            display: "flex",
+            flexDirection: "column",
+            alignItems: "stretch",
+            gap: 6,
+            pointerEvents: "none",
+            fontFamily: t.fontFamily,
+            zIndex,
+            ...style,
+        }, children: entries.map((entry) => {
+            const kindStyle = kindStyles?.[entry.kind];
+            const accent = kindStyle?.accent ?? t.accent;
+            const iconName = entry.icon ?? kindStyle?.icon;
+            const opacity = 1 - entry.fade * 0.85;
+            return (_jsxs("div", { "data-kill-feed-row": entry.id, "data-kind": entry.kind, style: {
+                    display: "flex",
+                    alignItems: "center",
+                    gap: 8,
+                    padding: "5px 10px",
+                    background: t.rowBg,
+                    borderLeft: `3px solid ${accent}`,
+                    borderRadius: t.radius,
+                    color: kindStyle?.color ?? t.text,
+                    fontSize: 13,
+                    fontWeight: 600,
+                    lineHeight: 1.2,
+                    whiteSpace: "nowrap",
+                    opacity,
+                    boxShadow: "0 2px 8px rgba(0,0,0,0.4)",
+                    transform: `translateX(${entry.fade * 8}px)`,
+                    willChange: "opacity, transform",
+                }, children: [iconName !== undefined && isGameIconName(iconName) ? (_jsx("span", { style: { color: accent, display: "flex", flexShrink: 0 }, children: _jsx(GameIcon, { name: iconName, size: iconSize }) })) : null, _jsx("span", { "data-kill-feed-text": "", children: entry.text })] }, entry.id));
+        }) }));
+}

package/dist/map.d.ts

@@ -2,7 +2,7 @@ import { type CSSProperties, type ReactNode } from "react";
 import type { FogField } from "@jgengine/core/world/fog";
 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";
+import { type MapCellStates, type MapLayerTone, type MapRoute, type MapZone } from "@jgengine/core/world/mapLayers";
 /** 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[];
@@ -210,9 +210,130 @@ export interface WorldMapProps {
     title?: string;
     onClose?: () => void;
 }
+/** Pan/zoom transform applied to a {@link WorldMapSurface}'s content group. */
+export interface MapViewport {
+    /** Uniform zoom factor; 1 = fit. */
+    scale: number;
+    /** Content-group translation in canvas px. */
+    tx: number;
+    ty: number;
+}
+/** Props for {@link WorldMapSurface}. */
+export interface WorldMapSurfaceProps {
+    markers: MarkerCollection;
+    bounds: MapBounds;
+    player?: WorldXZ;
+    facingYaw?: number;
+    fog?: FogField;
+    background?: string;
+    /** Content layout width in px (world bounds map into this). */
+    width?: number;
+    /** Content layout height; defaults to the bounds aspect ratio. */
+    height?: number;
+    kindStyles?: Record<string, MarkerKindStyle>;
+    routes?: readonly MapRoute[];
+    zones?: readonly MapZone[];
+    cellStates?: readonly MapCellStates[];
+    onWorldClick?: (world: WorldXZ) => void;
+    /** Outer `<svg>` pixel size; defaults to the content `width`/`height` (no viewport). */
+    canvasWidth?: number;
+    canvasHeight?: number;
+    /** Pan/zoom transform; identity when omitted. Click math inverts it before unprojecting. */
+    viewport?: MapViewport;
+    style?: CSSProperties;
+}
+/**
+ * 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 declare function WorldMapSurface({ markers, bounds, player, facingYaw, fog, background, width, height, kindStyles, routes, zones, cellStates, onWorldClick, canvasWidth, canvasHeight, viewport, style, }: WorldMapSurfaceProps): ReactNode;
 /**
  * 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`.
+ * Rectangular linear projection over the supplied world `bounds`. Framed panel
+ * wrapper over {@link WorldMapSurface}.
  */
 export declare function WorldMap({ markers, bounds, player, facingYaw, fog, background, width, height, kindStyles, routes, zones, cellStates, onWorldClick, className, title, onClose, }: WorldMapProps): ReactNode;
+/** Props for {@link FullscreenMap}. */
+export interface FullscreenMapProps extends Omit<WorldMapSurfaceProps, "canvasWidth" | "canvasHeight" | "viewport" | "width" | "height" | "style"> {
+    /** Render nothing when false. Default true. */
+    open?: boolean;
+    /** Content layout width in px before zoom; height derives from the bounds aspect. Default 900. */
+    contentWidth?: number;
+    /** Zoom bounds. Default 0.5 / 8. */
+    minScale?: number;
+    maxScale?: number;
+    title?: string;
+    onClose?: () => void;
+    /**
+     * Interaction mode. `"pan"` (default) drags to pan and click-to-place fires
+     * `onWorldClick`; `"draw"` drags to paint a freehand stroke, committed to
+     * `onStrokeComplete` (panning and click-to-place are suppressed).
+     */
+    tool?: "pan" | "draw";
+    /** Called with a finished freehand stroke (world-XZ points) in `"draw"` mode — wire to an annotation layer's `addStroke`. */
+    onStrokeComplete?: (points: readonly WorldXZ[]) => void;
+    /** Tone of the in-progress stroke while drawing. Default `"info"`. */
+    drawTone?: MapLayerTone;
+    /** Width (map px) of the in-progress stroke. Default 3. */
+    drawWidth?: number;
+    /** Overlay chrome drawn above the map (legend, tool palette, hints). */
+    children?: ReactNode;
+    overlayClassName?: string;
+    overlayStyle?: CSSProperties;
+}
+/**
+ * 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 declare function FullscreenMap({ open, bounds, contentWidth, minScale, maxScale, title, onClose, onWorldClick, tool, onStrokeComplete, drawTone, drawWidth, children, overlayClassName, overlayStyle, ...surfaceProps }: FullscreenMapProps): ReactNode;
+/** Props for {@link MapLegend}. */
+export interface MapLegendProps {
+    /** Marker kinds to key, in order. */
+    kinds: readonly string[];
+    /** Human labels per kind; falls back to the kind id. */
+    labels?: Record<string, string>;
+    kindStyles?: Record<string, MarkerKindStyle>;
+    title?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * 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 declare function MapLegend({ kinds, labels, kindStyles, title, className, style, }: MapLegendProps): ReactNode;
+/** Props for {@link WaypointArrow}. */
+export interface WaypointArrowProps {
+    /** Bearing to the target relative to facing (radians); 0 = dead ahead. From `WaypointStore.guidance().relative`. */
+    relative: number;
+    /** XZ distance in world units; renders a readout when supplied. */
+    distance?: number;
+    label?: string;
+    /** Format the distance readout; defaults to whole units + "m". */
+    formatDistance?: (distance: number) => string;
+    size?: number;
+    color?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * 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 declare function WaypointArrow({ relative, distance, label, formatDistance, size, color, className, style, }: WaypointArrowProps): ReactNode;

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]);
+}