@jgengine/core 0.10.0 → 0.12.0

package/dist/ui/hudDocument.d.ts

@@ -0,0 +1,114 @@
+import type { ParamSchema } from "../scene/sceneKinds.js";
+import type { HudAnchor, HudPlacement, HudSize } from "./hudLayout.js";
+/**
+ * Which axes a panel type may grow when resized in canvas mode. Resize is semantic —
+ * content reflows (longer track, more rows) — never a CSS scale of the whole panel.
+ */
+export type HudResizeAxes = "none" | "x" | "y" | "both";
+/** Authored layout for one HUD panel inside `editor.scene.json` → `ui.panels`. */
+export interface EditorUiPanelLayout {
+    anchor: HudAnchor;
+    dx: number;
+    dy: number;
+    width?: number;
+    height?: number;
+    visible?: boolean;
+    /** Panel type id registered via {@link registerHudPanelType}; drives resize + schema. */
+    type?: string;
+}
+/** Scene-document HUD section: panel id → layout. Single source of truth for placement. */
+export interface EditorUiDocument {
+    panels: Record<string, EditorUiPanelLayout>;
+}
+/** TSX-declared fallback when the document has no entry for a panel. */
+export interface HudPanelFallback {
+    anchor: HudAnchor;
+    inset?: {
+        x: number;
+        y: number;
+    };
+    width?: number;
+    height?: number;
+    visible?: boolean;
+    type?: string;
+}
+/** Fully resolved panel layout after document + fallback merge. */
+export interface ResolvedHudPanelLayout {
+    placement: HudPlacement;
+    width?: number;
+    height?: number;
+    visible: boolean;
+    type?: string;
+    /** True when the document owned at least one field (not pure TSX fallback). */
+    fromDocument: boolean;
+}
+/** Declared panel type: growable axes, size limits, optional ParamSchema for the editor. */
+export interface HudPanelTypeDef {
+    id: string;
+    label: string;
+    resize: HudResizeAxes;
+    minWidth?: number;
+    maxWidth?: number;
+    minHeight?: number;
+    maxHeight?: number;
+    defaultWidth?: number;
+    defaultHeight?: number;
+    schema?: ParamSchema;
+}
+/** Register a HUD panel type so the editor can list/add/configure it and canvas resize knows axes. */
+export declare function registerHudPanelType(def: HudPanelTypeDef): void;
+/** @internal Look up a registered panel type by id. */
+export declare function getHudPanelType(id: string): HudPanelTypeDef | undefined;
+/** Every registered panel type, sorted by id — editor palette / agent listing. */
+export declare function listHudPanelTypes(): HudPanelTypeDef[];
+/** @internal Test seam — clear the registry between tests. */
+export declare function clearHudPanelTypes(): void;
+/** @internal Convert a document panel layout into a runtime placement. */
+export declare function placementFromUiPanel(panel: EditorUiPanelLayout): HudPlacement;
+/** @internal Build a document panel layout from a runtime placement plus optional size/visibility. */
+export declare function uiPanelFromPlacement(placement: HudPlacement, options?: {
+    width?: number;
+    height?: number;
+    visible?: boolean;
+    type?: string;
+}): EditorUiPanelLayout;
+/**
+ * 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 declare function resolveHudPanelLayout(docPanel: EditorUiPanelLayout | undefined, fallback: HudPanelFallback): ResolvedHudPanelLayout;
+/** @internal Read a panel layout from a document ui section, or undefined when absent. */
+export declare function findUiPanel(ui: EditorUiDocument | undefined, id: string): EditorUiPanelLayout | undefined;
+/** @internal Immutable patch of one panel into a ui section (creates the section when missing). */
+export declare function patchUiPanel(ui: EditorUiDocument | undefined, id: string, patch: Partial<EditorUiPanelLayout>): EditorUiDocument;
+/** @internal Remove a panel entry from the ui section; returns undefined when the section empties. */
+export declare function removeUiPanel(ui: EditorUiDocument | undefined, id: string): EditorUiDocument | undefined;
+/**
+ * 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 declare function resizePanelSize(current: HudSize, delta: {
+    dw: number;
+    dh: number;
+}, axes: HudResizeAxes, limits?: {
+    minWidth?: number;
+    maxWidth?: number;
+    minHeight?: number;
+    maxHeight?: number;
+}): HudSize;
+/** @internal Resolve resize axes + limits for a panel type id (defaults to none when unregistered). */
+export declare function resolvePanelResize(typeId: string | undefined): {
+    axes: HudResizeAxes;
+    minWidth?: number;
+    maxWidth?: number;
+    minHeight?: number;
+    maxHeight?: number;
+};
+/** @internal Decode a single panel layout from untrusted JSON; null when invalid. */
+export declare function decodeUiPanelLayout(raw: unknown): EditorUiPanelLayout | null;
+/** @internal Decode a ui section from untrusted JSON; undefined when absent, empty object when empty panels. */
+export declare function decodeEditorUiDocument(raw: unknown): EditorUiDocument | undefined;
+/** @internal Deep-clone a ui section for document history snapshots. */
+export declare function cloneEditorUiDocument(ui: EditorUiDocument | undefined): EditorUiDocument | undefined;
+/** @internal Convert a layout store-style placement map into a document ui section. */
+export declare function uiDocumentFromPlacements(panels: Record<string, EditorUiPanelLayout>): EditorUiDocument;

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,64 @@ 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 Notified whenever a `HudCanvas` mounts or unmounts (the active-layout set changes).
+ * Lets the editor's HUD-layout surface enable editing on layouts that mount after it opens.
+ */
+export declare function subscribeActiveHudLayouts(listener: () => void): () => void;
+/** @internal */
 export declare function createHudLayout(options?: HudLayoutOptions): HudLayoutStore;