@jgengine/react 0.8.0 → 0.9.0

package/dist/liveBind.js

@@ -1,32 +1,44 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useRef } from "react";
-/**
- * Drive a DOM/SVG element from a per-frame value without re-rendering React.
- * Runs one requestAnimationFrame loop, reads `get()` each frame, and calls
- * `apply(value, element)` so HUDs bound to live engine state (speed, pose)
- * never re-render and never lag. `get`/`apply` may change without restarting.
- */
+const subscribers = new Set();
+let sharedRaf = 0;
+function sharedTick() {
+    for (const subscriber of subscribers)
+        subscriber();
+    if (subscribers.size > 0)
+        sharedRaf = requestAnimationFrame(sharedTick);
+    else
+        sharedRaf = 0;
+}
+export function subscribeFrameBind(subscriber) {
+    subscribers.add(subscriber);
+    if (sharedRaf === 0 && typeof requestAnimationFrame !== "undefined") {
+        sharedRaf = requestAnimationFrame(sharedTick);
+    }
+    return () => {
+        subscribers.delete(subscriber);
+        if (subscribers.size === 0 && sharedRaf !== 0 && typeof cancelAnimationFrame !== "undefined") {
+            cancelAnimationFrame(sharedRaf);
+            sharedRaf = 0;
+        }
+    };
+}
+export function frameBindSubscriberCount() {
+    return subscribers.size;
+}
 export function useFrameBind(ref, get, apply) {
     const getRef = useRef(get);
     getRef.current = get;
     const applyRef = useRef(apply);
     applyRef.current = apply;
     useEffect(() => {
-        let raf = 0;
-        const tick = () => {
+        return subscribeFrameBind(() => {
             const element = ref.current;
             if (element !== null)
                 applyRef.current(getRef.current(), element);
-            raf = requestAnimationFrame(tick);
-        };
-        raf = requestAnimationFrame(tick);
-        return () => cancelAnimationFrame(raf);
+        });
     }, [ref]);
 }
