@jgengine/react 0.9.0 → 0.11.0

package/dist/hud.js

@@ -0,0 +1,144 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { groundSpeed } from "@jgengine/core/scene/entityStore";
+import { useCurrency, useEntityStat, useGameClock, useGameStore, useInventory, localPlayerEntity } from "./hooks.js";
+/**
+ * Drop-in HUD components — good-looking with zero styling, and fully opt-in: a game imports only the
+ * pieces it wants (`StatBar`, `Hotbar`, `Speedometer`, `Clock`, `WaveBanner`, `Coins`, `Crosshair`)
+ * and places them itself. The engine imposes none of these; there is no forced HUD. Styling is
+ * self-contained inline CSS (no Tailwind `@source` needed) with a shared dark-glass look; pass
+ * `style`/`className` to override. Anything reading the player defaults to the local player entity.
+ *
+ * @capability hud-components opt-in drop-in health/hotbar/speed/clock/wave/currency HUD widgets
+ */
+const PANEL = {
+    background: "rgba(10,12,16,0.62)",
+    backdropFilter: "blur(6px)",
+    WebkitBackdropFilter: "blur(6px)",
+    border: "1px solid rgba(255,255,255,0.10)",
+    borderRadius: 10,
+    color: "#f4f6fb",
+    fontFamily: "ui-sans-serif, system-ui, -apple-system, sans-serif",
+    boxShadow: "0 4px 16px rgba(0,0,0,0.35)",
+};
+/** Named color ramps for {@link StatBar} tones. `fn` maps fill fraction (0..1) → gradient stops. */
+const TONES = {
+    health: (t) => (t > 0.5 ? ["#22c55e", "#4ade80"] : t > 0.25 ? ["#f59e0b", "#fbbf24"] : ["#dc2626", "#f87171"]),
+    mana: () => ["#2563eb", "#60a5fa"],
+    stamina: () => ["#65a30d", "#a3e635"],
+    shield: () => ["#0891b2", "#22d3ee"],
+    xp: () => ["#7c3aed", "#a78bfa"],
+    neutral: () => ["#475569", "#94a3b8"],
+};
+function useLocalPlayerId(entityId) {
+    return useGameStore((ctx) => entityId ?? localPlayerEntity(ctx)?.id ?? null);
+}
+/**
+ * A polished stat bar (health/mana/stamina/shield/xp) — a rounded, glassy meter with a tone-colored
+ * fill and an optional value readout. Reads `statId` off `entityId` (defaults to the local player).
+ * Renders nothing until the stat exists.
+ */
+export function StatBar({ statId = "health", entityId, tone = "health", label, showValue = true, width = 200, icon, style, className, }) {
+    const id = useLocalPlayerId(entityId);
+    const stat = useEntityStat(id ?? "", statId);
+    if (id === null || stat === null)
+        return null;
+    const range = stat.max - stat.min;
+    const fraction = range <= 0 ? 0 : Math.max(0, Math.min(1, (stat.current - stat.min) / range));
+    const [from, to] = (TONES[tone] ?? TONES.neutral)(fraction);
+    return (_jsxs("div", { className: className, style: { ...PANEL, padding: "6px 8px", width, ...style }, "data-stat": statId, children: [(label !== undefined || icon !== undefined || showValue) && (_jsxs("div", { style: { display: "flex", alignItems: "center", gap: 6, marginBottom: 4, fontSize: 11, fontWeight: 600, letterSpacing: 0.3 }, children: [icon, _jsx("span", { style: { textTransform: "uppercase", opacity: 0.75 }, children: label ?? statId }), showValue ? (_jsxs("span", { style: { marginLeft: "auto", fontVariantNumeric: "tabular-nums", opacity: 0.9 }, children: [Math.round(stat.current), _jsxs("span", { style: { opacity: 0.5 }, children: [" / ", Math.round(stat.max)] })] })) : null] })), _jsx("div", { style: { height: 8, borderRadius: 999, background: "rgba(255,255,255,0.10)", overflow: "hidden" }, children: _jsx("div", { style: { width: `${fraction * 100}%`, height: "100%", borderRadius: 999, background: `linear-gradient(90deg, ${from}, ${to})`, transition: "width 160ms ease" } }) })] }));
+}
+/**
+ * A numbered hotbar bound to an inventory — glassy slots, an active-slot highlight, item id + count,
+ * and a keycap per slot. Place it and pass the `inventoryId`; `activeSlot` highlights the equipped one.
+ */
+export function Hotbar({ inventoryId, activeSlot, keys, slotSize = 46, style, className, }) {
+    const slots = useInventory(inventoryId);
+    return (_jsx("div", { className: className, style: { display: "flex", gap: 6, ...style }, "data-inventory": inventoryId, children: slots.map((slot, index) => {
+            const active = index === activeSlot;
+            return (_jsxs("div", { "data-slot": index, style: {
+                    ...PANEL,
+                    width: slotSize,
+                    height: slotSize,
+                    position: "relative",
+                    display: "flex",
+                    alignItems: "center",
+                    justifyContent: "center",
+                    borderColor: active ? "rgba(56,189,248,0.9)" : "rgba(255,255,255,0.10)",
+                    boxShadow: active ? "0 0 0 1px rgba(56,189,248,0.7), 0 4px 16px rgba(0,0,0,0.35)" : PANEL.boxShadow,
+                }, children: [_jsx("span", { style: { position: "absolute", top: 2, left: 4, fontSize: 9, fontWeight: 700, opacity: 0.55 }, children: keys?.[index] ?? index + 1 }), slot !== null ? (_jsxs("span", { style: { fontSize: 10, textAlign: "center", lineHeight: 1.1, padding: "0 2px", wordBreak: "break-word" }, children: [slot.itemId, slot.count > 1 ? _jsxs("span", { style: { display: "block", opacity: 0.6 }, children: ["\u00D7", slot.count] }) : null] })) : null] }, index));
+        }) }));
+}
+/**
+ * A speedometer for an entity (defaults to the local player) — an SVG arc gauge + a digital readout.
+ * `scale` converts world units/second to your display unit (3.6 → km/h, 2.237 → mph); `max` sets the
+ * gauge's top of scale.
+ */
+export function Speedometer({ entityId, scale = 3.6, unit = "km/h", max = 60, size = 96, style, className, }) {
+    const speed = useGameStore((ctx) => {
+        const entity = entityId === undefined ? localPlayerEntity(ctx) : ctx.scene.entity.get(entityId);
+        return entity === null ? 0 : groundSpeed(entity) * scale;
+    });
+    const fraction = Math.max(0, Math.min(1, speed / max));
+    // 240° sweep from -210° to +30°.
+    const startDeg = -210;
+    const sweep = 240;
+    const radius = size / 2 - 8;
+    const cx = size / 2;
+    const cy = size / 2;
+    const arc = (fromFrac, toFrac) => {
+        const a0 = ((startDeg + sweep * fromFrac) * Math.PI) / 180;
+        const a1 = ((startDeg + sweep * toFrac) * Math.PI) / 180;
+        const large = sweep * (toFrac - fromFrac) > 180 ? 1 : 0;
+        return `M ${cx + radius * Math.cos(a0)} ${cy + radius * Math.sin(a0)} A ${radius} ${radius} 0 ${large} 1 ${cx + radius * Math.cos(a1)} ${cy + radius * Math.sin(a1)}`;
+    };
+    return (_jsxs("div", { className: className, style: { ...PANEL, width: size, padding: 6, textAlign: "center", ...style }, children: [_jsxs("svg", { width: size - 12, height: (size - 12) * 0.72, viewBox: `0 0 ${size} ${size * 0.72}`, style: { display: "block", margin: "0 auto" }, children: [_jsx("path", { d: arc(0, 1), fill: "none", stroke: "rgba(255,255,255,0.12)", strokeWidth: 7, strokeLinecap: "round" }), _jsx("path", { d: arc(0, fraction), fill: "none", stroke: fraction > 0.85 ? "#f87171" : "#38bdf8", strokeWidth: 7, strokeLinecap: "round" })] }), _jsx("div", { style: { marginTop: -8, fontVariantNumeric: "tabular-nums", fontWeight: 700, fontSize: 18, lineHeight: 1 }, children: Math.round(speed) }), _jsx("div", { style: { fontSize: 9, opacity: 0.6, letterSpacing: 0.4, textTransform: "uppercase" }, children: unit })] }));
+}
+/**
+ * A time-of-day clock reading the sim calendar — `Day N · HH:MM`, 24h or 12h. `controls` adds
+ * pause + the game's speed multipliers as clickable pills (the "fast-forward" bar), off by default so
+ * a game opts into letting the player scrub time.
+ */
+export function Clock({ format = "24h", showDay = true, controls = false, style, className, }) {
+    const clock = useGameClock();
+    const { hour, minute, day } = clock.calendar;
+    const label = useMemo(() => {
+        const mm = minute.toString().padStart(2, "0");
+        if (format === "12h") {
+            const h12 = hour % 12 === 0 ? 12 : hour % 12;
+            return `${h12}:${mm} ${hour < 12 ? "AM" : "PM"}`;
+        }
+        return `${hour.toString().padStart(2, "0")}:${mm}`;
+    }, [hour, minute, format]);
+    return (_jsxs("div", { className: className, style: { ...PANEL, padding: "5px 10px", display: "inline-flex", alignItems: "center", gap: 8, fontVariantNumeric: "tabular-nums", ...style }, children: [showDay ? _jsxs("span", { style: { fontSize: 11, opacity: 0.6 }, children: ["Day ", day + 1] }) : null, _jsx("span", { style: { fontWeight: 700, fontSize: 14 }, children: label }), controls ? (_jsxs("span", { style: { display: "inline-flex", gap: 3, marginLeft: 4 }, children: [_jsx(ClockPill, { label: clock.paused ? "▶" : "❚❚", active: false, onClick: () => (clock.paused ? clock.controls.play() : clock.controls.pause()) }), clock.speeds.map((s) => (_jsx(ClockPill, { label: `${s}×`, active: !clock.paused && clock.speed === s, onClick: () => clock.controls.setSpeed(s) }, s)))] })) : null] }));
+}
+function ClockPill({ label, active, onClick }) {
+    return (_jsx("button", { type: "button", onClick: onClick, style: {
+            pointerEvents: "auto",
+            cursor: "pointer",
+            fontSize: 10,
+            fontWeight: 600,
+            padding: "1px 6px",
+            borderRadius: 6,
+            border: "none",
+            color: active ? "#0a0c10" : "#cbd5e1",
+            background: active ? "#38bdf8" : "rgba(255,255,255,0.08)",
+        }, children: label }));
+}
+/**
+ * A wave / round banner — a bold centered pill for "WAVE 3" style callouts, with an optional subtitle
+ * (enemies remaining, timer). Pure display: pass the current `wave` and whatever subtitle you track.
+ */
+export function WaveBanner({ wave, label = "Wave", subtitle, style, className, }) {
+    return (_jsxs("div", { className: className, style: { ...PANEL, padding: "6px 16px", textAlign: "center", display: "inline-block", ...style }, children: [_jsx("div", { style: { fontSize: 10, letterSpacing: 2, textTransform: "uppercase", opacity: 0.65 }, children: label }), _jsx("div", { style: { fontSize: 24, fontWeight: 800, lineHeight: 1.1 }, children: wave }), subtitle !== undefined ? _jsx("div", { style: { fontSize: 11, opacity: 0.7, marginTop: 2 }, children: subtitle }) : null] }));
+}
+/** A currency counter — an icon (emoji/char, default a coin) plus the live amount for `currencyId`. */
+export function Coins({ currencyId, icon = "🪙", style, className, }) {
+    const amount = useCurrency(currencyId);
+    return (_jsxs("span", { className: className, style: { ...PANEL, padding: "3px 10px", display: "inline-flex", alignItems: "center", gap: 6, fontWeight: 700, fontVariantNumeric: "tabular-nums", ...style }, "data-currency": currencyId, children: [_jsx("span", { "aria-hidden": true, children: icon }), amount] }));
+}
+/** A minimal center crosshair reticle — four ticks around a gap. Purely presentational. */
+export function Crosshair({ size = 18, gap = 5, thickness = 2, color = "rgba(255,255,255,0.85)", style, className, }) {
+    const tick = (extra) => ({ position: "absolute", background: color, borderRadius: thickness, ...extra });
+    return (_jsx("div", { className: className, style: { position: "absolute", inset: 0, display: "flex", alignItems: "center", justifyContent: "center", pointerEvents: "none", ...style }, children: _jsxs("div", { style: { position: "relative", width: size, height: size }, children: [_jsx("div", { style: tick({ left: "50%", top: 0, width: thickness, height: size / 2 - gap, transform: "translateX(-50%)" }) }), _jsx("div", { style: tick({ left: "50%", bottom: 0, width: thickness, height: size / 2 - gap, transform: "translateX(-50%)" }) }), _jsx("div", { style: tick({ top: "50%", left: 0, height: thickness, width: size / 2 - gap, transform: "translateY(-50%)" }) }), _jsx("div", { style: tick({ top: "50%", right: 0, height: thickness, width: size / 2 - gap, transform: "translateY(-50%)" }) })] }) }));
+}

