machinalayout 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yuechen Li
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# MachinaLayout
+
+MachinaLayout is a framework-independent, machine-native layout system that resolves flat typed layout records into deterministic rectangles.
+
+## Install
+
+```bash
+npm install machinalayout
+```
+
+## Core principles
+
+- **Layout is data.**
+- **Rendering is an adapter.**
+- **Nesting is an output shape, not an authoring strategy.**
+- **MachinaLayout controls outer rectangles; host frameworks control view internals (using `view ?? slot`).**
+
+## What problem it solves
+
+MachinaLayout keeps geometry explicit and local:
+
+- avoids vague CSS negotiation,
+- makes numeric layout edits predictable,
+- gives humans and LLMs a table/record-shaped layout format.
+
+## Tiny `LayoutRow[]` example
+
+```ts
+import {
+  type LayoutRow,
+  resolveLayoutRows,
+  type Rect,
+} from "machinalayout";
+
+const rows: LayoutRow[] = [
+  {
+    id: "root",
+    frame: { kind: "root" },
+  },
+  {
+    id: "header",
+    parent: "root",
+    order: 0,
+    frame: { kind: "anchor", left: 0, right: 0, top: 0, height: 64 },
+    slot: "header",
+  },
+  {
+    id: "sidebar",
+    parent: "root",
+    order: 1,
+    frame: { kind: "anchor", left: 0, top: 64, bottom: 0, width: 240 },
+    slot: "sidebar",
+  },
+  {
+    id: "toolbar",
+    parent: "root",
+    order: 2,
+    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: "toolbar-button-1",
+    parent: "toolbar",
+    order: 0,
+    frame: { kind: "fixed", width: 120, height: 40 },
+    slot: "toolbarButton",
+  },
+];
+
+const rootRect: Rect = { x: 0, y: 0, width: 1024, height: 640 };
+const resolved = resolveLayoutRows(rows, rootRect);
+```
+
+## React adapter quick example
+
+```tsx
+import { MachinaReactView, resolveLayoutRows } from "machinalayout";
+
+const resolved = resolveLayoutRows(rows, rootRect);
+
+const views = {
+  header: HeaderView,
+  sidebar: SidebarView,
+  toolbarButton: ToolbarButtonView,
+};
+
+export function App() {
+  return <MachinaReactView layout={resolved} views={views} viewData={{ sidebar: { collapsed: false } }} />;
+}
+```
+
+## Sample demo
+
+See [`samples/control-room`](samples/control-room/README.md).
+
+Run it locally:
+
+```bash
+cd samples/control-room
+npm install
+npm run dev
+```
+
+## M0 scope (current)
+
+M0 supports:
+
+- `RootFrame` (M1a)
+- `AbsoluteFrame`
+- `AnchorFrame`
+- `FixedFrame`
+- `FillFrame` (M1b, stack-child weighted fill)
+- `StackArrange`
+- bounded sibling-local z metadata
+- React adapter
+
+M0 does **not** support:
+
+- FlowBox
+- wrapping
+- flexbox-style shrink/basis/min/max negotiation
+- intrinsic sizing
+- text measurement
+- routing
+- state management
+- CSS layout authority for Machina rectangles
+
+## Documentation
+
+- [M0 contract](docs/m0-contract.md)
+- [Row model](docs/row-model.md)
+- [Frames and stack](docs/frames-and-stack.md)
+- [React adapter boundary](docs/react-adapter.md)
+- [Z-order and containment](docs/z-order-and-containment.md)
+- [Forbidden concepts](docs/forbidden-concepts.md)
+
+
+## M1c typed UI lengths
+
+Anchor fields now accept typed `UiLength` values in addition to numeric pixels:
+
+- `number` (implicit px)
+- `{ unit: "px", value: number }`
+- `{ unit: "ui", value: number }` (normalized against parent axis)
+
+Example: `left: { unit: "ui", value: 0.25 }`.
+
+- node-level `OffsetSpec` post-placement nudges (M1d, not margins)

package/dist/index.d.ts

