@slowclap/rezi-core 0.1.0-fork.1

package/dist/layout/engine/layoutEngine.js

@@ -0,0 +1,969 @@
+/**
+ * packages/core/src/layout/layout.ts — Widget tree layout computation.
+ *
+ * Why: Computes absolute positions and sizes for all widgets in a VNode tree.
+ * Uses a constraint-based approach: parent provides max width/height, children
+ * report their natural size, and the layout algorithm positions them accordingly.
+ *
+ * Layout rules:
+ *   - Text/Button/Input: single row, width = content width
+ *   - Spacer: size cells in stack axis, 0 or 1 in cross axis
+ *   - Row: horizontal stack with pad/gap/align
+ *   - Column: vertical stack with pad/gap/align
+ *   - Box: optional border + pad, children laid out as column
+ *
+ * Invariants:
+ *   - All coordinates are int32 in range [-2147483648, 2147483647]
+ *   - Negative dimensions clamped to 0
+ *   - Props validated before layout; invalid props produce fatal error
+ *
+ * @see docs/guide/layout.md
+ */
+import { layoutBoxKinds, measureBoxKinds } from "../kinds/box.js";
+import { layoutCollections, measureCollections } from "../kinds/collections.js";
+import { layoutGridKinds, measureGridKinds } from "../kinds/grid.js";
+import { layoutLeafKind, measureLeaf } from "../kinds/leaf.js";
+import { layoutNavigationKinds, measureNavigationKinds } from "../kinds/navigation.js";
+import { layoutOverlays, measureOverlays } from "../kinds/overlays.js";
+import { layoutSplitPaneKinds, measureSplitPaneKinds } from "../kinds/splitPane.js";
+import { layoutStackKinds, measureStackKinds } from "../kinds/stack.js";
+import { clampNonNegative, isI32 } from "./bounds.js";
+import { getActiveDirtySet, popDirtySet, pushDirtySet } from "./dirtySet.js";
+// Layout profiling counters exposed via the pipeline API.
+export const __layoutProfile = {
+    enabled: false,
+    layoutNodeCalls: 0,
+    measureNodeCalls: 0,
+    measureCacheHits: 0,
+    layoutCacheHits: 0,
+    layoutByKind: {},
+    measureByKind: {},
+    reset() {
+        this.layoutNodeCalls = 0;
+        this.measureNodeCalls = 0;
+        this.measureCacheHits = 0;
+        this.layoutCacheHits = 0;
+        this.layoutByKind = {};
+        this.measureByKind = {};
+    },
+};
+let activeMeasureCache = null;
+const measureCacheStack = [];
+let activeLayoutCache = null;
+const layoutCacheStack = [];
+const syntheticTransparentColumnCache = new WeakMap();
+const NULL_FORCED_DIMENSION = -1;
+const LEGACY_SIZE_PROP_NAMES = Object.freeze([
+    "width",
+    "height",
+    "minWidth",
+    "maxWidth",
+    "minHeight",
+    "maxHeight",
+    "flexBasis",
+]);
+const LAYOUT_CHILD_CONSTRAINT_PROP_NAMES = Object.freeze([
+    "flex",
+    "flexShrink",
+    "flexBasis",
+    "alignSelf",
+    "gridColumn",
+    "gridRow",
+    "colSpan",
+    "rowSpan",
+]);
+const ABSOLUTE_POSITION_PROP_NAMES = Object.freeze([
+    "position",
+    "top",
+    "right",
+    "bottom",
+    "left",
+]);
+const LAYOUT_CHILD_CONSTRAINT_KINDS = new Set([
+    "box",
+    "row",
+    "column",
+    "grid",
+    "virtualList",
+    "table",
+    "tree",
+    "filePicker",
+    "fileTreeExplorer",
+    "codeEditor",
+    "diffViewer",
+    "logsConsole",
+    "canvas",
+    "image",
+    "lineChart",
+    "scatter",
+    "heatmap",
+    "sparkline",
+    "barChart",
+    "miniChart",
+    "gauge",
+]);
+const ABSOLUTE_POSITION_PARENT_KINDS = new Set(["box", "row", "column"]);
+const LAYOUT_CHILD_CONSTRAINT_KIND_LIST = Array.from(LAYOUT_CHILD_CONSTRAINT_KINDS)
+    .sort()
+    .join(", ");
+const NODE_ENV = globalThis.process?.env?.NODE_ENV ??
+    "development";
+const DEV_MODE = NODE_ENV !== "production";
+const emittedLayoutConstraintWarnings = new Set();
+function warnDev(message) {
+    if (!DEV_MODE)
+        return;
+    const c = globalThis.console;
+    c?.warn?.(message);
+}
+export function __resetLayoutConstraintWarningsForTest() {
+    emittedLayoutConstraintWarnings.clear();
+}
+function isLegacyBreakpointMap(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    if (value.kind === "fluid")
+        return false;
+    const record = value;
+    return "sm" in record || "md" in record || "lg" in record || "xl" in record;
+}
+function findLegacyConstraintUsage(root) {
+    const stack = [{ node: root, path: root.kind }];
+    const visited = new WeakSet();
+    while (stack.length > 0) {
+        const frame = stack.pop();
+        if (!frame)
+            continue;
+        const { node, path } = frame;
+        if (visited.has(node))
+            continue;
+        visited.add(node);
+        const props = (node.props ?? {});
+        for (const propName of LEGACY_SIZE_PROP_NAMES) {
+            const value = props[propName];
+            if (typeof value === "string" && value.trim().endsWith("%")) {
+                return `${path}.${propName}: percentage strings are removed. Use expr("parent.${propName === "height" || propName === "minHeight" || propName === "maxHeight" ? "h" : "w"} * <ratio>"), "full", numbers, or fluid(...).`;
+            }
+            if (isLegacyBreakpointMap(value)) {
+                return `${path}.${propName}: responsive maps are removed. Use expr("steps(...)"), fluid(...), or explicit values.`;
+            }
+        }
+        const children = node.children;
+        if (Array.isArray(children) && children.length > 0) {
+            for (let i = children.length - 1; i >= 0; i--) {
+                const child = children[i];
+                if (!child)
+                    continue;
+                stack.push({ node: child, path: `${path}>${child.kind}[${String(i)}]` });
+            }
+        }
+        if (node.kind === "modal") {
+            const modalProps = node.props;
+            if (modalProps.content &&
+                typeof modalProps.content === "object" &&
+                "kind" in modalProps.content) {
+                stack.push({ node: modalProps.content, path: `${path}.content` });
+            }
+            if (Array.isArray(modalProps.actions)) {
+                for (let i = modalProps.actions.length - 1; i >= 0; i--) {
+                    const action = modalProps.actions[i];
+                    if (!action || typeof action !== "object" || !("kind" in action))
+                        continue;
+                    stack.push({ node: action, path: `${path}.actions[${String(i)}]` });
+                }
+            }
+        }
+        else if (node.kind === "layer") {
+            const layerContent = node.props.content;
+            if (layerContent && typeof layerContent === "object" && "kind" in layerContent) {
+                stack.push({ node: layerContent, path: `${path}.content` });
+            }
+        }
+    }
+    return null;
+}
+function findUnsupportedLayoutConstraintUsage(root) {
+    const issues = [];
+    const stack = [
+        { node: root, path: root.kind, parentKind: null },
+    ];
+    const visitedByParentKind = new WeakMap();
+    while (stack.length > 0) {
+        const frame = stack.pop();
+        if (!frame)
+            continue;
+        const { node, path, parentKind } = frame;
+        const seenParentKinds = visitedByParentKind.get(node);
+        if (seenParentKinds?.has(parentKind))
+            continue;
+        if (seenParentKinds === undefined) {
+            visitedByParentKind.set(node, new Set([parentKind]));
+        }
+        else {
+            seenParentKinds.add(parentKind);
+        }
+        const props = (node.props ?? {});
+        if (!LAYOUT_CHILD_CONSTRAINT_KINDS.has(node.kind)) {
+            const unsupportedProps = [];
+            for (const propName of LAYOUT_CHILD_CONSTRAINT_PROP_NAMES) {
+                if (props[propName] === undefined)
+                    continue;
+                // spacer supports only flex grow/shrink behavior from parent stack.
+                if (node.kind === "spacer" && propName === "flex")
+                    continue;
+                unsupportedProps.push(propName);
+            }
+            if (unsupportedProps.length > 0) {
+                issues.push(`${path}: ${node.kind} ignores ${unsupportedProps.join(", ")}`);
+            }
+        }
+        const position = props.position;
+        const usesAbsoluteOffsets = LAYOUT_CHILD_CONSTRAINT_KINDS.has(node.kind) &&
+            ABSOLUTE_POSITION_PROP_NAMES.some((propName) => propName !== "position" && props[propName] !== undefined);
+        const usesAbsolutePosition = position === "absolute" || usesAbsoluteOffsets;
+        if (usesAbsolutePosition &&
+            (parentKind === null || !ABSOLUTE_POSITION_PARENT_KINDS.has(parentKind))) {
+            const parentLabel = parentKind === null ? "root" : parentKind;
+            issues.push(`${path}: absolute positioning is only honored for children of box/row/column (parent: ${parentLabel})`);
+        }
+        const children = node.children;
+        if (Array.isArray(children) && children.length > 0) {
+            for (let i = children.length - 1; i >= 0; i--) {
+                const child = children[i];
+                if (!child)
+                    continue;
+                stack.push({
+                    node: child,
+                    path: `${path}>${child.kind}[${String(i)}]`,
+                    parentKind: node.kind,
+                });
+            }
+        }
+        if (node.kind === "modal") {
+            const modalProps = node.props;
+            if (modalProps.content &&
+                typeof modalProps.content === "object" &&
+                "kind" in modalProps.content) {
+                stack.push({
+                    node: modalProps.content,
+                    path: `${path}.content`,
+                    parentKind: node.kind,
+                });
+            }
+            if (Array.isArray(modalProps.actions)) {
+                for (let i = modalProps.actions.length - 1; i >= 0; i--) {
+                    const action = modalProps.actions[i];
+                    if (!action || typeof action !== "object" || !("kind" in action))
+                        continue;
+                    stack.push({
+                        node: action,
+                        path: `${path}.actions[${String(i)}]`,
+                        parentKind: node.kind,
+                    });
+                }
+            }
+        }
+        else if (node.kind === "layer") {
+            const layerContent = node.props.content;
+            if (layerContent && typeof layerContent === "object" && "kind" in layerContent) {
+                stack.push({
+                    node: layerContent,
+                    path: `${path}.content`,
+                    parentKind: node.kind,
+                });
+            }
+        }
+    }
+    return Object.freeze(issues);
+}
+function warnUnsupportedLayoutConstraintUsage(root) {
+    if (!DEV_MODE)
+        return;
+    const issues = findUnsupportedLayoutConstraintUsage(root);
+    for (const issue of issues) {
+        if (emittedLayoutConstraintWarnings.has(issue))
+            continue;
+        emittedLayoutConstraintWarnings.add(issue);
+        warnDev(`[rezi] layout: ${issue}. Supported child-constraint kinds: ${LAYOUT_CHILD_CONSTRAINT_KIND_LIST}.`);
+    }
+}
+function pushMeasureCache(cache) {
+    measureCacheStack.push(cache);
+    activeMeasureCache = cache;
+}
+function popMeasureCache() {
+    measureCacheStack.pop();
+    activeMeasureCache =
+        measureCacheStack.length > 0 ? (measureCacheStack[measureCacheStack.length - 1] ?? null) : null;
+}
+function pushLayoutCache(cache) {
+    layoutCacheStack.push(cache);
+    activeLayoutCache = cache;
+}
+function popLayoutCache() {
+    layoutCacheStack.pop();
+    activeLayoutCache =
+        layoutCacheStack.length > 0 ? (layoutCacheStack[layoutCacheStack.length - 1] ?? null) : null;
+}
+function forcedDimensionKey(value) {
+    if (value === null)
+        return NULL_FORCED_DIMENSION;
+    if (value < 0) {
+        throw new RangeError("layout: forced dimensions must be >= 0");
+    }
+    return value;
+}
+function getLayoutCacheHit(axisMap, maxW, maxH, forcedW, forcedH, x, y) {
+    const byMaxH = axisMap.get(maxW);
+    if (!byMaxH)
+        return null;
+    const byForcedW = byMaxH.get(maxH);
+    if (!byForcedW)
+        return null;
+    const byForcedH = byForcedW.get(forcedDimensionKey(forcedW));
+    if (!byForcedH)
+        return null;
+    const byX = byForcedH.get(forcedDimensionKey(forcedH));
+    if (!byX)
+        return null;
+    const byY = byX.get(x);
+    if (!byY)
+        return null;
+    return byY.get(y) ?? null;
+}
+function setLayoutCacheValue(axisMap, maxW, maxH, forcedW, forcedH, x, y, value) {
+    let byMaxH = axisMap.get(maxW);
+    if (!byMaxH) {
+        byMaxH = new Map();
+        axisMap.set(maxW, byMaxH);
+    }
+    let byForcedW = byMaxH.get(maxH);
+    if (!byForcedW) {
+        byForcedW = new Map();
+        byMaxH.set(maxH, byForcedW);
+    }
+    const forcedWKey = forcedDimensionKey(forcedW);
+    let byForcedH = byForcedW.get(forcedWKey);
+    if (!byForcedH) {
+        byForcedH = new Map();
+        byForcedW.set(forcedWKey, byForcedH);
+    }
+    const forcedHKey = forcedDimensionKey(forcedH);
+    let byX = byForcedH.get(forcedHKey);
+    if (!byX) {
+        byX = new Map();
+        byForcedH.set(forcedHKey, byX);
+    }
+    let byY = byX.get(x);
+    if (!byY) {
+        byY = new Map();
+        byX.set(x, byY);
+    }
+    byY.set(y, value);
+}
+function getSyntheticTransparentColumn(vnode) {
+    const hit = syntheticTransparentColumnCache.get(vnode);
+    if (hit && hit.childrenRef === vnode.children)
+        return hit.columnNode;
+    const columnNode = { kind: "column", props: { gap: 0 }, children: vnode.children };
+    syntheticTransparentColumnCache.set(vnode, Object.freeze({ childrenRef: vnode.children, columnNode }));
+    return columnNode;
+}
+function isVNode(value) {
+    return typeof value === "object" && value !== null && "kind" in value;
+}
+function hiddenLayoutChildrenForVNode(vnode) {
+    if (vnode.kind === "field" || vnode.kind === "resizablePanel") {
+        const onlyChild = vnode.children[0];
+        return isVNode(onlyChild) ? [onlyChild] : [];
+    }
+    const directChildren = vnode.children;
+    if (Array.isArray(directChildren) && directChildren.length > 0) {
+        return directChildren.filter((child) => isVNode(child));
+    }
+    if (vnode.kind === "layer") {
+        const content = vnode.props?.content;
+        return isVNode(content) ? [content] : [];
+    }
+    if (vnode.kind === "modal") {
+        const props = vnode.props ?? {};
+        const children = [];
+        if (isVNode(props.content))
+            children.push(props.content);
+        if (Array.isArray(props.actions)) {
+            for (let i = 0; i < props.actions.length; i++) {
+                const action = props.actions[i];
+                if (isVNode(action))
+                    children.push(action);
+            }
+        }
+        return children;
+    }
+    return [];
+}
+function buildHiddenLayoutTree(vnode, x, y) {
+    const childNodes = hiddenLayoutChildrenForVNode(vnode);
+    if (childNodes.length === 0) {
+        return {
+            vnode,
+            rect: { x, y, w: 0, h: 0 },
+            children: Object.freeze([]),
+        };
+    }
+    const hiddenChildren = [];
+    for (let i = 0; i < childNodes.length; i++) {
+        const child = childNodes[i];
+        if (!child)
+            continue;
+        hiddenChildren.push(buildHiddenLayoutTree(child, x, y));
+    }
+    return {
+        vnode,
+        rect: { x, y, w: 0, h: 0 },
+        children: Object.freeze(hiddenChildren),
+    };
+}
+/**
+ * Measure the natural size of a VNode given constraints.
+ * Does not position; only computes width and height.
+ */
+function measureNode(vnode, maxW, maxH, axis) {
+    if (!isI32(maxW) || maxW < 0) {
+        return {
+            ok: false,
+            fatal: { code: "ZRUI_INVALID_PROPS", detail: "measure: maxW must be an int32 >= 0" },
+        };
+    }
+    if (!isI32(maxH) || maxH < 0) {
+        return {
+            ok: false,
+            fatal: { code: "ZRUI_INVALID_PROPS", detail: "measure: maxH must be an int32 >= 0" },
+        };
+    }
+    const display = vnode.props?.display;
+    if (display === false) {
+        return { ok: true, value: { w: 0, h: 0 } };
+    }
+    if (__layoutProfile.enabled) {
+        __layoutProfile.measureNodeCalls++;
+        __layoutProfile.measureByKind[vnode.kind] =
+            (__layoutProfile.measureByKind[vnode.kind] ?? 0) + 1;
+    }
+    const cache = activeMeasureCache;
+    if (cache) {
+        const entry = cache.get(vnode);
+        if (entry) {
+            const axisMap = axis === "row" ? entry.row : entry.column;
+            const byH = axisMap.get(maxW);
+            const hit = byH?.get(maxH);
+            if (hit) {
+                if (__layoutProfile.enabled)
+                    __layoutProfile.measureCacheHits++;
+                return hit;
+            }
+        }
+    }
+    let computed;
+    switch (vnode.kind) {
+        case "text":
+        case "button":
+        case "input":
+        case "focusAnnouncer":
+        case "slider":
+        case "spacer":
+        case "divider":
+        case "icon":
+        case "spinner":
+        case "progress":
+        case "skeleton":
+        case "richText":
+        case "kbd":
+        case "badge":
+        case "status":
+        case "tag":
+        case "gauge":
+        case "empty":
+        case "errorDisplay":
+        case "callout":
+        case "link":
+        case "canvas":
+        case "image":
+        case "lineChart":
+        case "scatter":
+        case "heatmap":
+        case "sparkline":
+        case "barChart":
+        case "miniChart": {
+            computed = measureLeaf(vnode, maxW, maxH, axis);
+            break;
+        }
+        case "row": {
+            computed = measureStackKinds(vnode, maxW, maxH, axis, measureNode);
+            break;
+        }
+        case "column": {
+            computed = measureStackKinds(vnode, maxW, maxH, axis, measureNode);
+            break;
+        }
+        case "fragment":
+        case "themed": {
+            const transparentVNode = vnode;
+            if (transparentVNode.children.length === 0) {
+                computed = { ok: true, value: { w: 0, h: 0 } };
+                break;
+            }
+            if (transparentVNode.children.length === 1) {
+                const child = transparentVNode.children[0];
+                computed = child
+                    ? measureNode(child, maxW, maxH, axis)
+                    : { ok: true, value: { w: 0, h: 0 } };
+                break;
+            }
+            const syntheticColumn = getSyntheticTransparentColumn(transparentVNode);
+            computed = measureNode(syntheticColumn, maxW, maxH, "column");
+            break;
+        }
+        case "grid": {
+            computed = measureGridKinds(vnode, maxW, maxH, axis, measureNode);
+            break;
+        }
+        case "box": {
+            computed = measureBoxKinds(vnode, maxW, maxH, axis, measureNode);
+            break;
+        }
+        case "focusZone":
+        case "focusTrap": {
+            computed = measureOverlays(vnode, maxW, maxH, axis, measureNode);
+            break;
+        }
+        case "virtualList": {
+            computed = measureCollections(vnode, maxW, maxH);
+            break;
+        }
+        case "layers":
+        case "modal":
+        case "dropdown":
+        case "layer": {
+            computed = measureOverlays(vnode, maxW, maxH, axis, measureNode);
+            break;
+        }
+        case "table":
+        case "tree": {
+            computed = measureCollections(vnode, maxW, maxH);
+            break;
+        }
+        case "field": {
+            computed = measureBoxKinds(vnode, maxW, maxH, axis, measureNode);
+            break;
+        }
+        case "select":
+        case "checkbox":
+        case "radioGroup": {
+            computed = measureLeaf(vnode, maxW, maxH, axis);
+            break;
+        }
+        case "tabs":
+        case "accordion":
+        case "breadcrumb":
+        case "pagination": {
+            computed = measureNavigationKinds(vnode, maxW, maxH, measureNode);
+            break;
+        }
+        /* ========== Advanced Widgets (GitHub issue #136) ========== */
+        case "commandPalette": {
+            computed = measureOverlays(vnode, maxW, maxH, axis, measureNode);
+            break;
+        }
+        case "filePicker":
+        case "fileTreeExplorer": {
+            computed = measureCollections(vnode, maxW, maxH);
+            break;
+        }
+        case "splitPane":
+        case "panelGroup":
+        case "resizablePanel": {
+            computed = measureSplitPaneKinds(vnode, maxW, maxH);
+            break;
+        }
+        case "codeEditor":
+        case "diffViewer": {
+            computed = measureCollections(vnode, maxW, maxH);
+            break;
+        }
+        case "toolApprovalDialog": {
+            computed = measureOverlays(vnode, maxW, maxH, axis, measureNode);
+            break;
+        }
+        case "logsConsole": {
+            computed = measureCollections(vnode, maxW, maxH);
+            break;
+        }
+        case "toastContainer": {
+            computed = measureOverlays(vnode, maxW, maxH, axis, measureNode);
+            break;
+        }
+        default: {
+            computed = {
+                ok: false,
+                fatal: {
+                    code: "ZRUI_INVALID_PROPS",
+                    detail: "measure: unexpected vnode kind",
+                },
+            };
+            break;
+        }
+    }
+    if (cache) {
+        let entry = cache.get(vnode);
+        if (!entry) {
+            entry = Object.freeze({ row: new Map(), column: new Map() });
+            cache.set(vnode, entry);
+        }
+        const axisMap = axis === "row" ? entry.row : entry.column;
+        let byH = axisMap.get(maxW);
+        if (!byH) {
+            byH = new Map();
+            axisMap.set(maxW, byH);
+        }
+        byH.set(maxH, computed);
+    }
+    return computed;
+}
+/**
+ * Layout a VNode and its children, producing a positioned LayoutTree.
+ * Combines measurement with positioning based on stack axis and alignment.
+ */
+function layoutNode(vnode, x, y, maxW, maxH, axis, forcedW = null, forcedH = null, precomputedSize = null) {
+    if (!isI32(x)) {
+        return {
+            ok: false,
+            fatal: { code: "ZRUI_INVALID_PROPS", detail: "layout: x must be an int32" },
+        };
+    }
+    if (!isI32(y)) {
+        return {
+            ok: false,
+            fatal: { code: "ZRUI_INVALID_PROPS", detail: "layout: y must be an int32" },
+        };
+    }
+    if (!isI32(maxW) || maxW < 0) {
+        return {
+            ok: false,
+            fatal: { code: "ZRUI_INVALID_PROPS", detail: "layout: maxW must be an int32 >= 0" },
+        };
+    }
+    if (!isI32(maxH) || maxH < 0) {
+        return {
+            ok: false,
+            fatal: { code: "ZRUI_INVALID_PROPS", detail: "layout: maxH must be an int32 >= 0" },
+        };
+    }
+    if (__layoutProfile.enabled) {
+        __layoutProfile.layoutNodeCalls++;
+        __layoutProfile.layoutByKind[vnode.kind] = (__layoutProfile.layoutByKind[vnode.kind] ?? 0) + 1;
+    }
+    const cache = activeLayoutCache;
+    const dirtySet = getActiveDirtySet();
+    let cacheHit = null;
+    if (cache) {
+        const entry = cache.get(vnode);
+        if (entry) {
+            const axisMap = axis === "row" ? entry.row : entry.column;
+            cacheHit = getLayoutCacheHit(axisMap, maxW, maxH, forcedW, forcedH, x, y);
+            if (cacheHit && (dirtySet === null || !dirtySet.has(vnode))) {
+                if (__layoutProfile.enabled)
+                    __layoutProfile.layoutCacheHits++;
+                return cacheHit;
+            }
+        }
+    }
+    const sizeRes = precomputedSize === null
+        ? measureNode(vnode, maxW, maxH, axis)
+        : { ok: true, value: precomputedSize };
+    if (!sizeRes.ok)
+        return sizeRes;
+    const hiddenByDisplay = vnode.props?.display === false;
+    if (hiddenByDisplay) {
+        const hiddenResult = {
+            ok: true,
+            value: buildHiddenLayoutTree(vnode, x, y),
+        };
+        if (cache) {
+            let entry = cache.get(vnode);
+            if (!entry) {
+                entry = Object.freeze({ row: new Map(), column: new Map() });
+                cache.set(vnode, entry);
+            }
+            const axisMap = axis === "row" ? entry.row : entry.column;
+            setLayoutCacheValue(axisMap, maxW, maxH, forcedW, forcedH, x, y, hiddenResult);
+        }
+        return hiddenResult;
+    }
+    const rectW = clampNonNegative(Math.min(maxW, forcedW ?? sizeRes.value.w));
+    const rectH = clampNonNegative(Math.min(maxH, forcedH ?? sizeRes.value.h));
+    let computed;
+    switch (vnode.kind) {
+        case "text":
+        case "button":
+        case "input":
+        case "focusAnnouncer":
+        case "slider":
+        case "spacer":
+        case "divider":
+        case "icon":
+        case "spinner":
+        case "progress":
+        case "skeleton":
+        case "richText":
+        case "kbd":
+        case "badge":
+        case "status":
+        case "tag":
+        case "gauge":
+        case "empty":
+        case "errorDisplay":
+        case "callout":
+        case "link":
+        case "canvas":
+        case "image":
+        case "lineChart":
+        case "scatter":
+        case "heatmap":
+        case "sparkline":
+        case "barChart":
+        case "miniChart":
+        case "select":
+        case "checkbox":
+        case "radioGroup": {
+            computed = layoutLeafKind(vnode, x, y, rectW, rectH);
+            break;
+        }
+        case "row": {
+            computed = layoutStackKinds(vnode, x, y, rectW, rectH, axis, measureNode, layoutNode);
+            break;
+        }
+        case "column": {
+            computed = layoutStackKinds(vnode, x, y, rectW, rectH, axis, measureNode, layoutNode);
+            break;
+        }
+        case "fragment":
+        case "themed": {
+            const transparentVNode = vnode;
+            if (transparentVNode.children.length === 0) {
+                computed = {
+                    ok: true,
+                    value: {
+                        vnode,
+                        rect: { x, y, w: rectW, h: rectH },
+                        children: Object.freeze([]),
+                    },
+                };
+                break;
+            }
+            if (transparentVNode.children.length === 1) {
+                const children = [];
+                const child = transparentVNode.children[0];
+                if (child) {
+                    const childRes = layoutNode(child, x, y, rectW, rectH, axis, rectW, rectH);
+                    if (!childRes.ok) {
+                        computed = childRes;
+                        break;
+                    }
+                    children.push(childRes.value);
+                }
+                computed = {
+                    ok: true,
+                    value: {
+                        vnode,
+                        rect: { x, y, w: rectW, h: rectH },
+                        children: Object.freeze(children),
+                    },
+                };
+                break;
+            }
+            const syntheticColumn = getSyntheticTransparentColumn(transparentVNode);
+            const innerRes = layoutNode(syntheticColumn, x, y, rectW, rectH, "column", rectW, rectH);
+            if (!innerRes.ok) {
+                computed = innerRes;
+                break;
+            }
+            computed = {
+                ok: true,
+                value: {
+                    vnode,
+                    rect: { x, y, w: rectW, h: rectH },
+                    children: innerRes.value.children,
+                },
+            };
+            break;
+        }
+        case "grid": {
+            computed = layoutGridKinds(vnode, x, y, rectW, rectH, axis, measureNode, layoutNode);
+            break;
+        }
+        case "box": {
+            computed = layoutBoxKinds(vnode, x, y, rectW, rectH, axis, measureNode, layoutNode);
+            break;
+        }
+        case "focusZone":
+        case "focusTrap": {
+            computed = layoutOverlays(vnode, x, y, maxW, maxH, rectW, rectH, axis, measureNode, layoutNode);
+            break;
+        }
+        case "virtualList": {
+            computed = layoutCollections(vnode, x, y, rectW, rectH);
+            break;
+        }
+        case "layers": {
+            computed = layoutOverlays(vnode, x, y, maxW, maxH, rectW, rectH, axis, measureNode, layoutNode);
+            break;
+        }
+        case "modal": {
+            computed = layoutOverlays(vnode, x, y, maxW, maxH, rectW, rectH, axis, measureNode, layoutNode);
+            break;
+        }
+        case "dropdown": {
+            computed = layoutOverlays(vnode, x, y, maxW, maxH, rectW, rectH, axis, measureNode, layoutNode);
+            break;
+        }
+        case "layer": {
+            computed = layoutOverlays(vnode, x, y, maxW, maxH, rectW, rectH, axis, measureNode, layoutNode);
+            break;
+        }
+        case "table": {
+            computed = layoutCollections(vnode, x, y, rectW, rectH);
+            break;
+        }
+        case "tree": {
+            computed = layoutCollections(vnode, x, y, rectW, rectH);
+            break;
+        }
+        case "field": {
+            computed = layoutBoxKinds(vnode, x, y, rectW, rectH, axis, measureNode, layoutNode);
+            break;
+        }
+        case "tabs":
+        case "accordion":
+        case "breadcrumb":
+        case "pagination": {
+            computed = layoutNavigationKinds(vnode, x, y, rectW, rectH, layoutNode);
+            break;
+        }
+        /* ========== Advanced Widgets (GitHub issue #136) ========== */
+        case "commandPalette": {
+            computed = layoutOverlays(vnode, x, y, maxW, maxH, rectW, rectH, axis, measureNode, layoutNode);
+            break;
+        }
+        case "filePicker": {
+            computed = layoutCollections(vnode, x, y, rectW, rectH);
+            break;
+        }
+        case "fileTreeExplorer": {
+            computed = layoutCollections(vnode, x, y, rectW, rectH);
+            break;
+        }
+        case "splitPane":
+        case "panelGroup":
+        case "resizablePanel": {
+            computed = layoutSplitPaneKinds(vnode, x, y, maxW, maxH, rectW, rectH, axis, layoutNode);
+            break;
+        }
+        case "codeEditor": {
+            computed = layoutCollections(vnode, x, y, rectW, rectH);
+            break;
+        }
+        case "diffViewer": {
+            computed = layoutCollections(vnode, x, y, rectW, rectH);
+            break;
+        }
+        case "toolApprovalDialog": {
+            computed = layoutOverlays(vnode, x, y, maxW, maxH, rectW, rectH, axis, measureNode, layoutNode);
+            break;
+        }
+        case "logsConsole": {
+            computed = layoutCollections(vnode, x, y, rectW, rectH);
+            break;
+        }
+        case "toastContainer": {
+            computed = layoutOverlays(vnode, x, y, maxW, maxH, rectW, rectH, axis, measureNode, layoutNode);
+            break;
+        }
+        default: {
+            computed = {
+                ok: false,
+                fatal: {
+                    code: "ZRUI_INVALID_PROPS",
+                    detail: "layout: unexpected vnode kind",
+                },
+            };
+            break;
+        }
+    }
+    if (cache) {
+        let entry = cache.get(vnode);
+        if (!entry) {
+            entry = Object.freeze({ row: new Map(), column: new Map() });
+            cache.set(vnode, entry);
+        }
+        const axisMap = axis === "row" ? entry.row : entry.column;
+        setLayoutCacheValue(axisMap, maxW, maxH, forcedW, forcedH, x, y, computed);
+    }
+    return computed;
+}
+/** Measure a VNode tree without positioning (public API). */
+export function measure(node, maxW, maxH, axis) {
+    const legacyUsage = findLegacyConstraintUsage(node);
+    if (legacyUsage !== null) {
+        return {
+            ok: false,
+            fatal: {
+                code: "ZRUI_INVALID_PROPS",
+                detail: `Legacy size constraint usage detected: ${legacyUsage}`,
+            },
+        };
+    }
+    warnUnsupportedLayoutConstraintUsage(node);
+    return measureNode(node, maxW, maxH, axis);
+}
+/**
+ * Compute layout for a VNode tree starting at position (x,y) with constraints.
+ *
+ * @param node - Root VNode to layout
+ * @param x - Starting X position in terminal cells
+ * @param y - Starting Y position in terminal cells
+ * @param maxW - Maximum available width
+ * @param maxH - Maximum available height
+ * @param axis - Stack axis for root container behavior
+ * @returns LayoutTree on success, fatal error on invalid props
+ */
+export function layout(node, x, y, maxW, maxH, axis, measureCache, layoutCache, dirtySet) {
+    const legacyUsage = findLegacyConstraintUsage(node);
+    if (legacyUsage !== null) {
+        return {
+            ok: false,
+            fatal: {
+                code: "ZRUI_INVALID_PROPS",
+                detail: `Legacy size constraint usage detected: ${legacyUsage}`,
+            },
+        };
+    }
+    warnUnsupportedLayoutConstraintUsage(node);
+    const resolvedMeasureCache = measureCache
+        ? measureCache
+        : new WeakMap();
+    const resolvedLayoutCache = layoutCache
+        ? layoutCache
+        : new WeakMap();
+    pushMeasureCache(resolvedMeasureCache);
+    pushLayoutCache(resolvedLayoutCache);
+    pushDirtySet(dirtySet ?? null);
+    try {
+        return layoutNode(node, x, y, maxW, maxH, axis);
+    }
+    finally {
+        popDirtySet();
+        popLayoutCache();
+        popMeasureCache();
+    }
+}
+//# sourceMappingURL=layoutEngine.js.map