package/dist/hudLayout.d.ts

@@ -1,5 +1,10 @@
 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). */
+export declare function hudVisibleInPhase(showDuring: readonly GamePhase[] | undefined, phase: GamePhase): boolean;
 /**
  * How a panel behaves on compact (phone-scale) displays. `keep` stays visible
  * at the global compact scale, `chip` collapses to a small tap-to-expand
@@ -14,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
@@ -22,15 +34,17 @@ export declare function useHudLayout(options?: {
  * (`--jg-hud-dock-clearance`), or device safe areas. On compact displays the
  * whole surface scales down and each panel applies its `compact` behavior.
  */
-export declare function HudCanvas({ layout, editChord, compactScale, className, style, children, }: {
+export declare function HudCanvas({ layout, editChord, compactScale, showDuring, className, style, children, }: {
     layout: HudLayoutStore;
     editChord?: HudEditChord | false;
     /** Zoom applied to the whole HUD on compact displays. Default 0.85. */
     compactScale?: number;
+    /** Opt-in play-phase gate: render the HUD only during these phases (e.g. `["playing"]`). Omit for always-visible (default). */
+    showDuring?: readonly GamePhase[];
     className?: string;
     style?: CSSProperties;
     children?: ReactNode;
-}): import("react").JSX.Element;
+}): import("react").JSX.Element | null;
 /**
  * A HUD block that lives in one of the nine anchor regions. Panels sharing a
  * region stack outward from the screen edge in ascending `order`. On fine
@@ -38,7 +52,7 @@ export declare function HudCanvas({ layout, editChord, compactScale, className,
  * 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, 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. */
