machinalayout 0.1.0 → 0.2.0

package/dist/vue/index.js

@@ -0,0 +1,111 @@
+import {
+  toResolvedTree
+} from "../chunk-TR24ERZT.js";
+
+// src/vue/MachinaVueView.ts
+import { computed, 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);
+var MachinaVueView = defineComponent({
+  name: "MachinaVueView",
+  props: {
+    layout: { type: Object, required: true },
+    views: { type: Object, default: () => ({}) },
+    viewData: { type: Object, default: () => ({}) },
+    nodeData: { type: Object, default: () => ({}) },
+    layers: {
+      type: Object,
+      default: () => ({ base: { z: 0 } })
+    },
+    defaultLayer: { type: String, default: "base" },
+    debug: { type: Boolean, default: false },
+    rootClass: { type: null, default: void 0 },
+    rootStyle: { type: null, default: void 0 },
+    nodeClass: { type: null, default: void 0 },
+    nodeStyle: { type: null, default: void 0 },
+    nodeContainment: {
+      type: String,
+      default: "layout-paint"
+    },
+    nodeContentVisibility: { type: String, default: "none" },
+    nodeContainIntrinsicSize: { type: String, default: void 0 }
+  },
+  setup(props) {
+    const tree = computed(() => toResolvedTree(props.layout));
+    const renderNode = (node, parentRect) => {
+      const viewKey = node.view ?? node.slot;
+      const View = viewKey ? props.views[viewKey] : void 0;
+      const left = node.rect.x - parentRect.x;
+      const top = node.rect.y - parentRect.y;
+      const layer = getEffectiveLayer(node, props.defaultLayer);
+      const layerZ = getEffectiveLayerZ(node, props.layers, props.defaultLayer);
+      const baseStyle = {
+        position: "absolute",
+        left: `${left}px`,
+        top: `${top}px`,
+        width: `${node.rect.width}px`,
+        height: `${node.rect.height}px`,
+        boxSizing: "border-box",
+        zIndex: `${layerZ * 100 + (node.z ?? 0)}`,
+        ...props.nodeContainment === "layout-paint" ? { contain: "layout paint" } : null,
+        ...props.nodeContainment === "strict" ? { contain: "strict" } : null,
+        ...props.nodeContentVisibility === "auto" ? { contentVisibility: "auto" } : null,
+        ...props.nodeContainIntrinsicSize !== void 0 ? { containIntrinsicSize: props.nodeContainIntrinsicSize } : null,
+        ...props.debug ? { outline: "1px dashed rgba(59, 130, 246, 0.9)" } : null
+      };
+      const rendered = View && props.layout.nodes[node.id] ? h(View, {
+        id: node.id,
+        rect: { ...node.rect },
+        debugLabel: node.debugLabel,
+        node: {
+          ...props.layout.nodes[node.id],
+          rect: { ...props.layout.nodes[node.id].rect }
+        },
+        viewKey,
+        viewData: viewKey ? props.viewData[viewKey] : void 0,
+        nodeData: props.nodeData[node.id]
+      }) : null;
+      const kids = [...node.children].map((child, index) => ({ child, index })).sort(
+        (a, b) => getEffectiveLayerZ(a.child, props.layers, props.defaultLayer) - getEffectiveLayerZ(b.child, props.layers, props.defaultLayer) || (a.child.z ?? 0) - (b.child.z ?? 0) || a.index - b.index
+      ).map(({ child }) => renderNode(child, node.rect));
+      return h(
+        "div",
+        {
+          key: node.id,
+          class: props.nodeClass,
+          style: [baseStyle, props.nodeStyle],
+          "data-machina-node-id": node.id,
+          "data-machina-slot": node.slot,
+          "data-machina-view": viewKey,
+          "data-machina-debug-label": node.debugLabel,
+          "data-machina-layer": layer
+        },
+        [props.debug ? h("small", {}, node.debugLabel ?? node.id) : null, rendered, ...kids]
+      );
+    };
+    return () => {
+      const root = tree.value;
+      return h(
+        "div",
+        {
+          class: props.rootClass,
+          style: [
+            {
+              position: "relative",
+              width: `${root.rect.width}px`,
+              height: `${root.rect.height}px`,
+              boxSizing: "border-box"
+            },
+            props.rootStyle
+          ],
+          "data-machina-root-id": root.id
+        },
+        [renderNode(root, root.rect)]
+      );
+    };
+  }
+});
+export {
+  MachinaVueView
+};

