@jgengine/react 0.8.0 → 0.9.0

package/dist/hudLayout.d.ts

@@ -0,0 +1,61 @@
+import { type CSSProperties, type ReactNode } from "react";
+import { type HudAnchor, type HudLayoutStore } from "@jgengine/core/ui/hudLayout";
+/**
+ * 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
+ * pill, `hide` unmounts entirely.
+ */
+export type HudCompactMode = "keep" | "chip" | "hide";
+export interface HudEditChord {
+    hold: string;
+    press: string;
+}
+export declare function useHudLayout(options?: {
+    storageKey?: string;
+    snap?: number;
+    locked?: boolean;
+}): HudLayoutStore;
+/**
+ * Full-viewport HUD surface. Panels declared with `HudPanel` flow into nine
+ * anchor regions and stack automatically with a gap — no per-panel pixel
+ * offsets, no manual clearance for sibling panels, the touch-control dock
+ * (`--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, }: {
+    layout: HudLayoutStore;
+    editChord?: HudEditChord | false;
+    /** Zoom applied to the whole HUD on compact displays. Default 0.85. */
+    compactScale?: number;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * 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
+ * pointers panels stay draggable through the edit chord; a dragged panel
+ * 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, }: {
+    id: string;
+    anchor?: HudAnchor;
+    /** Stack position within the region, ascending outward from the screen edge. Default 0. */
+    order?: number;
+    /** Behavior on compact displays. Default `"keep"`. */
+    compact?: HudCompactMode;
+    /** Chip label when `compact="chip"`. Defaults to the panel id. */
+    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. */
+    inset?: {
+        x: number;
+        y: number;
+    };
+    locked?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+}): import("react").JSX.Element | null;

package/dist/hudLayout.js

