machinalayout 0.1.0 → 0.3.0

package/docs/reference-alignment.md

@@ -0,0 +1,44 @@
+# Reference alignment (M7b runtime)
+
+`GuideFrame` provides narrow reference-based placement without changing parent ownership.
+
+- **Parent owns coordinates**.
+- **Reference target is read-only geometry input**.
+
+## GuideFrame
+- Two-of-three per axis (`left/right/width`, `top/bottom/height`).
+- `width`/`height` are `UiLength` only.
+- `left/right/top/bottom` can be `UiLength` or `EdgeRef`.
+
+## Edge refs
+- Horizontal fields allow `left/right/centerX`.
+- Vertical fields allow `top/bottom/centerY`.
+- Max one reference per axis.
+
+## Coordinate semantics
+- Ui lengths resolve against parent axis.
+- Ui positional values convert to root-space with parent origin.
+- Edge refs read target resolved rect edge in root-space.
+- Edge ref offset resolves against referencing parent axis.
+- Node `offset` applies after guide placement.
+
+## Dependency model
+- Non-guide nodes resolve first.
+- Guide nodes are queued until parent + all referenced targets are resolved.
+- Remaining unresolved guides classify as `GuideReferenceCycle` or `GuideTargetUnresolved`.
+
+## Errors
+`GuideTargetNotFound`, `GuideSelfReference`, `GuideReferenceCycle`, `GuideInvalidEdgeForAxis`, `GuideTooManyReferencesPerAxis`, `InvalidGuideFrame`, `GuideTargetUnresolved`.
+
+## Examples
+- Start after inspector edge (`left: { ref: "inspector", edge: "right", offset: 8 }`).
+- Tooltip below button (`top: { ref: "button", edge: "bottom", offset: 6 }`).
+- Badge at card corner (`left` from `card.right`, `top` from `card.top`).
+- Responsive variant swaps anchor to guide frame.
+
+## Limitations
+- No refs in `AnchorFrame`.
+- No `AttachFrame`.
+- No portals/reparenting or clipping escape.
+- No general solver.
+- No width/height refs.

package/docs/responsive-variants.md

@@ -0,0 +1,54 @@
+# Responsive variants (M4b)
+
+Responsive variants let a single flat `LayoutRow[]` express row-local overrides selected by `rootRect` dimensions.
+
+## Purpose
+
+- Keep responsive behavior explicit and deterministic.
+- Keep selection resolver-owned and driven only by caller-provided root geometry.
+- Avoid userland row-array branching for common desktop/tablet/mobile style differences.
+
+## Authoring model
+
+Add `variants` to a `LayoutRow`. Each variant has a `when` condition plus optional override fields.
+
+```ts
+{
+  id: "sidebar",
+  parent: "root",
+  frame: { kind: "anchor", left: 0, top: 64, bottom: 0, width: 280 },
+  variants: [
+    {
+      when: { maxWidth: 800 },
+      frame: { kind: "anchor", left: 0, right: 0, top: 64, height: 56 },
+      slot: "mobileNav",
+    },
+    {
+      when: {},
+      slot: "desktopSidebar",
+    },
+  ],
+}
+```
+
+## Selection semantics
+
+- `resolveLayoutRows(rows, rootRect)` calls `selectLayoutRowsForRoot(rows, rootRect)` first.
+- Conditions are inclusive (`>= min*`, `<= max*`).
+- First matching variant wins.
+- `when: {}` matches all root rects and can be used as a fallback.
+- Effective rows are fresh copies and do not include `variants`.
+
+## Phase separation
+
+- `compileLayoutRows(rows)` directly uses base row values only.
+- Variants are an authoring-time input feature, not part of compiled or resolved node types.
+
+## Constraints and non-goals
+
+M4b variants can override row metadata (`frame`, `arrange`, `offset`, `z`, `view`, `slot`, `debugLabel`) but cannot:
+
+- change graph identity (`id`, `parent`, `order`),
+- add/remove rows,
+- use DOM measurement,
+- use CSS media query semantics.

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/docs/vue-adapter.md

