machinalayout 0.1.0

package/docs/forbidden-concepts.md

@@ -0,0 +1,60 @@
+# Forbidden Concepts (M0/M1 Guardrails)
+
+These concepts are forbidden in core M0/M1 unless a future milestone deliberately revisits them.
+
+## Flexbox negotiation features
+
+Forbidden: `flex-basis`, `flex-shrink`, flex grow/shrink/basis triangle, `align-content`, `align-self`, `space-around`, `space-evenly`, stretch defaults, baseline alignment. FillFrame weights are not flexbox.
+
+Why: this would reintroduce hidden layout negotiation and makes layout harder to reason about from records.
+
+## Margin-driven placement
+
+Forbidden: auto margins, per-child margins, margin collapse. FillFrame does not add per-item margin behavior.
+
+Why: margins introduce implicit inter-node coupling and hidden offsets that are not explicit in row geometry.
+
+## Stack wrapping and implicit sizing behavior
+
+Forbidden: wrap on `Stack`, percent units, implicit stretch behaviors.
+
+Why: this belongs in a future separate primitive, not Stack.
+
+## DOM/CSS-driven geometry authority
+
+Forbidden: DOM measurement in core layout, selector-based layout, descendant selector semantics, CSS classes as layout inputs.
+
+Why: renderer-dependent inputs break deterministic resolution and move authority away from typed records.
+
+## Authoring model drift
+
+Forbidden: nested JSX as canonical authoring, recursive `children` on `LayoutNode`.
+
+Why: Machina’s contract is flat record authoring; tree shape is derived output.
+
+## Out-of-scope platform concerns in core
+
+Forbidden: routing inside layout core, state management inside layout core.
+
+Why: layout core should stay a geometry engine, not an application framework.
+
+## Ordering and layering misuse
+
+Forbidden: global z-index solver, z-based layout ordering.
+
+Why: z is sibling-local paint metadata; geometry and order resolution must remain independent.
+
+## Silent correctness masking
+
+Forbidden: silent clamping.
+
+Why: silent repair hides authoring mistakes and weakens determinism guarantees.
+
+
+## Unit parsing guardrail
+
+Forbidden: string percentages (e.g. `"50%"`), CSS unit parsing, and CSS `calc`.
+
+Allowed in M1c: typed `UiLength` objects for `AnchorFrame` only (`px` and normalized `ui`), because conversion is explicit and deterministic.
+
+M1d clarification: per-item margins remain forbidden. Use explicit node `offset` for local post-placement nudges when needed.

package/docs/frames-and-stack.md

