@jgengine/react 0.10.0 → 0.11.0

package/dist/hudLayout.d.ts

@@ -1,5 +1,6 @@
 import { type CSSProperties, type ReactNode } from "react";
 import { type HudAnchor, type HudLayoutStore } from "@jgengine/core/ui/hudLayout";
+import { type EditorUiDocument } from "@jgengine/core/ui/hudDocument";
 import { type HudPriority, type MobileHudBehavior } from "@jgengine/core/ui/gameLayout";
 import type { GamePhase } from "@jgengine/core/game/gamePhase";
 /** Whether a HUD element opted into `showDuring` is visible in the current phase; `undefined` = always visible (default). */
@@ -18,6 +19,13 @@ export declare function useHudLayout(options?: {
     storageKey?: string;
     snap?: number;
     locked?: boolean;
+    /**
+     * Scene-document `ui` section — source of truth for panel placement/size.
+     * When provided, hydrates the layout store (and wins over legacy localStorage).
+     */
+    documentUi?: EditorUiDocument;
+    /** When true (default), canvas moves/resizes write undoable `setUiPanel` patches to a live editor host. */
+    documentPatches?: boolean;
 }): HudLayoutStore;
 /**
  * Full-viewport HUD surface. Panels declared with `HudPanel` flow into nine
@@ -44,7 +52,7 @@ export declare function HudCanvas({ layout, editChord, compactScale, showDuring,
  * leaves the flow and keeps its custom placement. On compact displays custom
  * placements are ignored and the `compact` behavior applies.
  */