@@ -0,0 +1,488 @@
+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 { hudScaleForViewport, overflowingPanels, resolveHudFit } from "@jgengine/core/ui/hudScale";
+import { useDisplayProfile } from "./display.js";
+import { useEngineState } from "./engineStore.js";
+import { useHudViewport } from "./hudViewport.js";
+const STORAGE_PREFIX = "jg:hud:";
+const DRAG_THRESHOLD_PX = 4;
+const PERSIST_DELAY_MS = 200;
+const EDIT_BAR_Z = 100000;
+const REGION_GAP = 10;
+const COMPACT_HUD_SCALE = 0.85;
+const HUD_ANCHORS = Object.keys(HUD_ANCHOR_FRACTIONS);
+export function useHudLayout(options) {
+    const storageKey = options?.storageKey;
+    const snap = options?.snap;
+    const locked = options?.locked;
+    const layout = useMemo(() => {
+        const store = createHudLayout({ snap, locked });
+        if (storageKey !== undefined && typeof localStorage !== "undefined") {
+            store.hydrate(localStorage.getItem(STORAGE_PREFIX + storageKey));
+        }
+        return store;
+    }, [storageKey, snap, locked]);
+    useEffect(() => {
+        if (storageKey === undefined || typeof localStorage === "undefined")
+            return;
+        let timer = null;
+        const unsubscribe = layout.subscribe(() => {
+            if (timer !== null)
+                clearTimeout(timer);
+            timer = setTimeout(() => {
+                timer = null;
+                localStorage.setItem(STORAGE_PREFIX + storageKey, layout.serialize());
+            }, PERSIST_DELAY_MS);
+        });
+        return () => {
+            unsubscribe();
+            if (timer !== null) {
+                clearTimeout(timer);
+                localStorage.setItem(STORAGE_PREFIX + storageKey, layout.serialize());
+            }
+        };
+    }, [layout, storageKey]);
+    return layout;
+}
+const HudCanvasContext = createContext(null);
+function HudEditBar({ layout }) {
+    return (_jsxs("div", { "data-hud-edit-bar": "", style: {
+            position: "absolute",
+            top: 12,
+            left: "50%",
+            transform: "translateX(-50%)",
+            zIndex: EDIT_BAR_Z,
+            pointerEvents: "auto",
+            display: "flex",
+            alignItems: "center",
+            gap: 10,
+            padding: "6px 12px",
+            borderRadius: 999,
+            background: "rgba(10, 10, 14, 0.92)",
+            border: "1px solid rgba(255, 255, 255, 0.25)",
+            color: "rgba(255, 255, 255, 0.92)",
+            font: "12px/1.4 system-ui, sans-serif",
+            whiteSpace: "nowrap",
+        }, children: [_jsx("span", { children: "HUD layout \u2014 drag panels to rearrange" }), _jsx("button", { type: "button", onClick: () => layout.reset(), style: {
+                    padding: "2px 10px",
+                    borderRadius: 999,
+                    border: "1px solid rgba(255, 255, 255, 0.3)",
+                    background: "transparent",
+                    color: "inherit",
+                    font: "inherit",
+                    cursor: "pointer",
+                }, children: "Reset" }), _jsx("button", { type: "button", onClick: () => layout.setEditing(false), style: {
+                    padding: "2px 10px",
+                    borderRadius: 999,
+                    border: "1px solid transparent",
+                    background: "rgba(255, 255, 255, 0.92)",
+                    color: "rgb(10, 10, 14)",
+                    font: "inherit",
+                    cursor: "pointer",
+                }, children: "Done" })] }));
+}
+const PAD_TOP = "var(--jg-hud-pad-top)";
+const PAD_BOTTOM = "var(--jg-hud-pad-bottom)";
+const PAD_LEFT = "var(--jg-hud-pad-left)";
+const PAD_RIGHT = "var(--jg-hud-pad-right)";
+const REGION_LAYOUT = {
+    "top-left": { top: PAD_TOP, left: PAD_LEFT, alignItems: "flex-start" },
+    top: { top: PAD_TOP, left: "50%", transform: "translateX(-50%)", alignItems: "center" },
+    "top-right": { top: PAD_TOP, right: PAD_RIGHT, alignItems: "flex-end" },
+    left: { left: PAD_LEFT, top: "50%", transform: "translateY(-50%)", alignItems: "flex-start" },
+    center: { left: "50%", top: "50%", transform: "translate(-50%, -50%)", alignItems: "center" },
+    right: { right: PAD_RIGHT, top: "50%", transform: "translateY(-50%)", alignItems: "flex-end" },
+    "bottom-left": {
+        bottom: PAD_BOTTOM,
+        left: PAD_LEFT,
+        flexDirection: "column-reverse",
+        alignItems: "flex-start",
+    },
+    bottom: {
+        bottom: PAD_BOTTOM,
+        left: "50%",
+        transform: "translateX(-50%)",
+        flexDirection: "column-reverse",
+        alignItems: "center",
+    },
+    "bottom-right": {
+        bottom: PAD_BOTTOM,
+        right: PAD_RIGHT,
+        flexDirection: "column-reverse",
+        alignItems: "flex-end",
+    },
+};
+function edgePad(envInset, extra, basePx, scale) {
+    const outer = extra === null ? envInset : `${envInset} + ${extra}`;
+    return scale === 1 ? `calc(${outer} + ${basePx}px)` : `calc((${outer}) / ${scale} + ${basePx}px)`;
+}
+/**
+ * Full-viewport HUD surface. Panels declared with `HudPanel` flow into nine
+ * anchor regions and stack automatically with a gap — no per-panel pixel
+ * offsets, no manual clearance for sibling panels, the touch-control dock
+ * (`--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, }) {
+    const canvasRef = useRef(null);
+    const { compact } = useDisplayProfile();
+    const hudViewport = useHudViewport();
+    const fitEnabled = hudViewport?.fitEnabled === true;
+    const [viewport, setViewport] = useState(null);
+    const [regions, setRegions] = useState({});
+    const regionRefs = useMemo(() => {
+        const refs = {};
+        for (const anchor of HUD_ANCHORS) {
+            refs[anchor] = (el) => {
+                setRegions((prev) => {
+                    if (el === null) {
+                        if (prev[anchor] === undefined)
+                            return prev;
+                        const next = { ...prev };
+                        delete next[anchor];
+                        return next;
+                    }
+                    return prev[anchor] === el ? prev : { ...prev, [anchor]: el };
+                });
+            };
+        }
+        return refs;
+    }, []);
+    const value = useMemo(() => ({ layout, canvasRef, regions, compact }), [layout, regions, compact]);
+    const editing = useEngineState(layout).editing;
+    const chordEnabled = editChord !== false;
+    const hold = editChord === false ? undefined : (editChord?.hold ?? "F2");
+    const press = editChord === false ? undefined : (editChord?.press ?? "KeyC");
+    useEffect(() => {
+        if (!chordEnabled || hold === undefined || press === undefined)
+            return;
+        if (typeof window === "undefined")
+            return;
+        let holding = false;
+        const onKeyDown = (event) => {
+            if (event.code === hold) {
+                holding = true;
+                return;
+            }
+            if (event.code === press && holding) {
+                event.preventDefault();
+                layout.setEditing(!layout.getState().editing);
+                return;
+            }
+            if (event.code === "Escape" && layout.getState().editing) {
+                layout.setEditing(false);
+            }
+        };
+        const onKeyUp = (event) => {
+            if (event.code === hold)
+                holding = false;
+        };
+        const onBlur = () => {
+            holding = false;
+        };
+        window.addEventListener("keydown", onKeyDown);
+        window.addEventListener("keyup", onKeyUp);
+        window.addEventListener("blur", onBlur);
+        return () => {
+            window.removeEventListener("keydown", onKeyDown);
+            window.removeEventListener("keyup", onKeyUp);
+            window.removeEventListener("blur", onBlur);
+        };
+    }, [layout, chordEnabled, hold, press]);
+    useEffect(() => {
+        if (!fitEnabled)
+            return;
+        const host = canvasRef.current?.parentElement;
+        if (host === undefined || host === null || typeof ResizeObserver === "undefined")
+            return;
+        const measure = () => {
+            const rect = host.getBoundingClientRect();
+            const next = { width: Math.round(rect.width), height: Math.round(rect.height) };
+            setViewport((prev) => prev !== null && prev.width === next.width && prev.height === next.height ? prev : next);
+        };
+        measure();
+        const observer = new ResizeObserver(measure);
+        observer.observe(host);
+        return () => observer.disconnect();
+    }, [fitEnabled]);
+    useEffect(() => {
+        const canvas = canvasRef.current;
+        const host = canvas?.parentElement;
+        if (canvas === null || canvas === undefined || host === undefined || host === null)
+            return;
+        if (typeof requestAnimationFrame !== "function")
+            return;
+        let frame = 0;
+        let lastReport = "";
+        const check = () => {
+            frame = 0;
+            const hostRect = host.getBoundingClientRect();
+            if (hostRect.width <= 0 || hostRect.height <= 0)
+                return;
+            const panels = [];
+            for (const el of canvas.querySelectorAll("[data-hud-panel]")) {
+                const rect = el.getBoundingClientRect();
+                if (rect.width === 0 && rect.height === 0)
+                    continue;
+                panels.push({
+                    id: el.getAttribute("data-hud-panel") ?? "?",
+                    rect: {
+                        x: rect.left - hostRect.left,
+                        y: rect.top - hostRect.top,
+                        width: rect.width,
+                        height: rect.height,
+                    },
+                });
+            }
+            const offenders = overflowingPanels(panels, { width: hostRect.width, height: hostRect.height });
+            const report = offenders.length === 0 ? "" : JSON.stringify(offenders);
+            if (report === lastReport)
+                return;
+            lastReport = report;
+            if (report === "") {
+                canvas.removeAttribute("data-hud-overflow");
+            }
+            else {
+                canvas.setAttribute("data-hud-overflow", report);
+                console.warn(`[jgengine] HUD panels overflow the ${Math.round(hostRect.width)}x${Math.round(hostRect.height)} viewport: ${report}`);
+            }
+        };
+        const schedule = () => {
+            if (frame !== 0)
+                return;
+            frame = requestAnimationFrame(check);
+        };
+        const settle = setTimeout(schedule, 400);
+        const resizeObserver = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(schedule);
+        resizeObserver?.observe(host);
+        const mutationObserver = typeof MutationObserver === "undefined" ? null : new MutationObserver(schedule);
+        mutationObserver?.observe(canvas, { childList: true, subtree: true });
+        return () => {
+            clearTimeout(settle);
+            if (frame !== 0)
+                cancelAnimationFrame(frame);
+            resizeObserver?.disconnect();
+            mutationObserver?.disconnect();
+        };
+    }, []);
+    const fit = fitEnabled ? resolveHudFit(hudViewport?.config, compact) : null;
+    const baseScale = fit !== null && viewport !== null
+        ? hudScaleForViewport(fit, viewport)
+        : compact
+            ? (compactScale ?? COMPACT_HUD_SCALE)
+            : 1;
+    const scale = baseScale * (hudViewport?.userScale ?? 1);
+    const basePad = compact ? 10 : 16;
+    const canvasStyle = {
+        position: "absolute",
+        inset: 0,
+        pointerEvents: "none",
+        zoom: scale === 1 ? undefined : scale,
+        "--jg-hud-pad-top": edgePad("env(safe-area-inset-top, 0px)", null, basePad, scale),
+        "--jg-hud-pad-bottom": edgePad("env(safe-area-inset-bottom, 0px)", "var(--jg-hud-dock-clearance, 0px)", basePad, scale),
+        "--jg-hud-pad-left": edgePad("env(safe-area-inset-left, 0px)", null, basePad, scale),
+        "--jg-hud-pad-right": edgePad("env(safe-area-inset-right, 0px)", null, basePad, scale),
+        ...style,
+    };
+    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",
+                        flexDirection: "column",
+                        gap: REGION_GAP,
+                        pointerEvents: "none",
+                        zIndex: 1,
+                        ...REGION_LAYOUT[anchor],
+                    } }, anchor))), children, editing ? _jsx(HudEditBar, { layout: layout }) : null] }) }));
+}
+function chipAlignment(anchor) {
+    if (anchor.endsWith("right"))
+        return "flex-end";
+    if (anchor.endsWith("left"))
+        return "flex-start";
+    return "center";
+}
+function HudChip({ label, anchor, children, }) {
+    const [open, setOpen] = useState(false);
+    return (_jsxs("div", { style: {
+            display: "flex",
+            flexDirection: "column",
+            gap: 6,
+            alignItems: chipAlignment(anchor),
+        }, children: [_jsxs("button", { type: "button", "data-hud-chip": "", onClick: () => setOpen((current) => !current), style: {
+                    pointerEvents: "auto",
+                    display: "inline-flex",
+                    alignItems: "center",
+                    gap: 6,
+                    padding: "4px 10px",
+                    borderRadius: 999,
+                    background: "rgba(10, 10, 14, 0.72)",
+                    border: "1px solid rgba(255, 255, 255, 0.22)",
+                    color: "rgba(255, 255, 255, 0.92)",
+                    font: "600 11px/1.2 system-ui, sans-serif",
+                    letterSpacing: "0.04em",
+                    textTransform: "uppercase",
+                    cursor: "pointer",
+                    whiteSpace: "nowrap",
+                }, children: [_jsx("span", { children: label }), _jsx("span", { "aria-hidden": true, children: open ? "▾" : "▸" })] }), open ? children : 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
+ * pointers panels stay draggable through the edit chord; a dragged panel
+ * 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, }) {
+    const ctx = useContext(HudCanvasContext);
+    if (ctx === null)
+        throw new Error("HudPanel must be rendered inside a HudCanvas");
+    const { layout, canvasRef, regions, compact } = ctx;
+    const registeredOnRef = useRef(null);
+    if (registeredOnRef.current !== layout) {
+        registeredOnRef.current = layout;
+        layout.register(id, anchoredPlacement(anchor, inset ?? { x: 16, y: 16 }));
+    }
+    const layoutState = useEngineState(layout);
+    const panel = layoutState.panels[id];
+    const draggable = !compact && locked !== true && isPanelDraggable(layoutState, id);
+    const editing = layoutState.editing && draggable;
+    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 onPointerDown = (event) => {
+        if (!draggable || event.button !== 0)
+            return;
+        const root = rootRef.current;
+        const canvas = canvasRef.current;
+        if (root === null || canvas === null)
+            return;
+        const canvasRect = canvas.getBoundingClientRect();
+        const rect = root.getBoundingClientRect();
+        suppressClickRef.current = false;
+        const drag = {
+            pointerId: event.pointerId,
+            startX: event.clientX,
+            startY: event.clientY,
+            x: rect.left - canvasRect.left,
+            y: rect.top - canvasRect.top,
+            width: rect.width,
+            height: rect.height,
+            active: false,
+        };
+        dragRef.current = drag;
+        const onMove = (moveEvent) => {
+            if (moveEvent.pointerId !== drag.pointerId)
+                return;
+            const dx = moveEvent.clientX - drag.startX;
+            const dy = moveEvent.clientY - drag.startY;
+            if (!drag.active) {
+                if (dx * dx + dy * dy < DRAG_THRESHOLD_PX * DRAG_THRESHOLD_PX)
+                    return;
+                drag.active = true;
+                suppressClickRef.current = true;
+                layout.bringToFront(id);
+                setDragging(true);
+            }
+            const liveCanvas = canvasRef.current;
+            if (liveCanvas === null)
+                return;
+            const liveRect = liveCanvas.getBoundingClientRect();
+            layout.move(id, { x: drag.x + dx, y: drag.y + dy, width: drag.width, height: drag.height }, { width: liveRect.width, height: liveRect.height });
+        };
+        const onEnd = (endEvent) => {
+            if (endEvent.pointerId !== drag.pointerId)
+                return;
+            detachRef.current?.();
+            dragRef.current = null;
+            setDragging(false);
+        };
+        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;
+        suppressClickRef.current = false;
+        event.preventDefault();
+        event.stopPropagation();
+    };
+    const editingChrome = editing ? (_jsxs(_Fragment, { children: [_jsx("div", { "data-hud-panel-shield": "", style: { position: "absolute", inset: 0, zIndex: 1, cursor: "inherit" } }), _jsx("div", { "data-hud-panel-label": "", style: {
+                    position: "absolute",
+                    top: -20,
+                    left: 0,
+                    zIndex: 2,
+                    pointerEvents: "none",
+                    padding: "1px 6px",
+                    borderRadius: 4,
+                    background: "rgba(10, 10, 14, 0.85)",
+                    color: "rgba(255, 255, 255, 0.9)",
+                    font: "10px/1.5 system-ui, sans-serif",
+                    whiteSpace: "nowrap",
+                }, children: id })] })) : null;
+    if (panel === undefined)
+        return null;
+    if (compact && compactMode === "hide")
+        return null;
+    const flow = compact || !panel.moved;
+    if (flow) {
+        const regionEl = regions[compact ? anchor : panel.placement.anchor];
+        if (regionEl === undefined)
+            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: {
+                position: "relative",
+                order: order ?? 0,
+                pointerEvents: passThrough ? "none" : "auto",
+                touchAction: draggable ? "none" : undefined,
+                userSelect: editing || dragging ? "none" : undefined,
+                cursor: dragging ? "grabbing" : editing ? "grab" : undefined,
+                outline: editing ? "1px dashed rgba(255, 255, 255, 0.6)" : undefined,
+                outlineOffset: editing ? 2 : undefined,
+                ...style,
+            }, children: [chipped ? (_jsx(HudChip, { label: chip ?? id, anchor: anchor, children: children })) : (children), editingChrome] }), regionEl);
+    }
+    const { fx, fy } = HUD_ANCHOR_FRACTIONS[panel.placement.anchor];
+    const position = {};
+    if (fx === 0)
+        position.left = panel.placement.dx;
+    else if (fx === 1)
+        position.right = -panel.placement.dx;
+    else
+        position.left = `calc(50% + ${panel.placement.dx}px)`;
+    if (fy === 0)
+        position.top = panel.placement.dy;
+    else if (fy === 1)
+        position.bottom = -panel.placement.dy;
+    else
+        position.top = `calc(50% + ${panel.placement.dy}px)`;
+    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: {
+            position: "absolute",
+            ...position,
+            zIndex: panel.z,
+            pointerEvents: "auto",
+            touchAction: draggable ? "none" : undefined,
+            userSelect: editing || dragging ? "none" : undefined,
+            cursor: dragging ? "grabbing" : editing ? "grab" : undefined,
+            outline: editing ? "1px dashed rgba(255, 255, 255, 0.6)" : undefined,
+            outlineOffset: editing ? 2 : undefined,
+            ...style,
+        }, children: [children, editingChrome] }));
+}

package/dist/hudViewport.d.ts

@@ -0,0 +1,21 @@
+import { type ReactNode } from "react";
+import type { HudPlatform, HudViewportConfig } from "@jgengine/core/ui/hudScale";
+export interface HudViewportContextValue {
+    /** True unless the game's `platforms` explicitly excludes `"mobile"` — the HUD auto-fits the design resolution to the live viewport. */
+    fitEnabled: boolean;
+    config: HudViewportConfig | undefined;
+    /** Player's UI-scale setting; multiplies the computed fit scale everywhere. */
+    userScale: number;
+}
+/**
+ * Mounted by the shell around `GameUI` so every `HudCanvas` inside the game
+ * picks up the game's `platforms`/`hudFit` declaration and the player's UI
+ * scale setting without any game-side wiring.
+ */
+export declare function HudViewportProvider({ platforms, config, userScale, children, }: {
+    platforms: readonly HudPlatform[] | undefined;
+    config: HudViewportConfig | undefined;
+    userScale?: number;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+export declare function useHudViewport(): HudViewportContextValue | null;

package/dist/hudViewport.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from "react";
+const HudViewportContext = createContext(null);
+/**
+ * Mounted by the shell around `GameUI` so every `HudCanvas` inside the game
+ * picks up the game's `platforms`/`hudFit` declaration and the player's UI
+ * scale setting without any game-side wiring.
+ */
+export function HudViewportProvider({ platforms, config, userScale, children, }) {
+    const fitEnabled = platforms?.includes("mobile") ?? true;
+    const scale = userScale ?? 1;
+    const value = useMemo(() => ({ fitEnabled, config, userScale: scale }), [fitEnabled, config, scale]);
+    return _jsx(HudViewportContext.Provider, { value: value, children: children });
+}
+export function useHudViewport() {
+    return useContext(HudViewportContext);
+}

package/dist/index.d.ts

@@ -1,11 +1,16 @@
 export * from "./provider.js";
 export * from "./identity.js";
 export * from "./chat.js";
+export * from "./chatBubbles.js";
 export * from "./voice.js";
 export * from "./social.js";
 export * from "./hooks.js";
+export * from "./settings.js";
 export * from "./components.js";
 export * from "./engineStore.js";
 export * from "./dragLayer.js";
+export * from "./hudLayout.js";
+export * from "./hudViewport.js";
 export * from "./display.js";
 export * from "./map.js";
+export * from "./preview.js";

package/dist/index.js

@@ -1,11 +1,16 @@
 export * from "./provider.js";
 export * from "./identity.js";
 export * from "./chat.js";
+export * from "./chatBubbles.js";
 export * from "./voice.js";
 export * from "./social.js";
 export * from "./hooks.js";
+export * from "./settings.js";
 export * from "./components.js";
 export * from "./engineStore.js";
 export * from "./dragLayer.js";
+export * from "./hudLayout.js";
+export * from "./hudViewport.js";
 export * from "./display.js";
 export * from "./map.js";
+export * from "./preview.js";

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