machinalayout 0.1.0

package/docs/npm-prepublish-m2z-audit.md

@@ -0,0 +1,233 @@
+# MachinaLayout M2z npm prepublish readiness audit
+
+Date: 2026-05-02 (UTC)
+Scope: prepublish readiness for a future `0.1.0` npm publish (audit only, no publish action).
+
+## 1) Executive summary
+
+Current repo state is **not publish-ready** for npm consumers. The biggest blockers are:
+
+1. Root package is marked `"private": true` and has no runtime entrypoint metadata (`main`/`exports`/`types`), while README demonstrates package consumption by name.
+2. Build script is typecheck-only (`tsc --noEmit`), so there is no emitted JS or declaration output for consumers.
+3. Tarball currently includes raw source/tests/sample/docs and excludes any built dist folder (none exists).
+4. Consumer smoke test via packed tarball fails to resolve `machinalayout` module/types.
+
+No feature/API behavior changes were made in this pass.
+
+## 2) Current package metadata status
+
+Observed in root `package.json`:
+
+- `name`: `machinalayout`
+- `version`: `0.1.0`
+- `private`: `true`
+- `type`: `module`
+- Missing: `description`, `license` field, `author`, `repository`, `homepage`, `bugs`, `keywords`, `main`, `module`, `types`, `exports`, `files`, `sideEffects`, `dependencies`
+- Present scripts: `build`, `test`
+- `peerDependencies`: `react`, `react-dom`
+- `devDependencies`: test/build tooling only (TypeScript, Vitest, jsdom, testing-library, React type packages)
+
+Assessment:
+
+- Package name appears npm-compatible syntactically (unscoped), but final naming strategy is unresolved from metadata alone.
+- Package is currently **unscoped**.
+- Version `0.1.0` is consistent with first publish intent, but `private: true` currently blocks publish.
+- React/ReactDOM are correctly peer dependencies, not runtime dependencies.
+- Tooling is correctly in devDependencies.
+- Export surface metadata is not declared at package boundary (no `exports`/`main`/`types`).
+- README/docs are currently included by default due no restrictive `files` list.
+- Sample is also included by default and should likely be excluded for library publish unless intentionally bundled.
+
+## 3) Build output status
+
+Command run: `npm run build`
+
+Result: pass, but script is `tsc --noEmit` (typecheck only).
+
+Implications:
+
+- No compiled JS output emitted.
+- No `.d.ts` output emitted.
+- No source maps emitted.
+- No ESM/CJS build artifacts produced.
+- Therefore output cannot match package runtime entrypoints (none configured).
+- React/text modules exist in source, but not in emitted build artifacts.
+
+## 4) Public exports/API surface status
+
+`src/index.ts` re-exports core modules (`types`, `errors`, validation/padding/length/offset helpers, compile/resolve functions, resolved tree helpers), plus `./react` and `./text`.
+
+Findings:
+
+- Major APIs appear reachable from root source barrel in-repo.
+- React exports are intentionally included via `export * from "./react"`.
+- Text parser/types and React text view are intentionally included via `export * from "./text"` and nested text/react barrel.
+- No obvious accidental internal export from top-level barrel based on current file list.
+- Before publish, explicit package `exports` map (root + optional subpaths) is recommended for stability.
+
+## 5) Type declaration status
+
+Post-build status: **no declarations emitted** because build uses `--noEmit`.
+
+- `types` field is absent in `package.json`.
+- `.d.ts` distribution is absent.
+- This is a **publish blocker**.
+
+## 6) React peer dependency status
+
+Root package uses:
+
+- `peerDependencies.react: ^19.2.5`
+- `peerDependencies.react-dom: ^19.2.5`
+
+Assessment:
+
+- Correct placement as peer deps for adapter components.
+- No runtime `dependencies` are declared.
+- Consider whether peer range should be broadened for ecosystem compatibility in M3.
+
+## 7) Package contents / `npm pack --dry-run` status
+
+Command run: `npm pack --dry-run`
+
+Result:
+
+- Tarball name: `machinalayout-0.1.0.tgz`
+- Package size: 57.1 kB
+- Unpacked size: 247.2 kB
+- Total files: 67
+
+Included content highlights:
+
+- `src/**` TypeScript sources
+- `test/**` test sources
+- `samples/control-room/**` including its `package-lock.json`
+- `docs/**`
+- `README.md`, `LICENSE`, `tsconfig.json`
+
+Not included: no `dist/**` output (none exists).
+
+Assessment:
+
+- Current pack contents look like a source repository bundle, not a focused library distribution.
+- Inclusion of tests and sample app is likely unintentional for npm consumers unless explicitly desired.
+- README and LICENSE are present (good).
+
+## 8) README/docs publish-readiness status
+
+README currently:
+
+- Uses install/import examples with package name `machinalayout`.
+- Demonstrates `resolveLayoutRows`, `LayoutRow`, `MachinaReactView` usage.
+- Mentions sample run instructions (`cd samples/control-room`, `npm install`, `npm run dev`).
+- Explicitly states boundaries like no intrinsic sizing / no CSS layout authority.
+
+Assessment:
+
+- API narrative is mostly aligned with current source exports.
+- Install instructions will remain provisional until package metadata/export strategy is finalized.
+- No obvious critical stale claims found during this pass.
+
+## 9) Sample package status
+
+Command run in sample: `cd samples/control-room && npm run build`
+
+Result: pass.
+
+Sample dependency model:
+
+- `machinalayout` is consumed via local file dependency: `"file:../.."`.
+
+Assessment:
+
+- Sample is wired to root workspace package path, useful for local integration.
+- Sample should likely be excluded from root publish tarball unless intentional.
+
+## 10) Consumer smoke-test status
+
+Method used:
+
+1. Created real tarball via `npm pack`.
+2. Created temporary external consumer at `/tmp/machina-consumer-smoke/consumer`.
+3. Installed tarball + minimal deps.
+4. Created `smoke.ts` importing:
+   - `resolveLayoutRows`
+   - `RootFrame` type
+   - `MachinaReactView`
+   - `parseMachinaText`
+   - `MachinaTextView`
+5. Ran TypeScript compile check.
+
+Result: **fail**.
+
+Error:
+
+- `TS2307: Cannot find module 'machinalayout' or its corresponding type declarations.`
+
+Interpretation:
+
+- Packed package is not consumable as a normal npm dependency due missing entrypoint/type declarations.
+
+## 11) Risks/blockers before 0.1.0
+
+Blockers:
+
+1. `private: true` in root package metadata.
+2. Missing entrypoint metadata (`main`/`exports`/`types`).
+3. No emitted build artifacts (JS/d.ts).
+4. Consumer smoke test fails module/type resolution.
+
+Risks (non-blocker but important):
+
+1. Over-inclusive tarball (tests/samples/docs/source-only) may confuse consumers and bloat installs.
+2. Missing discoverability metadata (`description`, repository/homepage/bugs/keywords).
+3. No explicit `sideEffects` declaration; tree-shaking semantics are implicit.
+
+## 12) Recommended M3 cleanup checklist
+
+### Package metadata
+
+- [ ] Decide final npm name strategy (keep unscoped `machinalayout` or scope it).
+- [ ] Remove/adjust `private` for publish pipeline.
+- [ ] Add `description`, `license` field, `author`, `repository`, `homepage`, `bugs`, `keywords`.
+- [ ] Add explicit runtime/type entrypoints: `main`/`module` (if dual), `types`, and `exports` map.
+- [ ] Add `sideEffects` policy.
+
+### Build/distribution
+
+- [ ] Add actual emit build (e.g., dist JS + d.ts, optional sourcemaps).
+- [ ] Ensure build output paths align with package entrypoints.
+- [ ] Confirm React/text modules are included in emitted artifacts.
+
+### Packaging contents
+
+- [ ] Add `files` allowlist (or `.npmignore`) to publish intended artifacts only.
+- [ ] Exclude tests/sample sources and lockfiles from library tarball unless intentionally shipped.
+- [ ] Re-run `npm pack --dry-run` and validate final file list.
+
+### Consumer validation
+
+- [ ] Re-run tarball-based smoke test after metadata/build fixes.
+- [ ] Add a lightweight CI smoke-check that installs packed tarball and typechecks imports.
+
+### Docs/readiness
+
+- [ ] Update README install command once final package name/scope is confirmed.
+- [ ] Ensure docs state publish support level and adapter peer dependency expectations.
+
+## 13) Exact commands run and results
+
+1. `npm test` → **pass** (17 files, 170 tests). Observed benign environment stderr in jsdom test: "Not implemented: navigation to another Document".
+2. `npm run build` → **pass** as typecheck-only (`tsc --noEmit`), no distributable output.
+3. `cd samples/control-room && npm run build` → **pass** (`tsc -b && vite build`).
+4. `npm pack --dry-run` → **pass**, tarball preview generated with 67 files, includes src/test/sample/docs.
+5. Consumer smoke sequence using `npm pack` + external temp project + `npx tsc smoke.ts ...` → **fail** with TS2307 unable to resolve `machinalayout` module/types.
+
+---
+
+Non-goal compliance check:
+
+- No `npm publish` run.
+- No release tags created.
+- No version bumps performed.
+- No runtime/layout/text feature changes performed.

