machinalayout 0.2.0 → 0.3.1

package/dist/vue/index.js

@@ -1,9 +1,43 @@
 import {
   toResolvedTree
-} from "../chunk-TR24ERZT.js";
+} from "../chunk-SVWYWI7I.js";
+import "../chunk-VREK57S3.js";
+import {
+  createDeusSnapshot,
+  stepDeusMachine
+} from "../chunk-2ZQ2RFFI.js";
+
+// src/vue/useDeusMachine.ts
+import { computed, ref } from "vue";
+function resolveInitialBoard(initialBoard) {
+  return typeof initialBoard === "function" ? initialBoard() : initialBoard;
+}
+function useDeusMachine(machine, initialBoard) {
+  const createSnapshot = (board) => createDeusSnapshot(machine, resolveInitialBoard(board ?? initialBoard));
+  const snapshot = ref(createSnapshot());
+  const lastTrace = ref(null);
+  const dispatch = (event) => {
+    const result = stepDeusMachine(machine, snapshot.value, event);
+    snapshot.value = result.snapshot;
+    lastTrace.value = result.trace;
+    return result;
+  };
+  const reset = (board) => {
+    snapshot.value = createSnapshot(board);
+    lastTrace.value = null;
+  };
+  return {
+    snapshot,
+    board: computed(() => snapshot.value.board),
+    state: computed(() => snapshot.value.state),
+    dispatch,
+    lastTrace,
+    reset
+  };
+}
 
 // src/vue/MachinaVueView.ts
-import { computed, defineComponent, h } from "vue";
+import { computed as computed2, defineComponent, h } from "vue";
 var normalizeLayerZ = (v) => v === void 0 || !Number.isFinite(v) || !Number.isInteger(v) || v < -5 || v > 5 ? 0 : v;
 var getEffectiveLayer = (n, d) => n.layer ?? d;
 var getEffectiveLayerZ = (n, l, d) => normalizeLayerZ(l[getEffectiveLayer(n, d)]?.z);