@@ -0,0 +1,135 @@
+# Frames and Stack
+
+## Rects
+
+Resolved rectangles are numeric records:
+
+- `x`
+- `y`
+- `width`
+- `height`
+
+## `AbsoluteFrame`
+
+Absolute frame gives explicit parent-local position and size.
+
+- `x = parent.x + frame.x`
+- `y = parent.y + frame.y`
+- `width = frame.width`
+- `height = frame.height`
+
+## `AnchorFrame`
+
+Anchor requires exactly two horizontal constraints from `left`, `right`, `width`, and exactly two vertical constraints from `top`, `bottom`, `height`.
+
+Supported horizontal cases:
+
+- `left + width`
+- `right + width`
+- `left + right`
+
+Supported vertical cases:
+
+- `top + height`
+- `bottom + height`
+- `top + bottom`
+
+Invalid combinations fail. Negative resolved sizes fail.
+
+## `FixedFrame`
+
+Fixed frame is size-only.
+
+- It cannot resolve by itself.
+- It is valid as a direct child of `StackArrange`.
+- It is invalid on the root row (same compile-time rejection code as non-arranged fixed usage): `FixedFrameWithoutArranger`.
+- Otherwise resolution fails with `FixedFrameWithoutArranger`.
+
+## `StackArrange`
+
+Stack is ordered sequence arrangement over direct children.
+
+- Direct children must be `FixedFrame` or `FillFrame`.
+- Axis: `horizontal` or `vertical`.
+- Supports `gap` and `padding`.
+- `justify`: `start` | `center` | `end` | `space-between`
+- `align`: `start` | `center` | `end`
+
+Deliberate exclusions:
+
+- no shrink
+- no stretch
+- no shrink/basis/min/max negotiation
+- no wrap
+- no margins
+
+### Toolbar example
+
+```ts
+{
+  id: "toolbar",
+  frame: { kind: "anchor", left: 240, right: 0, top: 64, height: 56 },
+  arrange: {
+    kind: "stack",
+    axis: "horizontal",
+    gap: 8,
+    padding: { top: 8, right: 8, bottom: 8, left: 8 },
+    justify: "start",
+    align: "center",
+  },
+}
+
+{ id: "button-a", parent: "toolbar", frame: { kind: "fixed", width: 120, height: 40 } }
+{ id: "button-b", parent: "toolbar", frame: { kind: "fixed", width: 96, height: 40 } }
+```
+
+Stack computes positions by arithmetic over order, fixed sizes, gap, and padding.
+
+> Stack is ordered arithmetic, not Flexbox.
+
+
+## RootFrame
+
+`RootFrame` is `{ kind: "root" }` and is valid only on the root row (`parent === undefined`).
+
+- Root geometry is still copied from `rootRect` passed by the caller.
+- `resolveFrame(parent, { kind: "root" })` throws `RootFrameWithoutRoot`.
+- Non-root rows with `RootFrame` are rejected during compile with `RootFrameNotRoot`.
+- Root should use `RootFrame`; legacy root `AbsoluteFrame` and `AnchorFrame` remain accepted for compatibility.
+- Root `FixedFrame` and root `FillFrame` are invalid because both require arranger/stack context.
+
+
+## `FillFrame`
+
+`FillFrame` is valid only as a direct child of `StackArrange`.
+
+- `weight` defaults to `1` and must be finite and `> 0`.
+- `cross` defaults to `"fill"`.
+- `cross: "fill"` uses stack content cross size.
+- numeric `cross` is explicit cross size and must be finite/non-negative.
+
+Fill children consume all remaining main-axis space after fixed sizes and gaps. When one or more fill children exist, `justify` has no additional free space to distribute.
+
+
+## Anchor UiLength (M1c)
+
+Anchor fields `left/right/top/bottom/width/height` accept `UiLength`:
+- plain number means px
+- `{ unit: "px", value }` explicit px
+- `{ unit: "ui", value }` normalized unit resolved deterministically during frame resolution
+
+Axis mapping:
+- horizontal (`left/right/width`) uses `parent.width`
+- vertical (`top/bottom/height`) uses `parent.height`
+
+Notes:
+- no string percentages
+- no CSS `calc`
+- fractional pixels are preserved
+- negative `left/right/top/bottom` positional constraints are deliberately allowed for intentional overflow/bleed
+- explicit negative width/height are rejected
+- derived negative size from `left+right` or `top+bottom` is rejected
+
+## Node offsets (M1d)
+
+`offset` is applied after normal frame/stack placement and does not change stack distribution, sibling positions, or width/height. `offset.x` resolves against parent rect width; `offset.y` resolves against parent rect height.

package/docs/m0-contract.md

@@ -0,0 +1,70 @@
+# M0 Contract
+
+## Purpose
+
+M0 defines a deterministic, framework-independent rectangle resolution pipeline with a narrow, explicit scope.
+
+## Architecture pipeline
+
+`LayoutRow[]`
+→ `compileLayoutRows`
+→ `LayoutDocument`
+→ `resolveLayoutDocument`
+→ `ResolvedLayoutDocument`
+→ optional `toResolvedTree`
+→ renderer adapter
+
+## Core model
+
+- **Flat rows** are the canonical input model.
+- **Indexed documents** (`nodes`, `children`, `rootId`) are the compiled representation.
+- **Flat resolved output** is the canonical resolved geometry model.
+- **Derived tree** is for rendering/debugging convenience, not authoring.
+
+## Supported primitives
+
+- `AbsoluteFrame`
+- `AnchorFrame`
+- `FixedFrame`
+- `StackArrange`
+
+## Supported metadata
+
+- `slot`
+- `debugLabel`
+- `z`
+
+## Adapter boundary
+
+- The React adapter renders resolved rectangles as absolutely positioned wrappers.
+- Slots are rendered via a slot registry (`views`).
+- Coordinates are normalized to root-local space for embedding.
+- Containment/content-visibility are adapter-level policy knobs.
+
+## Sample
+
+The Control Room sample (`samples/control-room`) demonstrates the M0 contract in a runnable app.
+
+## Non-goals
+
+- routing
+- state framework
+- full design system
+- CSS replacement
+- flexbox clone
+- grid clone
+
+
+> M1a note: Root rows may now declare `frame: { kind: "root" }`; root geometry still comes from caller-provided `rootRect`.
+
+
+> M1b note: `FillFrame` is now supported as a direct child of `StackArrange` for weighted remaining-space distribution.
+
+
+## M1c implemented scope note
+
+M1c adds typed `UiLength` support for `AnchorFrame` only; resolved rect outputs remain numeric pixels.
+
+## M1d implemented scope note
+
+M1d adds optional node-level `OffsetSpec` for deterministic post-placement translation. Offsets are not margins and do not participate in stack distribution.