-/**
- * A `<span>` whose text tracks a live value every frame (the 90% case of
- * useFrameBind). `<LiveText get={() => groundSpeed(car) * KMH} format={Math.round} />`.
- */
 export function LiveText({ get, format, className, style, }) {
     const ref = useRef(null);
     useFrameBind(ref, get, (value, element) => {

package/dist/map.d.ts

@@ -2,6 +2,7 @@ import { 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 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[];
 export declare function useFog(fog: FogField): ReturnType<FogField["cells"]>;
 export interface MinimapProps {
@@ -10,12 +11,21 @@ export interface MinimapProps {
     worldRadius: number;
     fog?: FogField;
     size?: number;
-    heading?: number;
+    /** Facing yaw (`rotationY`, forward = `(sin yaw, cos yaw)`) of the tracked entity — pass it raw, never pre-converted to a bearing. */
+    facingYaw?: number;
     rotate?: boolean;
     kindStyles?: Record<string, MarkerKindStyle>;
     background?: string;
     /** World bounds the `background` image spans, so it pans correctly under a player-centered map. */
     mapBounds?: MapBounds;
+    /** Route/corridor polylines drawn under the markers (#285.2); `forecast` routes dash. */
+    routes?: readonly MapRoute[];
+    /** Zone/hazard overlays with live fills and dashed forecast outlines (#285.1). */
+    zones?: readonly MapZone[];
+    /** Per-cell status heatmaps (#285.1) — pair with `world/cellStates`. */
+    cellStates?: readonly MapCellStates[];
+    /** Click-to-pin seam (#285.6): receives the clicked world XZ via `unprojectFromMinimap`. */
+    onWorldClick?: (world: WorldXZ) => void;
     className?: string;
     title?: string;
     children?: ReactNode;
@@ -31,9 +41,10 @@ export interface MapBounds {
  * fog overlay, categorized marker icons, and a facing arrow. Reads a core
  * `MarkerSet` / `FogField`; supply your own `kindStyles` palette to reskin.
  */
-export declare function Minimap({ markers, center, worldRadius, fog, size, heading, rotate, kindStyles, background, mapBounds, className, title, children, }: MinimapProps): ReactNode;
+export declare function Minimap({ markers, center, worldRadius, fog, size, facingYaw, rotate, kindStyles, background, mapBounds, routes, zones, cellStates, onWorldClick, className, title, children, }: MinimapProps): ReactNode;
 export interface CompassProps {
-    heading: number;
+    /** 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;
     width?: number;
@@ -42,20 +53,29 @@ export interface CompassProps {
     className?: string;
 }
 /**
- * Horizontal compass strip centered on the player's facing bearing, with the
+ * Horizontal compass strip centered on the player's facing direction, with the
  * eight cardinals and optional marker pips (bearing to each `MarkerSet` entry).
  */
-export declare function Compass({ heading, center, markers, width, fov, kindStyles, className, }: CompassProps): ReactNode;
+export declare function Compass({ facingYaw, center, markers, width, fov, kindStyles, className, }: CompassProps): ReactNode;
 export interface WorldMapProps {
     markers: MarkerSet;
     bounds: MapBounds;
     player?: WorldXZ;
-    heading?: number;
+    /** Facing yaw (`rotationY`, forward = `(sin yaw, cos yaw)`) of the player — pass it raw, never pre-converted to a bearing. */
+    facingYaw?: number;
     fog?: FogField;
     background?: string;
     width?: number;
     height?: number;
     kindStyles?: Record<string, MarkerKindStyle>;
+    /** Route/corridor polylines drawn under the markers (#285.2); `forecast` routes dash. */
+    routes?: readonly MapRoute[];
+    /** Zone/hazard overlays with live fills and dashed forecast outlines (#285.1). */
+    zones?: readonly MapZone[];
+    /** Per-cell status heatmaps (#285.1) — pair with `world/cellStates`. */
+    cellStates?: readonly MapCellStates[];
+    /** Click-to-pin seam (#285.6): receives the clicked world XZ. */
+    onWorldClick?: (world: WorldXZ) => void;
     className?: string;
     title?: string;
     onClose?: () => void;
@@ -65,4 +85,4 @@ export interface WorldMapProps {
  * background, reveal-on-event fog, all markers with labels, and the player.
  * Rectangular linear projection over the supplied world `bounds`.
  */
-export declare function WorldMap({ markers, bounds, player, heading, fog, background, width, height, kindStyles, className, title, onClose, }: WorldMapProps): ReactNode;
+export declare function WorldMap({ markers, bounds, player, facingYaw, fog, background, width, height, kindStyles, routes, zones, cellStates, onWorldClick, className, title, onClose, }: WorldMapProps): ReactNode;

package/dist/map.js

@@ -1,7 +1,73 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useSyncExternalStore } from "react";
+import { useMemo, useSyncExternalStore } from "react";
 import { DEFAULT_MARKER_KINDS, markerKindStyle, } from "@jgengine/core/world/markers";
-import { bearingToCardinal, clampToMinimapEdge, compassBearing, projectToMinimap, relativeBearing, } from "@jgengine/core/world/minimap";
+import { bearingToCardinal, clampToMinimapEdge, compassBearing, headingToBearing, projectToMinimap, relativeBearing, unprojectFromMinimap, } from "@jgengine/core/world/minimap";
+import { mapLayerColor, } from "@jgengine/core/world/mapLayers";
+import { createFogDataUrl } from "./fogOverlay.js";
+function routeNodes(routes, project, keyPrefix) {
+    if (routes === undefined)
+        return [];
+    return routes.map((route) => {
+        const points = route.closed === true && route.points.length > 1 ? [...route.points, route.points[0]] : route.points;
+        const path = points.map(([x, z]) => {
+            const at = project(x, z);
+            return `${at.x},${at.y}`;
+        });
+        return (_jsx("polyline", { "data-map-route": route.id, points: path.join(" "), fill: "none", stroke: mapLayerColor(route.tone), strokeWidth: route.width ?? 2, strokeLinejoin: "round", strokeLinecap: "round", opacity: 0.9, ...(route.forecast === true ? { strokeDasharray: "6 4" } : {}) }, `${keyPrefix}-route-${route.id}`));
+    });
+}
+function zoneNodes(zones, project, scale, keyPrefix) {
+    if (zones === undefined)
+        return [];
+    return zones.map((zone) => {
+        const color = mapLayerColor(zone.tone);
+        const forecast = zone.forecast === true;
+        const fill = forecast ? "none" : color;
+        const fillOpacity = forecast ? 0 : zone.opacity ?? 0.25;
+        const stroke = { stroke: color, strokeWidth: 1.5, ...(forecast ? { strokeDasharray: "6 4" } : {}) };
+        const shape = zone.shape;
+        let node = null;
+        let labelAt = null;
+        if (shape.kind === "circle") {
+            const at = project(shape.center[0], shape.center[1]);
+            labelAt = at;
+            node = (_jsx("ellipse", { cx: at.x, cy: at.y, rx: scale.x(shape.radius), ry: scale.y(shape.radius), fill: fill, fillOpacity: fillOpacity, ...stroke }));
+        }
+        else {
+            const corners = shape.kind === "rect"
+                ? rectCorners(shape).map(([x, z]) => project(x, z))
+                : shape.points.map(([x, z]) => project(x, z));
+            labelAt = corners[0] ?? null;
+            node = (_jsx("polygon", { points: corners.map((at) => `${at.x},${at.y}`).join(" "), fill: fill, fillOpacity: fillOpacity, ...stroke }));
+        }
+        return (_jsxs("g", { "data-map-zone": zone.id, opacity: 0.9, children: [node, zone.label !== undefined && labelAt !== null ? (_jsx("text", { x: labelAt.x, y: labelAt.y - 4, textAnchor: "middle", fontSize: 9, fill: color, style: { fontWeight: 700 }, children: zone.label })) : null] }, `${keyPrefix}-zone-${zone.id}`));
+    });
+}
+function rectCorners(shape) {
+    const halfW = shape.w / 2;
+    const halfD = shape.d / 2;
+    const rotate = shape.rotate ?? 0;
+    const cos = Math.cos(rotate);
+    const sin = Math.sin(rotate);
+    return [[-halfW, -halfD], [halfW, -halfD], [halfW, halfD], [-halfW, halfD]].map(([dx, dz]) => [
+        shape.center[0] + dx * cos - dz * sin,
+        shape.center[1] + dx * sin + dz * cos,
+    ]);
+}
+function cellStateNodes(layers, project, scale, keyPrefix) {
+    if (layers === undefined)
+        return [];
+    const nodes = [];
+    for (const layer of layers) {
+        const w = scale.x(layer.cellSize);
+        const h = scale.y(layer.cellSize);
+        for (const cell of layer.cells) {
+            const at = project(layer.origin[0] + cell.col * layer.cellSize, layer.origin[1] + cell.row * layer.cellSize);
+            nodes.push(_jsx("rect", { x: at.x - w / 2, y: at.y - h / 2, width: w, height: h, fill: mapLayerColor(cell.tone), opacity: cell.opacity ?? 0.35 }, `${keyPrefix}-${layer.id}-${cell.col}-${cell.row}`));
+        }
+    }
+    return nodes;
+}
 export function useMarkers(markers) {
     return useSyncExternalStore(markers.subscribe, markers.snapshot, markers.snapshot);
 }
@@ -13,34 +79,37 @@ export function useFog(fog) {
  * fog overlay, categorized marker icons, and a facing arrow. Reads a core
  * `MarkerSet` / `FogField`; supply your own `kindStyles` palette to reskin.
  */
-export function Minimap({ markers, center, worldRadius, fog, size = 176, heading = 0, rotate = false, kindStyles = DEFAULT_MARKER_KINDS, background, mapBounds, 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, 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);
     const view = {
         center,
         worldRadius,
         size,
-        ...(rotate ? { rotate: -heading } : {}),
+        ...(rotate ? { rotate: bearing } : {}),
     };
     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 fogRects = [];
-    if (fogCells !== null) {
+    const fogImage = useMemo(() => {
+        if (fogCells === null)
+            return null;
         const cellPx = (fogCells.cellSize / worldRadius) * half;
-        for (let row = 0; row < fogCells.rows; row += 1) {
-            for (let col = 0; col < fogCells.cols; col += 1) {
-                if (fogCells.revealed[row * fogCells.cols + col])
-                    continue;
-                const worldX = fogCells.minX + (col + 0.5) * fogCells.cellSize;
-                const worldZ = fogCells.minZ + (row + 0.5) * fogCells.cellSize;
-                const projected = projectToMinimap([worldX, worldZ], view);
-                if (projected.distance > worldRadius + fogCells.cellSize)
-                    continue;
-                fogRects.push(_jsx("rect", { x: projected.x - cellPx / 2 - 0.5, y: projected.y - cellPx / 2 - 0.5, width: cellPx + 1, height: cellPx + 1, fill: "#0b0f14", opacity: 0.82 }, `fog-${col}-${row}`));
-            }
-        }
-    }
+        return createFogDataUrl(fogCells, { width: size, height: size }, (col, row) => {
+            const worldX = fogCells.minX + (col + 0.5) * fogCells.cellSize;
+            const worldZ = fogCells.minZ + (row + 0.5) * fogCells.cellSize;
+            const projected = projectToMinimap([worldX, worldZ], view);
+            if (projected.distance > worldRadius + fogCells.cellSize)
+                return null;
+            return {
+                x: projected.x - cellPx / 2 - 0.5,
+                y: projected.y - cellPx / 2 - 0.5,
+                width: cellPx + 1,
+                height: cellPx + 1,
+            };
+        });
+    }, [fogCells, center[0], center[1], worldRadius, size, rotate, bearing]);
     return (_jsxs("div", { className: className, "data-minimap": true, style: {
             width: size,
             borderRadius: 14,
@@ -59,7 +128,17 @@ export function Minimap({ markers, center, worldRadius, fog, size = 176, heading
                     letterSpacing: 1.4,
                     textTransform: "uppercase",
                     color: "rgba(203,213,225,0.75)",
-                }, children: [_jsx("span", { children: title }), _jsx("span", { style: { color: "rgba(148,163,184,0.6)" }, children: bearingToCardinal(heading) })] }), _jsxs("svg", { width: size, height: size, viewBox: `0 0 ${size} ${size}`, "data-minimap-canvas": true, children: [_jsx("defs", { children: _jsx("clipPath", { id: clipId, children: _jsx("circle", { cx: half, cy: half, r: half - 1 }) }) }), _jsxs("g", { clipPath: `url(#${clipId})`, children: [_jsx("circle", { cx: half, cy: half, r: half - 1, fill: "#1c2733" }), background !== undefined
+                }, children: [_jsx("span", { children: title }), _jsx("span", { style: { color: "rgba(148,163,184,0.6)" }, children: bearingToCardinal(bearing) })] }), _jsxs("svg", { width: size, height: size, viewBox: `0 0 ${size} ${size}`, "data-minimap-canvas": true, ...(onWorldClick === undefined
+                    ? {}
+                    : {
+                        onClick: (event) => {
+                            const rect = event.currentTarget.getBoundingClientRect();
+                            const px = ((event.clientX - rect.left) / rect.width) * size;
+                            const py = ((event.clientY - rect.top) / rect.height) * size;
+                            onWorldClick(unprojectFromMinimap({ x: px, y: py }, view));
+                        },
+                        style: { cursor: "crosshair" },
+                    }), children: [_jsx("defs", { children: _jsx("clipPath", { id: clipId, children: _jsx("circle", { cx: half, cy: half, r: half - 1 }) }) }), _jsxs("g", { clipPath: `url(#${clipId})`, children: [_jsx("circle", { cx: half, cy: half, r: half - 1, fill: "#1c2733" }), background !== undefined
                                 ? (() => {
                                     if (mapBounds === undefined) {
                                         return (_jsx("image", { href: background, x: 0, y: 0, width: size, height: size, preserveAspectRatio: "xMidYMid slice", opacity: 0.9 }));
@@ -67,12 +146,21 @@ export function Minimap({ markers, center, worldRadius, fog, size = 176, heading
                                     const pxPerWorld = half / worldRadius;
                                     return (_jsx("image", { href: background, x: half + (mapBounds.minX - center[0]) * pxPerWorld, y: half + (mapBounds.minZ - center[1]) * pxPerWorld, width: (mapBounds.maxX - mapBounds.minX) * pxPerWorld, height: (mapBounds.maxZ - mapBounds.minZ) * pxPerWorld, preserveAspectRatio: "none", opacity: 0.92 }));
                                 })()
-                                : null, fogRects, _jsx("circle", { cx: half, cy: half, r: half - 1, fill: "none", stroke: "rgba(148,163,184,0.12)" }), sorted.map((marker) => {
+                                : null, fogImage !== null ? (_jsx("image", { href: fogImage, x: 0, y: 0, width: size, height: size, preserveAspectRatio: "none" })) : null, (() => {
+                                const projectXZ = (x, z) => projectToMinimap([x, z], view);
+                                const pxPerWorld = worldRadius === 0 ? 0 : half / worldRadius;
+                                const layerScale = { x: (units) => units * pxPerWorld, y: (units) => units * pxPerWorld };
+                                return [
+                                    ...cellStateNodes(cellStates, projectXZ, layerScale, "mm"),
+                                    ...zoneNodes(zones, projectXZ, layerScale, "mm"),
+                                    ...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 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));
-                            }), _jsx("g", { transform: `translate(${half} ${half}) rotate(${(rotate ? 0 : heading) * (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] }));
+                            }), _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] }));
 }
 const NO_SUBSCRIBE = () => () => undefined;
 const NULL_CELLS = () => null;
@@ -89,14 +177,15 @@ const COMPASS_TICKS = [
     { cardinal: "NW", bearing: (7 * Math.PI) / 4 },
 ];
 /**
- * Horizontal compass strip centered on the player's facing bearing, with the
+ * Horizontal compass strip centered on the player's facing direction, with the
  * eight cardinals and optional marker pips (bearing to each `MarkerSet` entry).
  */
-export function Compass({ heading, center, markers, width = 340, fov = (Math.PI * 2) / 3, kindStyles = DEFAULT_MARKER_KINDS, className, }) {
+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 facingBearing = headingToBearing(facingYaw);
     const half = fov / 2;
     const toX = (bearing) => {
-        const delta = relativeBearing(bearing, heading);
+        const delta = relativeBearing(bearing, facingBearing);
         if (Math.abs(delta) > half)
             return null;
         return width / 2 + (delta / half) * (width / 2);
@@ -151,12 +240,27 @@ export function Compass({ heading, center, markers, width = 340, fov = (Math.PI
                 })
                 : null] }));
 }
+function WorldMapFogImage({ fogCells, project, worldW, worldD, width, mapH, }) {
+    const fogImage = useMemo(() => {
+        if (fogCells === null)
+            return null;
+        const cellW = (fogCells.cellSize / worldW) * width;
+        const cellH = (fogCells.cellSize / worldD) * mapH;
+        return createFogDataUrl(fogCells, { width, height: mapH }, (col, row) => {
+            const at = project(fogCells.minX + col * fogCells.cellSize, fogCells.minZ + row * fogCells.cellSize);
+            return { x: at.x, y: at.y, width: cellW + 0.5, height: cellH + 0.5 };
+        }, "rgba(11, 15, 20, 0.86)");
+    }, [fogCells, project, worldW, worldD, width, mapH]);
+    if (fogImage === null)
+        return null;
+    return _jsx("image", { href: fogImage, x: 0, y: 0, width: width, height: mapH, preserveAspectRatio: "none" });
+}
 /**
  * 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`.
  */
-export function WorldMap({ markers, bounds, player, heading = 0, fog, background, width = 520, height, kindStyles = DEFAULT_MARKER_KINDS, className, title = "World Map", onClose, }) {
+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, }) {
     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;
@@ -182,29 +286,34 @@ export function WorldMap({ markers, bounds, player, heading = 0, fog, background
                             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 }, 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, fogCells !== null
-                        ? (() => {
-                            const cellW = (fogCells.cellSize / worldW) * width;
-                            const cellH = (fogCells.cellSize / worldD) * mapH;
-                            const rects = [];
-                            for (let row = 0; row < fogCells.rows; row += 1) {
-                                for (let col = 0; col < fogCells.cols; col += 1) {
-                                    if (fogCells.revealed[row * fogCells.cols + col])
-                                        continue;
-                                    const at = project(fogCells.minX + col * fogCells.cellSize, fogCells.minZ + row * fogCells.cellSize);
-                                    rects.push(_jsx("rect", { x: at.x, y: at.y, width: cellW + 0.5, height: cellH + 0.5, fill: "#0b0f14", opacity: 0.86 }, `wfog-${col}-${row}`));
-                                }
-                            }
-                            return rects;
-                        })()
-                        : null, markerList.map((marker) => {
+                        }, 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 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));
                     }), player !== undefined
                         ? (() => {
                             const at = project(player[0], player[1]);
-                            return (_jsx("g", { transform: `translate(${at.x} ${at.y}) rotate(${heading * (180 / Math.PI)})`, children: _jsx("path", { d: "M0,-11 L7,9 L0,4 L-7,9 Z", fill: "#4ade80", stroke: "#052e16", strokeWidth: 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] })] }));
 }

package/dist/preview.d.ts

@@ -0,0 +1,6 @@
+import type { ComponentType } from "react";
+export type GamePreviewProps = {
+    className?: string;
+};
+export type GamePreviewComponent = ComponentType<GamePreviewProps>;
+export type GamePreviewStates = Record<string, GamePreviewComponent>;

package/dist/preview.js

@@ -0,0 +1 @@
+export {};

package/dist/selectSnapshot.d.ts

@@ -0,0 +1,7 @@
+export type SelectCache<TSnapshot, TSelected> = {
+    ready: boolean;
+    snapshot: TSnapshot;
+    value: TSelected;
+};
+export declare function createSelectCache<TSnapshot, TSelected>(): SelectCache<TSnapshot, TSelected>;
+export declare function readSelectSnapshot<TSnapshot, TSelected>(cache: SelectCache<TSnapshot, TSelected>, snapshot: TSnapshot, select: (snapshot: TSnapshot) => TSelected, isEqual?: (previous: TSelected, next: TSelected) => boolean): TSelected;

package/dist/selectSnapshot.js

@@ -0,0 +1,16 @@
+export function createSelectCache() {
+    return { ready: false, snapshot: undefined, value: undefined };
+}
+export function readSelectSnapshot(cache, snapshot, select, isEqual = Object.is) {
+    if (cache.ready && Object.is(cache.snapshot, snapshot))
+        return cache.value;
+    const next = select(snapshot);
+    if (cache.ready && isEqual(cache.value, next)) {
+        cache.snapshot = snapshot;
+        return cache.value;
+    }
+    cache.ready = true;
+    cache.snapshot = snapshot;
+    cache.value = next;
+    return cache.value;
+}

package/dist/settings.d.ts

@@ -0,0 +1,75 @@
+import { type ReactNode } from "react";
+import { type SettingCategory, type SettingKind, type SettingOption, type SettingsStore, type SettingsSurface, type SettingsVariant, type SettingValue } from "@jgengine/core/settings/settingsModel";
+export declare function SettingsProvider({ store, children }: {
+    store: SettingsStore;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** The shared settings store, or a standalone one when no provider is mounted (game code read outside the shell). */
+export declare function useSettingsStore(): SettingsStore;
+/** Read + write one persisted setting; re-renders when the value changes anywhere. */
+export declare function useSetting<T extends SettingValue>(id: string, fallback: T): readonly [T, (value: SettingValue) => void];
+export interface SettingsRow {
+    id: string;
+    label: string;
+    kind: SettingKind;
+    value: SettingValue;
+    min?: number;
+    max?: number;
+    step?: number;
+    options?: readonly SettingOption[];
+    format?: (value: number) => string;
+    set: (value: SettingValue) => void;
+}
+export interface SettingsKeybindRow {
+    action: string;
+    label: string;
+    bindingLabel: string;
+    isDefault: boolean;
+    rebind: (code: string) => void;
+    reset: () => void;
+}
+export interface SettingsCategoryView {
+    id: SettingCategory;
+    label: string;
+    rows: SettingsRow[];
+    keybinds: SettingsKeybindRow[];
+}
+/** A resolved game-state action — `run` is already bound to the game context and closes the menu. */
+export interface SettingsActionView {
+    id: string;
+    label: string;
+    kind: "default" | "danger";
+    description?: string;
+    run: () => void;
+}
+/** The live settings controller — every category/row/keybind/action plus open-state. Render it any way you like or drive the engine menu. */
+export interface SettingsController {
+    categories: SettingsCategoryView[];
+    /** Game-state actions (Restart, Quit…) — the menu shows them as its first "Game" tab. */
+    actions: SettingsActionView[];
+    variant: SettingsVariant;
+    surface: SettingsSurface | false;
+    isOpen: boolean;
+    open: () => void;
+    close: () => void;
+    setOpen: (open: boolean) => void;
+}
+export declare function SettingsControllerProvider({ controller, children, }: {
+    controller: SettingsController;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** The engine settings controller for the current game — render your own settings UI from `categories`, or open the built-in menu with `open()`. Null-safe stub when mounted outside the shell. */
+export declare function useSettings(): SettingsController;
+/** True when the game has any setting or game-action to show — gate your own settings entry on it. */
+export declare function useHasSettings(): boolean;
+/**
+ * Inline settings entry — drop it anywhere in your game's menu or HUD; it opens
+ * the themed settings menu. Headless: pass `className` for placement/skin and
+ * `children` to replace the default gear glyph. Renders nothing when the game
+ * has no settings to show, so it never leaves a dead button behind.
+ */
+export declare function SettingsTrigger({ className, children, label, }: {
+    className?: string;
+    children?: ReactNode;
+    label?: string;
+}): import("react").JSX.Element | null;

package/dist/settings.js

@@ -0,0 +1,61 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useSyncExternalStore } from "react";
+import { createSettingsStore, } from "@jgengine/core/settings/settingsModel";
+const SettingsStoreContext = createContext(null);
+export function SettingsProvider({ store, children }) {
+    return _jsx(SettingsStoreContext.Provider, { value: store, children: children });
+}
+/** The shared settings store, or a standalone one when no provider is mounted (game code read outside the shell). */
+export function useSettingsStore() {
+    const store = useContext(SettingsStoreContext);
+    return store ?? fallbackStore();
+}
+let standalone = null;
+function fallbackStore() {
+    if (standalone === null)
+        standalone = createSettingsStore();
+    return standalone;
+}
+/** Read + write one persisted setting; re-renders when the value changes anywhere. */
+export function useSetting(id, fallback) {
+    const store = useSettingsStore();
+    const value = useSyncExternalStore(store.subscribe, () => store.get(id, fallback), () => fallback);
+    const set = useCallback((next) => store.set(id, next), [store, id]);
+    return [value, set];
+}
+const SettingsControllerContext = createContext(null);
+export function SettingsControllerProvider({ controller, children, }) {
+    return _jsx(SettingsControllerContext.Provider, { value: controller, children: children });
+}
+/** The engine settings controller for the current game — render your own settings UI from `categories`, or open the built-in menu with `open()`. Null-safe stub when mounted outside the shell. */
+export function useSettings() {
+    return useContext(SettingsControllerContext) ?? EMPTY_CONTROLLER;
+}
+const noop = () => undefined;
+const EMPTY_CONTROLLER = {
+    categories: [],
+    actions: [],
+    variant: "panel",
+    surface: false,
+    isOpen: false,
+    open: noop,
+    close: noop,
+    setOpen: noop,
+};
+/** True when the game has any setting or game-action to show — gate your own settings entry on it. */
+export function useHasSettings() {
+    const s = useSettings();
+    return s.categories.length > 0 || s.actions.length > 0;
+}
+/**
+ * Inline settings entry — drop it anywhere in your game's menu or HUD; it opens
+ * the themed settings menu. Headless: pass `className` for placement/skin and
+ * `children` to replace the default gear glyph. Renders nothing when the game
+ * has no settings to show, so it never leaves a dead button behind.
+ */
+export function SettingsTrigger({ className, children, label = "Settings", }) {
+    const settings = useSettings();
+    if (settings.categories.length === 0 && settings.actions.length === 0)
+        return null;
+    return (_jsx("button", { type: "button", "aria-label": label, onClick: settings.open, className: className, children: children ?? (_jsxs("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: 1.8, strokeLinecap: "round", strokeLinejoin: "round", width: "1em", height: "1em", "aria-hidden": true, children: [_jsx("circle", { cx: "12", cy: "12", r: "3" }), _jsx("path", { d: "M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 1 1-2.83 2.83l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 1 1-4 0v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 1 1-2.83-2.83l.06-.06a1.65 1.65 0 0 0 .33-1.82 1.65 1.65 0 0 0-1.51-1H3a2 2 0 1 1 0-4h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 1 1 2.83-2.83l.06.06a1.65 1.65 0 0 0 1.82.33H9a1.65 1.65 0 0 0 1-1.51V3a2 2 0 1 1 4 0v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 1 1 2.83 2.83l-.06.06a1.65 1.65 0 0 0-.33 1.82V9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 1 1 0 4h-.09a1.65 1.65 0 0 0-1.51 1z" })] })) }));
+}

package/dist/skillCheckPaint.d.ts

@@ -0,0 +1,4 @@
+import type { SkillCheckConfig, SkillCheckResult } from "@jgengine/core/interaction/skillCheck";
+import type { QteStep } from "@jgengine/core/interaction/qte";
+export declare function paintSkillCheckDom(root: HTMLElement, zone: HTMLElement, marker: HTMLElement, config: SkillCheckConfig, result: SkillCheckResult): void;
+export declare function paintQteStepDom(elements: ReadonlyMap<string, HTMLElement>, steps: readonly QteStep[], elapsed: number, activeId: string | null, stepClassName?: string, activeClassName?: string, doneClassName?: string): void;

package/dist/skillCheckPaint.js

@@ -0,0 +1,28 @@
+export function paintSkillCheckDom(root, zone, marker, config, result) {
+    const zoneLeft = (result.zone.start / config.trackWidth) * 100;
+    const zoneWidth = ((result.zone.end - result.zone.start) / config.trackWidth) * 100;
+    const markerLeft = (result.markerPosition / config.trackWidth) * 100;
+    zone.style.left = `${zoneLeft}%`;
+    zone.style.width = `${zoneWidth}%`;
+    marker.style.left = `${markerLeft}%`;
+    root.dataset.inZone = result.success ? "true" : "false";
+    root.dataset.timedOut = result.timedOut ? "true" : "false";
+}
+export function paintQteStepDom(elements, steps, elapsed, activeId, stepClassName, activeClassName, doneClassName) {
+    for (const step of steps) {
+        const el = elements.get(step.id);
+        if (el === undefined)
+            continue;
+        const isActive = activeId === step.id;
+        const isDone = elapsed > step.windowEnd;
+        const classes = [stepClassName, isActive ? activeClassName : isDone ? doneClassName : undefined]
+            .filter(Boolean)
+            .join(" ");
+        if (classes.length > 0)
+            el.className = classes;
+        else
+            el.removeAttribute("class");
+        el.dataset.active = isActive ? "true" : "false";
+        el.dataset.done = isDone ? "true" : "false";
+    }
+}