@@ -32,7 +66,7 @@ var MachinaVueView = defineComponent({
     nodeContainIntrinsicSize: { type: String, default: void 0 }
   },
   setup(props) {
-    const tree = computed(() => toResolvedTree(props.layout));
+    const tree = computed2(() => toResolvedTree(props.layout));
     const renderNode = (node, parentRect) => {
       const viewKey = node.view ?? node.slot;
       const View = viewKey ? props.views[viewKey] : void 0;
@@ -107,5 +141,6 @@ var MachinaVueView = defineComponent({
   }
 });
 export {
-  MachinaVueView
+  MachinaVueView,
+  useDeusMachine
 };

package/docs/deusmachina.md

@@ -0,0 +1,191 @@
+# 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.
+
+## Framework bindings
+
+M26b adds thin framework bindings for the DeusMachina kernel from the existing adapter subpaths:
+
+```ts
+import { useDeusMachine } from "machinalayout/react";
+import { useDeusMachine as useNativeDeusMachine } from "machinalayout/react-native";
+import { useDeusMachine as useVueDeusMachine } from "machinalayout/vue";
+```
+
+The bindings wrap `createDeusSnapshot` and `stepDeusMachine`; `machinalayout/deus` remains framework-free and does not import React, React Native, or Vue. They do not add stores, context providers, async workflows, persistence, actors, or router integration.
+
+All bindings return the current `snapshot`, `board`, `state`, `dispatch`, `lastTrace`, and `reset`. Deus actions keep the kernel's mutable board convention: user actions may mutate the board in place, and the bindings trigger framework updates by replacing the snapshot wrapper after every dispatch. They do not deep-clone, freeze, proxy, or sandbox the board.
+
+Define machines outside render/setup when possible. The React and React Native hooks reset the snapshot when the `machine` reference changes; the Vue composable expects a stable machine input.
+
+`reset()` recreates the snapshot with `stepIndex: 0` and clears `lastTrace`. Pass a board value or factory to reset to that board; omit the argument to reuse the original initial board/factory.
+
+### React debug overlay example
+
+```tsx
+import {
+  createMachinaDebugOverlayMachine,
+  getMachinaDebugOverlayBehavior,
+  type MachinaDebugOverlayBoard,
+  type MachinaDebugOverlayEvent,
+} from "machinalayout/deus";
+import { useDeusMachine } from "machinalayout/react";
+
+const debugMachine = createMachinaDebugOverlayMachine();
+
+function DebugControls() {
+  const debug = useDeusMachine<MachinaDebugOverlayBoard, MachinaDebugOverlayEvent>(debugMachine, {
+    mode: "collapsed",
+    labels: true,
+    borders: true,
+  });
+  const behavior = getMachinaDebugOverlayBehavior(debug.board);
+
+  return (
+    <>
+      <button onClick={() => debug.dispatch({ type: "showOverlay" })}>Overlay</button>
+      <button onClick={() => debug.dispatch({ type: "openPanel" })}>Panel</button>
+      <button onClick={() => debug.dispatch({ type: "collapse" })}>Collapse</button>
+      <pre>{JSON.stringify(behavior, null, 2)}</pre>
+    </>
+  );
+}
+```
+
+### React Native debug overlay example
+
+```tsx
+import { Button, Text, View } from "react-native";
+import { createMachinaDebugOverlayMachine, getMachinaDebugOverlayBehavior } from "machinalayout/deus";
+import { useDeusMachine } from "machinalayout/react-native";
+
+const debugMachine = createMachinaDebugOverlayMachine();
+
+function NativeDebugControls() {
+  const debug = useDeusMachine(debugMachine, { mode: "collapsed", labels: true, borders: true });
+  const behavior = getMachinaDebugOverlayBehavior(debug.board);
+  return (
+    <View>
+      <Button title="Overlay" onPress={() => debug.dispatch({ type: "showOverlay" })} />
+      <Text>{behavior.visible ? "visible" : "hidden"}</Text>
+    </View>
+  );
+}
+```
+
+### Vue debug overlay example
+
+```ts
+import { computed } from "vue";
+import { createMachinaDebugOverlayMachine, getMachinaDebugOverlayBehavior } from "machinalayout/deus";
+import { useDeusMachine } from "machinalayout/vue";
+
+const debugMachine = createMachinaDebugOverlayMachine();
+const debug = useDeusMachine(debugMachine, { mode: "collapsed", labels: true, borders: true });
+const behavior = computed(() => getMachinaDebugOverlayBehavior(debug.board.value));
+```

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.

package/docs/inspection-and-handoff.md

@@ -0,0 +1,126 @@
+# Inspection and handoff bundles
+
+MachinaLayout inspection helpers provide a small, framework-light contract for handing UI work from one person or model to another. The utilities standardize the data shapes that app-local workflows can combine with screenshots and layout snapshots, without adding browser automation to MachinaLayout itself.
+
+## Purpose
+
+A useful UI handoff often contains four artifacts:
+
+- a screenshot for visual truth, produced by userland tooling;
+- a compact DOM summary for semantic/browser truth;
+- a Machina layout snapshot for layout truth;
+- a handoff manifest for route, viewport, screen, and artifact metadata.
+
+M25c standardizes the DOM summary and handoff manifest/writer pieces. It does not capture screenshots, launch browsers, drive routes, run viewport matrices, or perform visual diffs.
+
+## DOM summary
+
+Import DOM-safe helpers from the inspect subpath:
+
+```ts
+import { summarizeMachinaDom } from "machinalayout/inspect";
+
+const summary = summarizeMachinaDom({
+  root: document,
+  includeA11y: true,
+  includeTextExcerpt: true,
+  generatedAt: "2026-01-01T00:00:00.000Z",
+});
+```
+
+By default, `summarizeMachinaDom` selects `[data-machina-node-id]`, reads only compact debug metadata, calls `getBoundingClientRect()` for each selected element, and reconstructs the nearest matching ancestor hierarchy. It intentionally does not dump full HTML.
+
+The standard Machina browser debug attributes are:
+
+- `data-machina-node-id`
+- `data-machina-view`
+- `data-machina-slot`
+- `data-machina-debug-label`
+- `data-machina-layer`
+
+When `includeA11y` is enabled, the summary includes `role` and `aria-label` if present. When `includeTextExcerpt` is enabled, the summary includes normalized `textContent` excerpts. Text excerpts are compact hints, not a lossless DOM serialization; the simple text collection may include descendant text in ancestor excerpts.
+
+You can also provide a custom selector for app-specific annotations:
+
+```ts
+const summary = summarizeMachinaDom({
+  selector: "[data-debug-node]",
+  includeTextExcerpt: true,
+});
+```
+
+## Handoff bundle writer
+
+Import Node-only handoff helpers from the handoff subpath:
+
+```ts
+import { writeMachinaHandoffBundle } from "machinalayout/handoff";
+
+await writeMachinaHandoffBundle({
+  outputDir: "./artifacts/provider-setup-phone",
+  artifactBaseName: "Provider Setup / Phone!",
+  screenshotPath: "./artifacts/screenshot.png",
+  domSummary: summary,
+  layoutSnapshot,
+  route: "/provider/setup",
+  tags: ["handoff", "phone"],
+});
+```
+
+`writeMachinaHandoffBundle` ensures the output directory exists, writes JSON with two-space indentation, copies an existing screenshot when one is supplied, and returns absolute output paths. The manifest stores relative artifact file names so the bundle can move as a directory.
+
+The writer uses deterministic artifact names based on a slugged base name:
+
+- `${base}__screenshot.<ext>`
+- `${base}__dom-summary.json`
+- `${base}__machina-snapshot.json`
+- `${base}__handoff.json`
+
+If no explicit base name is supplied, the writer uses `task.artifactBaseName`, then route/fixture/viewport metadata, then `machina-handoff`.
+
+## Manifest shape
+
+The manifest has `schemaVersion: 1`, a `createdAt` timestamp, optional route/fixture/screen/viewport metadata, optional tags and metadata, and an `artifacts` object containing relative file names.
+
+```json
+{
+  "schemaVersion": 1,
+  "createdAt": "2026-01-01T00:00:00.000Z",
+  "route": "/provider/setup",
+  "viewportKey": "phone",
+  "artifactBaseName": "provider-setup-phone",
+  "artifacts": {
+    "screenshot": "provider-setup-phone__screenshot.png",
+    "domSummary": "provider-setup-phone__dom-summary.json",
+    "layoutSnapshot": "provider-setup-phone__machina-snapshot.json",
+    "manifest": "provider-setup-phone__handoff.json"
+  }
+}
+```
+
+## Composition with screen tasks
+
+The handoff writer accepts a `MachinaScreenViewportTask` from the screen catalog and viewport matrix helpers. When provided, the writer copies `route`, `fixture`, `screenKey`, `viewportKey`, `viewport`, `task.artifactBaseName`, and task tags into the manifest. Input tags are merged after task tags with duplicates removed while preserving order.
+
+```ts
+await writeMachinaHandoffBundle({
+  outputDir: "./artifacts",
+  task,
+  domSummary,
+  layoutSnapshot,
+});
+```
+
+## Limitations and boundaries
+
+These utilities are intentionally narrow:
+
+- no Playwright dependency;
+- no browser launch or browser automation;
+- no screenshot capture;
+- no viewport matrix runner;
+- no visual diff;
+- no adapter behavior changes;
+- no layout resolver semantics changes.
+
+Userland tooling remains responsible for route navigation, viewport setup, screenshots, and any visual comparison workflow. MachinaLayout provides the lightweight schemas and writing helpers that make those artifacts predictable.

package/docs/react-adapter.md

@@ -90,3 +90,30 @@ Not used as geometry authority:
 - CSS classes determining solved geometry
 
 React components render payload UI inside adapter-owned rectangles; React does not own outer layout geometry.
+
+## Inspection handoff surface
+
+React DOM rendering includes the standard Machina `data-machina-*` debug attributes used by the framework-light DOM summary helpers. See [Inspection and handoff bundles](inspection-and-handoff.md) for the `machinalayout/inspect` and `machinalayout/handoff` workflow.
+
+## Debug overlay
+
+`MachinaReactView` accepts an optional controlled `debugOverlay` prop:
+
+```tsx
+<MachinaReactView
+  layout={layout}
+  debugOverlay={{ mode: "nonInteractiveOverlay", labels: true, borders: true }}
+/>
+```
+
+Modes:
+
+- `collapsed`: no overlay labels or borders are rendered and app interactions are not blocked.
+- `nonInteractiveOverlay`: overlay labels and borders render when enabled, do not consume layout space, and use `pointer-events: none`, making the mode suitable for screenshots and browser automation.
+- `interactivePanel`: overlay labels/borders can render with a small panel and `pointer-events: auto` for human inspection.
+
+The prop is controlled. M26 does not add React state management or hooks; DeusMachina provides the standalone behavior helpers used to derive the rendering semantics. In `nonInteractiveOverlay`, overlay artifacts use `pointer-events: none` and do not consume layout space; in `collapsed`, overlay artifacts are not rendered. Labels and borders remain controlled booleans and do not change existing `data-machina-*` attributes on node wrappers.
+
+## DeusMachina hook
+
+`machinalayout/react` exports `useDeusMachine(machine, initialBoard)`. The hook is a thin wrapper around the DeusMachina kernel and returns `snapshot`, `board`, `state`, `dispatch`, `lastTrace`, and `reset`. It follows the mutable board contract: actions may mutate the board, while the hook replaces the snapshot object after dispatch so React re-renders. Keep machine definitions stable; changing the machine reference resets the hook snapshot.

package/docs/react-native-adapter.md

@@ -54,3 +54,7 @@ Keep `views` stable (component references). Send changing values through `viewDa
 - this package only renders layout boxes; text rendering is provided separately by `machinalayout/text/react-native`
 - portals/reparenting
 - DOM-only features
+
+## DeusMachina hook
+
+`machinalayout/react-native` exports the same `useDeusMachine(machine, initialBoard)` contract as the React adapter without importing the DOM adapter. It returns `snapshot`, `board`, `state`, `dispatch`, `lastTrace`, and `reset`, and re-renders by replacing the snapshot wrapper while preserving the mutable board convention.

package/docs/screen-catalog-and-viewports.md

@@ -0,0 +1,124 @@
+# Screen catalog and viewport matrix
+
+Machina screen catalog helpers describe named app screens and responsive viewport presets as plain TypeScript data. They are intended for future capture, inspection, and handoff tooling, but they do not perform any browser automation themselves.
+
+These utilities model this relationship:
+
+```ts
+screen + viewport -> task metadata
+```
+
+A future runner can consume each task to navigate an app route, set a viewport, capture screenshots, inspect DOM, collect layout snapshots, or write handoff bundles.
+
+## Screen catalog
+
+A `MachinaScreen` is a stable, named screen entry:
+
+```ts
+const screens = defineMachinaScreens([
+  {
+    key: "provider-setup",
+    route: "/apps/scheduling/setup",
+    fixture: "provider-setup",
+    viewports: ["desktop", "tablet", "phone"],
+    tags: ["scheduling", "setup"],
+  },
+]);
+```
+
+The `route` value is opaque app metadata. Machina does not parse it, validate URL semantics, or integrate with a router. `fixture`, `tags`, `title`, and `metadata` are also app-owned metadata for downstream tools.
+
+`defineMachinaScreens` validates screen keys and routes, rejects duplicate keys, returns fresh screen objects, and preserves author order in `catalog.order`.
+
+## Viewport matrix
+
+A `MachinaViewport` is a stable viewport preset:
+
+```ts
+const viewports = createViewportMatrix("standard-responsive");
+```
+
+Built-in presets:
+
+| Preset | Order | Sizes |
+| --- | --- | --- |
+| `standard-responsive` | desktop, tablet, phone | 1440×900, 1024×768, 390×844 |
+| `desktop-only` | desktop | 1440×900 |
+| `mobile-first` | phone, tablet, desktop | 390×844, 1024×768, 1440×900 |
+
+Default preset is `standard-responsive`. Built-in viewport tags are:
+
+- desktop: `desktop`
+- tablet: `tablet`
+- phone: `phone`, `mobile`
+
+Use `defineMachinaViewports` for custom matrices. It validates unique non-empty keys, positive finite width/height, optional positive finite `deviceScaleFactor`, and preserves input order.
+
+## Task expansion
+
+`expandScreenViewportTasks` expands a screen catalog and viewport matrix into deterministic `MachinaScreenViewportTask[]` values:
+
+```ts
+const screens = defineMachinaScreens([
+  {
+    key: "provider-setup",
+    route: "/apps/scheduling/setup",
+    fixture: "provider-setup",
+    viewports: ["desktop", "tablet", "phone"],
+    tags: ["scheduling", "setup"],
+  },
+]);
+
+const viewports = createViewportMatrix("standard-responsive");
+const tasks = expandScreenViewportTasks(screens, viewports);
+```
+
+Task ordering is always catalog order first, then viewport matrix order. One task represents one screen at one viewport and includes the raw screen route, fixture, copied screen/viewport references, merged tags, a deterministic task key, and a filesystem-safe artifact base name.
+
+## Filtering semantics
+
+Expansion accepts optional filters:
+
+```ts
+const phoneSchedulingTasks = expandScreenViewportTasks(screens, viewports, {
+  screenKeys: ["provider-setup"],
+  viewportKeys: ["phone"],
+  tags: ["scheduling", "mobile"],
+});
+```
+
+Filtering is deterministic:
+
+1. Start with screens in catalog order.
+2. If `screenKeys` is present, include only those screens. Unknown requested screen keys throw `UnknownScreenKey`.
+3. A screen's `viewports` list limits the default eligible viewport set for that screen.
+4. If `viewportKeys` is present, it further filters eligible viewport keys. Unknown requested viewport keys throw `UnknownViewportKey`.
+5. Screen-referenced viewport keys must exist in the provided viewport matrix or expansion throws `UnknownViewportKey`.
+6. Tags merge screen tags first, then viewport tags, with duplicates removed while preserving order.
+7. If `tags` is present, a task is included only when every requested tag is in the merged task tags.
+
+## Artifact base names
+
+Task keys use raw keys joined by `__`, for example `provider-setup__phone`. Artifact base names slug each side independently:
+
+```ts
+slugMachinaArtifactName("Provider Setup!"); // "provider-setup"
+```
+
+A task for screen key `Provider Setup` and viewport key `Phone XL` receives `artifactBaseName: "provider-setup__phone-xl"`.
+
+## Limitations
+
+This is a framework-independent metadata layer only. It intentionally does not include:
+
+- browser automation,
+- screenshot capture,
+- DOM inspection or DOM summaries,
+- handoff bundle writing,
+- router integration,
+- route parsing,
+- fixture serving,
+- adapter behavior,
+- layout resolver semantic changes.
+
+The helpers work in Node or the browser and have no Playwright, DOM, React, Vue, or React Native dependency.