-export declare function HudPanel({ id, anchor, order, compact: compactMode, chip, interactive, inset, locked, showDuring, priority, mobileBehavior, allowOverlapWith, collisionGroup, region, className, style, children, }: {
+export declare function HudPanel({ id, anchor, order, compact: compactMode, chip, interactive, inset, locked, showDuring, priority, mobileBehavior, allowOverlapWith, collisionGroup, region, width, height, type, className, style, children, }: {
     id: string;
     anchor?: HudAnchor;
     /** Stack position within the region, ascending outward from the screen edge. Default 0. */
@@ -55,7 +63,10 @@ export declare function HudPanel({ id, anchor, order, compact: compactMode, chip
     chip?: string;
     /** `false` lets pointer events pass through to the game (read-only panels). Default true. */
     interactive?: boolean;
-    /** Legacy pixel inset from the anchor; only used as the reset placement for dragged panels. */
+    /**
+     * Fallback pixel inset from the anchor when the scene document has no `ui.panels[id]`.
+     * Document layout is the source of truth once authored; TSX props are fallback-only.
+     */
     inset?: {
         x: number;
         y: number;
@@ -73,6 +84,12 @@ export declare function HudPanel({ id, anchor, order, compact: compactMode, chip
     collisionGroup?: string;
     /** Register this panel as a collision-tracked layout region. Default true. */
     region?: boolean;
+    /** Fallback width when the document has not authored a size. */
+    width?: number;
+    /** Fallback height when the document has not authored a size. */
+    height?: number;
+    /** Panel type id ({@link registerHudPanelType}) — drives resize axes + ParamSchema. */
+    type?: string;
     className?: string;
     style?: CSSProperties;
     children?: ReactNode;

package/dist/hudLayout.js

@@ -1,7 +1,8 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { createContext, useContext, useEffect, useMemo, useRef, useState, } from "react";
 import { createPortal } from "react-dom";
-import { HUD_ANCHOR_FRACTIONS, anchoredPlacement, createHudLayout, isPanelDraggable, } from "@jgengine/core/ui/hudLayout";
+import { HUD_ANCHOR_FRACTIONS, anchoredPlacement, createHudLayout, isPanelDraggable, registerActiveHudLayout, } from "@jgengine/core/ui/hudLayout";
+import { resizePanelSize, resolvePanelResize, } from "@jgengine/core/ui/hudDocument";
 import { hudScaleForViewport, overflowingPanels, resolveHudFit } from "@jgengine/core/ui/hudScale";
 import { isMobileMode, } from "@jgengine/core/ui/gameLayout";
 import { useDisplayProfile } from "./display.js";
@@ -20,18 +21,73 @@ const EDIT_BAR_Z = 100000;
 const REGION_GAP = 10;
 const COMPACT_HUD_SCALE = 0.85;
 const HUD_ANCHORS = Object.keys(HUD_ANCHOR_FRACTIONS);
+function patchDocumentUi(id, panel) {
+    if (typeof window === "undefined")
+        return;
+    const host = window.__jgengineEditorHost;
+    if (host === undefined)
+        return;
+    host.handle({
+        method: "dispatch",
+        command: { type: "setUiPanel", id, patch: panel },
+    });
+}
+function sizeStyle(panel) {
+    if (panel === undefined)
+        return {};
+    return {
+        ...(panel.width === undefined ? {} : { width: panel.width }),
+        ...(panel.height === undefined ? {} : { height: panel.height }),
+    };
+}
+function ResizeHandles({ axes, onResizeStart, }) {
+    if (axes === "none")
+        return null;
+    const handle = (edge, cursor, style) => (_jsx("div", { "data-hud-resize": edge, onPointerDown: (event) => {
+            event.stopPropagation();
+            onResizeStart(edge, event);
+        }, style: {
+            position: "absolute",
+            zIndex: 3,
+            pointerEvents: "auto",
+            background: "rgba(255, 255, 255, 0.85)",
+            cursor,
+            ...style,
+        } }, edge));
+    return (_jsxs(_Fragment, { children: [axes === "x" || axes === "both"
+                ? handle("e", "ew-resize", { top: 4, bottom: 4, right: -3, width: 6 })
+                : null, axes === "y" || axes === "both"
+                ? handle("s", "ns-resize", { left: 4, right: 4, bottom: -3, height: 6 })
+                : null, axes === "both" ? handle("se", "nwse-resize", { right: -4, bottom: -4, width: 10, height: 10 }) : null] }));
+}
 export function useHudLayout(options) {
     const storageKey = options?.storageKey;
     const snap = options?.snap;
     const locked = options?.locked;
+    const documentUi = options?.documentUi;
+    const documentPatches = options?.documentPatches !== false;
     const layout = useMemo(() => {
-        const store = createHudLayout({ snap, locked });
-        if (storageKey !== undefined && typeof localStorage !== "undefined") {
+        const store = createHudLayout({
+            snap,
+            locked,
+            onDocumentPatch: documentPatches ? patchDocumentUi : undefined,
+        });
+        if (documentUi !== undefined) {
+            store.applyDocumentUi(documentUi);
+        }
+        else if (storageKey !== undefined && typeof localStorage !== "undefined") {
             store.hydrate(localStorage.getItem(STORAGE_PREFIX + storageKey));
         }
         return store;
-    }, [storageKey, snap, locked]);
+    }, [storageKey, snap, locked, documentPatches]);
+    useEffect(() => {
+        if (documentUi !== undefined) {
+            layout.applyDocumentUi(documentUi);
+        }
+    }, [layout, documentUi]);
     useEffect(() => {
+        if (documentUi !== undefined)
+            return;
         if (storageKey === undefined || typeof localStorage === "undefined")
             return;
         let timer = null;
@@ -50,7 +106,7 @@ export function useHudLayout(options) {
                 localStorage.setItem(STORAGE_PREFIX + storageKey, layout.serialize());
             }
         };
-    }, [layout, storageKey]);
+    }, [layout, storageKey, documentUi]);
     return layout;
 }
 const HudCanvasContext = createContext(null);
@@ -160,6 +216,7 @@ export function HudCanvas({ layout, editChord, compactScale, showDuring, classNa
     }, []);
     const value = useMemo(() => ({ layout, canvasRef, regions, compact }), [layout, regions, compact]);
     const editing = useEngineState(layout).editing;
+    useEffect(() => registerActiveHudLayout(layout), [layout]);
     const chordEnabled = editChord !== false;
     const hold = editChord === false ? undefined : (editChord?.hold ?? "F2");
     const press = editChord === false ? undefined : (editChord?.press ?? "KeyC");
@@ -344,7 +401,7 @@ function HudChip({ label, anchor, children, }) {
  * leaves the flow and keeps its custom placement. On compact displays custom
  * placements are ignored and the `compact` behavior applies.
  */
-export function HudPanel({ id, anchor = "top-left", order, compact: compactMode = "keep", chip, interactive, inset, locked, showDuring, priority, mobileBehavior, allowOverlapWith, collisionGroup, region = true, className, style, children, }) {
+export function HudPanel({ id, anchor = "top-left", order, compact: compactMode = "keep", chip, interactive, inset, locked, showDuring, priority, mobileBehavior, allowOverlapWith, collisionGroup, region = true, width, height, type, className, style, children, }) {
     const ctx = useContext(HudCanvasContext);
     const phase = useOptionalGamePhase();
     const layoutMode = useGameLayoutMode();
@@ -355,12 +412,18 @@ export function HudPanel({ id, anchor = "top-left", order, compact: compactMode
     const registeredOnRef = useRef(null);
     if (registeredOnRef.current !== layout) {
         registeredOnRef.current = layout;
-        layout.register(id, anchoredPlacement(anchor, inset ?? { x: 16, y: 16 }));
+        layout.register(id, anchoredPlacement(anchor, inset ?? { x: 16, y: 16 }), {
+            width,
+            height,
+            type,
+        });
     }
     const layoutState = useEngineState(layout);
     const panel = layoutState.panels[id];
     const draggable = !compact && locked !== true && isPanelDraggable(layoutState, id);
     const editing = layoutState.editing && draggable;
+    const resizeSpec = resolvePanelResize(panel?.type ?? type);
+    const resizable = editing && resizeSpec.axes !== "none";
     const rootRef = useRef(null);
     const dragRef = useRef(null);
     const suppressClickRef = useRef(false);
@@ -368,6 +431,7 @@ export function HudPanel({ id, anchor = "top-left", order, compact: compactMode
     const [dragging, setDragging] = useState(false);
     useEffect(() => () => detachRef.current?.(), []);
     const regionHidden = panel === undefined ||
+        panel.visible === false ||
         (compact && compactMode === "hide") ||
         (onMobile && mobileBehavior === "hidden") ||
         !hudVisibleInPhase(showDuring, phase);
@@ -383,6 +447,8 @@ export function HudPanel({ id, anchor = "top-left", order, compact: compactMode
     const onPointerDown = (event) => {
         if (!draggable || event.button !== 0)
             return;
+        if (event.target?.closest?.("[data-hud-resize]") != null)
+            return;
         const root = rootRef.current;
         const canvas = canvasRef.current;
         if (root === null || canvas === null)
@@ -439,6 +505,44 @@ export function HudPanel({ id, anchor = "top-left", order, compact: compactMode
         window.addEventListener("pointerup", onEnd);
         window.addEventListener("pointercancel", onEnd);
     };
+    const onResizeStart = (edge, event) => {
+        if (!resizable || event.button !== 0)
+            return;
+        const root = rootRef.current;
+        if (root === null)
+            return;
+        const startWidth = panel?.width ?? root.getBoundingClientRect().width;
+        const startHeight = panel?.height ?? root.getBoundingClientRect().height;
+        const pointerId = event.pointerId;
+        const startX = event.clientX;
+        const startY = event.clientY;
+        suppressClickRef.current = true;
+        layout.bringToFront(id);
+        const onMove = (moveEvent) => {
+            if (moveEvent.pointerId !== pointerId)
+                return;
+            const dw = edge === "s" ? 0 : moveEvent.clientX - startX;
+            const dh = edge === "e" ? 0 : moveEvent.clientY - startY;
+            const next = resizePanelSize({ width: startWidth, height: startHeight }, { dw, dh }, resizeSpec.axes, resizeSpec);
+            layout.resize(id, next);
+        };
+        const onEnd = (endEvent) => {
+            if (endEvent.pointerId !== pointerId)
+                return;
+            detachRef.current?.();
+        };
+        detachRef.current?.();
+        const detach = () => {
+            window.removeEventListener("pointermove", onMove);
+            window.removeEventListener("pointerup", onEnd);
+            window.removeEventListener("pointercancel", onEnd);
+            detachRef.current = null;
+        };
+        detachRef.current = detach;
+        window.addEventListener("pointermove", onMove);
+        window.addEventListener("pointerup", onEnd);
+        window.addEventListener("pointercancel", onEnd);
+    };
     const onClickCapture = (event) => {
         if (!suppressClickRef.current)
             return;
@@ -458,15 +562,18 @@ export function HudPanel({ id, anchor = "top-left", order, compact: compactMode
                     color: "rgba(255, 255, 255, 0.9)",
                     font: "10px/1.5 system-ui, sans-serif",
                     whiteSpace: "nowrap",
-                }, children: id })] })) : null;
+                }, children: id }), resizable ? _jsx(ResizeHandles, { axes: resizeSpec.axes, onResizeStart: onResizeStart }) : null] })) : null;
     if (panel === undefined)
         return null;
+    if (panel.visible === false)
+        return null;
     if (compact && compactMode === "hide")
         return null;
     if (onMobile && mobileBehavior === "hidden")
         return null;
     if (!hudVisibleInPhase(showDuring, phase))
         return null;
+    const authoredSize = sizeStyle(panel);
     const flow = compact || !panel.moved;
     if (flow) {
         const regionEl = regions[compact ? anchor : panel.placement.anchor];
@@ -474,7 +581,7 @@ export function HudPanel({ id, anchor = "top-left", order, compact: compactMode
             return null;
         const chipped = compact && compactMode === "chip";
         const passThrough = interactive === false && !editing && !chipped;
-        return createPortal(_jsxs("div", { ref: rootRef, "data-hud-panel": id, "data-dragging": dragging ? "" : undefined, "data-hud-priority": priority, "data-hud-mobile-behavior": mobileBehavior, className: className, onPointerDown: onPointerDown, onClickCapture: onClickCapture, style: {
+        return createPortal(_jsxs("div", { ref: rootRef, "data-hud-panel": id, "data-dragging": dragging ? "" : undefined, "data-hud-priority": priority, "data-hud-mobile-behavior": mobileBehavior, "data-hud-type": panel.type ?? type, className: className, onPointerDown: onPointerDown, onClickCapture: onClickCapture, style: {
                 position: "relative",
                 order: order ?? 0,
                 pointerEvents: passThrough ? "none" : "auto",
@@ -483,6 +590,8 @@ export function HudPanel({ id, anchor = "top-left", order, compact: compactMode
                 cursor: dragging ? "grabbing" : editing ? "grab" : undefined,
                 outline: editing ? "1px dashed rgba(255, 255, 255, 0.6)" : undefined,
                 outlineOffset: editing ? 2 : undefined,
+                boxSizing: "border-box",
+                ...authoredSize,
                 ...style,
             }, children: [chipped ? (_jsx(HudChip, { label: chip ?? id, anchor: anchor, children: children })) : (children), editingChrome] }), regionEl);
     }
@@ -503,7 +612,7 @@ export function HudPanel({ id, anchor = "top-left", order, compact: compactMode
     if (fx === 0.5 || fy === 0.5) {
         position.transform = `translate(${fx === 0.5 ? "-50%" : "0"}, ${fy === 0.5 ? "-50%" : "0"})`;
     }
-    return (_jsxs("div", { ref: rootRef, "data-hud-panel": id, "data-dragging": dragging ? "" : undefined, className: className, onPointerDown: onPointerDown, onClickCapture: onClickCapture, style: {
+    return (_jsxs("div", { ref: rootRef, "data-hud-panel": id, "data-dragging": dragging ? "" : undefined, "data-hud-type": panel.type ?? type, className: className, onPointerDown: onPointerDown, onClickCapture: onClickCapture, style: {
             position: "absolute",
             ...position,
             zIndex: panel.z,
@@ -513,6 +622,8 @@ export function HudPanel({ id, anchor = "top-left", order, compact: compactMode
             cursor: dragging ? "grabbing" : editing ? "grab" : undefined,
             outline: editing ? "1px dashed rgba(255, 255, 255, 0.6)" : undefined,
             outlineOffset: editing ? 2 : undefined,
+            boxSizing: "border-box",
+            ...authoredSize,
             ...style,
         }, children: [children, editingChrome] }));
 }

package/dist/index.d.ts

@@ -5,10 +5,18 @@ export * from "./chatBubbles.js";
 export * from "./voice.js";
 export * from "./social.js";
 export * from "./hooks.js";
+export * from "./store.js";
 export * from "./settings.js";
+export * from "./save.js";
 export * from "./components.js";
+export * from "./hud.js";
+export * from "./keyHint.js";
+export * from "./startScreen.js";
 export * from "./engineStore.js";
 export * from "./dragLayer.js";
+export * from "./cards.js";
+export * from "./actionHud.js";
+export * from "./selectionHud.js";
 export * from "./hudLayout.js";
 export * from "./hudViewport.js";
 export * from "./gameViewport.js";

package/dist/index.js

@@ -5,10 +5,18 @@ export * from "./chatBubbles.js";
 export * from "./voice.js";
 export * from "./social.js";
 export * from "./hooks.js";
+export * from "./store.js";
 export * from "./settings.js";
+export * from "./save.js";
 export * from "./components.js";
+export * from "./hud.js";
+export * from "./keyHint.js";
+export * from "./startScreen.js";
 export * from "./engineStore.js";
 export * from "./dragLayer.js";
+export * from "./cards.js";
+export * from "./actionHud.js";
+export * from "./selectionHud.js";
 export * from "./hudLayout.js";
 export * from "./hudViewport.js";
 export * from "./gameViewport.js";

package/dist/keyHint.d.ts

@@ -0,0 +1,30 @@
+import { type CSSProperties, type ReactNode } from "react";
+/**
+ * A single keyboard/mouse key rendered as a cap. Tagged `data-jg-kbd` so tooling
+ * can find it; on its own it stays visible (hiding a lone cap would strand its
+ * label). Wrap keys + their meaning in `KeyHint` to make the whole hint vanish
+ * on touch.
+ *
+ * @capability keycap styled keyboard/mouse key cap for control hints
+ */
+export declare function Keycap({ children, className, style, }: {
+    children: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}): import("react").JSX.Element;
+/**
+ * Wraps a keyboard/mouse control hint (a cap plus what it does). Renders nothing
+ * on coarse-pointer devices — a touchscreen has no keyboard, so the hint is
+ * noise and only fights the on-screen controls for space. The `data-jg-kbd-hint`
+ * marker is also hidden by an engine stylesheet as a hydration-safe backstop, so
+ * a hint stays hidden on touch even before this component's effect runs. Put the
+ * touch equivalent (a `TouchControls` dock, a tappable button) on the coarse
+ * branch instead.
+ *
+ * @capability key-hint keyboard/mouse control hint that hides itself on touch
+ */
+export declare function KeyHint({ children, className, style, }: {
+    children: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}): import("react").JSX.Element | null;

package/dist/keyHint.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import {} from "react";
+import { useDisplayProfile } from "./display.js";
+/**
+ * A single keyboard/mouse key rendered as a cap. Tagged `data-jg-kbd` so tooling
+ * can find it; on its own it stays visible (hiding a lone cap would strand its
+ * label). Wrap keys + their meaning in `KeyHint` to make the whole hint vanish
+ * on touch.
+ *
+ * @capability keycap styled keyboard/mouse key cap for control hints
+ */
+export function Keycap({ children, className, style, }) {
+    return (_jsx("kbd", { "data-jg-kbd": "", className: className, style: style, children: children }));
+}
+/**
+ * Wraps a keyboard/mouse control hint (a cap plus what it does). Renders nothing
+ * on coarse-pointer devices — a touchscreen has no keyboard, so the hint is
+ * noise and only fights the on-screen controls for space. The `data-jg-kbd-hint`
+ * marker is also hidden by an engine stylesheet as a hydration-safe backstop, so
+ * a hint stays hidden on touch even before this component's effect runs. Put the
+ * touch equivalent (a `TouchControls` dock, a tappable button) on the coarse
+ * branch instead.
+ *
+ * @capability key-hint keyboard/mouse control hint that hides itself on touch
+ */
+export function KeyHint({ children, className, style, }) {
+    const { coarsePointer } = useDisplayProfile();
+    if (coarsePointer)
+        return null;
+    return (_jsx("span", { "data-jg-kbd-hint": "", className: className, style: style, children: children }));
+}

package/dist/map.d.ts

@@ -1,7 +1,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 MinimapView, type WorldXZ } from "@jgengine/core/world/minimap";
 import { type MapCellStates, type MapRoute, type MapZone } from "@jgengine/core/world/mapLayers";
 export declare function useMarkers(markers: MarkerSet): readonly MapMarker[];
 export declare function useFog(fog: FogField): ReturnType<FogField["cells"]>;
@@ -40,8 +40,53 @@ export interface MapBounds {
  * Framed circular minimap: optional baked terrain background, reveal-on-event
  * fog overlay, categorized marker icons, and a facing arrow. Reads a core
  * `MarkerSet` / `FogField`; supply your own `kindStyles` palette to reskin.
+ *
+ * @capability minimap framed circular minimap with terrain bake, fog, markers, and facing arrow
  */
 export declare function Minimap({ markers, center, worldRadius, fog, size, facingYaw, rotate, kindStyles, background, mapBounds, routes, zones, cellStates, onWorldClick, className, title, children, }: MinimapProps): ReactNode;
+/** One dot (or, with `heading`, a rotated arrow) drawn by `MinimapChrome`. */
+export interface MinimapChromeMarker {
+    id: string;
+    position: WorldXZ | readonly [number, number, number];
+    /** Bearing (radians) to draw an arrow instead of a dot — pass `headingToBearing(yaw)` for the player/other facing blips. */
+    heading?: number;
+    color?: string;
+    radius?: number;
+    glyph?: string;
+    glyphColor?: string;
+    strokeColor?: string;
+    strokeWidth?: number;
+    /** Clamp to the minimap edge when outside `view.worldRadius` (off-screen indicator); `false` hides it instead. Default `true`. */
+    clampToEdge?: boolean;
+}
+/** Props for `MinimapChrome`. */
+export interface MinimapChromeProps {
+    /** Shared with `projectToMinimap`/`clampToMinimapEdge` — pass `view.rotate` to keep a rotating map's arrows pointed correctly. */
+    view: MinimapView;
+    /** Ring outline (+ `cardinalLabel`). Default `false` — most games draw their own frame/panel around the chrome. */
+    frame?: boolean;
+    frameColor?: string;
+    frameStrokeWidth?: number;
+    /** Label drawn at the top of the ring when `frame` is on; `false` omits it. */
+    cardinalLabel?: string | false;
+    markers?: readonly MinimapChromeMarker[];
+    markerColor?: string;
+    markerRadius?: number;
+    className?: string;
+}
+/**
+ * Headless minimap chrome — nests inside a game's own `<svg>`: an optional
+ * ring frame, and edge-clamped marker dots that draw as directional arrows
+ * when a marker carries a `heading` (the compass-arrow / player-blip layer
+ * ~8 games were re-drawing by hand over `projectToMinimap`/`clampToMinimapEdge`).
+ * Renders a bare `<g>` — no background, panel, or title; compose your own
+ * content layer (routes, zones, terrain) as sibling SVG nodes for full control
+ * of z-order, or call `MinimapChrome` twice (once for `frame`, again for
+ * `markers`) to sandwich custom content between the ring and the blips.
+ *
+ * @capability minimap-chrome ring frame plus edge-clamped, heading-aware marker dots to nest inside a game's own `<svg>`
+ */
+export declare function MinimapChrome({ view, frame, frameColor, frameStrokeWidth, cardinalLabel, markers, markerColor, markerRadius, className, }: MinimapChromeProps): ReactNode;
 export interface CompassProps {
     /** Facing yaw (`rotationY`, forward = `(sin yaw, cos yaw)`) of the tracked entity — pass it raw, never pre-converted to a bearing. */
     facingYaw: number;
@@ -57,6 +102,29 @@ export interface CompassProps {
  * eight cardinals and optional marker pips (bearing to each `MarkerSet` entry).
  */
 export declare function Compass({ facingYaw, center, markers, width, fov, kindStyles, className, }: CompassProps): ReactNode;
+/** Props for `MinimapPanel` — all `MinimapProps` plus the zone-label/clock header and compass slots. */
+export interface MinimapPanelProps extends MinimapProps {
+    /** Zone/area name slot rendered in the chrome header — the game supplies its own zone lookup. */
+    zoneLabel?: ReactNode;
+    /** Clock readout slot rendered in the chrome header — pair with `useGameClock()` + `calendar()`. */
+    clock?: ReactNode;
+    /** Compass strip beneath the circle. Default true; pass `false` to omit it entirely. */
+    showCompass?: boolean;
+    compassProps?: Partial<Omit<CompassProps, "className">>;
+    headerClassName?: string;
+    zoneLabelClassName?: string;
+    clockClassName?: string;
+    compassClassName?: string;
+}
+/**
+ * Composed circular-minimap chrome: optional zone-label + clock header above
+ * the `Minimap`, optional `Compass` strip below. Purely a wiring layer over
+ * the existing primitives — the game supplies the zone name and clock text,
+ * this only places them; omit either slot and the header disappears.
+ *
+ * @capability minimap-panel circular minimap with zone label, clock, and compass composed together
+ */
+export declare function MinimapPanel({ zoneLabel, clock, showCompass, compassProps, headerClassName, zoneLabelClassName, clockClassName, compassClassName, children, ...minimapProps }: MinimapPanelProps): ReactNode;
 export interface WorldMapProps {
     markers: MarkerSet;
     bounds: MapBounds;

package/dist/map.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo, 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";
@@ -78,6 +78,8 @@ export function useFog(fog) {
  * Framed circular minimap: optional baked terrain background, reveal-on-event
  * fog overlay, categorized marker icons, and a facing arrow. Reads a core
  * `MarkerSet` / `FogField`; supply your own `kindStyles` palette to reskin.
+ *
+ * @capability minimap framed circular minimap with terrain bake, fog, markers, and facing arrow
  */
 export function Minimap({ markers, center, worldRadius, fog, size = 176, facingYaw = 0, rotate = false, kindStyles = DEFAULT_MARKER_KINDS, background, mapBounds, routes, zones, cellStates, onWorldClick, className, title = "Map", children, }) {
     const markerList = useMarkers(markers);
@@ -162,6 +164,36 @@ export function Minimap({ markers, center, worldRadius, fog, size = 176, facingY
                                 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 : 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] }));
 }
+/**
+ * Headless minimap chrome — nests inside a game's own `<svg>`: an optional
+ * ring frame, and edge-clamped marker dots that draw as directional arrows
+ * when a marker carries a `heading` (the compass-arrow / player-blip layer
+ * ~8 games were re-drawing by hand over `projectToMinimap`/`clampToMinimapEdge`).
+ * Renders a bare `<g>` — no background, panel, or title; compose your own
+ * content layer (routes, zones, terrain) as sibling SVG nodes for full control
+ * of z-order, or call `MinimapChrome` twice (once for `frame`, again for
+ * `markers`) to sandwich custom content between the ring and the blips.
+ *
+ * @capability minimap-chrome ring frame plus edge-clamped, heading-aware marker dots to nest inside a game's own `<svg>`
+ */
+export function MinimapChrome({ view, frame = false, frameColor = "rgba(148,163,184,0.4)", frameStrokeWidth = 1.5, cardinalLabel = "N", markers = [], markerColor = "#e2e8f0", markerRadius = 5, className, }) {
+    const half = view.size / 2;
+    const rotate = view.rotate ?? 0;
+    return (_jsxs("g", { className: className, "data-minimap-chrome": true, children: [frame ? (_jsxs(_Fragment, { children: [_jsx("circle", { cx: half, cy: half, r: half - 1, fill: "none", stroke: frameColor, strokeWidth: frameStrokeWidth }), cardinalLabel !== false ? (_jsx("text", { x: half, y: 13, textAnchor: "middle", fontSize: 11, fill: frameColor, style: { fontWeight: 700 }, children: cardinalLabel })) : null] })) : null, markers.map((marker) => {
+                const projected = projectToMinimap(marker.position, view);
+                const clamp = marker.clampToEdge ?? true;
+                if (!projected.inside && !clamp)
+                    return null;
+                const at = projected.inside ? projected : clampToMinimapEdge(projected, view.size);
+                const color = marker.color ?? markerColor;
+                const radius = marker.radius ?? markerRadius;
+                if (marker.heading !== undefined) {
+                    const deg = (marker.heading - rotate) * (180 / Math.PI);
+                    return (_jsx("g", { "data-minimap-marker": marker.id, transform: `translate(${at.x} ${at.y}) rotate(${deg})`, children: _jsx("path", { d: `M0,${-radius} L${radius * 0.7},${radius * 0.8} L0,${radius * 0.35} L${-radius * 0.7},${radius * 0.8} Z`, fill: color, stroke: marker.strokeColor ?? "rgba(0,0,0,0.6)", strokeWidth: marker.strokeWidth ?? 0.75 }) }, marker.id));
+                }
+                return (_jsxs("g", { "data-minimap-marker": marker.id, children: [_jsx("circle", { cx: at.x, cy: at.y, r: radius, fill: color, stroke: marker.strokeColor, strokeWidth: marker.strokeWidth }), marker.glyph !== undefined ? (_jsx("text", { x: at.x, y: at.y + 3.5, textAnchor: "middle", fontSize: 10, fill: marker.glyphColor ?? "#0f172a", style: { fontWeight: 700 }, children: marker.glyph })) : null] }, marker.id));
+            })] }));
+}
 const NO_SUBSCRIBE = () => () => undefined;
 const NULL_CELLS = () => null;
 const EMPTY_MARKERS_VALUE = [];
@@ -240,6 +272,27 @@ export function Compass({ facingYaw, center, markers, width = 340, fov = (Math.P
                 })
                 : null] }));
 }
+/**
+ * Composed circular-minimap chrome: optional zone-label + clock header above
+ * the `Minimap`, optional `Compass` strip below. Purely a wiring layer over
+ * the existing primitives — the game supplies the zone name and clock text,
+ * this only places them; omit either slot and the header disappears.
+ *
+ * @capability minimap-panel circular minimap with zone label, clock, and compass composed together
+ */
+export function MinimapPanel({ zoneLabel, clock, showCompass = true, compassProps, headerClassName, zoneLabelClassName, clockClassName, compassClassName, children, ...minimapProps }) {
+    const hasHeader = zoneLabel !== undefined || clock !== undefined;
+    return (_jsxs("div", { "data-minimap-chrome": true, children: [hasHeader ? (_jsxs("div", { className: headerClassName, "data-minimap-chrome-header": true, style: {
+                    display: "flex",
+                    justifyContent: "space-between",
+                    alignItems: "baseline",
+                    gap: 8,
+                    marginBottom: 4,
+                    width: minimapProps.size ?? 176,
+                    color: "#e2e8f0",
+                    fontFamily: "ui-sans-serif, system-ui, sans-serif",
+                }, children: [zoneLabel !== undefined ? (_jsx("span", { className: zoneLabelClassName, "data-minimap-chrome-zone": true, style: { fontSize: 12, fontWeight: 700 }, children: zoneLabel })) : (_jsx("span", {})), clock !== undefined ? (_jsx("span", { className: clockClassName, "data-minimap-chrome-clock": true, style: { fontSize: 11, color: "rgba(226,232,240,0.75)" }, children: clock })) : null] })) : null, _jsx(Minimap, { ...minimapProps, children: children }), showCompass ? (_jsx("div", { className: compassClassName, "data-minimap-chrome-compass": true, style: { marginTop: 6 }, children: _jsx(Compass, { facingYaw: minimapProps.facingYaw ?? 0, center: minimapProps.center, markers: minimapProps.markers, width: minimapProps.size ?? 176, ...compassProps }) })) : null] }));
+}
 function WorldMapFogImage({ fogCells, project, worldW, worldD, width, mapH, }) {
     const fogImage = useMemo(() => {
         if (fogCells === null)

package/dist/save.d.ts

@@ -0,0 +1,25 @@
+import type { SaveStatus, SaveStore } from "@jgengine/core/game/saveStore";
+/** The reactive slice of a {@link SaveStore} returned by {@link useSaveStore} — the live value plus bound save actions, all re-rendering on change. */
+export interface SaveStoreView<T> {
+    value: T;
+    status: SaveStatus;
+    slot: string;
+    /** True while the initial `load()` is in flight — gate a loading screen on it. */
+    loading: boolean;
+    /** True while a write is in flight — show a "Saving…" indicator. */
+    saving: boolean;
+    set: (value: T) => void;
+    patch: (mutate: (previous: T) => T) => void;
+    save: () => Promise<void>;
+    clear: () => Promise<void>;
+}
+/**
+ * Bind a {@link SaveStore} to React: returns the live `value` and `status` and
+ * re-renders whenever either changes. By default it calls `load()` once on
+ * mount (pass `{ load: false }` to hydrate yourself). The same hook works for
+ * offline (localStorage) and cloud (Convex/DB) saves — only the store's backend
+ * differs.
+ */
+export declare function useSaveStore<T>(store: SaveStore<T>, options?: {
+    load?: boolean;
+}): SaveStoreView<T>;

package/dist/save.js

@@ -0,0 +1,37 @@
+import { useCallback, useEffect, useRef, useSyncExternalStore } from "react";
+/**
+ * Bind a {@link SaveStore} to React: returns the live `value` and `status` and
+ * re-renders whenever either changes. By default it calls `load()` once on
+ * mount (pass `{ load: false }` to hydrate yourself). The same hook works for
+ * offline (localStorage) and cloud (Convex/DB) saves — only the store's backend
+ * differs.
+ */
+export function useSaveStore(store, options) {
+    useSyncExternalStore(store.subscribe, store.revision, store.revision);
+    const shouldLoad = options?.load !== false;
+    const loadedFor = useRef(null);
+    useEffect(() => {
+        if (!shouldLoad)
+            return;
+        if (loadedFor.current === store)
+            return;
+        loadedFor.current = store;
+        void store.load();
+    }, [store, shouldLoad]);
+    const set = useCallback((value) => store.set(value), [store]);
+    const patch = useCallback((mutate) => void store.patch(mutate), [store]);
+    const save = useCallback(() => store.save(), [store]);
+    const clear = useCallback(() => store.clear(), [store]);
+    const status = store.status();
+    return {
+        value: store.value(),
+        status,
+        slot: store.slot(),
+        loading: status === "loading",
+        saving: status === "saving",
+        set,
+        patch,
+        save,
+        clear,
+    };
+}

package/dist/selectSnapshot.d.ts

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