@jgengine/core 0.10.0 → 0.11.0

package/dist/ui/hudDocument.js

@@ -0,0 +1,220 @@
+import { isHudAnchor } from "./hudLayout.js";
+const panelTypes = new Map();
+/** Register a HUD panel type so the editor can list/add/configure it and canvas resize knows axes. */
+export function registerHudPanelType(def) {
+    panelTypes.set(def.id, def);
+}
+/** @internal Look up a registered panel type by id. */
+export function getHudPanelType(id) {
+    return panelTypes.get(id);
+}
+/** Every registered panel type, sorted by id — editor palette / agent listing. */
+export function listHudPanelTypes() {
+    return [...panelTypes.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+/** @internal Test seam — clear the registry between tests. */
+export function clearHudPanelTypes() {
+    panelTypes.clear();
+}
+/** @internal Convert a document panel layout into a runtime placement. */
+export function placementFromUiPanel(panel) {
+    return { anchor: panel.anchor, dx: panel.dx, dy: panel.dy };
+}
+/** @internal Build a document panel layout from a runtime placement plus optional size/visibility. */
+export function uiPanelFromPlacement(placement, options) {
+    const panel = {
+        anchor: placement.anchor,
+        dx: placement.dx,
+        dy: placement.dy,
+    };
+    if (options?.width !== undefined)
+        panel.width = options.width;
+    if (options?.height !== undefined)
+        panel.height = options.height;
+    if (options?.visible !== undefined)
+        panel.visible = options.visible;
+    if (options?.type !== undefined)
+        panel.type = options.type;
+    return panel;
+}
+function fallbackPlacement(fallback) {
+    const inset = fallback.inset ?? { x: 16, y: 16 };
+    const { anchor } = fallback;
+    const edgeX = anchor.endsWith("right") || anchor === "right";
+    const edgeY = anchor.startsWith("bottom") || anchor === "bottom";
+    return {
+        anchor,
+        dx: edgeX ? -inset.x : inset.x,
+        dy: edgeY ? -inset.y : inset.y,
+    };
+}
+/**
+ * Resolve a panel's layout: document entry wins field-by-field over TSX fallback.
+ * TSX props are fallback-only — the scene document is the source of truth once authored.
+ */
+export function resolveHudPanelLayout(docPanel, fallback) {
+    if (docPanel === undefined) {
+        return {
+            placement: fallbackPlacement(fallback),
+            width: fallback.width,
+            height: fallback.height,
+            visible: fallback.visible !== false,
+            type: fallback.type,
+            fromDocument: false,
+        };
+    }
+    return {
+        placement: placementFromUiPanel(docPanel),
+        width: docPanel.width ?? fallback.width,
+        height: docPanel.height ?? fallback.height,
+        visible: docPanel.visible ?? fallback.visible !== false,
+        type: docPanel.type ?? fallback.type,
+        fromDocument: true,
+    };
+}
+/** @internal Read a panel layout from a document ui section, or undefined when absent. */
+export function findUiPanel(ui, id) {
+    return ui?.panels[id];
+}
+/** @internal Immutable patch of one panel into a ui section (creates the section when missing). */
+export function patchUiPanel(ui, id, patch) {
+    const existing = ui?.panels[id];
+    const base = existing !== undefined
+        ? { ...existing }
+        : {
+            anchor: isHudAnchor(patch.anchor) ? patch.anchor : "top-left",
+            dx: typeof patch.dx === "number" ? patch.dx : 0,
+            dy: typeof patch.dy === "number" ? patch.dy : 0,
+        };
+    const next = { ...base };
+    if (patch.anchor !== undefined && isHudAnchor(patch.anchor))
+        next.anchor = patch.anchor;
+    if (typeof patch.dx === "number" && Number.isFinite(patch.dx))
+        next.dx = patch.dx;
+    if (typeof patch.dy === "number" && Number.isFinite(patch.dy))
+        next.dy = patch.dy;
+    if (typeof patch.width === "number" && Number.isFinite(patch.width))
+        next.width = patch.width;
+    if (typeof patch.height === "number" && Number.isFinite(patch.height))
+        next.height = patch.height;
+    if (typeof patch.visible === "boolean")
+        next.visible = patch.visible;
+    if (typeof patch.type === "string")
+        next.type = patch.type;
+    return {
+        panels: {
+            ...(ui?.panels ?? {}),
+            [id]: next,
+        },
+    };
+}
+/** @internal Remove a panel entry from the ui section; returns undefined when the section empties. */
+export function removeUiPanel(ui, id) {
+    if (ui === undefined || ui.panels[id] === undefined)
+        return ui;
+    const panels = { ...ui.panels };
+    delete panels[id];
+    return Object.keys(panels).length === 0 ? undefined : { panels };
+}
+/**
+ * Semantic resize: apply pixel deltas only on growable axes, clamped to min/max.
+ * Never scales content — callers reflow layout size (track length, list rows).
+ */
+export function resizePanelSize(current, delta, axes, limits) {
+    if (axes === "none")
+        return { ...current };
+    let width = current.width;
+    let height = current.height;
+    if (axes === "x" || axes === "both")
+        width = current.width + delta.dw;
+    if (axes === "y" || axes === "both")
+        height = current.height + delta.dh;
+    const minW = limits?.minWidth ?? 1;
+    const minH = limits?.minHeight ?? 1;
+    const maxW = limits?.maxWidth ?? Number.POSITIVE_INFINITY;
+    const maxH = limits?.maxHeight ?? Number.POSITIVE_INFINITY;
+    return {
+        width: Math.max(minW, Math.min(maxW, Math.round(width))),
+        height: Math.max(minH, Math.min(maxH, Math.round(height))),
+    };
+}
+/** @internal Resolve resize axes + limits for a panel type id (defaults to none when unregistered). */
+export function resolvePanelResize(typeId) {
+    if (typeId === undefined)
+        return { axes: "none" };
+    const def = panelTypes.get(typeId);
+    if (def === undefined)
+        return { axes: "none" };
+    return {
+        axes: def.resize,
+        minWidth: def.minWidth,
+        maxWidth: def.maxWidth,
+        minHeight: def.minHeight,
+        maxHeight: def.maxHeight,
+    };
+}
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+/** @internal Decode a single panel layout from untrusted JSON; null when invalid. */
+export function decodeUiPanelLayout(raw) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        return null;
+    const value = raw;
+    if (!isHudAnchor(value.anchor))
+        return null;
+    if (!isFiniteNumber(value.dx) || !isFiniteNumber(value.dy))
+        return null;
+    const panel = {
+        anchor: value.anchor,
+        dx: value.dx,
+        dy: value.dy,
+    };
+    if (isFiniteNumber(value.width))
+        panel.width = value.width;
+    if (isFiniteNumber(value.height))
+        panel.height = value.height;
+    if (typeof value.visible === "boolean")
+        panel.visible = value.visible;
+    if (typeof value.type === "string" && value.type.length > 0)
+        panel.type = value.type;
+    return panel;
+}
+/** @internal Decode a ui section from untrusted JSON; undefined when absent, empty object when empty panels. */
+export function decodeEditorUiDocument(raw) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const panelsRaw = raw.panels;
+    if (typeof panelsRaw !== "object" || panelsRaw === null || Array.isArray(panelsRaw)) {
+        return { panels: {} };
+    }
+    const panels = {};
+    for (const [id, entry] of Object.entries(panelsRaw)) {
+        if (id.length === 0)
+            continue;
+        const decoded = decodeUiPanelLayout(entry);
+        if (decoded !== null)
+            panels[id] = decoded;
+    }
+    return { panels };
+}
+/** @internal Deep-clone a ui section for document history snapshots. */
+export function cloneEditorUiDocument(ui) {
+    if (ui === undefined)
+        return undefined;
+    const panels = {};
+    for (const [id, panel] of Object.entries(ui.panels)) {
+        panels[id] = { ...panel };
+    }
+    return { panels };
+}
+/** @internal Convert a layout store-style placement map into a document ui section. */
+export function uiDocumentFromPlacements(panels) {
+    const out = {};
+    for (const [id, panel] of Object.entries(panels)) {
+        out[id] = { ...panel };
+    }
+    return { panels: out };
+}