package/docs/adapter-packaging-a0-plan.md

@@ -0,0 +1,352 @@
+# Adapter Packaging A0 Plan
+
+## 1) Executive summary
+
+MachinaLayout should stay as a **single npm package during `0.x`**, but move toward a **subpath-exported adapter model** so new adapters do not impose framework installs on every user.
+
+Recommended direction:
+
+- Keep `machinalayout` root import stable for compatibility during `0.x`.
+- Add framework-specific adapter entrypoints as subpaths (`machinalayout/react`, `machinalayout/text/react`, future `machinalayout/react-native`, `machinalayout/vue`, etc.).
+- Treat new framework peers (`react-native`, `vue`) as **optional peers** when their adapters are added.
+- Keep runtime/package behavior unchanged in A0; implement packaging/build updates as A1 prerequisites.
+
+## 2) Current package/export state (observed)
+
+### Package/build
+
+- Package name is `machinalayout`, version `0.1.0`, ESM package type.
+- Build command uses `tsup` with a **single entry**: `src/index.ts`.
+- Current output is a **single dist entrypoint**:
+  - `dist/index.js`
+  - `dist/index.d.ts`
+- `exports` currently expose only `"."`.
+
+### Peer dependencies
+
+- Current peers are:
+  - `react` (`>=18 <20`)
+  - `react-dom` (`>=18 <20`)
+- No optional peer metadata yet.
+
+### Public exports and source layout
+
+- `src/index.ts` re-exports core, React adapter (`./react`), and text module (`./text`).
+- React adapter exists under `src/react`.
+- Text parser/types and React text renderer exist under `src/text` and `src/text/react`.
+- README examples/documentation currently import React adapter from root (`machinalayout`).
+
+### Packaging snapshot
+
+- `npm pack --dry-run` currently includes `dist` (single bundle), README, LICENSE, and docs.
+- No subpath build artifacts are currently emitted.
+
+## 3) Recommended package strategy
+
+### Evaluated options
+
+#### A. Single package + subpath exports (recommended for now)
+
+Pros:
+
+- Minimal project/process overhead while API is still evolving.
+- Keeps install/discovery simple for early adopters.
+- Preserves existing import compatibility.
+
+Cons:
+
+- `exports`/build matrix becomes more complex.
+- Peer policy must clearly separate required vs optional framework peers.
+
+#### B. Separate packages (`@machina/*`) later
+
+Pros:
+
+- Clean dependency isolation per framework.
+- Natural long-term scaling for adapters.
+
+Cons:
+
+- Multi-package release/publishing overhead now.
+- More migration friction before APIs settle.
+
+### Decision
+
+For `0.x`, use **single package + subpath exports**. Reassess split packages after adapter APIs stabilize and usage justifies monorepo/package split effort.
+
+## 4) Proposed subpath export map
+
+Target import shapes:
+
+```ts
+import { resolveLayoutRows } from "machinalayout";
+import { MachinaReactView } from "machinalayout/react";
+import { parseMachinaText } from "machinalayout/text";
+import { MachinaTextView } from "machinalayout/text/react";
+import { MachinaReactNativeView } from "machinalayout/react-native";
+import { MachinaVueView } from "machinalayout/vue";
+```
+
+Export policy:
+
+- **Keep root exports unchanged during `0.x`** for compatibility.
+- Introduce and document subpath exports as preferred for adapters.
+- New adapters (`react-native`, `vue`, future) should be **subpath-only**.
+- Existing root React exports remain temporarily for non-breaking transition.
+
+## 5) Peer dependency policy
+
+### Near term (`0.x`, current compatibility)
+
+- Keep `react` and `react-dom` as non-optional peers while root still exports React adapter surfaces.
+- When adding adapter subpaths:
+  - Add `react-native` peer + `peerDependenciesMeta.react-native.optional = true`.
+  - Add `vue` peer + `peerDependenciesMeta.vue.optional = true`.
+
+### Later (future major or de-rooting)
+
+- If React DOM adapter is no longer root-exported, convert renderer peers to optional and strictly subpath-scoped usage.
+
+Rationale: users should only need the framework peer for the adapter they import.
+
+## 6) Build output proposal
+
+A1 prerequisite: move from single-entry build to multi-entry/subpath build.
+
+Proposed dist shape:
+
+```txt
+dist/index.js
+dist/index.d.ts
+dist/react/index.js
+dist/react/index.d.ts
+dist/text/index.js
+dist/text/index.d.ts
+dist/text/react/index.js
+dist/text/react/index.d.ts
+dist/react-native/index.js
+dist/react-native/index.d.ts
+dist/vue/index.js
+dist/vue/index.d.ts
+```
+
+Build notes:
+
+- Use tsup multi-entry configuration (or equivalent) with explicit entry files.
+- Externalize framework runtimes in adapter bundles:
+  - `react`, `react-dom`, `react/jsx-runtime`
+  - `react-native`
+  - `vue`
+- Keep core runtime free of adapter-specific runtime imports.
+
+## 7) Source tree proposal
+
+Recommended organization:
+
+```txt
+src/
+  index.ts
+  react/
+    index.ts
+    MachinaReactView.tsx
+  react-native/
+    index.ts
+    MachinaReactNativeView.tsx
+  vue/
+    index.ts
+    MachinaVueView.ts
+  text/
+    index.ts
+    types.ts
+    parseMachinaText.ts
+    react/
+      index.ts
+      MachinaTextView.tsx
+    react-native/
+      index.ts
+      MachinaNativeTextView.tsx
+    vue/
+      index.ts
+      MachinaVueTextView.ts
+```
+
+Guideline:
+
+- Layout adapters: `src/<adapter>`.
+- Text renderers: `src/text/<adapter>`.
+
+This keeps parser/core text independent from renderer frameworks.
+
+## 8) Adapter API previews (non-binding)
+
+### React Native layout adapter
+
+```ts
+export type { MachinaReactNativeViewProps, MachinaNativeSlotProps };
+export { MachinaReactNativeView };
+```
+
+Expected behavior:
+
+- Uses RN `View` + style objects.
+- No `className`, no DOM data-attributes.
+- No DOM containment/content-visibility policy.
+- Preserve layout semantics, `viewData`/`nodeData`, layers/z ordering, and parent-local coordinates.
+
+### Vue layout adapter
+
+```ts
+export type { MachinaVueViewProps, MachinaVueSlotProps };
+export { MachinaVueView };
+```
+
+Expected behavior:
+
+- Vue component/composable renderer using `h()`.
+- Supports `layout`, `views`, `viewData`, `nodeData`, `layers`, `defaultLayer`, `debug`.
+- Dynamic view mapping via component references.
+
+### Text
+
+- `parseMachinaText` remains framework-agnostic in `machinalayout/text`.
+- Framework renderers exposed by subpath (`text/react`, future `text/react-native`, `text/vue`).
+
+## 9) Test strategy
+
+Principles:
+
+- Core tests always run and remain framework-independent.
+- Adapter tests are isolated by adapter folders and entrypoints.
+- Avoid forcing heavy framework stacks for users who do not use them.
+
+Proposed test layout:
+
+```txt
+test/
+  core/... 
+  react/...
+  react-native/...
+  vue/...
+  text/
+    core/...
+    react/...
+    react-native/...
+    vue/...
+```
+
+Execution approach (A1+):
+
+- Default CI lane: core + existing React lanes.
+- Adapter lanes:
+  - RN adapter tests in dedicated job/environment.
+  - Vue adapter tests in dedicated job/environment.
+- Early RN adapter tests can start with type-level/shape tests and minimal render checks before deeper platform-specific behavior.
+
+## 10) Documentation plan
+
+Planned docs additions:
+
+- `docs/react-native-adapter.md`
+- `docs/vue-adapter.md`
+- `docs/adapter-packaging-a0-plan.md` (this file)
+- README update to clarify preferred import paths and adapter dependency expectations.
+
+Docs guidance:
+
+- Show subpath imports for framework adapters.
+- Keep compatibility notes for root React imports during `0.x`.
+- Explicitly state optional peer policy for non-default adapters.
+- Keep adapter docs aligned to one conceptual model: Machina records author geometry, adapters render resolved rectangles in host primitives.
+- Reinforce stable component registries (`views`) plus dynamic `viewData`/`nodeData` channels across React, React Native, and Vue.
+
+## 11) Migration / compatibility notes
+
+- Do **not** break current root import patterns in immediate work.
+- Maintain:
+
+```ts
+import { MachinaReactView } from "machinalayout";
+```
+
+through `0.x`.
+
+- Mark subpath imports as preferred forward path.
+- Consider root de-exports only in future major/split-package decision.
+
+## 12) Milestone decomposition
+
+### A1 — React Native layout adapter
+
+Scope:
+
+- Add `src/react-native` adapter entry.
+- Add `machinalayout/react-native` subpath export.
+- Add optional `react-native` peer metadata.
+- Add initial RN adapter tests in isolated lane.
+
+Prereqs from A0:
+
+- Multi-entry build/export plumbing.
+
+Status note (A1a, 2026-05-11): multi-entry dist output and subpath exports for existing modules (`./react`, `./text`, `./text/react`) are now being implemented while preserving root-import compatibility during `0.x`.
+
+### A2 — React Native text renderer
+
+Scope:
+
+- Add `src/text/react-native` renderer.
+- Add `machinalayout/text/react-native` subpath export.
+- Extend RN adapter test lane for text renderer behavior.
+
+### A3 — Vue layout adapter
+
+Scope:
+
+- Add `src/vue` adapter entry.
+- Add `machinalayout/vue` subpath export.
+- Add optional `vue` peer metadata.
+- Add Vue adapter tests in isolated lane.
+
+### A4 — Vue text renderer
+
+Scope:
+
+- Add `src/text/vue` renderer.
+- Add `machinalayout/text/vue` subpath export.
+- Extend Vue test lane for text rendering behavior.
+
+### Later adapters
+
+- SVG/debug renderer under dedicated subpaths.
+- Svelte/Solid exploration after adapter API stabilization.
+
+## 13) Risks and mitigations
+
+1. **Root export bloat and accidental framework coupling**
+   - Mitigation: keep new adapters subpath-only; avoid root re-exports for new frameworks.
+
+2. **Peer dependency confusion**
+   - Mitigation: explicit matrix in README (adapter → required peer).
+
+3. **Build complexity regression**
+   - Mitigation: explicit multi-entry manifest + pack smoke checks per milestone.
+
+4. **CI/test instability from heavy adapter stacks**
+   - Mitigation: separate adapter test lanes and scoped test commands.
+
+5. **Future package split cost**
+   - Mitigation: enforce subpath discipline now so split is mostly import-path and publish-surface work later.
+
+## 14) Exact verification commands run
+
+From repository root:
+
+```bash
+npm test
+npm run build
+cd samples/control-room && npm run build
+cd samples/music-player && npm run build
+npm pack --dry-run
+```
+
+Observed result in A0: all commands completed successfully in this environment.