package/docs/npm-prepublish-m3c-cleanup.md

@@ -0,0 +1,105 @@
+# MachinaLayout M3c npm packaging cleanup
+
+Date: 2026-05-02 (UTC)
+Scope: packaging/distribution readiness for future npm `0.1.0` publish (no publish action performed).
+
+## 1) What changed
+
+- Replaced typecheck-only build with a real package build that emits ESM JavaScript and declarations under `dist/`.
+- Added `tsup` build configuration for `src/index.ts` with externalized React dependencies.
+- Added root package entrypoint metadata (`main`, `module`, `types`, `exports`) and a `files` allowlist.
+- Removed `private: true` from root package to unblock publish readiness.
+- Broadened React peer dependency ranges to `>=18 <20`.
+- Added npm install guidance to README.
+- Verified package contents with `npm pack --dry-run`.
+- Verified packed tarball consumer typecheck in an external temporary consumer project.
+
+## 2) Package metadata decisions
+
+- Package name kept as `machinalayout`.
+- Version kept as `0.1.0`.
+- Kept ESM-only distribution for this pass (`type: module`, ESM `dist/index.js`).
+- Added:
+  - `description`, `license`, `author`, `repository`, `homepage`, `bugs`, `keywords`
+  - `main`, `module`, `types`, `exports`
+  - `files` allowlist
+  - `sideEffects: false`
+- React and ReactDOM remain peer dependencies and are not bundled.
+
+## 3) Build output shape
+
+`npm run build` now does:
+
+1. `npm run typecheck` (`tsc --noEmit`)
+2. `tsup --config tsup.config.ts --tsconfig tsconfig.build.json`
+
+Expected emitted artifacts:
+
+- `dist/index.js`
+- `dist/index.d.ts`
+
+## 4) Package exports shape
+
+Root package exports are configured as:
+
+- `exports["."].import -> ./dist/index.js`
+- `exports["."].types -> ./dist/index.d.ts`
+
+No subpath exports were introduced in this pass.
+
+## 5) Files/tarball contents
+
+`npm pack --dry-run` now shows a focused tarball containing:
+
+- `dist/**`
+- `README.md`
+- `LICENSE`
+- `docs/**`
+- `package.json`
+
+Observed exclusions (desired):
+
+- `src/**` excluded
+- `test/**` excluded
+- `samples/**` excluded
+
+Dry-run snapshot:
+
+- package size: `28.2 kB`
+- unpacked size: `93.5 kB`
+- total files: `15`
+
+No unexpected runtime payloads were observed.
+
+## 6) Consumer smoke result
+
+Smoke validation used a real packed tarball installed into `/tmp/machina-m3c-smoke` and compiled a TypeScript file importing:
+
+- `resolveLayoutRows`
+- `RootFrame` (type)
+- `MachinaReactView`
+- `parseMachinaText`
+- `MachinaTextView`
+
+TypeScript compile succeeded with no module/type resolution errors.
+
+## 7) Remaining manual publish steps (not executed here)
+
+1. Confirm npm auth:
+   - `npm whoami`
+2. Login if needed:
+   - `npm login`
+3. Optional name availability check:
+   - `npm view machinalayout`
+4. Final packaging check:
+   - `npm pack --dry-run`
+5. Publish:
+   - `npm publish --access public`
+   - Note: for unscoped packages, npm may not require/accept `--access public`; retry without flag if npm rejects it.
+6. Validate org policy for npm 2FA/token/trusted publishing.
+
+## 8) Remaining risks before npm publish
+
+- Repository/homepage/bugs URLs should be confirmed against the canonical upstream repository if different from current metadata.
+- No CJS build is included (intentional for this ESM-first pass); consumers requiring CJS will need transpilation/interoperability handling.
+- Moderate security advisories remain in current dev dependency graph (non-blocking for packaging outcome, but worth auditing).