package/dist/ui/hudLayout.d.ts

@@ -19,6 +19,10 @@ export interface HudPanelState {
     placement: HudPlacement;
     z: number;
     moved: boolean;
+    width?: number;
+    height?: number;
+    visible: boolean;
+    type?: string;
 }
 export interface HudLayoutState {
     panels: Record<string, HudPanelState>;
@@ -28,31 +32,59 @@ export interface HudLayoutState {
 export interface HudLayoutOptions {
     snap?: number;
     locked?: boolean;
+    /**
+     * Called after a panel placement/size is authored (move, resize, hydrate from document).
+     * Canvas mode + agent RPCs use this to write undoable scene-document patches.
+     */
+    onDocumentPatch?: (id: string, panel: import("./hudDocument.js").EditorUiPanelLayout) => void;
 }
+/** @internal */
 export declare function isPanelDraggable(state: HudLayoutState, id: string): boolean;
 export interface HudLayoutStore {
     getState(): HudLayoutState;
     subscribe(listener: (state: HudLayoutState) => void): () => void;
-    register(id: string, placement: HudPlacement): void;
+    register(id: string, placement: HudPlacement, options?: {
+        width?: number;
+        height?: number;
+        visible?: boolean;
+        type?: string;
+    }): void;
     move(id: string, rect: HudRect, viewport: HudSize): void;
+    resize(id: string, size: HudSize): void;
+    setVisible(id: string, visible: boolean): void;
     bringToFront(id: string): void;
     setLocked(locked: boolean): void;
     setEditing(editing: boolean): void;
     reset(id?: string): void;
     serialize(): string;
     hydrate(raw: string | null | undefined): void;
+    /** Apply scene-document `ui` section as the source of truth for registered/pending panels. */
+    applyDocumentUi(ui: import("./hudDocument.js").EditorUiDocument | undefined): void;
+    /** Snapshot moved/resized panels as a document ui section. */
+    toDocumentUi(): import("./hudDocument.js").EditorUiDocument;
 }
 export declare const HUD_ANCHOR_FRACTIONS: Record<HudAnchor, {
     fx: number;
     fy: number;
 }>;
+/** @internal */
 export declare function isHudAnchor(value: unknown): value is HudAnchor;
+/** @internal */
 export declare function anchoredPlacement(anchor: HudAnchor, inset: {
     x: number;
     y: number;
 }): HudPlacement;
+/** @internal */
 export declare function nearestAnchor(rect: HudRect, viewport: HudSize): HudAnchor;
+/** @internal */
 export declare function clampRect(rect: HudRect, viewport: HudSize): HudRect;
+/** @internal */
 export declare function placementFromRect(rect: HudRect, viewport: HudSize, snap?: number): HudPlacement;
+/** @internal */
 export declare function rectFromPlacement(placement: HudPlacement, size: HudSize, viewport: HudSize): HudRect;
+/** @internal Agent bridge seam — HudCanvas registers its store while mounted so headless drivers can reach canvas mode. */
+export declare function registerActiveHudLayout(store: HudLayoutStore): () => void;
+/** @internal */
+export declare function listActiveHudLayouts(): HudLayoutStore[];
+/** @internal */
 export declare function createHudLayout(options?: HudLayoutOptions): HudLayoutStore;

package/dist/ui/hudLayout.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function isPanelDraggable(state, id) {
     return state.panels[id] !== undefined && (state.editing || !state.locked);
 }
@@ -13,9 +14,11 @@ export const HUD_ANCHOR_FRACTIONS = {
     "bottom-right": { fx: 1, fy: 1 },
 };
 const HUD_ANCHORS = Object.keys(HUD_ANCHOR_FRACTIONS);
+/** @internal */
 export function isHudAnchor(value) {
     return typeof value === "string" && value in HUD_ANCHOR_FRACTIONS;
 }
+/** @internal */
 export function anchoredPlacement(anchor, inset) {
     const { fx, fy } = HUD_ANCHOR_FRACTIONS[anchor];
     return {
@@ -24,6 +27,7 @@ export function anchoredPlacement(anchor, inset) {
         dy: fy === 1 ? -inset.y : inset.y,
     };
 }
+/** @internal */
 export function nearestAnchor(rect, viewport) {
     const cx = viewport.width > 0 ? (rect.x + rect.width / 2) / viewport.width : 0.5;
     const cy = viewport.height > 0 ? (rect.y + rect.height / 2) / viewport.height : 0.5;
@@ -39,6 +43,7 @@ export function nearestAnchor(rect, viewport) {
     }
     return best;
 }
+/** @internal */
 export function clampRect(rect, viewport) {
     return {
         x: Math.max(0, Math.min(rect.x, viewport.width - rect.width)),
@@ -47,6 +52,7 @@ export function clampRect(rect, viewport) {
         height: rect.height,
     };
 }
+/** @internal */
 export function placementFromRect(rect, viewport, snap = 1) {
     const clamped = clampRect(rect, viewport);
     const anchor = nearestAnchor(clamped, viewport);
@@ -60,6 +66,7 @@ export function placementFromRect(rect, viewport, snap = 1) {
         dy: Math.round(dy / step) * step,
     };
 }
+/** @internal */
 export function rectFromPlacement(placement, size, viewport) {
     const { fx, fy } = HUD_ANCHOR_FRACTIONS[placement.anchor];
     return {
@@ -86,19 +93,77 @@ function parseSerialized(raw) {
     for (const [id, value] of Object.entries(panels)) {
         if (typeof value !== "object" || value === null)
             continue;
-        const { anchor, dx, dy } = value;
+        const record = value;
+        const placementSource = record.placement ?? record;
+        const { anchor, dx, dy } = placementSource;
         if (!isHudAnchor(anchor))
             continue;
         if (typeof dx !== "number" || !Number.isFinite(dx))
             continue;
         if (typeof dy !== "number" || !Number.isFinite(dy))
             continue;
-        out.set(id, { anchor, dx, dy });
+        const override = { placement: { anchor, dx, dy } };
+        if (typeof record.width === "number" && Number.isFinite(record.width))
+            override.width = record.width;
+        if (typeof record.height === "number" && Number.isFinite(record.height))
+            override.height = record.height;
+        if (typeof record.visible === "boolean")
+            override.visible = record.visible;
+        if (typeof record.type === "string")
+            override.type = record.type;
+        out.set(id, override);
     }
     return out;
 }
+const activeHudLayouts = new Set();
+/** @internal Agent bridge seam — HudCanvas registers its store while mounted so headless drivers can reach canvas mode. */
+export function registerActiveHudLayout(store) {
+    activeHudLayouts.add(store);
+    return () => {
+        activeHudLayouts.delete(store);
+    };
+}
+/** @internal */
+export function listActiveHudLayouts() {
+    return [...activeHudLayouts];
+}
+function panelToUi(panel) {
+    const layout = {
+        anchor: panel.placement.anchor,
+        dx: panel.placement.dx,
+        dy: panel.placement.dy,
+    };
+    if (panel.width !== undefined)
+        layout.width = panel.width;
+    if (panel.height !== undefined)
+        layout.height = panel.height;
+    if (panel.visible === false)
+        layout.visible = false;
+    if (panel.type !== undefined)
+        layout.type = panel.type;
+    return layout;
+}
+function overrideToUi(id, override) {
+    const layout = {
+        anchor: override.placement.anchor,
+        dx: override.placement.dx,
+        dy: override.placement.dy,
+    };
+    if (override.width !== undefined)
+        layout.width = override.width;
+    if (override.height !== undefined)
+        layout.height = override.height;
+    if (override.visible !== undefined)
+        layout.visible = override.visible;
+    if (override.type !== undefined)
+        layout.type = override.type;
+    void id;
+    return layout;
+}
+/** @internal */
 export function createHudLayout(options) {
     const snap = options?.snap ?? 1;
+    const onDocumentPatch = options?.onDocumentPatch;
     const defaults = new Map();
     const pending = new Map();
     let topZ = 0;
@@ -111,22 +176,37 @@ export function createHudLayout(options) {
     const setPanel = (panel) => {
         state = { ...state, panels: { ...state.panels, [panel.id]: panel } };
     };
+    const notifyDocument = (panel) => {
+        onDocumentPatch?.(panel.id, panelToUi(panel));
+    };
     return {
         getState: () => state,
         subscribe(listener) {
             listeners.add(listener);
             return () => listeners.delete(listener);
         },
-        register(id, placement) {
-            defaults.set(id, placement);
+        register(id, placement, registerOptions) {
+            const fallback = {
+                placement,
+                width: registerOptions?.width,
+                height: registerOptions?.height,
+                visible: registerOptions?.visible,
+                type: registerOptions?.type,
+            };
+            defaults.set(id, fallback);
             if (state.panels[id] !== undefined)
                 return;
             const override = pending.get(id);
+            const source = override ?? fallback;
             setPanel({
                 id,
-                placement: override ?? placement,
+                placement: source.placement,
                 z: ++topZ,
                 moved: override !== undefined,
+                width: source.width ?? fallback.width,
+                height: source.height ?? fallback.height,
+                visible: source.visible ?? fallback.visible !== false,
+                type: source.type ?? fallback.type,
             });
         },
         move(id, rect, viewport) {
@@ -134,8 +214,32 @@ export function createHudLayout(options) {
             if (panel === undefined)
                 return;
             const placement = placementFromRect(rect, viewport, snap);
-            setPanel({ ...panel, placement, moved: true });
+            const next = { ...panel, placement, moved: true };
+            setPanel(next);
             emit();
+            notifyDocument(next);
+        },
+        resize(id, size) {
+            const panel = state.panels[id];
+            if (panel === undefined)
+                return;
+            const width = Math.max(1, Math.round(size.width));
+            const height = Math.max(1, Math.round(size.height));
+            if (panel.width === width && panel.height === height)
+                return;
+            const next = { ...panel, width, height, moved: true };
+            setPanel(next);
+            emit();
+            notifyDocument(next);
+        },
+        setVisible(id, visible) {
+            const panel = state.panels[id];
+            if (panel === undefined || panel.visible === visible)
+                return;
+            const next = { ...panel, visible, moved: true };
+            setPanel(next);
+            emit();
+            notifyDocument(next);
         },
         bringToFront(id) {
             const panel = state.panels[id];
@@ -163,9 +267,23 @@ export function createHudLayout(options) {
                 pending.delete(panelId);
                 const panel = state.panels[panelId];
                 const fallback = defaults.get(panelId);
-                if (panel === undefined || fallback === undefined || !panel.moved)
+                if (panel === undefined || fallback === undefined)
+                    continue;
+                const hasAuthored = panel.moved ||
+                    panel.width !== fallback.width ||
+                    panel.height !== fallback.height ||
+                    panel.visible !== (fallback.visible !== false);
+                if (!hasAuthored)
                     continue;
-                setPanel({ ...panel, placement: fallback, moved: false });
+                setPanel({
+                    ...panel,
+                    placement: fallback.placement,
+                    width: fallback.width,
+                    height: fallback.height,
+                    visible: fallback.visible !== false,
+                    type: fallback.type,
+                    moved: false,
+                });
                 changed = true;
             }
             if (changed)
@@ -174,14 +292,32 @@ export function createHudLayout(options) {
         serialize() {
             const panels = {};
             for (const panel of Object.values(state.panels)) {
-                if (panel.moved)
-                    panels[panel.id] = panel.placement;
+                if (!panel.moved)
+                    continue;
+                panels[panel.id] = {
+                    anchor: panel.placement.anchor,
+                    dx: panel.placement.dx,
+                    dy: panel.placement.dy,
+                    ...(panel.width === undefined ? {} : { width: panel.width }),
+                    ...(panel.height === undefined ? {} : { height: panel.height }),
+                    ...(panel.visible === false ? { visible: false } : {}),
+                    ...(panel.type === undefined ? {} : { type: panel.type }),
+                };
             }
-            for (const [id, placement] of pending) {
-                if (state.panels[id] === undefined)
-                    panels[id] = placement;
+            for (const [id, override] of pending) {
+                if (state.panels[id] !== undefined)
+                    continue;
+                panels[id] = {
+                    anchor: override.placement.anchor,
+                    dx: override.placement.dx,
+                    dy: override.placement.dy,
+                    ...(override.width === undefined ? {} : { width: override.width }),
+                    ...(override.height === undefined ? {} : { height: override.height }),
+                    ...(override.visible === undefined ? {} : { visible: override.visible }),
+                    ...(override.type === undefined ? {} : { type: override.type }),
+                };
             }
-            const data = { v: 1, panels };
+            const data = { v: 2, panels };
             return JSON.stringify(data);
         },
         hydrate(raw) {
@@ -191,17 +327,68 @@ export function createHudLayout(options) {
             if (parsed.size === 0)
                 return;
             let changed = false;
-            for (const [id, placement] of parsed) {
+            for (const [id, override] of parsed) {
+                const panel = state.panels[id];
+                if (panel === undefined) {
+                    pending.set(id, override);
+                    continue;
+                }
+                setPanel({
+                    ...panel,
+                    placement: override.placement,
+                    width: override.width ?? panel.width,
+                    height: override.height ?? panel.height,
+                    visible: override.visible ?? panel.visible,
+                    type: override.type ?? panel.type,
+                    moved: true,
+                });
+                changed = true;
+            }
+            if (changed)
+                emit();
+        },
+        applyDocumentUi(ui) {
+            if (ui === undefined)
+                return;
+            let changed = false;
+            for (const [id, layout] of Object.entries(ui.panels)) {
+                const override = {
+                    placement: { anchor: layout.anchor, dx: layout.dx, dy: layout.dy },
+                    width: layout.width,
+                    height: layout.height,
+                    visible: layout.visible,
+                    type: layout.type,
+                };
                 const panel = state.panels[id];
                 if (panel === undefined) {
-                    pending.set(id, placement);
+                    pending.set(id, override);
                     continue;
                 }
-                setPanel({ ...panel, placement, moved: true });
+                setPanel({
+                    ...panel,
+                    placement: override.placement,
+                    width: override.width ?? panel.width,
+                    height: override.height ?? panel.height,
+                    visible: override.visible ?? panel.visible,
+                    type: override.type ?? panel.type,
+                    moved: true,
+                });
                 changed = true;
             }
             if (changed)
                 emit();
         },
+        toDocumentUi() {
+            const panels = {};
+            for (const panel of Object.values(state.panels)) {
+                if (panel.moved)
+                    panels[panel.id] = panelToUi(panel);
+            }
+            for (const [id, override] of pending) {
+                if (state.panels[id] === undefined)
+                    panels[id] = overrideToUi(id, override);
+            }
+            return { panels };
+        },
     };
 }