package/docs/adapters.md

@@ -0,0 +1,19 @@
+# Adapter overview
+
+Machina adapters ask you to learn one layout model: Machina records. The framework adapter only asks for components in that framework.
+
+Layout geometry stays in `LayoutRow[]` + resolved rectangles from core APIs. Adapter differences are host-renderer details (DOM versus React Native style primitives), not separate layout dialects.
+
+## Adapter + text renderer matrix
+
+| Target | Layout adapter | Text renderer | Required peer(s) | Notes |
+| --- | --- | --- | --- | --- |
+| React DOM | `machinalayout/react` | `machinalayout/text/react` | `react`, `react-dom` | Supports DOM containment/content-visibility and DOM wrapper hooks (`className`/`style`, attrs). |
+| React Native | `machinalayout/react-native` | `machinalayout/text/react-native` | `react`, `react-native` | Uses numeric RN styles and RN primitives (`View`/`Text`); no DOM containment/content-visibility. |
+| Vue DOM | `machinalayout/vue` | `machinalayout/text/vue` | `vue` | Adapter uses `h()` internally; users keep normal Vue components/templates as payloads. |
+
+## Import guidance
+
+- Subpath imports are preferred for adapters/renderers: `machinalayout/react`, `machinalayout/react-native`, `machinalayout/vue`, `machinalayout/text`, `machinalayout/text/react`, `machinalayout/text/react-native`, and `machinalayout/text/vue`.
+- Root imports remain valid during `0.x` compatibility windows.
+- Framework peers are adapter-specific: install only peers needed by the subpaths you use.