machinalayout 0.2.0 → 0.3.0

package/dist/index.js

@@ -1,6 +1,15 @@
+import {
+  createViewportMatrix,
+  defineMachinaScreens,
+  defineMachinaViewports,
+  expandScreenViewportTasks,
+  getMachinaViewport,
+  slugMachinaArtifactName
+} from "./chunk-33CKBEJH.js";
 import {
   MachinaReactView
-} from "./chunk-HU6XYOH7.js";
+} from "./chunk-ZVDE7PX4.js";
+import "./chunk-2ZQ2RFFI.js";
 import "./chunk-RJYRJ3LD.js";
 import {
   MachinaTextView
@@ -10,9 +19,11 @@ import {
   parseMachinaTextInline
 } from "./chunk-BJOQRPPX.js";
 import {
-  MachinaLayoutError,
   toResolvedTree
-} from "./chunk-TR24ERZT.js";
+} from "./chunk-SVWYWI7I.js";
+import {
+  MachinaLayoutError
+} from "./chunk-VREK57S3.js";
 
 // src/validation.ts
 function assertFiniteNumber(value, fieldName) {
@@ -947,6 +958,149 @@ function formatRect(rect) {
   return `x=${rect.x} y=${rect.y} w=${rect.width} h=${rect.height}`;
 }
 
+// src/stackGeometry.ts
+function copyRect(rect) {
+  return { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
+}
+function applyPadding(parentRect, padding) {
+  return {
+    x: parentRect.x + padding.left,
+    y: parentRect.y + padding.top,
+    width: parentRect.width - padding.left - padding.right,
+    height: parentRect.height - padding.top - padding.bottom
+  };
+}
+function assertContentNonNegative(contentRect, code) {
+  if (contentRect.width < 0 || contentRect.height < 0) {
+    throw new MachinaLayoutError(
+      code,
+      `${code === "StackContentNegative" ? "stack" : "grid"} content size cannot be negative after applying padding`
+    );
+  }
+}
+function requireNode(layout, nodeId) {
+  const node = layout.nodes[nodeId];
+  if (!node) throw new MachinaLayoutError("InvalidId", `node id not found: ${nodeId}`);
+  return node;
+}
+function requireStackArrange(layout, parentId) {
+  const parent = requireNode(layout, parentId);
+  if (parent.arrange?.kind !== "stack") {
+    throw new MachinaLayoutError(
+      "ExpectedStackArrange",
+      `expected stack arrange for node: ${parentId}`
+    );
+  }
+  return parent.arrange;
+}
+function getArrangeContentRect(parentRect, arrange) {
+  if (!arrange) return copyRect(parentRect);
+  if (arrange.kind === "stack") {
+    const contentRect = applyPadding(parentRect, normalizePadding(arrange.padding));
+    assertContentNonNegative(contentRect, "StackContentNegative");
+    return contentRect;
+  }
+  if (arrange.kind === "grid") {
+    const contentRect = applyPadding(parentRect, normalizePadding(arrange.padding));
+    assertContentNonNegative(contentRect, "GridContentNegative");
+    return contentRect;
+  }
+  return copyRect(parentRect);
+}
+function getStackContentRect(layout, parentId) {
+  const parent = requireNode(layout, parentId);
+  const arrange = requireStackArrange(layout, parentId);
+  return getArrangeContentRect(parent.rect, arrange);
+}
+function getStackMainAxisMetrics(layout, parentId) {
+  const parent = requireNode(layout, parentId);
+  const arrange = requireStackArrange(layout, parentId);
+  const contentRect = getArrangeContentRect(parent.rect, arrange);
+  const isHorizontal = arrange.axis === "horizontal";
+  const childIds = [...layout.children[parentId] ?? []];
+  const childMetrics = childIds.map((id) => {
+    const child = requireNode(layout, id);
+    const rect = copyRect(child.rect);
+    const mainStart = isHorizontal ? rect.x - contentRect.x : rect.y - contentRect.y;
+    const mainSize = isHorizontal ? rect.width : rect.height;
+    const crossStart = isHorizontal ? rect.y - contentRect.y : rect.x - contentRect.x;
+    const crossSize = isHorizontal ? rect.height : rect.width;
+    return {
+      id,
+      rect,
+      mainStart,
+      mainEnd: mainStart + mainSize,
+      mainSize,
+      crossStart,
+      crossEnd: crossStart + crossSize,
+      crossSize,
+      frameKind: child.frame.kind,
+      z: child.z,
+      layer: child.layer
+    };
+  });
+  const contentMainSize = isHorizontal ? contentRect.width : contentRect.height;
+  const contentCrossSize = isHorizontal ? contentRect.height : contentRect.width;
+  const totalChildMainSize = childMetrics.reduce((sum, metric) => sum + metric.mainSize, 0);
+  const totalGapSize = (arrange.gap ?? 0) * Math.max(0, childMetrics.length - 1);
+  const usedMainSize = totalChildMainSize + totalGapSize;
+  return {
+    parentId,
+    axis: arrange.axis,
+    parentRect: copyRect(parent.rect),
+    contentRect,
+    padding: normalizePadding(arrange.padding),
+    gap: arrange.gap ?? 0,
+    childIds,
+    childMetrics,
+    contentMainSize,
+    contentCrossSize,
+    totalChildMainSize,
+    totalGapSize,
+    usedMainSize,
+    unusedMainSize: contentMainSize - usedMainSize
+  };
+}
+function getStackChildRects(layout, parentId) {
+  requireStackArrange(layout, parentId);
+  const rects = {};
+  for (const childId of layout.children[parentId] ?? []) {
+    rects[childId] = copyRect(requireNode(layout, childId).rect);
+  }
+  return rects;
+}
+function getRemainingStackRect(layout, options) {
+  const metrics = getStackMainAxisMetrics(layout, options.parentId);
+  const byId = new Map(metrics.childMetrics.map((metric) => [metric.id, metric]));
+  const after = options.afterChildren ?? [];
+  const before = options.beforeChildren ?? [];
+  const start = after.length === 0 ? 0 : Math.max(...after.map((id) => requireStackMetric(byId, id).mainEnd));
+  const end = before.length === 0 ? metrics.contentMainSize : Math.min(...before.map((id) => requireStackMetric(byId, id).mainStart));
+  const size = end - start;
+  if (size < 0) {
+    throw new MachinaLayoutError(
+      "StackQueryInvalidRange",
+      `remaining stack interval is negative for parent: ${options.parentId}`
+    );
+  }
+  return metrics.axis === "horizontal" ? {
+    x: metrics.contentRect.x + start,
+    y: metrics.contentRect.y,
+    width: size,
+    height: metrics.contentRect.height
+  } : {
+    x: metrics.contentRect.x,
+    y: metrics.contentRect.y + start,
+    width: metrics.contentRect.width,
+    height: size
+  };
+}
+function requireStackMetric(metrics, childId) {
+  const metric = metrics.get(childId);
+  if (!metric) throw new MachinaLayoutError("InvalidId", `stack child id not found: ${childId}`);
+  return metric;
+}
+
 // src/lerp.ts
 function assertFiniteNumber2(value) {
   if (!Number.isFinite(value)) {
@@ -1056,8 +1210,18 @@ export {
   assertNonNegativePadding,
   assertNonNegativeSize,
   compileLayoutRows,
+  createViewportMatrix,
+  defineMachinaScreens,
+  defineMachinaViewports,
+  expandScreenViewportTasks,
   flattenResolvedTree,
   formatRect,
+  getArrangeContentRect,
+  getMachinaViewport,
+  getRemainingStackRect,
+  getStackChildRects,
+  getStackContentRect,
+  getStackMainAxisMetrics,
   lerpNumber,
   lerpRect,
   lerpResolvedLayouts,
@@ -1069,5 +1233,6 @@ export {
   resolveLayoutRows,
   resolveUiLength,
   selectLayoutRowsForRoot,
+  slugMachinaArtifactName,
   toResolvedTree
 };

package/dist/inspect/index.d.ts

@@ -0,0 +1,8 @@
+import { S as SummarizeMachinaDomOptions, M as MachinaDomSummary } from '../types-DLYAhNXw.js';
+export { a as MachinaDomSummaryNode } from '../types-DLYAhNXw.js';
+import '../types-B90jb3RW.js';
+
+type DomRoot = ParentNode | Element | Document;
+declare function summarizeMachinaDom(rootOrOptions?: DomRoot | SummarizeMachinaDomOptions): MachinaDomSummary;
+
+export { MachinaDomSummary, SummarizeMachinaDomOptions, summarizeMachinaDom };

package/dist/inspect/index.js

@@ -0,0 +1,97 @@
+// src/inspect/summarizeMachinaDom.ts
+var DEFAULT_SELECTOR = "[data-machina-node-id]";
+var DEFAULT_MAX_TEXT_LENGTH = 120;
+function getGlobalDocument() {
+  return typeof document === "undefined" ? void 0 : document;
+}
+function isOptions(value) {
+  if (value === void 0 || value === null || typeof value !== "object") return false;
+  return "root" in value || "selector" in value || "includeTextExcerpt" in value || "includeA11y" in value || "generatedAt" in value || "maxTextLength" in value || "includeEmptyNodes" in value;
+}
+function readOptionalAttribute(element, name) {
+  const value = element.getAttribute(name);
+  return value === null || value === "" ? void 0 : value;
+}
+function rectFromElement(element) {
+  const rect = element.getBoundingClientRect();
+  return { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
+}
+function textExcerpt(element, maxLength) {
+  const normalized = (element.textContent ?? "").replace(/\s+/g, " ").trim();
+  if (normalized === "") return void 0;
+  return normalized.length > maxLength ? normalized.slice(0, maxLength) : normalized;
+}
+function canMatchRoot(root) {
+  return typeof root.matches === "function";
+}
+function queryMatchingElements(root, selector) {
+  const matches = Array.from(root.querySelectorAll(selector));
+  if (canMatchRoot(root) && root.matches(selector)) return [root, ...matches];
+  return matches;
+}
+function nearestMatchingAncestor(element, selected, root) {
+  let parent = element.parentElement;
+  while (parent) {
+    if (selected.has(parent)) return parent;
+    if (parent === root) return void 0;
+    parent = parent.parentElement;
+  }
+  return void 0;
+}
+function makeSummaryNode(element, options) {
+  const node = {
+    tagName: element.tagName.toLowerCase(),
+    rect: rectFromElement(element),
+    children: []
+  };
+  const nodeId = readOptionalAttribute(element, "data-machina-node-id");
+  const view = readOptionalAttribute(element, "data-machina-view");
+  const slot = readOptionalAttribute(element, "data-machina-slot");
+  const debugLabel = readOptionalAttribute(element, "data-machina-debug-label");
+  const layer = readOptionalAttribute(element, "data-machina-layer");
+  if (nodeId !== void 0) node.nodeId = nodeId;
+  if (view !== void 0) node.view = view;
+  if (slot !== void 0) node.slot = slot;
+  if (debugLabel !== void 0) node.debugLabel = debugLabel;
+  if (layer !== void 0) node.layer = layer;
+  if (options.includeA11y) {
+    const role = readOptionalAttribute(element, "role");
+    const ariaLabel = readOptionalAttribute(element, "aria-label");
+    if (role !== void 0) node.role = role;
+    if (ariaLabel !== void 0) node.ariaLabel = ariaLabel;
+  }
+  if (options.includeTextExcerpt) {
+    const excerpt = textExcerpt(element, options.maxTextLength);
+    if (excerpt !== void 0) node.textExcerpt = excerpt;
+  }
+  return node;
+}
+function summarizeMachinaDom(rootOrOptions) {
+  const options = isOptions(rootOrOptions) ? rootOrOptions : { root: rootOrOptions };
+  const selector = options.selector ?? DEFAULT_SELECTOR;
+  const root = options.root ?? getGlobalDocument();
+  const summary = { schemaVersion: 1, rootSelector: selector, nodes: [] };
+  if (options.generatedAt !== void 0) summary.generatedAt = options.generatedAt;
+  if (root === void 0 || typeof root.querySelectorAll !== "function") return summary;
+  const elements = queryMatchingElements(root, selector);
+  const selected = new Set(elements);
+  const nodeByElement = /* @__PURE__ */ new Map();
+  const nodeOptions = {
+    includeTextExcerpt: options.includeTextExcerpt ?? false,
+    includeA11y: options.includeA11y ?? false,
+    maxTextLength: options.maxTextLength ?? DEFAULT_MAX_TEXT_LENGTH
+  };
+  for (const element of elements) nodeByElement.set(element, makeSummaryNode(element, nodeOptions));
+  for (const element of elements) {
+    const node = nodeByElement.get(element);
+    if (!node) continue;
+    const parent = nearestMatchingAncestor(element, selected, root);
+    const parentNode = parent === void 0 ? void 0 : nodeByElement.get(parent);
+    if (parentNode) parentNode.children.push(node);
+    else summary.nodes.push(node);
+  }
+  return summary;
+}
+export {
+  summarizeMachinaDom
+};

package/dist/react/index.d.ts

@@ -1,5 +1,6 @@
 import React from 'react';
-import { b as ResolvedLayoutDocument, N as NodeId, R as Rect, a as ResolvedLayoutNode } from '../types-BudfpzZX.js';
+import { o as MachinaDebugOverlayMode } from '../debugOverlay-pJpj0n5H.js';
+import { b as ResolvedLayoutDocument, N as NodeId, R as Rect, a as ResolvedLayoutNode } from '../types-B90jb3RW.js';
 
 type MachinaSlotProps<TViewData = unknown, TNodeData = unknown> = {
     id: NodeId;
@@ -13,6 +14,12 @@ type MachinaSlotProps<TViewData = unknown, TNodeData = unknown> = {
 type MachinaRenderLayer = {
     z: number;
 };
+type MachinaReactDebugOverlayOptions = {
+    mode?: MachinaDebugOverlayMode;
+    labels?: boolean;
+    borders?: boolean;
+    selectedNodeId?: string;
+};
 type MachinaReactViewProps = {
     layout: ResolvedLayoutDocument;
     views?: Record<string, React.ComponentType<MachinaSlotProps>>;
@@ -27,7 +34,8 @@ type MachinaReactViewProps = {
     nodeContainIntrinsicSize?: string;
     layers?: Record<string, MachinaRenderLayer>;
     defaultLayer?: string;
+    debugOverlay?: MachinaReactDebugOverlayOptions;
 };
 declare function MachinaReactView(props: MachinaReactViewProps): React.JSX.Element;
 
-export { MachinaReactView, type MachinaReactViewProps, type MachinaSlotProps };
+export { type MachinaReactDebugOverlayOptions, MachinaReactView, type MachinaReactViewProps, type MachinaSlotProps };

package/dist/react/index.js

@@ -1,7 +1,9 @@
 import {
   MachinaReactView
-} from "../chunk-HU6XYOH7.js";
-import "../chunk-TR24ERZT.js";
+} from "../chunk-ZVDE7PX4.js";
+import "../chunk-2ZQ2RFFI.js";
+import "../chunk-SVWYWI7I.js";
+import "../chunk-VREK57S3.js";
 export {
   MachinaReactView
 };

package/dist/react-native/index.d.ts

@@ -1,6 +1,6 @@
 import React from 'react';
 import { StyleProp, ViewStyle } from 'react-native';
-import { N as NodeId, R as Rect, a as ResolvedLayoutNode, b as ResolvedLayoutDocument } from '../types-BudfpzZX.js';
+import { N as NodeId, R as Rect, a as ResolvedLayoutNode, b as ResolvedLayoutDocument } from '../types-B90jb3RW.js';
 
 type MachinaNativeSlotProps<TViewData = unknown, TNodeData = unknown> = {
     id: NodeId;

package/dist/react-native/index.js

@@ -1,6 +1,7 @@
 import {
   toResolvedTree
-} from "../chunk-TR24ERZT.js";
+} from "../chunk-SVWYWI7I.js";
+import "../chunk-VREK57S3.js";
 
 // src/react-native/MachinaReactNativeView.tsx
 import React from "react";

package/dist/screenCatalog-ZjonGiOi.d.ts

@@ -0,0 +1,46 @@
+type MachinaViewport = {
+    key: string;
+    width: number;
+    height: number;
+    deviceScaleFactor?: number;
+    label?: string;
+    tags?: readonly string[];
+};
+type MachinaViewportMatrix = readonly MachinaViewport[];
+type MachinaScreen = {
+    key: string;
+    route: string;
+    fixture?: string;
+    viewports?: readonly string[];
+    tags?: readonly string[];
+    title?: string;
+    metadata?: Record<string, unknown>;
+};
+type MachinaScreenCatalog = {
+    screens: Record<string, MachinaScreen>;
+    order: string[];
+};
+type MachinaScreenViewportTask = {
+    key: string;
+    screenKey: string;
+    viewportKey: string;
+    route: string;
+    fixture?: string;
+    viewport: MachinaViewport;
+    screen: MachinaScreen;
+    tags: readonly string[];
+    artifactBaseName: string;
+};
+type ExpandOptions = {
+    screenKeys?: readonly string[];
+    viewportKeys?: readonly string[];
+    tags?: readonly string[];
+};
+declare function defineMachinaViewports(viewports: readonly MachinaViewport[]): MachinaViewportMatrix;
+declare function createViewportMatrix(preset?: "standard-responsive" | "desktop-only" | "mobile-first"): MachinaViewportMatrix;
+declare function defineMachinaScreens(screens: readonly MachinaScreen[]): MachinaScreenCatalog;
+declare function slugMachinaArtifactName(input: string): string;
+declare function getMachinaViewport(viewports: MachinaViewportMatrix, key: string): MachinaViewport;
+declare function expandScreenViewportTasks(catalog: MachinaScreenCatalog, viewports: MachinaViewportMatrix, options?: ExpandOptions): MachinaScreenViewportTask[];
+
+export { type MachinaViewport as M, type MachinaScreenViewportTask as a, type MachinaScreen as b, type MachinaScreenCatalog as c, type MachinaViewportMatrix as d, createViewportMatrix as e, defineMachinaScreens as f, defineMachinaViewports as g, expandScreenViewportTasks as h, getMachinaViewport as i, slugMachinaArtifactName as s };

package/dist/{types-BudfpzZX.d.ts → types-B90jb3RW.d.ts}

@@ -181,4 +181,4 @@ type ResolvedLayoutTree = {
     children: ResolvedLayoutTree[];
 };
 
-export type { AbsoluteFrame as A, CellFrame as C, EdgeInsets as E, FrameSpec as F, GridArrange as G, LayoutRow as L, NodeId as N, OffsetSpec as O, Rect as R, StackAlign as S, UiLength as U, ResolvedLayoutNode as a, ResolvedLayoutDocument as b, LayoutDocument as c, ResolvedLayoutTree as d, AnchorFrame as e, ArrangeSpec as f, EdgeRef as g, FillFrame as h, FixedFrame as i, GridTrack as j, GuideFrame as k, GuideLength as l, LayerName as m, LayoutNode as n, LayoutRowVariant as o, LayoutVariantCondition as p, RectEdge as q, RootFrame as r, StackArrange as s, StackAxis as t, StackJustify as u };
+export type { ArrangeSpec as A, CellFrame as C, EdgeInsets as E, FrameSpec as F, GridArrange as G, LayoutRow as L, NodeId as N, OffsetSpec as O, Rect as R, StackAxis as S, UiLength as U, ResolvedLayoutNode as a, ResolvedLayoutDocument as b, LayoutDocument as c, ResolvedLayoutTree as d, LayerName as e, AbsoluteFrame as f, AnchorFrame as g, EdgeRef as h, FillFrame as i, FixedFrame as j, GridTrack as k, GuideFrame as l, GuideLength as m, LayoutNode as n, LayoutRowVariant as o, LayoutVariantCondition as p, RectEdge as q, RootFrame as r, StackAlign as s, StackArrange as t, StackJustify as u };

package/dist/types-DLYAhNXw.d.ts

@@ -0,0 +1,32 @@
+import { R as Rect } from './types-B90jb3RW.js';
+
+type MachinaDomSummaryNode = {
+    nodeId?: string;
+    view?: string;
+    slot?: string;
+    debugLabel?: string;
+    layer?: string;
+    tagName: string;
+    role?: string;
+    ariaLabel?: string;
+    textExcerpt?: string;
+    rect: Rect;
+    children: MachinaDomSummaryNode[];
+};
+type MachinaDomSummary = {
+    schemaVersion: 1;
+    rootSelector?: string;
+    generatedAt?: string;
+    nodes: MachinaDomSummaryNode[];
+};
+type SummarizeMachinaDomOptions = {
+    root?: ParentNode | Element | Document;
+    selector?: string;
+    includeTextExcerpt?: boolean;
+    includeA11y?: boolean;
+    maxTextLength?: number;
+    includeEmptyNodes?: boolean;
+    generatedAt?: string;
+};
+
+export type { MachinaDomSummary as M, SummarizeMachinaDomOptions as S, MachinaDomSummaryNode as a };

package/dist/vue/index.d.ts

@@ -1,6 +1,6 @@
 import * as vue from 'vue';
 import { PropType, Component, StyleValue } from 'vue';
-import { N as NodeId, R as Rect, a as ResolvedLayoutNode, b as ResolvedLayoutDocument } from '../types-BudfpzZX.js';
+import { N as NodeId, R as Rect, a as ResolvedLayoutNode, b as ResolvedLayoutDocument } from '../types-B90jb3RW.js';
 
 type MachinaVueSlotProps<TViewData = unknown, TNodeData = unknown> = {
     id: NodeId;

package/dist/vue/index.js

@@ -1,6 +1,7 @@
 import {
   toResolvedTree
-} from "../chunk-TR24ERZT.js";
+} from "../chunk-SVWYWI7I.js";
+import "../chunk-VREK57S3.js";
 
 // src/vue/MachinaVueView.ts
 import { computed, defineComponent, h } from "vue";

package/docs/deusmachina.md

@@ -0,0 +1,108 @@
+# DeusMachina
+
+DeusMachina is MachinaLayout's tiny behavioral kernel. It is deliberately small: utility judgment, explicit row-first state machines, stack-style state paths, deterministic stepping, and trace output.
+
+```ts
+import { defineDeusMachine, judgeUtility, stepDeusMachine } from "machinalayout/deus";
+```
+
+## Contract summary
+
+DeusMachina combines three narrow pieces:
+
+1. `judgeUtility(context, candidates, options)` for deterministic utility selection.
+2. `defineDeusMachine(machine)` for validating row-first stack HFSM definitions.
+3. `stepDeusMachine(machine, snapshot, event)` for one synchronous deterministic step with trace output.
+
+State paths are non-empty arrays of non-empty strings. Segments are not trimmed; empty or whitespace-only segments are invalid. `formatDeusPath(["a", "b"])` formats paths as `a/b`. DeusMachina treats a path as its own ancestor for transition candidate collection.
+
+## Row-first authoring
+
+Machines are authored as arrays, not nested objects:
+
+```ts
+defineDeusMachine({
+  initial: ["debugOverlay", "collapsed"],
+  states: [{ path: ["debugOverlay", "collapsed"] }],
+  transitions: [{ key: "show", from: ["debugOverlay", "collapsed"], event: "showOverlay" }],
+});
+```
+
+Hierarchy comes from stack paths such as `debugOverlay/nonInteractiveOverlay`, not from nested authoring syntax.
+
+## Mutable board convention
+
+Snapshots keep the board by reference. `stepDeusMachine` returns a new snapshot object and a copied state path, but it does not clone the board. User actions may mutate the board intentionally. Machine definitions are treated as immutable and are copied where DeusMachina normalizes paths.
+
+## Purity rules
+
+`when`, `score`, and `reason` should be pure. They may read the board and event, but should not mutate them. `do`, `onEnter`, and `onExit` may mutate the board. DeusMachina does not sandbox user functions, so accidental mutation from guards, scores, or reasons is possible and is the caller's responsibility.
+
+User errors are not swallowed. If a guard, score, reason, action, enter hook, or exit hook throws, the error propagates to the caller.
+
+## Transition selection semantics
+
+A step gathers candidate transitions from the exact current state path, then parent paths upward to root. Candidate grouping is leaf first, then parent, then grandparent. Within each `from` path, author transition order is preserved.
+
+An omitted transition `event` accepts any event. Otherwise, the transition event must equal `event.type`. An omitted `when` means eligible; a false `when` makes the transition ineligible and keeps it in the trace with score `0`.
+
+Eligible transitions score as follows:
+
+- omitted transition `score`: `1`
+- numeric or function transition `score`: that finite score
+- utility transition with no explicit transition `score`: selected utility candidate score
+
+All gathered eligible candidates compete by score regardless of depth. Highest score wins. Ties are stable by candidate search order, so a leaf transition beats an equal-scored parent transition, and earlier author rows beat later rows within the same path.
+
+If no transition is selected, state and board reference are unchanged, but `stepIndex` increments because a step occurred. If a selected transition has no `to`, state remains the same. Same-state transitions do not run exit or enter hooks.
+
+Dynamic `to` functions are validated at runtime. They must return a valid path that exists in the machine.
+
+## Utility judgment semantics
+
+`judgeUtility` preserves candidate array order in its trace. Omitted `when` means eligible. A false `when` makes the candidate ineligible with score `0`, and score functions are evaluated only for eligible candidates. Reason strings or functions are included in trace entries; reason functions are evaluated while building trace entries.
+
+Scores must be finite. If no candidate is eligible, `selected` is `null`. Highest score wins and ties are stable by candidate order.
+
+Hysteresis accepts a finite margin greater than or equal to `0`. If `previousKey` is present and the previous candidate is still eligible, a challenger must satisfy `challengerScore >= previousScore + margin` to replace it. If margin is `0`, normal highest-score semantics apply. If the previous candidate is missing or ineligible, normal selection applies.
+
+`judgeUtility` does not mutate candidate definitions or the context itself, though user-provided functions can mutate external objects if they choose to.
+
+## Utility transition semantics
+
+A transition with `utility` evaluates utility candidates only after its event and `when` checks pass. If no utility candidate is selected, the transition is not eligible and neither utility `do` nor transition `do` runs.
+
+If a utility candidate is selected, its judgment appears in the transition trace. The transition score is the explicit transition score when provided; otherwise it is the selected utility candidate score. Transition `hysteresis` is passed through to the utility judgment via `hysteresis.previous(board)` and `hysteresis.margin`; `undefined` from `previous` means no previous key.
+
+Utility candidate `do` receives the original board and event and runs before the outer transition `do`.
+
+## Enter, exit, and action order
+
+When state changes, execution order is:
+
+1. `onExit` for states being exited, deepest first.
+2. Selected utility candidate `do`, if present.
+3. Transition `do`, if present.
+4. `onEnter` for states being entered, shallow to deep.
+
+For `root/a/x -> root/b/y`, exit order is `root/a/x`, then `root/a`; enter order is `root/b`, then `root/b/y`. For `root/a/x -> root/a/y`, only `root/a/x` exits and only `root/a/y` enters. For `root/a -> root/a`, no exit or enter hooks run.
+
+## Trace contract
+
+`stepDeusMachine` returns a trace containing state before, state after, event type, considered transitions, selected transition, transition eligibility, transition score, transition search index, reasons when provided, and inner utility judgment when applicable.
+
+Trace data is intended to be JSON-serializable. It does not include function references, the board object, or arbitrary event payloads. `formatDeusStepTrace(trace)` provides a small deterministic one-line summary for selected and unselected steps.
+
+## Debug overlay helper
+
+`createMachinaDebugOverlayMachine()` returns a validated DeusMachina machine for the controlled React debug overlay modes. `getMachinaDebugOverlayBehavior(board)` maps the board to rendering behavior:
+
+- `collapsed`: not visible, `pointerEvents: "none"`, consumes no layout space.
+- `nonInteractiveOverlay`: visible, `pointerEvents: "none"`, consumes no layout space.
+- `interactivePanel`: visible, `pointerEvents: "auto"`, consumes layout space.
+
+Labels and borders remain controlled by the board booleans; `false` stays false in overlay and panel modes.
+
+## Non-goals
+
+DeusMachina intentionally does not include async workflows, tools, actors, persistence, LLM calls, schedulers, nested authoring syntax, uncontrolled React state, or a visual editor.

package/docs/error-codes.md

@@ -47,6 +47,8 @@ This document summarizes public layout and text diagnostic codes.
   - Note: this code name is historical and stable; do not rename it.
 - `StackContentNegative` — stack content space became negative. Typical cause: padding/gaps exceed container space.
 - `StackOverflow` — stack children exceed available axis space. Typical cause: fixed sizes + gaps exceed container.
+- `ExpectedStackArrange` — a stack query helper was called on a non-stack node. Typical cause: using stack-only geometry helpers with a plain or grid parent.
+- `StackQueryInvalidRange` — a remaining stack rectangle query produced a negative interval. Typical cause: `afterChildren` resolve after `beforeChildren`.
 
 ### Grid
 
@@ -66,6 +68,15 @@ This document summarizes public layout and text diagnostic codes.
 - `InvalidGuideFrame` — guide frame declaration is malformed. Typical cause: incomplete or conflicting guide spec.
 - `GuideTargetUnresolved` — guide target exists but was not resolved when needed. Typical cause: invalid dependency order/cycle.
 
+### Screen catalog and viewport matrix
+
+- `InvalidViewport` — viewport metadata is malformed. Typical cause: blank key, non-positive dimensions, invalid `deviceScaleFactor`, or invalid lightweight metadata.
+- `DuplicateViewportKey` — two viewport presets share one key. Typical cause: duplicate matrix entries.
+- `UnknownViewportKey` — a requested or screen-referenced viewport key is absent from the matrix. Typical cause: typo or filtered matrix mismatch.
+- `InvalidScreen` — screen catalog metadata is malformed. Typical cause: blank key, blank route, or invalid lightweight metadata.
+- `DuplicateScreenKey` — two screen definitions share one key. Typical cause: duplicate catalog entries.
+- `UnknownScreenKey` — a requested screen key is absent from the catalog. Typical cause: typo in an expansion filter.
+
 ### Variants
 
 - `InvalidVariantCondition` — variant condition is invalid. Typical cause: unsupported operator/value shape.