package/docs/react-adapter.md

@@ -0,0 +1,110 @@
+# React Adapter
+
+## Boundary
+
+- Core layout resolution has no React dependency.
+- The React adapter consumes a `ResolvedLayoutDocument`.
+- The adapter renders absolutely positioned wrappers.
+- Slot components render inside those wrappers.
+
+## Basic usage
+
+```tsx
+import { MachinaReactView, resolveLayoutRows } from "machinalayout";
+
+const resolved = resolveLayoutRows(rows, rootRect);
+
+const views = {
+  header: HeaderView,
+  sidebar: SidebarView,
+  toolbarButton: ToolbarButtonView,
+};
+
+<MachinaReactView layout={resolved} views={views} />;
+```
+
+## Slot props
+
+Slot views receive:
+
+- `id`
+- `rect`
+- `debugLabel`
+- `node`
+
+## Coordinate normalization
+
+Core resolved rects are global/root-space coordinates.
+
+The React adapter renders nested absolutely positioned DOM wrappers, so each node
+wrapper is positioned in its parent-local DOM coordinate space:
+
+- `left = node.rect.x - parent.rect.x`
+- `top = node.rect.y - parent.rect.y`
+
+The outer wrapper represents the root coordinate space and uses the resolved root
+width/height. The root node itself renders at local `left: 0` and `top: 0`.
+
+Examples:
+
+- root rect `{ x: 100, y: 200, width: 800, height: 600 }`
+- child rect `{ x: 116, y: 212, width: 100, height: 50 }`
+- rendered child CSS `left: 16px; top: 12px;`
+
+Nested example:
+
+- parent rect `{ x: 268, y: 88, width: 816, height: 616 }`
+- child rect `{ x: 284, y: 104, width: 784, height: 48 }`
+- rendered child CSS `left: 16px; top: 16px;`
+
+## CSS boundary
+
+Allowed for Machina wrappers:
+
+- position (`relative`/`absolute`)
+- `left` / `top` / `width` / `height`
+- `box-sizing`
+- `z-index`
+- containment/content-visibility
+- cosmetic/debug styles
+
+Not allowed as Machina geometry authority:
+
+- flexbox
+- grid
+- margins
+- transforms
+- DOM measurement
+- CSS classes determining geometry
+
+Slot internals may use normal React/CSS/shadcn-style components. Machina controls only the outer rectangle.
+
+## Stable view registry and data channels
+
+`views` should be a stable registry of component types, not inline factories recreated from state.
+
+Bad (new component identity each render):
+
+```tsx
+const views = {
+  Inspector: () => <Inspector sidebarLeft={sidebarLeft} />,
+};
+```
+
+Good (stable component type + dynamic data):
+
+```tsx
+const views = { Inspector };
+
+<MachinaReactView
+  layout={resolved}
+  views={views}
+  viewData={{ Inspector: { sidebarLeft } }}
+/>
+```
+
+Use adapter data channels for changing values:
+
+- `viewData`: keyed by effective `view ?? slot` key.
+- `nodeData`: keyed by concrete node id.
+- slot props include `viewKey`, `viewData`, and `nodeData`.