@@ -0,0 +1,269 @@
+import React from 'react';
+
+type NodeId = string;
+type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+type AbsoluteFrame = {
+    kind: "absolute";
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+type UiLength = number | {
+    unit: "px";
+    value: number;
+} | {
+    unit: "ui";
+    value: number;
+};
+type OffsetSpec = {
+    x?: UiLength;
+    y?: UiLength;
+};
+type AnchorFrame = {
+    kind: "anchor";
+    left?: UiLength;
+    right?: UiLength;
+    top?: UiLength;
+    bottom?: UiLength;
+    width?: UiLength;
+    height?: UiLength;
+};
+type RootFrame = {
+    kind: "root";
+};
+type FixedFrame = {
+    kind: "fixed";
+    width: number;
+    height: number;
+};
+type FillFrame = {
+    kind: "fill";
+    weight?: number;
+    cross?: number | "fill";
+};
+type FrameSpec = RootFrame | AbsoluteFrame | AnchorFrame | FixedFrame | FillFrame;
+type StackAxis = "horizontal" | "vertical";
+type StackJustify = "start" | "center" | "end" | "space-between";
+type StackAlign = "start" | "center" | "end";
+type EdgeInsets = {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+};
+type StackArrange = {
+    kind: "stack";
+    axis: StackAxis;
+    gap?: number;
+    padding?: number | EdgeInsets;
+    justify?: StackJustify;
+    align?: StackAlign;
+};
+type ArrangeSpec = StackArrange;
+type LayoutRow = {
+    id: NodeId;
+    parent?: NodeId;
+    order?: number;
+    z?: number;
+    frame: FrameSpec;
+    arrange?: ArrangeSpec;
+    view?: string;
+    slot?: string;
+    debugLabel?: string;
+    offset?: OffsetSpec;
+};
+type LayoutNode = {
+    id: NodeId;
+    z?: number;
+    frame: FrameSpec;
+    arrange?: ArrangeSpec;
+    view?: string;
+    slot?: string;
+    debugLabel?: string;
+    offset?: OffsetSpec;
+};
+type LayoutDocument = {
+    rootId: NodeId;
+    nodes: Record<NodeId, LayoutNode>;
+    children: Record<NodeId, NodeId[]>;
+};
+type ResolvedLayoutNode = {
+    id: NodeId;
+    z?: number;
+    rect: Rect;
+    frame: FrameSpec;
+    arrange?: ArrangeSpec;
+    view?: string;
+    slot?: string;
+    debugLabel?: string;
+    offset?: OffsetSpec;
+};
+type ResolvedLayoutDocument = {
+    rootId: NodeId;
+    nodes: Record<NodeId, ResolvedLayoutNode>;
+    children: Record<NodeId, NodeId[]>;
+};
+type ResolvedLayoutTree = {
+    id: NodeId;
+    z?: number;
+    rect: Rect;
+    frame: FrameSpec;
+    arrange?: ArrangeSpec;
+    view?: string;
+    slot?: string;
+    debugLabel?: string;
+    offset?: OffsetSpec;
+    children: ResolvedLayoutTree[];
+};
+
+type MachinaLayoutErrorCode = "EmptyRows" | "MissingRoot" | "MultipleRoots" | "DuplicateId" | "InvalidId" | "MissingParent" | "UnknownParent" | "SelfParent" | "Cycle" | "UnreachableNode" | "NonFiniteNumber" | "InvalidLengthUnit" | "InvalidZ" | "NegativeSize" | "NegativeGap" | "NegativePadding" | "InvalidAnchorHorizontal" | "InvalidAnchorVertical" | "NegativeResolvedSize" | "FixedFrameWithoutArranger" | "FillFrameWithoutArranger" | "InvalidFillWeight" | "StackChildMustBeFixed" | "StackContentNegative" | "StackOverflow" | "RootFrameNotRoot" | "RootFrameWithoutRoot";
+declare class MachinaLayoutError extends Error {
+    readonly code: MachinaLayoutErrorCode;
+    constructor(code: MachinaLayoutErrorCode, message: string);
+}
+
+declare function assertFiniteNumber(value: number, fieldName: string): void;
+declare function assertNonNegativeSize(value: number, fieldName: string): void;
+declare function assertNonNegativeGap(value: number, fieldName?: string): void;
+declare function assertNonNegativePadding(value: number, fieldName?: string): void;
+
+declare function normalizePadding(padding?: number | EdgeInsets): EdgeInsets;
+
+declare function resolveUiLength(length: UiLength, axisSize: number, fieldName?: string): number;
+
+declare function applyOffset(rect: Rect, parentRect: Rect, offset?: OffsetSpec): Rect;
+
+declare function compileLayoutRows(rows: LayoutRow[]): LayoutDocument;
+
+declare function resolveFrame(parent: Rect, frame: FrameSpec): Rect;
+
+declare function resolveLayoutDocument(document: LayoutDocument, rootRect: Rect): ResolvedLayoutDocument;
+
+declare function resolveLayoutRows(rows: LayoutRow[], rootRect: Rect): ResolvedLayoutDocument;
+
+declare function toResolvedTree(document: ResolvedLayoutDocument): ResolvedLayoutTree;
+
+declare function flattenResolvedTree(tree: ResolvedLayoutTree): ResolvedLayoutNode[];
+
+declare function formatRect(rect: Rect): string;
+
+type MachinaSlotProps<TViewData = unknown, TNodeData = unknown> = {
+    id: NodeId;
+    rect: Rect;
+    debugLabel?: string;
+    node: ResolvedLayoutNode;
+    viewKey?: string;
+    viewData?: TViewData;
+    nodeData?: TNodeData;
+};
+type MachinaReactViewProps = {
+    layout: ResolvedLayoutDocument;
+    views?: Record<string, React.ComponentType<MachinaSlotProps>>;
+    viewData?: Record<string, unknown>;
+    nodeData?: Record<NodeId, unknown>;
+    className?: string;
+    style?: React.CSSProperties;
+    nodeClassName?: string;
+    debug?: boolean;
+    nodeContainment?: "none" | "layout-paint" | "strict";
+    nodeContentVisibility?: "none" | "auto";
+    nodeContainIntrinsicSize?: string;
+};
+declare function MachinaReactView(props: MachinaReactViewProps): React.JSX.Element;
+
+type MachinaTextSource = {
+    kind: "plain";
+    text: string;
+} | {
+    kind: "machina-text";
+    text: string;
+};
+type MachinaTextVariant = "body" | "label" | "caption" | "title" | "mono";
+type MachinaTextWrap = "word" | "none";
+type MachinaTextOverflow = "clip" | "ellipsis" | "scroll";
+type MachinaTextAlign = "start" | "center" | "end";
+type MachinaTextLeading = "tight" | "normal" | "loose" | number;
+type MachinaTextVerticalAlign = "top" | "center" | "bottom";
+type MachinaTextSpec = {
+    kind: "text";
+    source: MachinaTextSource;
+    variant?: MachinaTextVariant;
+    wrap?: MachinaTextWrap;
+    overflow?: MachinaTextOverflow;
+    align?: MachinaTextAlign;
+    leading?: MachinaTextLeading;
+    blockGap?: number;
+    listGap?: number;
+    valign?: MachinaTextVerticalAlign;
+};
+type MachinaTextDocument = {
+    blocks: MachinaTextBlock[];
+};
+type MachinaTextBlock = {
+    kind: "paragraph";
+    inline: MachinaInline[];
+} | {
+    kind: "bulletList";
+    items: MachinaBulletItem[];
+};
+type MachinaBulletItem = {
+    inline: MachinaInline[];
+    children?: MachinaBulletItem[];
+};
+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 MachinaTextDiagnosticLevel = "error" | "warning";
+type MachinaTextDiagnosticCode = "unsupported_syntax" | "heading_forbidden" | "max_list_depth_exceeded" | "malformed_link" | "unclosed_inline" | "invalid_escape";
+type MachinaTextDiagnostic = {
+    code: MachinaTextDiagnosticCode;
+    message: string;
+    index: number;
+    length: number;
+    line: number;
+    column: number;
+    level: MachinaTextDiagnosticLevel;
+};
+type ParseMachinaTextResult = {
+    ok: boolean;
+    document: MachinaTextDocument;
+    diagnostics: MachinaTextDiagnostic[];
+};
+
+declare function parseMachinaTextInline(text: string): {
+    inline: MachinaInline[];
+    diagnostics: MachinaTextDiagnostic[];
+};
+declare function parseMachinaText(source: MachinaTextSource | string): ParseMachinaTextResult;
+
+type MachinaTextViewProps = {
+    text: MachinaTextSpec | MachinaTextSource | MachinaTextDocument | string;
+    className?: string;
+    style?: React.CSSProperties;
+    linkTarget?: React.HTMLAttributeAnchorTarget;
+    onLinkClick?: (href: string, event: React.MouseEvent<HTMLAnchorElement>) => void;
+    showDiagnostics?: boolean;
+};
+declare function MachinaTextView(props: MachinaTextViewProps): React.JSX.Element;
+
+export { type AbsoluteFrame, type AnchorFrame, type ArrangeSpec, type EdgeInsets, type FillFrame, type FixedFrame, type FrameSpec, type LayoutDocument, type LayoutNode, type LayoutRow, type MachinaBulletItem, type MachinaInline, MachinaLayoutError, type MachinaLayoutErrorCode, MachinaReactView, type MachinaReactViewProps, type MachinaSlotProps, type MachinaTextAlign, type MachinaTextBlock, type MachinaTextDiagnostic, type MachinaTextDiagnosticCode, type MachinaTextDiagnosticLevel, type MachinaTextDocument, type MachinaTextLeading, type MachinaTextOverflow, type MachinaTextSource, type MachinaTextSpec, type MachinaTextVariant, type MachinaTextVerticalAlign, MachinaTextView, type MachinaTextViewProps, type MachinaTextWrap, type NodeId, type OffsetSpec, type ParseMachinaTextResult, type Rect, type ResolvedLayoutDocument, type ResolvedLayoutNode, type ResolvedLayoutTree, type RootFrame, type StackAlign, type StackArrange, type StackAxis, type StackJustify, type UiLength, applyOffset, assertFiniteNumber, assertNonNegativeGap, assertNonNegativePadding, assertNonNegativeSize, compileLayoutRows, flattenResolvedTree, formatRect, normalizePadding, parseMachinaText, parseMachinaTextInline, resolveFrame, resolveLayoutDocument, resolveLayoutRows, resolveUiLength, toResolvedTree };