@@ -49,12 +63,33 @@ 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;
     };
     locked?: boolean;
+    /** Opt-in play-phase gate: render this panel only during these phases. Omit for always-visible (default). */
+    showDuring?: readonly GamePhase[];
+    /** Gameplay-importance tier, surfaced to layout tooling. `critical` stays visible; `tertiary` is the first to fold away. */
+    priority?: HudPriority;
+    /** How the panel adapts on mobile. `"hidden"` unmounts on phones; `"transient"` softens its collision policy; others tag the element for game CSS. */
+    mobileBehavior?: MobileHudBehavior;
+    /** Region ids this panel may overlap without a forbidden-collision report. */
+    allowOverlapWith?: readonly string[];
+    /** Regions sharing a non-empty group never collide with each other. */
+    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,11 +1,19 @@
 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";
 import { useEngineState } from "./engineStore.js";
+import { useGameLayoutMode, useRegisterLayoutRegion } from "./gameViewport.js";
+import { useOptionalGamePhase } from "./hooks.js";
 import { useHudViewport } from "./hudViewport.js";
+/** Whether a HUD element opted into `showDuring` is visible in the current phase; `undefined` = always visible (default). */
+export function hudVisibleInPhase(showDuring, phase) {
+    return showDuring === undefined || showDuring.includes(phase);
+}
 const STORAGE_PREFIX = "jg:hud:";
 const DRAG_THRESHOLD_PX = 4;
 const PERSIST_DELAY_MS = 200;
