machinalayout 0.2.0 → 0.3.0

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,26 @@ 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.

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.

package/docs/stack-geometry-helpers.md

@@ -0,0 +1,115 @@
+# Stack geometry helpers
+
+MachinaLayout stack geometry helpers are pure query utilities for resolved layout documents. They make common stack arithmetic inspectable without introducing new layout primitives or changing resolver behavior.
+
+## Why these helpers exist
+
+Apps with fixed chrome, content panes, sidebars, and inspectors often need to ask questions like:
+
+- What rectangle is left after stack padding?
+- How much of a stack main axis is consumed by direct children and gaps?
+- Where is the interval between a header-like child and an inspector-like child?
+
+The resolver already computes deterministic rectangles. These helpers expose that resolved state so humans and LLMs do not have to hand-copy padding, gap, and fixed/fill calculations.
+
+## Resolved-document query boundary
+
+These helpers inspect existing rectangles. They do not:
+
+- mutate the resolved layout document,
+- recompute layout from `LayoutRow[]`,
+- account for DOM measurements,
+- inspect descendants when a helper is scoped to direct stack children,
+- change `StackArrange` or `GridArrange` semantics.
+
+They report resolved state, including resolved fill allocations, rather than pre-resolution authoring guesses.
+
+## `getArrangeContentRect(parentRect, arrange)`
+
+`getArrangeContentRect` returns a fresh content rectangle for an arranger:
+
+- `stack`: subtracts normalized stack padding and throws `StackContentNegative` if padding makes content negative.
+- `grid`: subtracts normalized grid padding and throws `GridContentNegative` if padding makes content negative.
+- omitted or unsupported arranger: returns a fresh copy of the parent rectangle.
+
+```ts
+const contentRect = getArrangeContentRect(parent.rect, parent.arrange);
+```
+
+## `getStackContentRect(layout, parentId)`
+
+`getStackContentRect` looks up a resolved stack parent and returns its content rectangle after stack padding.
+
+```ts
+const content = getStackContentRect(layout, "scheduling-content");
+```
+
+The parent must exist and must have `arrange.kind === "stack"`. A non-stack parent throws `ExpectedStackArrange`.
+
+## `getStackMainAxisMetrics(layout, parentId)`
+
+`getStackMainAxisMetrics` returns main-axis and cross-axis data for a resolved stack parent:
+
+- parent and content rectangles,
+- normalized padding and gap,
+- direct child ids in resolved child order,
+- per-child rectangles and main/cross starts, ends, and sizes relative to the content rectangle,
+- content main/cross sizes,
+- total child main size,
+- total gap size,
+- used main size,
+- unused main size.
+
+Because the input is a resolved document, fill children are reported at their actual resolved sizes.
+
+```ts
+const metrics = getStackMainAxisMetrics(layout, "root");
+const remaining = metrics.unusedMainSize;
+```
+
+## `getStackChildRects(layout, parentId)`
+
+`getStackChildRects` returns fresh direct-child rectangle copies keyed by child id.
+
+```ts
+const childRects = getStackChildRects(layout, "root");
+const sidebar = childRects.sidebar;
+```
+
+Only direct stack children are returned. Descendant rectangles should be queried from `layout.nodes` or from a helper scoped to their own parent.
+
+## `getRemainingStackRect(layout, options)`
+
+`getRemainingStackRect` is a narrow interval query over direct children of one resolved stack parent.
+
+It computes the interval between:
+
+- the latest `mainEnd` among `afterChildren`, or the content start when no `afterChildren` are provided, and
+- the earliest `mainStart` among `beforeChildren`, or the content end when no `beforeChildren` are provided.
+
+The returned rectangle preserves the full content cross-axis size.
+
+```ts
+const shellContent = getRemainingStackRect(layout, {
+  parentId: "root",
+  afterChildren: ["hero"],
+  beforeChildren: ["inspector"],
+});
+```
+
+If the computed interval is negative, the helper throws `StackQueryInvalidRange`. This helper is a query helper, not a solver; it does not move children or search descendants.
+
+## Inspector/content shell example
+
+```ts
+const metrics = getStackMainAxisMetrics(layout, "root");
+const content = getStackContentRect(layout, "scheduling-content");
+
+const interactiveRegion = getRemainingStackRect(layout, {
+  parentId: "root",
+  afterChildren: ["toolbar"],
+  beforeChildren: ["inspector"],
+});
+```
+
+This pattern is useful for app shells that place fixed controls around an interactive content region while still keeping all geometry framework-independent.

package/package.json