package/docs/row-model.md

@@ -0,0 +1,82 @@
+# Row Model
+
+`LayoutRow[]` is the canonical authoring model.
+
+## Why rows
+
+Rows are:
+
+- easy to read,
+- easy to diff,
+- easy to patch,
+- easy to serialize,
+- easy for humans and LLMs,
+- naturally table/record-shaped.
+
+> Nesting is an output shape, not an authoring strategy.
+
+## Row fields
+
+- `id`: stable node identifier.
+- `parent`: parent node id (omit only for root).
+- `order`: sibling order key.
+- `frame`: geometry primitive (`absolute`, `anchor`, `fixed`).
+- `arrange`: optional arrangement strategy (currently `stack`).
+- `slot`: renderer view key.
+- `debugLabel`: optional debug-facing label.
+- `z`: optional sibling-local paint layer metadata.
+
+## Parent-child meaning
+
+Parent-child means only:
+
+- resolve this child rectangle in the parent coordinate space.
+
+It does **not** imply:
+
+- component ownership,
+- state ownership,
+- event ownership,
+- routing hierarchy,
+- semantic DOM hierarchy,
+- styling inheritance.
+
+## Deterministic sibling order
+
+Siblings are ordered by:
+
+1. `order ?? 0`
+2. original row index (tie-break)
+
+This keeps compile and resolve deterministic.
+
+## Compile validation guarantees
+
+`compileLayoutRows` rejects invalid row graphs:
+
+- exactly one root required,
+- duplicate ids rejected,
+- unknown parents rejected,
+- cycles rejected,
+- invalid `z` rejected.
+
+## Compact row table example
+
+| id               | parent  | order | frame                                | arrange | slot          | z |
+|------------------|---------|-------|--------------------------------------|---------|---------------|---|
+| root             | —       | 0     | absolute `{x:0,y:0,w:1024,h:640}`   | —       | —             | — |
+| header           | root    | 0     | anchor `{left:0,right:0,top:0,h:64}`| —       | `header`      | 0 |
+| sidebar          | root    | 1     | anchor `{left:0,top:64,bottom:0,w:240}` | —   | `sidebar`     | 0 |
+| toolbar          | root    | 2     | anchor `{left:240,right:0,top:64,h:56}` | stack | —             | 0 |
+| toolbar-button-1 | toolbar | 0     | fixed `{w:120,h:40}`                | —       | `toolbarButton` | 0 |
+
+- `offset`: optional post-placement local translation (`OffsetSpec` using `UiLength`), not margin and does not affect siblings.
+
+
+## Root row frame guidance (M3a)
+
+Use `RootFrame` on the root row. Root geometry is sourced from caller `rootRect`, not from row frame numbers.
+
+- Root `FillFrame` is invalid (`FillFrameWithoutArranger`).
+- Root `FixedFrame` is invalid (`FixedFrameWithoutArranger`).
+- Root `AbsoluteFrame` and `AnchorFrame` remain accepted for compatibility, but `RootFrame` is preferred.

