machinalayout 0.2.0 → 0.3.1

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

@@ -53,3 +53,7 @@ To avoid conflicts with Vue fallthrough attrs, root/node styling props are:
 - this package only renders layout boxes; text rendering is provided separately by `machinalayout/text/vue`
 - portals/reparenting
 - router/state abstraction layers
+
+## DeusMachina composable
+
+`machinalayout/vue` exports `useDeusMachine(machine, initialBoard)`. The composable returns `snapshot` and `lastTrace` refs, computed `board` and `state`, plus `dispatch` and `reset`. It wraps `createDeusSnapshot` and `stepDeusMachine`; board mutations are visible through `debug.board.value` because dispatch assigns a new snapshot object. Keep the machine input stable.

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.1",
+  "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
+    }
+  }
+}