@@ -1,115 +1,127 @@
-{
-  "name": "machinalayout",
-  "version": "0.2.0",
-  "type": "module",
-  "scripts": {
-    "typecheck": "tsc --noEmit",
-    "build": "npm run typecheck && tsup --config tsup.config.ts --tsconfig tsconfig.build.json",
-    "test": "vitest run",
-    "format": "biome format --write .",
-    "format:check": "biome format .",
-    "lint": "biome lint .",
-    "check": "biome check ."
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.4.15",
-    "@testing-library/jest-dom": "^6.9.1",
-    "@testing-library/react": "^16.3.2",
-    "@types/react": "^19.2.14",
-    "@types/react-dom": "^19.2.3",
-    "@types/react-test-renderer": "^19.1.0",
-    "@vue/test-utils": "^2.4.6",
-    "jsdom": "^29.1.1",
-    "react": "^19.2.6",
-    "react-dom": "^19.2.6",
-    "react-native": "^0.82.0",
-    "react-test-renderer": "^19.2.6",
-    "tsup": "^8.5.1",
-    "typescript": "^5.6.3",
-    "vitest": "^2.1.8",
-    "vue": "^3.5.22"
-  },
-  "peerDependencies": {
-    "react": ">=18 <20",
-    "react-dom": ">=18 <20",
-    "react-native": ">=0.72 <1",
-    "vue": ">=3.4 <4"
-  },
-  "description": "Machine-native layout and text primitives for deterministic app UI records.",
-  "license": "MIT",
-  "author": "MachinaLayout contributors",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/machinalayout/MachinaLayout.JS.git"
-  },
-  "homepage": "https://github.com/machinalayout/MachinaLayout.JS#readme",
-  "bugs": {
-    "url": "https://github.com/machinalayout/MachinaLayout.JS/issues"
-  },
-  "keywords": [
-    "layout",
-    "ui",
-    "react",
-    "typescript",
-    "machina",
-    "text",
-    "rectangles"
-  ],
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./react": {
-      "types": "./dist/react/index.d.ts",
-      "import": "./dist/react/index.js"
-    },
-    "./text": {
-      "types": "./dist/text/index.d.ts",
-      "import": "./dist/text/index.js"
-    },
-    "./text/react": {
-      "types": "./dist/text/react/index.d.ts",
-      "import": "./dist/text/react/index.js"
-    },
-    "./package.json": "./package.json",
-    "./react-native": {
-      "types": "./dist/react-native/index.d.ts",
-      "import": "./dist/react-native/index.js"
-    },
-    "./vue": {
-      "types": "./dist/vue/index.d.ts",
-      "import": "./dist/vue/index.js"
-    },
-    "./text/react-native": {
-      "types": "./dist/text/react-native/index.d.ts",
-      "import": "./dist/text/react-native/index.js"
-    },
-    "./text/vue": {
-      "types": "./dist/text/vue/index.d.ts",
-      "import": "./dist/text/vue/index.js"
-    },
-    "./dispatch": {
-      "types": "./dist/dispatch/index.d.ts",
-      "import": "./dist/dispatch/index.js"
-    }
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE",
-    "docs"
-  ],
-  "sideEffects": false,
-  "peerDependenciesMeta": {
-    "react-native": {
-      "optional": true
-    },
-    "vue": {
-      "optional": true
-    }
-  }
-}
+{
+  "name": "machinalayout",
+  "version": "0.3.0",
+  "type": "module",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "npm run typecheck && tsup --config tsup.config.ts --tsconfig tsconfig.build.json",
+    "test": "vitest run",
+    "format": "biome format --write .",
+    "format:check": "biome format .",
+    "lint": "biome lint .",
+    "check": "biome check ."
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.15",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@types/react-test-renderer": "^19.1.0",
+    "@vue/test-utils": "^2.4.6",
+    "jsdom": "^29.1.1",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "react-native": "^0.82.0",
+    "react-test-renderer": "^19.2.6",
+    "tsup": "^8.5.1",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8",
+    "vue": "^3.5.22"
+  },
+  "peerDependencies": {
+    "react": ">=18 <20",
+    "react-dom": ">=18 <20",
+    "react-native": ">=0.72 <1",
+    "vue": ">=3.4 <4"
+  },
+  "description": "Machine-native layout and text primitives for deterministic app UI records.",
+  "license": "MIT",
+  "author": "MachinaLayout contributors",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/machinalayout/MachinaLayout.JS.git"
+  },
+  "homepage": "https://github.com/machinalayout/MachinaLayout.JS#readme",
+  "bugs": {
+    "url": "https://github.com/machinalayout/MachinaLayout.JS/issues"
+  },
+  "keywords": [
+    "layout",
+    "ui",
+    "react",
+    "typescript",
+    "machina",
+    "text",
+    "rectangles"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./inspect": {
+      "types": "./dist/inspect/index.d.ts",
+      "import": "./dist/inspect/index.js"
+    },
+    "./handoff": {
+      "types": "./dist/handoff/index.d.ts",
+      "import": "./dist/handoff/index.js"
+    },
+    "./deus": {
+      "types": "./dist/deus/index.d.ts",
+      "import": "./dist/deus/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js"
+    },
+    "./text": {
+      "types": "./dist/text/index.d.ts",
+      "import": "./dist/text/index.js"
+    },
+    "./text/react": {
+      "types": "./dist/text/react/index.d.ts",
+      "import": "./dist/text/react/index.js"
+    },
+    "./package.json": "./package.json",
+    "./react-native": {
+      "types": "./dist/react-native/index.d.ts",
+      "import": "./dist/react-native/index.js"
+    },
+    "./vue": {
+      "types": "./dist/vue/index.d.ts",
+      "import": "./dist/vue/index.js"
+    },
+    "./text/react-native": {
+      "types": "./dist/text/react-native/index.d.ts",
+      "import": "./dist/text/react-native/index.js"
+    },
+    "./text/vue": {
+      "types": "./dist/text/vue/index.d.ts",
+      "import": "./dist/text/vue/index.js"
+    },
+    "./dispatch": {
+      "types": "./dist/dispatch/index.d.ts",
+      "import": "./dist/dispatch/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "docs"
+  ],
+  "sideEffects": false,
+  "peerDependenciesMeta": {
+    "react-native": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  }
+}