machinalayout 0.2.0 → 0.3.0

package/dist/{chunk-HU6XYOH7.js → chunk-ZVDE7PX4.js}

@@ -1,6 +1,9 @@
+import {
+  getMachinaDebugOverlayBehavior
+} from "./chunk-2ZQ2RFFI.js";
 import {
   toResolvedTree
-} from "./chunk-TR24ERZT.js";
+} from "./chunk-SVWYWI7I.js";
 
 // src/react/MachinaReactView.tsx
 import React from "react";
@@ -88,6 +91,88 @@ function renderNode(node, parentRect, views, viewData, nodeData, nodeClassName,
     node.id
   );
 }
+function collectOverlayNodes(node) {
+  return [node, ...node.children.flatMap((child) => collectOverlayNodes(child))];
+}
+function renderDebugOverlay(tree, options) {
+  const board = {
+    mode: options.mode ?? "collapsed",
+    labels: options.labels ?? true,
+    borders: options.borders ?? true,
+    selectedNodeId: options.selectedNodeId
+  };
+  const behavior = getMachinaDebugOverlayBehavior(board);
+  if (!behavior.visible) return null;
+  const nodes = collectOverlayNodes(tree);
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      "data-testid": "machina-debug-overlay",
+      "data-machina-debug-overlay-mode": board.mode,
+      style: {
+        position: "absolute",
+        inset: 0,
+        pointerEvents: behavior.pointerEvents,
+        zIndex: 1e4,
+        boxSizing: "border-box"
+      },
+      children: [
+        nodes.map((node) => /* @__PURE__ */ jsx(
+          "div",
+          {
+            "data-testid": `machina-debug-overlay-node-${node.id}`,
+            "data-machina-debug-overlay-node-id": node.id,
+            style: {
+              position: "absolute",
+              left: node.rect.x - tree.rect.x,
+              top: node.rect.y - tree.rect.y,
+              width: node.rect.width,
+              height: node.rect.height,
+              boxSizing: "border-box",
+              border: behavior.showBorders ? "1px solid rgba(14, 165, 233, 0.9)" : "0",
+              pointerEvents: behavior.pointerEvents
+            },
+            children: behavior.showLabels ? /* @__PURE__ */ jsx(
+              "span",
+              {
+                style: {
+                  position: "absolute",
+                  left: 0,
+                  top: 0,
+                  fontSize: 10,
+                  lineHeight: "12px",
+                  background: "rgba(14, 165, 233, 0.9)",
+                  color: "white",
+                  padding: "0 3px"
+                },
+                children: node.debugLabel ?? node.id
+              }
+            ) : null
+          },
+          node.id
+        )),
+        behavior.showPanel ? /* @__PURE__ */ jsxs(
+          "div",
+          {
+            "data-testid": "machina-debug-overlay-panel",
+            style: {
+              position: "absolute",
+              right: 8,
+              top: 8,
+              background: "rgba(15, 23, 42, 0.92)",
+              color: "white",
+              padding: 8
+            },
+            children: [
+              "Debug overlay",
+              board.selectedNodeId ? `: ${board.selectedNodeId}` : ""
+            ]
+          }
+        ) : null
+      ]
+    }
+  );
+}
 function MachinaReactView(props) {
   const {
     layout,
@@ -102,7 +187,8 @@ function MachinaReactView(props) {
     nodeContentVisibility = "none",
     nodeContainIntrinsicSize,
     layers = { base: { z: 0 } },
-    defaultLayer = "base"
+    defaultLayer = "base",
+    debugOverlay
   } = props;
   const tree = toResolvedTree(layout);
   const wrapperStyle = {
@@ -111,21 +197,24 @@ function MachinaReactView(props) {
     height: tree.rect.height,
     ...style
   };
-  return /* @__PURE__ */ jsx("div", { className, style: wrapperStyle, "data-machina-root-id": tree.id, children: renderNode(
-    tree,
-    tree.rect,
-    views,
-    viewData,
-    nodeData,
-    nodeClassName,
-    debug,
-    nodeContainment,
-    nodeContentVisibility,
-    nodeContainIntrinsicSize,
-    layout.nodes,
-    layers,
-    defaultLayer
-  ) });
+  return /* @__PURE__ */ jsxs("div", { className, style: wrapperStyle, "data-machina-root-id": tree.id, children: [
+    renderNode(
+      tree,
+      tree.rect,
+      views,
+      viewData,
+      nodeData,
+      nodeClassName,
+      debug,
+      nodeContainment,
+      nodeContentVisibility,
+      nodeContainIntrinsicSize,
+      layout.nodes,
+      layers,
+      defaultLayer
+    ),
+    debugOverlay ? renderDebugOverlay(tree, debugOverlay) : null
+  ] });
 }
 
 export {

package/dist/debugOverlay-pJpj0n5H.d.ts

@@ -0,0 +1,125 @@
+declare class DeusMachinaError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+type UtilityScore<TContext> = number | ((context: TContext) => number);
+type UtilityCandidate<TContext, TKey extends string = string> = {
+    key: TKey;
+    when?: (context: TContext) => boolean;
+    score: UtilityScore<TContext>;
+    reason?: string | ((context: TContext) => string);
+};
+type UtilityCandidateResult<TKey extends string = string> = {
+    key: TKey;
+    eligible: boolean;
+    score: number;
+    index: number;
+    reason?: string;
+};
+type UtilityJudgment<TKey extends string = string> = {
+    selected: UtilityCandidateResult<TKey> | null;
+    candidates: UtilityCandidateResult<TKey>[];
+};
+type JudgeUtilityOptions<TKey extends string = string> = {
+    previousKey?: TKey;
+    hysteresis?: number;
+};
+type DeusStatePath = readonly string[];
+type DeusEvent = {
+    type: string;
+};
+type DeusAction<TBoard, TEvent extends DeusEvent> = (board: TBoard, event: TEvent) => void;
+type DeusStateRow<TBoard, TEvent extends DeusEvent> = {
+    path: DeusStatePath;
+    onEnter?: DeusAction<TBoard, TEvent>;
+    onExit?: DeusAction<TBoard, TEvent>;
+};
+type DeusUtilityTransitionCandidate<TBoard, TEvent extends DeusEvent, TKey extends string = string> = {
+    key: TKey;
+    when?: (board: TBoard, event: TEvent) => boolean;
+    score: number | ((board: TBoard, event: TEvent) => number);
+    do?: DeusAction<TBoard, TEvent>;
+    reason?: string | ((board: TBoard, event: TEvent) => string);
+};
+type DeusTransitionRow<TBoard, TEvent extends DeusEvent> = {
+    key: string;
+    from: DeusStatePath;
+    event?: TEvent["type"];
+    to?: DeusStatePath | ((board: TBoard, event: TEvent) => DeusStatePath);
+    when?: (board: TBoard, event: TEvent) => boolean;
+    score?: number | ((board: TBoard, event: TEvent) => number);
+    do?: DeusAction<TBoard, TEvent>;
+    reason?: string | ((board: TBoard, event: TEvent) => string);
+    utility?: readonly DeusUtilityTransitionCandidate<TBoard, TEvent>[];
+    hysteresis?: {
+        previous: (board: TBoard) => string | undefined;
+        margin: number;
+    };
+};
+type DeusMachine<TBoard, TEvent extends DeusEvent> = {
+    initial: DeusStatePath;
+    states: readonly DeusStateRow<TBoard, TEvent>[];
+    transitions: readonly DeusTransitionRow<TBoard, TEvent>[];
+};
+type DeusSnapshot<TBoard> = {
+    state: DeusStatePath;
+    board: TBoard;
+    stepIndex: number;
+};
+type DeusTransitionTrace = {
+    key: string;
+    from: DeusStatePath;
+    to?: DeusStatePath;
+    event?: string;
+    eligible: boolean;
+    score: number;
+    index: number;
+    reason?: string;
+    utility?: UtilityJudgment<string>;
+};
+type DeusStepTrace = {
+    stateBefore: DeusStatePath;
+    stateAfter: DeusStatePath;
+    event: string;
+    selectedTransition?: DeusTransitionTrace;
+    transitions: DeusTransitionTrace[];
+};
+type DeusStepResult<TBoard> = {
+    snapshot: DeusSnapshot<TBoard>;
+    trace: DeusStepTrace;
+};
+
+type MachinaDebugOverlayMode = "collapsed" | "nonInteractiveOverlay" | "interactivePanel";
+type MachinaDebugOverlayBoard = {
+    mode: MachinaDebugOverlayMode;
+    labels: boolean;
+    borders: boolean;
+    selectedNodeId?: string;
+};
+type MachinaDebugOverlayEvent = {
+    type: "showOverlay";
+} | {
+    type: "openPanel";
+    nodeId?: string;
+} | {
+    type: "collapse";
+} | {
+    type: "toggleLabels";
+} | {
+    type: "toggleBorders";
+} | {
+    type: "selectNode";
+    nodeId: string;
+};
+type MachinaDebugOverlayBehavior = {
+    visible: boolean;
+    pointerEvents: "none" | "auto";
+    consumesLayoutSpace: boolean;
+    showPanel: boolean;
+    showLabels: boolean;
+    showBorders: boolean;
+};
+declare function createMachinaDebugOverlayMachine(): DeusMachine<MachinaDebugOverlayBoard, MachinaDebugOverlayEvent>;
+declare function getMachinaDebugOverlayBehavior(board: MachinaDebugOverlayBoard): MachinaDebugOverlayBehavior;
+
+export { type DeusEvent as D, type JudgeUtilityOptions as J, type MachinaDebugOverlayBehavior as M, type UtilityCandidate as U, type UtilityJudgment as a, type DeusMachine as b, type DeusSnapshot as c, type DeusStatePath as d, type DeusStepTrace as e, type DeusStepResult as f, type DeusAction as g, DeusMachinaError as h, type DeusStateRow as i, type DeusTransitionRow as j, type DeusTransitionTrace as k, type DeusUtilityTransitionCandidate as l, type MachinaDebugOverlayBoard as m, type MachinaDebugOverlayEvent as n, type MachinaDebugOverlayMode as o, type UtilityCandidateResult as p, type UtilityScore as q, createMachinaDebugOverlayMachine as r, getMachinaDebugOverlayBehavior as s };

package/dist/deus/index.d.ts

@@ -0,0 +1,14 @@
+import { U as UtilityCandidate, J as JudgeUtilityOptions, a as UtilityJudgment, D as DeusEvent, b as DeusMachine, c as DeusSnapshot, d as DeusStatePath, e as DeusStepTrace, f as DeusStepResult } from '../debugOverlay-pJpj0n5H.js';
+export { g as DeusAction, h as DeusMachinaError, i as DeusStateRow, j as DeusTransitionRow, k as DeusTransitionTrace, l as DeusUtilityTransitionCandidate, M as MachinaDebugOverlayBehavior, m as MachinaDebugOverlayBoard, n as MachinaDebugOverlayEvent, o as MachinaDebugOverlayMode, p as UtilityCandidateResult, q as UtilityScore, r as createMachinaDebugOverlayMachine, s as getMachinaDebugOverlayBehavior } from '../debugOverlay-pJpj0n5H.js';
+
+declare function judgeUtility<TContext, TKey extends string = string>(context: TContext, candidates: readonly UtilityCandidate<TContext, TKey>[], options?: JudgeUtilityOptions<TKey>): UtilityJudgment<TKey>;
+
+declare function formatDeusPath(path: DeusStatePath): string;
+declare function sameDeusPath(a: DeusStatePath, b: DeusStatePath): boolean;
+declare function isDeusAncestorPath(ancestor: DeusStatePath, path: DeusStatePath): boolean;
+declare function defineDeusMachine<TBoard, TEvent extends DeusEvent>(machine: DeusMachine<TBoard, TEvent>): DeusMachine<TBoard, TEvent>;
+declare function createDeusSnapshot<TBoard, TEvent extends DeusEvent>(machine: DeusMachine<TBoard, TEvent>, board: TBoard): DeusSnapshot<TBoard>;
+declare function stepDeusMachine<TBoard, TEvent extends DeusEvent>(machine: DeusMachine<TBoard, TEvent>, snapshot: DeusSnapshot<TBoard>, event: NoInfer<TEvent>): DeusStepResult<TBoard>;
+declare function formatDeusStepTrace(trace: DeusStepTrace): string;
+
+export { DeusEvent, DeusMachine, DeusSnapshot, DeusStatePath, DeusStepResult, DeusStepTrace, JudgeUtilityOptions, UtilityCandidate, UtilityJudgment, createDeusSnapshot, defineDeusMachine, formatDeusPath, formatDeusStepTrace, isDeusAncestorPath, judgeUtility, sameDeusPath, stepDeusMachine };

package/dist/deus/index.js

@@ -0,0 +1,26 @@
+import {
+  DeusMachinaError,
+  createDeusSnapshot,
+  createMachinaDebugOverlayMachine,
+  defineDeusMachine,
+  formatDeusPath,
+  formatDeusStepTrace,
+  getMachinaDebugOverlayBehavior,
+  isDeusAncestorPath,
+  judgeUtility,
+  sameDeusPath,
+  stepDeusMachine
+} from "../chunk-2ZQ2RFFI.js";
+export {
+  DeusMachinaError,
+  createDeusSnapshot,
+  createMachinaDebugOverlayMachine,
+  defineDeusMachine,
+  formatDeusPath,
+  formatDeusStepTrace,
+  getMachinaDebugOverlayBehavior,
+  isDeusAncestorPath,
+  judgeUtility,
+  sameDeusPath,
+  stepDeusMachine
+};

package/dist/handoff/index.d.ts

@@ -0,0 +1,44 @@
+import { M as MachinaDomSummary } from '../types-DLYAhNXw.js';
+import { M as MachinaViewport, a as MachinaScreenViewportTask } from '../screenCatalog-ZjonGiOi.js';
+import '../types-B90jb3RW.js';
+
+type MachinaHandoffArtifactPaths = {
+    screenshot?: string;
+    domSummary?: string;
+    layoutSnapshot?: string;
+    manifest: string;
+};
+type MachinaHandoffBundleManifest = {
+    schemaVersion: 1;
+    createdAt: string;
+    route?: string;
+    fixture?: string;
+    screenKey?: string;
+    viewportKey?: string;
+    viewport?: MachinaViewport;
+    tags?: readonly string[];
+    artifactBaseName?: string;
+    artifacts: MachinaHandoffArtifactPaths;
+    metadata?: Record<string, unknown>;
+};
+type WriteMachinaHandoffBundleInput = {
+    outputDir: string;
+    artifactBaseName?: string;
+    screenshotPath?: string;
+    domSummary?: MachinaDomSummary;
+    layoutSnapshot?: unknown;
+    task?: MachinaScreenViewportTask;
+    route?: string;
+    fixture?: string;
+    tags?: readonly string[];
+    metadata?: Record<string, unknown>;
+    createdAt?: string;
+};
+type WriteMachinaHandoffBundleResult = {
+    manifest: MachinaHandoffBundleManifest;
+    paths: MachinaHandoffArtifactPaths;
+};
+
+declare function writeMachinaHandoffBundle(input: WriteMachinaHandoffBundleInput): Promise<WriteMachinaHandoffBundleResult>;
+
+export { type MachinaHandoffArtifactPaths, type MachinaHandoffBundleManifest, type WriteMachinaHandoffBundleInput, type WriteMachinaHandoffBundleResult, writeMachinaHandoffBundle };

package/dist/handoff/index.js

@@ -0,0 +1,83 @@
+import {
+  slugMachinaArtifactName
+} from "../chunk-33CKBEJH.js";
+import "../chunk-VREK57S3.js";
+
+// src/handoff/writeMachinaHandoffBundle.ts
+import { copyFile, mkdir, writeFile } from "fs/promises";
+import path from "path";
+function artifactBaseName(input) {
+  const candidate = input.artifactBaseName ?? input.task?.artifactBaseName ?? [
+    input.route ?? input.task?.route,
+    input.fixture ?? input.task?.fixture,
+    input.task?.viewportKey
+  ].filter((part) => typeof part === "string" && part.trim() !== "").join("-") ?? "";
+  return slugMachinaArtifactName(candidate === "" ? "machina-handoff" : candidate);
+}
+function orderedUnique(...groups) {
+  const result = [];
+  for (const group of groups) {
+    for (const tag of group ?? []) {
+      if (!result.includes(tag)) result.push(tag);
+    }
+  }
+  return result.length === 0 ? void 0 : result;
+}
+function json(value) {
+  return `${JSON.stringify(value, null, 2)}
+`;
+}
+function screenshotExtension(screenshotPath) {
+  const extension = path.extname(screenshotPath);
+  return extension === "" ? ".png" : extension;
+}
+async function writeMachinaHandoffBundle(input) {
+  if (typeof input.outputDir !== "string" || input.outputDir.trim() === "") {
+    throw new Error("outputDir must be a non-empty string");
+  }
+  const outputDir = path.resolve(input.outputDir);
+  await mkdir(outputDir, { recursive: true });
+  const base = artifactBaseName(input);
+  const artifactNames = { manifest: `${base}__handoff.json` };
+  const paths = {
+    manifest: path.join(outputDir, artifactNames.manifest)
+  };
+  if (input.screenshotPath !== void 0) {
+    artifactNames.screenshot = `${base}__screenshot${screenshotExtension(input.screenshotPath)}`;
+    paths.screenshot = path.join(outputDir, artifactNames.screenshot);
+    await copyFile(input.screenshotPath, paths.screenshot);
+  }
+  if (input.domSummary !== void 0) {
+    artifactNames.domSummary = `${base}__dom-summary.json`;
+    paths.domSummary = path.join(outputDir, artifactNames.domSummary);
+    await writeFile(paths.domSummary, json(input.domSummary), "utf8");
+  }
+  if (input.layoutSnapshot !== void 0) {
+    artifactNames.layoutSnapshot = `${base}__machina-snapshot.json`;
+    paths.layoutSnapshot = path.join(outputDir, artifactNames.layoutSnapshot);
+    await writeFile(paths.layoutSnapshot, json(input.layoutSnapshot), "utf8");
+  }
+  const tags = orderedUnique(input.task?.tags, input.tags);
+  const manifest = {
+    schemaVersion: 1,
+    createdAt: input.createdAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+    artifacts: artifactNames
+  };
+  const route = input.route ?? input.task?.route;
+  const fixture = input.fixture ?? input.task?.fixture;
+  if (route !== void 0) manifest.route = route;
+  if (fixture !== void 0) manifest.fixture = fixture;
+  if (input.task !== void 0) {
+    manifest.screenKey = input.task.screenKey;
+    manifest.viewportKey = input.task.viewportKey;
+    manifest.viewport = input.task.viewport;
+  }
+  if (tags !== void 0) manifest.tags = tags;
+  manifest.artifactBaseName = base;
+  if (input.metadata !== void 0) manifest.metadata = input.metadata;
+  await writeFile(paths.manifest, json(manifest), "utf8");
+  return { manifest, paths };
+}
+export {
+  writeMachinaHandoffBundle
+};

package/dist/index.d.ts

@@ -1,12 +1,14 @@
-import { E as EdgeInsets, U as UiLength, R as Rect, O as OffsetSpec, L as LayoutRow, c as LayoutDocument, F as FrameSpec, b as ResolvedLayoutDocument, d as ResolvedLayoutTree, a as ResolvedLayoutNode } from './types-BudfpzZX.js';
-export { A as AbsoluteFrame, e as AnchorFrame, f as ArrangeSpec, C as CellFrame, g as EdgeRef, h as FillFrame, i as FixedFrame, G as GridArrange, j as GridTrack, k as GuideFrame, l as GuideLength, m as LayerName, n as LayoutNode, o as LayoutRowVariant, p as LayoutVariantCondition, N as NodeId, q as RectEdge, r as RootFrame, S as StackAlign, s as StackArrange, t as StackAxis, u as StackJustify } from './types-BudfpzZX.js';
-export { MachinaReactView, MachinaReactViewProps, MachinaSlotProps } from './react/index.js';
+import { E as EdgeInsets, U as UiLength, R as Rect, O as OffsetSpec, L as LayoutRow, c as LayoutDocument, F as FrameSpec, b as ResolvedLayoutDocument, d as ResolvedLayoutTree, a as ResolvedLayoutNode, N as NodeId, e as LayerName, S as StackAxis, A as ArrangeSpec } from './types-B90jb3RW.js';
+export { f as AbsoluteFrame, g as AnchorFrame, C as CellFrame, h as EdgeRef, i as FillFrame, j as FixedFrame, G as GridArrange, k as GridTrack, l as GuideFrame, m as GuideLength, n as LayoutNode, o as LayoutRowVariant, p as LayoutVariantCondition, q as RectEdge, r as RootFrame, s as StackAlign, t as StackArrange, u as StackJustify } from './types-B90jb3RW.js';
+export { MachinaReactDebugOverlayOptions, MachinaReactView, MachinaReactViewProps, MachinaSlotProps } from './react/index.js';
 export { c as MachinaBulletItem, d as MachinaInline, e as MachinaTextAlign, f as MachinaTextBlock, g as MachinaTextDiagnostic, h as MachinaTextDiagnosticCode, i as MachinaTextDiagnosticLevel, b as MachinaTextDocument, j as MachinaTextLeading, k as MachinaTextOverflow, a as MachinaTextSource, M as MachinaTextSpec, l as MachinaTextVariant, m as MachinaTextVerticalAlign, n as MachinaTextWrap, P as ParseMachinaTextResult } from './types-C4poVJpR.js';
 export { parseMachinaText, parseMachinaTextInline } from './text/index.js';
 export { MachinaTextView, MachinaTextViewProps } from './text/react/index.js';
+export { b as MachinaScreen, c as MachinaScreenCatalog, a as MachinaScreenViewportTask, M as MachinaViewport, d as MachinaViewportMatrix, e as createViewportMatrix, f as defineMachinaScreens, g as defineMachinaViewports, h as expandScreenViewportTasks, i as getMachinaViewport, s as slugMachinaArtifactName } from './screenCatalog-ZjonGiOi.js';
 import 'react';
+import './debugOverlay-pJpj0n5H.js';
 
-type MachinaLayoutErrorCode = "EmptyRows" | "MissingRoot" | "MultipleRoots" | "DuplicateId" | "InvalidId" | "MissingParent" | "UnknownParent" | "SelfParent" | "Cycle" | "UnreachableNode" | "NonFiniteNumber" | "InvalidLengthUnit" | "InvalidZ" | "InvalidVariantCondition" | "NegativeSize" | "NegativeGap" | "NegativePadding" | "InvalidAnchorHorizontal" | "InvalidAnchorVertical" | "NegativeResolvedSize" | "FixedFrameWithoutArranger" | "FillFrameWithoutArranger" | "InvalidFillWeight" | "StackChildMustBeFixed" | "StackContentNegative" | "StackOverflow" | "CellFrameWithoutGrid" | "GridChildMustBeCell" | "InvalidGridTrack" | "InvalidGridCell" | "GridContentNegative" | "GridOverflow" | "RootFrameNotRoot" | "RootFrameWithoutRoot" | "IncompatibleLayouts" | "GuideTargetNotFound" | "GuideSelfReference" | "GuideReferenceCycle" | "GuideInvalidEdgeForAxis" | "GuideTooManyReferencesPerAxis" | "InvalidGuideFrame" | "GuideTargetUnresolved";
+type MachinaLayoutErrorCode = "EmptyRows" | "MissingRoot" | "MultipleRoots" | "DuplicateId" | "InvalidId" | "MissingParent" | "UnknownParent" | "SelfParent" | "Cycle" | "UnreachableNode" | "NonFiniteNumber" | "InvalidLengthUnit" | "InvalidZ" | "InvalidVariantCondition" | "NegativeSize" | "NegativeGap" | "NegativePadding" | "InvalidAnchorHorizontal" | "InvalidAnchorVertical" | "NegativeResolvedSize" | "FixedFrameWithoutArranger" | "FillFrameWithoutArranger" | "InvalidFillWeight" | "StackChildMustBeFixed" | "StackContentNegative" | "StackOverflow" | "ExpectedStackArrange" | "StackQueryInvalidRange" | "CellFrameWithoutGrid" | "GridChildMustBeCell" | "InvalidGridTrack" | "InvalidGridCell" | "GridContentNegative" | "GridOverflow" | "RootFrameNotRoot" | "RootFrameWithoutRoot" | "IncompatibleLayouts" | "GuideTargetNotFound" | "GuideSelfReference" | "GuideReferenceCycle" | "GuideInvalidEdgeForAxis" | "GuideTooManyReferencesPerAxis" | "InvalidGuideFrame" | "GuideTargetUnresolved" | "InvalidViewport" | "DuplicateViewportKey" | "UnknownViewportKey" | "InvalidScreen" | "DuplicateScreenKey" | "UnknownScreenKey";
 declare class MachinaLayoutError extends Error {
     readonly code: MachinaLayoutErrorCode;
     constructor(code: MachinaLayoutErrorCode, message: string);
@@ -39,8 +41,47 @@ declare function flattenResolvedTree(tree: ResolvedLayoutTree): ResolvedLayoutNo
 
 declare function formatRect(rect: Rect): string;
 
+type StackChildMetric = {
+    id: NodeId;
+    rect: Rect;
+    mainStart: number;
+    mainEnd: number;
+    mainSize: number;
+    crossStart: number;
+    crossEnd: number;
+    crossSize: number;
+    frameKind: FrameSpec["kind"];
+    z?: number;
+    layer?: LayerName;
+};
+type StackMainAxisMetrics = {
+    parentId: NodeId;
+    axis: StackAxis;
+    parentRect: Rect;
+    contentRect: Rect;
+    padding: EdgeInsets;
+    gap: number;
+    childIds: NodeId[];
+    childMetrics: StackChildMetric[];
+    contentMainSize: number;
+    contentCrossSize: number;
+    totalChildMainSize: number;
+    totalGapSize: number;
+    usedMainSize: number;
+    unusedMainSize: number;
+};
+declare function getArrangeContentRect(parentRect: Rect, arrange?: ArrangeSpec): Rect;
+declare function getStackContentRect(layout: ResolvedLayoutDocument, parentId: NodeId): Rect;
+declare function getStackMainAxisMetrics(layout: ResolvedLayoutDocument, parentId: NodeId): StackMainAxisMetrics;
+declare function getStackChildRects(layout: ResolvedLayoutDocument, parentId: NodeId): Record<NodeId, Rect>;
+declare function getRemainingStackRect(layout: ResolvedLayoutDocument, options: {
+    parentId: NodeId;
+    afterChildren?: NodeId[];
+    beforeChildren?: NodeId[];
+}): Rect;
+
 declare function lerpNumber(a: number, b: number, t: number): number;
 declare function lerpRect(a: Rect, b: Rect, t: number): Rect;
 declare function lerpResolvedLayouts(a: ResolvedLayoutDocument, b: ResolvedLayoutDocument, t: number): ResolvedLayoutDocument;
 
-export { EdgeInsets, FrameSpec, LayoutDocument, LayoutRow, MachinaLayoutError, type MachinaLayoutErrorCode, OffsetSpec, Rect, ResolvedLayoutDocument, ResolvedLayoutNode, ResolvedLayoutTree, UiLength, applyOffset, assertFiniteNumber, assertNonNegativeGap, assertNonNegativePadding, assertNonNegativeSize, compileLayoutRows, flattenResolvedTree, formatRect, lerpNumber, lerpRect, lerpResolvedLayouts, normalizePadding, resolveFrame, resolveLayoutDocument, resolveLayoutRows, resolveUiLength, selectLayoutRowsForRoot, toResolvedTree };
+export { ArrangeSpec, EdgeInsets, FrameSpec, LayerName, LayoutDocument, LayoutRow, MachinaLayoutError, type MachinaLayoutErrorCode, NodeId, OffsetSpec, Rect, ResolvedLayoutDocument, ResolvedLayoutNode, ResolvedLayoutTree, StackAxis, type StackChildMetric, type StackMainAxisMetrics, UiLength, applyOffset, assertFiniteNumber, assertNonNegativeGap, assertNonNegativePadding, assertNonNegativeSize, compileLayoutRows, flattenResolvedTree, formatRect, getArrangeContentRect, getRemainingStackRect, getStackChildRects, getStackContentRect, getStackMainAxisMetrics, lerpNumber, lerpRect, lerpResolvedLayouts, normalizePadding, resolveFrame, resolveLayoutDocument, resolveLayoutRows, resolveUiLength, selectLayoutRowsForRoot, toResolvedTree };