package/docs/z-order-and-containment.md

@@ -0,0 +1,38 @@
+# Z-order and Containment
+
+## Z-order
+
+- `z?: number` is node metadata.
+- Explicit `z` must be an integer in `-5..5`.
+- Omitted `z` defaults to effective `0`.
+- `z` is sibling-local.
+- Higher `z` paints in front.
+- Same `z` uses sibling order as tie-break.
+- `z` does not affect geometry.
+- `z` does not affect stack placement.
+- `z` does not reorder compiled/resolved/tree children.
+- React adapter sorts sibling render order by effective `z` for paint only.
+
+Rationale: if a UI needs more than eleven sibling-local paint layers, the layout structure should be reconsidered.
+
+## Containment policy
+
+Containment is adapter policy, not core layout semantics.
+
+React adapter props:
+
+- `nodeContainment?: "none" | "layout-paint" | "strict"`
+- `nodeContentVisibility?: "none" | "auto"`
+- `nodeContainIntrinsicSize?: string`
+
+Defaults:
+
+- `nodeContainment = "layout-paint"`
+- `nodeContentVisibility = "none"`
+
+Guidance:
+
+- `layout-paint` is the default safe performance posture.
+- `strict` is stronger and opt-in.
+- `content-visibility: auto` is powerful for large/offscreen content but opt-in.
+- `contain-intrinsic-size` can be supplied when using content visibility.

package/package.json

@@ -0,0 +1,60 @@
+{
+  "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
+}