@jgengine/react 0.8.0 → 0.10.0

package/dist/liveBind.d.ts

@@ -1,20 +1,14 @@
 import { type CSSProperties } 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.
- */
+type FrameSubscriber = () => void;
+export declare function subscribeFrameBind(subscriber: FrameSubscriber): () => void;
+export declare function frameBindSubscriberCount(): number;
 export declare function useFrameBind<T, E extends Element = Element>(ref: {
     current: E | null;
 }, get: () => T, apply: (value: T, element: E) => void): void;
-/**
- * A `<span>` whose text tracks a live value every frame (the 90% case of
- * useFrameBind). `<LiveText get={() => groundSpeed(car) * KMH} format={Math.round} />`.
- */
 export declare function LiveText({ get, format, className, style, }: {
     get: () => number | string;
     format?: (value: number | string) => string;
     className?: string;
     style?: CSSProperties;
 }): import("react").JSX.Element;
+export {};

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/provider.d.ts

@@ -5,3 +5,5 @@ export declare function GameProvider({ context, children }: {
     children?: ReactNode;
 }): import("react").JSX.Element;
 export declare function useGameContext(): GameContext;
+/** The game context if a `GameProvider` is present, otherwise `null` — for chrome that may render outside a running game (showcases, previews). */
+export declare function useOptionalGameContext(): GameContext | null;

package/dist/provider.js

@@ -10,3 +10,7 @@ export function useGameContext() {
         throw new Error("useGameContext must be used within <GameProvider>");
     return ctx;
 }
+/** The game context if a `GameProvider` is present, otherwise `null` — for chrome that may render outside a running game (showcases, previews). */
+export function useOptionalGameContext() {
+    return useContext(GameReactContext);
+}

package/dist/rotateDevice.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Engine-owned rotate-device screen. A polished, non-dismissible full-viewport
+ * gate shown when a game requires an orientation the device isn't in. It owns
+ * the visible viewport (visualViewport-sized), respects safe areas, blocks all
+ * pointer/touch input to the game beneath, and is themeable through `--jg-*`
+ * tokens. Reduced-motion respected. This is game UI, not a website toast.
+ */
+import type { CSSProperties, ReactNode } from "react";
+import type { LayoutOrientation } from "@jgengine/core/ui/orientation";
+/** Full-viewport, non-dismissible rotate-device gate shown when a game requires an orientation the device isn't in. */
+export declare function RotateDeviceScreen({ title, description, requiredOrientation, accent, icon, className, style, }: {
+    /** Short headline. */
+    title?: string;
+    /** One concise explanatory line. Defaults from `requiredOrientation`. */
+    description?: string;
+    /** Orientation the game needs. Drives the rotation animation direction. */
+    requiredOrientation?: LayoutOrientation;
+    /** Illustration/token color. */
+    accent?: string;
+    /** Custom illustration; defaults to an animated phone glyph. */
+    icon?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}): import("react").JSX.Element;

package/dist/rotateDevice.js