package/docs/machina-text-m2a-plan.md

@@ -0,0 +1,319 @@
+# MachinaText M2a Planning & Audit
+
+## Status note (M2c.1)
+
+M2c.1 is implemented in React renderer scope: explicit `leading`, `blockGap`, `listGap`, and `valign` policy fields now control vertical rhythm inside owned rectangles without changing layout resolver APIs or parser syntax.
+
+## 1) Executive summary
+
+MachinaText should be introduced as a **small, explicit text-content model** for authoring predictable text structures inside already-resolved Machina rectangles, without turning Machina into a document engine, Markdown engine, or font/layout measurement system.
+
+For M2a, the least disruptive path is:
+
+- add a **docs-first plan** (this file),
+- keep MachinaText **independent from layout core resolution**,
+- keep `LayoutRow` and resolver APIs unchanged,
+- attach text policy at the **view payload layer** (application/renderer side) first,
+- defer parser/runtime code to later milestones.
+
+## 2) Goals
+
+- Provide a brutally limited, machine-authorable text format for LLM-friendly edits.
+- Keep text content model renderer-agnostic.
+- Preserve Machina contract: layout owns rectangles, text stays inside resolved rectangles.
+- Support a narrow set of content primitives:
+  - plain text
+  - paragraph breaks
+  - strong
+  - emphasis
+  - inline code
+  - links
+  - unordered bullets with max depth 2
+- Make policy explicit (variant/wrap/overflow/align) rather than hidden in syntax tricks.
+
+## 3) Non-goals
+
+- No full Markdown compatibility.
+- No headings in M2.
+- No images/tables/raw HTML/blockquotes/ordered lists/task lists/footnotes.
+- No routing/dispatch/state behavior.
+- No rich text editor concerns (selection/caret/editing model).
+- No glyph shaping/font fallback/bidi engine in Machina core.
+- No intrinsic sizing or text-driven outer layout changes.
+
+## 4) Proposed package/module placement
+
+### Audit observations
+
+- Core public API is exported from `src/index.ts`, and currently exports geometry + react adapter modules only. `src/index.ts`.
+- Core types (`LayoutRow`, `FrameSpec`, resolved docs) are geometry-oriented and intentionally small. `src/types.ts`.
+- React integration currently maps `view ?? slot` keys to app-provided components via `views` registry; this is the existing integration seam for payload rendering. `src/react/MachinaReactView.tsx`.
+
+### Recommendation (least disruptive M2 path)
+
+1. **Add `src/text/` in same package** for M2-series incubation (types/contracts/docs-aligned naming).
+2. Keep React-specific text helpers under **`src/text/react/`** (not mixed into current generic `src/react` root) to keep text concerns modular.
+3. Re-export from root only when implementation starts (M2b+), not required for M2a docs-only.
+4. Consider separate package later (`@machina/text`) only after API stabilizes and at least one non-React renderer exists.
+
+Rationale: this keeps churn low, avoids premature package splitting, and preserves current adapter surface.
+
+## 5) Proposed public type surface
+
+> M2a recommendation: define these in plan only; do not implement yet.
+
+```ts
+export type MachinaTextSource =
+  | { kind: "plain"; text: string }
+  | { kind: "machina-text"; text: string };
+
+export type MachinaTextVariant = "body" | "label" | "caption" | "title" | "mono";
+export type MachinaTextWrap = "word" | "none";
+export type MachinaTextOverflow = "clip" | "ellipsis" | "scroll";
+export type MachinaTextAlign = "start" | "center" | "end";
+
+export type MachinaTextSpec = {
+  kind: "text";
+  source: MachinaTextSource;
+  variant?: MachinaTextVariant;
+  wrap?: MachinaTextWrap;
+  overflow?: MachinaTextOverflow;
+  align?: MachinaTextAlign;
+};
+```
+
+AST recommendation:
+
+```ts
+export type MachinaTextDocument = {
+  blocks: MachinaTextBlock[];
+};
+
+export type MachinaTextBlock =
+  | { kind: "paragraph"; inline: MachinaInline[] }
+  | { kind: "bulletList"; items: MachinaBulletItem[] };
+
+export type MachinaBulletItem = {
+  inline: MachinaInline[];
+  children?: MachinaBulletItem[];
+};
+
+export type MachinaInline =
+  | { kind: "text"; text: string }
+  | { kind: "strong"; children: MachinaInline[] }
+  | { kind: "emphasis"; children: MachinaInline[] }
+  | { kind: "code"; text: string }
+  | { kind: "link"; href: string; children: MachinaInline[] };
+```
+
+Type-shape decisions:
+
+- `strong` / `emphasis` should contain **children**, not raw text, to allow nested emphasis/code/link segments while keeping one consistent inline model.
+- `link` should contain **inline children**, not label-only text, for parity and explicit structure.
+- Bullets should allow nested inline formatting (same `MachinaInline[]` as paragraphs).
+- Bullet max depth should be enforced by parser validation/diagnostics, not encoded in types.
+- `variant/wrap/overflow/align` belong in `MachinaTextSpec` (content policy contract), while renderers decide exact visual implementation details.
+- `plain` source should normalize into one-paragraph AST during parse.
+
+## 6) Allowed syntax
+
+MachinaText syntax (M2 target):
+
+- plain text
+- paragraph breaks (blank line separation)
+- `**strong**`
+- `*emphasis*`
+- `` `code` ``
+- `[label](href)` links
+- unordered bullets (`-` prefix)
+- nested bullets max depth 2
+
+## 7) Forbidden syntax
+
+- headings (`#`, `##`, etc.)
+- ordered lists (`1.`)
+- task list checkboxes
+- blockquotes (`>`)
+- fenced code blocks
+- images (`![...]`)
+- tables
+- raw HTML
+- extension syntax / custom directives
+- CSS classes/styles inside text syntax
+- any layout declarations
+- route/action/dispatch syntax
+
+## 8) Heading decision and rationale
+
+**Decision: headings are explicitly out of scope in M2.**
+
+Rationale:
+
+- Heading markers smuggle hidden policy (typography scale, spacing, semantic levels).
+- MachinaText should keep policy explicit and inspectable.
+- “Title-like” rendering should come from explicit fields (`variant: "title"`) or explicit views, not punctuation shortcuts.
+
+## 9) Bullet list decision and max-depth rationale
+
+Decision:
+
+- support unordered bullets only,
+- allow nesting up to depth 2,
+- reject/diagnose deeper nesting.
+
+Rationale:
+
+- Depth cap preserves predictable rendering across hosts.
+- Prevents gradual drift toward document-authoring complexity.
+- Meets common UI copy needs (short status/checklist-like structure) without introducing full markdown list semantics.
+
+## 10) Parser behavior recommendation
+
+Recommendation:
+
+- Parser should return a **result object with diagnostics**, not throw for normal authoring errors.
+- Hard throw only for programmer misuse (invalid API call types), not syntax mistakes in content strings.
+
+Suggested shape:
+
+```ts
+export type MachinaTextDiagnosticLevel = "error" | "warning";
+
+export type MachinaTextDiagnostic = {
+  code:
+    | "unsupported_syntax"
+    | "heading_forbidden"
+    | "max_list_depth_exceeded"
+    | "malformed_link"
+    | "unclosed_inline"
+    | "invalid_escape";
+  message: string;
+  index: number;
+  length: number;
+  line: number;
+  column: number;
+  level: MachinaTextDiagnosticLevel;
+};
+
+export type ParseMachinaTextResult = {
+  ok: boolean;
+  document: MachinaTextDocument;
+  diagnostics: MachinaTextDiagnostic[];
+};
+```
+
+Fallback policy:
+
+- Unsupported constructs should be preserved as literal text where possible, with diagnostics.
+- Optional strict mode can fail `ok=false` on first unsupported construct.
+
+## 11) Renderer boundary
+
+Core MachinaText model owns:
+
+- content AST semantics,
+- small text policy flags (`variant`, `wrap`, `overflow`, `align`),
+- parser diagnostics contract.
+
+React/DOM renderer owns:
+
+- actual text rendering via browser engine,
+- mapping policy flags to CSS/DOM behavior,
+- link interaction callbacks passed from app,
+- accessibility annotations specific to host components.
+
+Future non-DOM renderer owns:
+
+- platform-specific shaping/layout internals,
+- equivalent wrap/clip/ellipsis/scroll behavior inside rectangle,
+- platform accessibility mapping.
+
+## 12) Layout boundary
+
+Hard boundary:
+
+- MachinaLayout resolves outer rectangles.
+- MachinaText operates inside resolved rectangle only.
+
+Not allowed:
+
+- requesting larger parent/sibling/root sizes,
+- intrinsic measurement feedback into resolver,
+- creating new layout nodes from text blocks.
+
+Allowed:
+
+- in-rectangle wrap/clip/ellipsis/scroll policy.
+
+## 13) Link behavior boundary
+
+Links are text semantics only:
+
+- link node stores `href` + label children,
+- no route syntax,
+- no command dispatch tables,
+- no state transition contract in MachinaText.
+
+Application/renderers decide click behavior.
+
+## 14) Suggested M2 milestone decomposition
+
+- **M2a (this pass):** audit + plan doc + agreed type contracts (docs only).
+- **M2b:** implement parser + diagnostics + unit tests (no renderer).
+- **M2c:** React/DOM rendering adapter for MachinaText AST inside node views.
+- **M2d:** sample integration in control-room-style demo with explicit text specs.
+- **M2e:** docs polish, migration notes, edge-case hardening, non-DOM renderer contract notes.
+
+## 15) Risks and mitigations
+
+1. **Heading semantics creep**  
+   Mitigation: explicit prohibition + diagnostic code `heading_forbidden`.
+
+2. **Markdown dialect creep**  
+   Mitigation: closed grammar and “unsupported as literal+diagnostic” policy.
+
+3. **Text measurement creep into core**  
+   Mitigation: hard boundary that no parser/model API takes font metrics or container reflow callbacks.
+
+4. **Routing/event creep via links**  
+   Mitigation: keep links as `href` semantics only, no action ids.
+
+5. **HTML passthrough pressure**  
+   Mitigation: explicit ban with diagnostics; no raw HTML node type.
+
+6. **Intrinsic sizing pressure**  
+   Mitigation: tests/docs asserting no resolver API change and no text->layout feedback path.
+
+7. **Accessibility overpromises in core**  
+   Mitigation: document that host renderers/apps own semantics and interaction behavior.
+
+8. **Renderer leakage into core types**  
+   Mitigation: keep core text types free of CSS/DOM-specific properties.
+
+## 16) Recommended next implementation prompt
+
+“Implement M2b parser-only MachinaText foundation (no renderer):
+
+- Add `src/text/types.ts` and `src/text/parseMachinaText.ts`.
+- Implement only allowed syntax: paragraphs, strong/emphasis/code/link, unordered bullets depth<=2.
+- Return `ParseMachinaTextResult` with diagnostics; no throws for authoring errors.
+- Forbid headings/raw HTML/ordered lists/etc. with explicit diagnostic codes.
+- Add focused Vitest coverage for success and failure cases.
+- Do not modify layout resolver APIs, `LayoutRow`, or React adapter behavior yet.”
+
+---
+
+## Repo-specific audit notes
+
+- Current core shape is layout-only and should remain unchanged for M2a. `src/types.ts`.
+- Current React integration seam (`view ?? slot` mapping) is a suitable place for app-level text view components in early milestones, avoiding immediate core API expansion. `src/react/MachinaReactView.tsx`.
+- Current docs already enforce similar anti-creep guardrails (no intrinsic sizing/DOM authority), and MachinaText should align with that philosophy. `docs/forbidden-concepts.md`.
+
+## M2b status note (implemented)
+
+M2b parser-only foundation is now implemented in `src/text`:
+
+- public MachinaText types are exported,
+- `parseMachinaText` returns AST + diagnostics,
+- no renderer integration added,
+- no layout resolver API changes made.