@@ -0,0 +1,55 @@
+# Vue adapter (`machinalayout/vue`)
+
+`MachinaVueView` renders a `ResolvedLayoutDocument` into DOM wrappers plus Vue view components.
+
+- Import path: `import { MachinaVueView } from "machinalayout/vue";`
+- Peer dependency: `vue` (`>=3.4 <4`).
+- Machina layout stays record-shaped (`LayoutRow[]` -> resolved rectangles) across frameworks.
+
+## Shared model boundary
+
+MachinaVueView uses Vue render functions internally so application code can stay record-shaped: layout rows describe geometry, and Vue components render inside the resolved rectangles.
+
+You do not need to write `h()` calls, template layout loops, or directive ceremony to place boxes. Users can keep normal Vue SFC/template authoring for component internals, reactivity, and lifecycle.
+
+## Basic usage
+
+```vue
+<script setup lang="ts">
+import { MachinaVueView } from "machinalayout/vue";
+
+const views = { Panel };
+</script>
+
+<template>
+  <MachinaVueView :layout="layout" :views="views" :view-data="viewData" :node-data="nodeData" />
+</template>
+```
+
+## Stable view registry and data channels
+
+Keep stable component references in `views`. Pass reactive/computed dynamic values through `viewData` and `nodeData`.
+
+Avoid rebuilding component definitions as data carriers.
+
+## Props note
+
+To avoid conflicts with Vue fallthrough attrs, root/node styling props are:
+
+- `rootClass`, `rootStyle`
+- `nodeClass`, `nodeStyle`
+
+## Supported
+
+- `view ?? slot` lookup
+- `viewData` / `nodeData`
+- layer/z sorting (`layer z`, then `node z`, then sibling order)
+- DOM containment/content-visibility policy
+- debug mode
+- parent-local coordinate normalization
+
+## Not included
+
+- this package only renders layout boxes; text rendering is provided separately by `machinalayout/text/vue`
+- portals/reparenting
+- router/state abstraction layers

package/docs/vue-text-renderer.md

@@ -0,0 +1,55 @@
+# Vue MachinaText renderer
+
+`MachinaVueTextView` renders MachinaText content into DOM elements inside an already-owned rectangle.
+
+## Import
+
+```ts
+import { MachinaVueTextView } from "machinalayout/text/vue";
+```
+
+## Peer dependency
+
+- `vue` (Vue 3)
+
+## Accepted `text` inputs
+
+- `string`
+- `MachinaTextSource`
+- `MachinaTextSpec`
+- `MachinaTextDocument`
+
+## Supported rendering
+
+- paragraphs (`p`)
+- bullet lists (`ul`/`li`)
+- inline strong/emphasis/code/link
+
+## Policy support
+
+- `variant`
+- `wrap`
+- `overflow`
+- `align`
+- `leading`
+- `blockGap`
+- `listGap`
+- `valign`
+
+## Notes
+
+- Uses Vue `h()` internally so app code does not need render-function loops for the text AST.
+- Supports `rootClass`/`rootStyle` plus `linkClass`/`linkStyle` and `codeClass`/`codeStyle` hooks.
+- Link handling uses `onLinkClick` only (no routing dispatch integration).
+
+## Difference from React DOM text renderer
+
+- Vue component API (`rootClass`/`rootStyle`) instead of React `className`/`style` prop names.
+- Same parser/document model and text policy behavior.
+
+## Non-goals
+
+- text measurement
+- intrinsic sizing
+- routing behavior
+- editor/caret/selection behavior

package/package.json

@@ -1,60 +1,127 @@
-{
-  "name": "machinalayout",
-  "version": "0.1.0",
-  "type": "module",
-  "scripts": {
-    "typecheck": "tsc --noEmit",
-    "build": "npm run typecheck && tsup --config tsup.config.ts --tsconfig tsconfig.build.json",
-    "test": "vitest run"
-  },
-  "devDependencies": {
-    "@testing-library/jest-dom": "^6.9.1",
-    "@testing-library/react": "^16.3.2",
-    "@types/react": "^19.2.14",
-    "@types/react-dom": "^19.2.3",
-    "jsdom": "^29.1.1",
-    "typescript": "^5.6.3",
-    "vitest": "^2.1.8",
-    "tsup": "^8.5.1"
-  },
-  "peerDependencies": {
-    "react": ">=18 <20",
-    "react-dom": ">=18 <20"
-  },
-  "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"
-    }
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE",
-    "docs"
-  ],
-  "sideEffects": false
-}
+{
+  "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
+    }
+  }
+}