@@ -0,0 +1,83 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const STYLE_ID = "jg-rotate-device-style";
+const ROTATE_CSS = `
+.jg-rotate-root {
+  position: fixed;
+  inset: 0;
+  z-index: 2147483000;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--jg-visual-viewport-width, 100vw);
+  height: var(--jg-visual-viewport-height, 100dvh);
+  min-height: var(--jg-visual-viewport-height, 100vh);
+  padding: calc(env(safe-area-inset-top, 0px) + 24px) calc(env(safe-area-inset-right, 0px) + 24px)
+    calc(env(safe-area-inset-bottom, 0px) + 24px) calc(env(safe-area-inset-left, 0px) + 24px);
+  color: var(--jg-text, #f4f4f6);
+  background:
+    radial-gradient(120% 120% at 50% 0%, var(--jg-accent-dim, rgba(120, 130, 160, 0.18)), transparent 60%),
+    var(--jg-surface, #0b0d13);
+  touch-action: none;
+  user-select: none;
+  -webkit-user-select: none;
+  overflow: hidden;
+}
+.jg-rotate-inner {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 22px;
+  text-align: center;
+  max-width: 22rem;
+}
+.jg-rotate-phone {
+  transform-origin: 50% 50%;
+}
+.jg-rotate-title {
+  margin: 0;
+  font: 700 clamp(1.25rem, 5vw, 1.75rem) / 1.15 system-ui, -apple-system, "Segoe UI", sans-serif;
+  letter-spacing: -0.01em;
+}
+.jg-rotate-desc {
+  margin: 0;
+  font: 400 clamp(0.9rem, 3.4vw, 1.05rem) / 1.5 system-ui, -apple-system, "Segoe UI", sans-serif;
+  color: var(--jg-text-dim, rgba(244, 244, 246, 0.66));
+}
+@media (prefers-reduced-motion: no-preference) {
+  .jg-rotate-phone--to-landscape { animation: jg-rotate-to-landscape 2.6s cubic-bezier(0.65, 0, 0.35, 1) infinite; }
+  .jg-rotate-phone--to-portrait { animation: jg-rotate-to-portrait 2.6s cubic-bezier(0.65, 0, 0.35, 1) infinite; }
+}
+@keyframes jg-rotate-to-landscape {
+  0%, 22% { transform: rotate(0deg); }
+  55%, 78% { transform: rotate(-90deg); }
+  100% { transform: rotate(-90deg); }
+}
+@keyframes jg-rotate-to-portrait {
+  0%, 22% { transform: rotate(-90deg); }
+  55%, 78% { transform: rotate(0deg); }
+  100% { transform: rotate(0deg); }
+}
+`;
+function ensureStyle() {
+    if (typeof document === "undefined")
+        return;
+    if (document.getElementById(STYLE_ID) !== null)
+        return;
+    const el = document.createElement("style");
+    el.id = STYLE_ID;
+    el.textContent = ROTATE_CSS;
+    document.head.appendChild(el);
+}
+function PhoneGlyph({ accent }) {
+    return (_jsxs("svg", { width: "96", height: "96", viewBox: "0 0 96 96", fill: "none", "aria-hidden": true, focusable: "false", children: [_jsx("rect", { x: "34", y: "10", width: "28", height: "52", rx: "6", stroke: accent, strokeWidth: "3", fill: "none" }), _jsx("rect", { x: "39", y: "18", width: "18", height: "34", rx: "2", fill: accent, opacity: "0.22" }), _jsx("circle", { cx: "48", cy: "57.5", r: "1.8", fill: accent }), _jsx("path", { d: "M22 74a30 30 0 0 1 52 0", stroke: accent, strokeWidth: "3", strokeLinecap: "round", fill: "none", opacity: "0.5" }), _jsx("path", { d: "M70 68l6 8-10 1z", fill: accent, opacity: "0.5" })] }));
+}
+/** Full-viewport, non-dismissible rotate-device gate shown when a game requires an orientation the device isn't in. */
+export function RotateDeviceScreen({ title = "Turn your device", description, requiredOrientation = "landscape", accent = "var(--jg-accent, #8ea2ff)", icon, className, style, }) {
+    ensureStyle();
+    const line = description ??
+        (requiredOrientation === "landscape"
+            ? "Rotate to landscape to play."
+            : "Rotate to portrait to play.");
+    const spin = requiredOrientation === "landscape" ? "jg-rotate-phone--to-landscape" : "jg-rotate-phone--to-portrait";
+    return (_jsx("div", { className: className === undefined ? "jg-rotate-root" : `jg-rotate-root ${className}`, style: style, "data-jg-orientation-gate": requiredOrientation, role: "dialog", "aria-modal": "true", "aria-label": title, onPointerDownCapture: (e) => e.stopPropagation(), onTouchStartCapture: (e) => e.stopPropagation(), children: _jsxs("div", { className: "jg-rotate-inner", children: [_jsx("div", { className: `jg-rotate-phone ${spin}`, children: icon ?? _jsx(PhoneGlyph, { accent: accent }) }), _jsx("h2", { className: "jg-rotate-title", children: title }), _jsx("p", { className: "jg-rotate-desc", children: line })] }) }));
+}

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