package/docs/machina-text-parser.md

@@ -0,0 +1,24 @@
+# MachinaText Parser
+
+MachinaText supports a narrow inline syntax: emphasis, strong, code spans, links, and bullets.
+
+## Escapes (M3a)
+
+Supported escapes in normal inline text:
+
+- `\\` => `\`
+- `\*` => `*`
+- ``\` `` => `` ` ``
+- `\[` => `[`
+- `\]` => `]`
+- `\(` => `(`
+- `\)` => `)`
+- `\-` => `-`
+
+Escapes are processed before inline marker detection, so escaped markers stay literal (example: `\*not emphasis\*`).
+
+Unsupported escapes (example: `\q`) emit diagnostic code `invalid_escape` and preserve visible content as literal text.
+
+A trailing dangling backslash also emits `invalid_escape` and preserves a literal backslash.
+
+Code spans do not process escapes. Content inside backticks is taken literally.

package/docs/machina-text-react.md

@@ -0,0 +1,68 @@
+# MachinaText React Renderer (M2c)
+
+`MachinaTextView` renders MachinaText content inside a rectangle already owned by a parent view. It does not participate in Machina layout resolution, sizing, or measurement.
+
+## Component
+
+- `MachinaTextView`
+- `MachinaTextViewProps`
+
+### `text` input forms
+
+- `string`: parsed as `{ kind: "machina-text", text }`
+- `MachinaTextSource`: parsed directly (`plain` stays literal)
+- `MachinaTextSpec`: parses `spec.source` and applies text policy
+- `MachinaTextDocument`: rendered directly with default policy
+
+## Policy fields
+
+Supported policy fields:
+
+- `variant`: `body | label | caption | title | mono`
+- `wrap`: `word | none`
+- `overflow`: `clip | ellipsis | scroll`
+- `align`: `start | center | end`
+- `leading`: `tight | normal | loose | number`
+- `blockGap`: non-negative number (pixels)
+- `listGap`: non-negative number (pixels)
+- `valign`: `top | center | bottom`
+
+Defaults are `body`, `word`, `clip`, `start`, `normal`, `8`, `2`, `top`.
+
+Vertical rhythm policy is internal to the text renderer inside an already-owned rectangle. It does not change outer Machina layout, resolver behavior, or sizing.
+
+- `leading` maps to `line-height` (`tight=1.15`, `loose=1.6`, `normal=variant default`, numeric uses provided value when valid).
+- `blockGap` controls spacing between top-level text blocks (paragraph/list blocks).
+- `listGap` controls spacing between list items (including nested list items).
+- `valign` controls vertical placement of content in the wrapper rectangle.
+
+`MachinaTextView` may use internal flex layout for this vertical positioning only. This does not imply flex/grid-based Machina node placement.
+
+## Link behavior boundary
+
+Links render as standard `<a>` tags.
+
+- optional `linkTarget`
+- if `_blank`, renderer sets `rel="noreferrer noopener"`
+- optional `onLinkClick(href, event)` callback
+
+No routing, dispatch, or action semantics are implemented.
+
+## Diagnostics
+
+Parsing diagnostics never throw. Best-effort content still renders.
+
+Set `showDiagnostics` to render parser diagnostics for development.
+
+
+## Overflow ellipsis policy (M3a)
+
+`overflow: "ellipsis"` is defined as **single-line ellipsis** in M3.
+
+When `overflow` is `ellipsis`, renderer normalization forces:
+
+- `white-space: nowrap`
+- `overflow: hidden`
+- `text-overflow: ellipsis`
+
+This overrides `wrap` for deterministic behavior. Multi-line ellipsis / line clamp is not supported.