@@ -13,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;
@@ -43,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);
@@ -125,8 +188,9 @@ function edgePad(envInset, extra, basePx, scale) {
  * (`--jg-hud-dock-clearance`), or device safe areas. On compact displays the
  * whole surface scales down and each panel applies its `compact` behavior.
  */
-export function HudCanvas({ layout, editChord, compactScale, className, style, children, }) {
+export function HudCanvas({ layout, editChord, compactScale, showDuring, className, style, children, }) {
     const canvasRef = useRef(null);
+    const phase = useOptionalGamePhase();
     const { compact } = useDisplayProfile();
     const hudViewport = useHudViewport();
     const fitEnabled = hudViewport?.fitEnabled === true;
@@ -152,6 +216,7 @@ export function HudCanvas({ layout, editChord, compactScale, className, style, c
     }, []);
     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");
@@ -286,6 +351,8 @@ export function HudCanvas({ layout, editChord, compactScale, className, style, c
         "--jg-hud-pad-right": edgePad("env(safe-area-inset-right, 0px)", null, basePad, scale),
         ...style,
     };
+    if (!hudVisibleInPhase(showDuring, phase))
+        return null;
     return (_jsx(HudCanvasContext.Provider, { value: value, children: _jsxs("div", { ref: canvasRef, "data-hud-canvas": "", "data-hud-editing": editing ? "" : undefined, className: className, style: canvasStyle, children: [HUD_ANCHORS.map((anchor) => (_jsx("div", { ref: regionRefs[anchor], "data-hud-region": anchor, style: {
                         position: "absolute",
                         display: "flex",
@@ -334,29 +401,54 @@ 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, 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();
     if (ctx === null)
         throw new Error("HudPanel must be rendered inside a HudCanvas");
     const { layout, canvasRef, regions, compact } = ctx;
+    const onMobile = isMobileMode(layoutMode);
     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);
     const detachRef = useRef(null);
     const [dragging, setDragging] = useState(false);
     useEffect(() => () => detachRef.current?.(), []);
+    const regionHidden = panel === undefined ||
+        panel.visible === false ||
+        (compact && compactMode === "hide") ||
+        (onMobile && mobileBehavior === "hidden") ||
+        !hudVisibleInPhase(showDuring, phase);
+    const regionSpec = useMemo(() => ({
+        id,
+        kind: "hud",
+        collisionPolicy: (mobileBehavior === "transient" ? "warn" : "forbid"),
+        priority,
+        allowOverlapWith,
+        collisionGroup,
+    }), [id, mobileBehavior, priority, allowOverlapWith, collisionGroup]);
+    useRegisterLayoutRegion(regionSpec, rootRef, region && !regionHidden);
     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)
@@ -413,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;
@@ -432,11 +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];
@@ -444,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, 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",
@@ -453,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);
     }
@@ -473,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,
@@ -483,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,12 +5,22 @@ 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";
+export * from "./rotateDevice.js";
 export * from "./display.js";
 export * from "./map.js";
 export * from "./preview.js";

package/dist/index.js

@@ -5,12 +5,22 @@ 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";
+export * from "./rotateDevice.js";
 export * from "./display.js";
 export * from "./map.js";
 export * from "./preview.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 }));
+}