@mildastudio/milda 0.1.0

package/dist/index.js

@@ -0,0 +1,3094 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// index.ts
+var index_exports = {};
+__export(index_exports, {
+  LexError: () => LexError,
+  TOKEN_VALUE_KIND: () => TOKEN_VALUE_KIND,
+  allTokensOfType: () => allTokensOfType,
+  archetypesByName: () => archetypesByName,
+  atomsByName: () => atomsByName,
+  collectActiveStates: () => collectActiveStates,
+  conformance: () => conformance,
+  findToken: () => findToken,
+  lex: () => lex,
+  parseMildaDocument: () => parseMildaDocument,
+  preludeV0: () => preludeV0,
+  resolveFacets: () => resolveFacets,
+  resolveLayout: () => resolveLayout,
+  resolveToken: () => resolveToken,
+  validate: () => validate
+});
+module.exports = __toCommonJS(index_exports);
+
+// types/tokens.ts
+var TOKEN_VALUE_KIND = {
+  color: "color",
+  spacing: "dimension",
+  radius: "dimension",
+  size: "dimension",
+  shadow: "shadow",
+  typography: "typography",
+  fontFamily: "fontFamily",
+  duration: "duration",
+  opacity: "opacity",
+  blur: "blur",
+  tonal: "tonal",
+  border: "border",
+  elevation: "facet",
+  ring: "facet",
+  backdrop: "facet",
+  none: "facet"
+};
+
+// prelude/preludeV0.ts
+var atoms = [
+  {
+    kind: "atom",
+    name: "activation",
+    doc: "invoke an action + emit event/payload on a trigger",
+    params: [{ name: "payload" }],
+    states: [{ id: "ready", initial: true }],
+    events: [{ name: "trigger" }],
+    transitions: [
+      {
+        from: "ready",
+        on: "trigger",
+        when: "enabled",
+        to: "ready",
+        emit: { event: "invoke", arg: "payload" }
+      }
+    ],
+    emits: [{ name: "invoke" }],
+    note: "transducer (single state); foundational atom under almost every interactive archetype"
+  },
+  {
+    kind: "atom",
+    name: "scheduler",
+    doc: "timed transition: auto-dismiss, auto-advance, debounce, delay",
+    modes: ["timeout", "debounce", "interval"],
+    params: [{ name: "t" }, { name: "mode" }],
+    states: [{ id: "idle", initial: true }, { id: "pending" }],
+    events: [{ name: "arm" }, { name: "cancel" }],
+    transitions: [
+      { from: "idle", on: "arm", to: "pending" },
+      { from: "pending", after: "t", to: "idle", emit: { event: "fire" } },
+      { from: "pending", on: "arm", to: "pending", note: "restart (debounce)" },
+      { from: "pending", on: "cancel", to: "idle" }
+    ],
+    emits: [{ name: "fire" }],
+    note: "load-bearing: all time-based interactions compose from it"
+  },
+  {
+    kind: "atom",
+    name: "toggle",
+    doc: "flip a boolean (BooleanInput core; tristate \u2192 +mixed)",
+    params: [{ name: "v", bind: true }],
+    states: [{ id: "off", initial: true }, { id: "on" }],
+    events: [{ name: "toggle" }, { name: "set", args: ["b"] }],
+    transitions: [
+      { from: "off", on: "toggle", to: "on", emit: { event: "change", arg: true } },
+      { from: "on", on: "toggle", to: "off", emit: { event: "change", arg: false } },
+      { from: "any", on: "set", to: { expr: "b?on:off" }, note: "controlled sync, no emit" }
+    ],
+    exposes: [{ state: "checked", when: "state==on" }],
+    emits: [{ name: "change" }]
+  },
+  {
+    kind: "atom",
+    name: "selection",
+    doc: "choose member(s) of a collection",
+    modes: ["single", "multiple", "range", "none"],
+    params: [{ name: "C" }, { name: "selected", bind: true }],
+    context: [{ name: "sel", type: "C|none", init: "none" }],
+    states: [{ id: "empty", initial: true }, { id: "chosen" }],
+    events: [{ name: "select", args: ["x"] }, { name: "clear" }, { name: "set", args: ["x"] }],
+    transitions: [
+      {
+        from: "any",
+        on: "select",
+        when: "x\u2208C",
+        to: "chosen",
+        ctx: [{ target: "sel", expr: "x" }],
+        emit: { event: "change", arg: "x" }
+      },
+      {
+        from: "chosen",
+        on: "clear",
+        to: "empty",
+        ctx: [{ target: "sel", expr: "none" }],
+        emit: { event: "change", arg: "none" }
+      },
+      {
+        from: "any",
+        on: "set",
+        to: { expr: "x?chosen:empty" },
+        ctx: [{ target: "sel", expr: "x" }],
+        note: "controlled sync, no emit"
+      }
+    ],
+    exposes: [{ state: "selected", arg: "x", when: "state==chosen \u2227 sel==x" }],
+    emits: [{ name: "change" }],
+    note: "multiple=set; range=anchor+extent (date range, shift-click, cell range)"
+  },
+  {
+    kind: "atom",
+    name: "browse",
+    doc: "move a cursor over a collection",
+    modes: ["roving", "spatial", "tree", "scroll-detent"],
+    requires: [{ anyOf: ["input.keyboard", "input.remote"], when: "mode\u2208{roving,tree}" }],
+    params: [{ name: "C" }, { name: "mode" }],
+    context: [{ name: "active", type: "C|none", init: "none" }],
+    events: [
+      { name: "move", args: ["dir"] },
+      { name: "to", args: ["x"] }
+    ],
+    transitions: [
+      {
+        from: "any",
+        on: "move",
+        to: "any",
+        ctx: [{ target: "active", expr: "neighbor(active,dir,mode,wrap)" }],
+        emit: { event: "activeChanged", arg: "active" }
+      },
+      {
+        from: "any",
+        on: "to",
+        to: "any",
+        ctx: [{ target: "active", expr: "x" }],
+        emit: { event: "activeChanged", arg: "x" }
+      }
+    ],
+    exposes: [{ state: "active", arg: "x", when: "active==x" }],
+    emits: [{ name: "activeChanged" }],
+    note: "neighbor(): roving=linear \xB7 spatial=2D \xB7 tree=in/out/sib \xB7 scroll-detent=nearest"
+  },
+  {
+    kind: "atom",
+    name: "presentation",
+    doc: "manage a surface",
+    modes: ["inline", "popover", "menu", "sheet", "dialog", "push", "wheel"],
+    params: [{ name: "surface" }],
+    states: [{ id: "closed", initial: true }, { id: "open" }],
+    events: [{ name: "open" }, { name: "close" }, { name: "toggle" }],
+    transitions: [
+      { from: "closed", on: "toggle|open", to: "open", emit: { event: "opened" } },
+      { from: "open", on: "toggle|close", to: "closed", emit: { event: "closed" } }
+    ],
+    exposes: [{ state: "open", when: "state==open" }],
+    emits: [{ name: "opened" }, { name: "closed" }],
+    note: "surface is realization-only"
+  },
+  {
+    kind: "atom",
+    name: "dismiss",
+    doc: "close on a configured trigger",
+    params: [{ name: "when" }],
+    states: [{ id: "armed", initial: true }],
+    events: [{ name: "trigger" }],
+    transitions: [
+      { from: "armed", on: "trigger", to: "armed", emit: { event: "dismissRequested" } }
+    ],
+    emits: [{ name: "dismissRequested" }],
+    note: "trigger \u2208 configured [outside, escape, commit, swipe-down, timeout]"
+  },
+  {
+    kind: "atom",
+    name: "focus-scope",
+    doc: "trap / contain / restore focus within a region (modal a11y)",
+    requires: [{ anyOf: ["input.keyboard", "input.remote"] }],
+    states: [{ id: "inactive", initial: true }, { id: "active" }],
+    events: [{ name: "activate" }, { name: "deactivate" }],
+    transitions: [
+      {
+        from: "inactive",
+        on: "activate",
+        to: "active",
+        note: "save prior focus; move focus into region; trap Tab"
+      },
+      {
+        from: "active",
+        on: "deactivate",
+        to: "inactive",
+        note: "release trap; restore prior focus"
+      }
+    ],
+    note: "no visual states (exposes none) \u2014 a behaviour guarantee, not a paint surface; realized as a focus trap on web, OS-owned on native sheets"
+  },
+  {
+    kind: "atom",
+    name: "value-entry",
+    doc: "free text/value entry; commit on change|blur|enter",
+    params: [{ name: "value", bind: true }, { name: "commit" }],
+    context: [
+      { name: "value", type: "V" },
+      { name: "draft", type: "V", init: "value" }
+    ],
+    states: [{ id: "idle", initial: true }, { id: "editing" }],
+    events: [
+      { name: "focus" },
+      { name: "input", args: ["t"] },
+      { name: "enter" },
+      { name: "blur" },
+      { name: "set", args: ["v"] }
+    ],
+    transitions: [
+      { from: "idle", on: "focus", to: "editing" },
+      {
+        from: "editing",
+        on: "input",
+        to: "editing",
+        ctx: [{ target: "draft", expr: "t" }],
+        when: "change\u2208commit",
+        emit: { event: "change", arg: "t" },
+        note: "value:=t only when change\u2208commit"
+      },
+      {
+        from: "editing",
+        on: "enter",
+        when: "enter\u2208commit",
+        to: "editing",
+        ctx: [{ target: "value", expr: "draft" }],
+        emit: { event: "change", arg: "draft" }
+      },
+      {
+        from: "editing",
+        on: "blur",
+        to: "idle",
+        note: "when blur\u2208commit: value:=draft, emit change(draft); else draft:=value"
+      },
+      {
+        from: "any",
+        on: "set",
+        to: "any",
+        ctx: [
+          { target: "value", expr: "v" },
+          { target: "draft", expr: "v" }
+        ],
+        note: "controlled, no emit"
+      }
+    ],
+    exposes: [
+      { state: "focused", when: "state==editing" },
+      { state: "empty", when: "value empty" },
+      { state: "dirty", when: "draft\u2260value" }
+    ],
+    emits: [{ name: "change" }]
+  },
+  {
+    kind: "atom",
+    name: "range",
+    doc: "value(s) along a min/max track (single/dual thumb)",
+    params: [
+      { name: "value", bind: true },
+      { name: "min" },
+      { name: "max" },
+      { name: "step" },
+      { name: "thumbs" }
+    ],
+    context: [
+      { name: "value", type: "V|{lo,hi}" },
+      { name: "active", type: "thumb|none", init: "none" }
+    ],
+    states: [{ id: "idle", initial: true }, { id: "dragging" }],
+    events: [
+      { name: "grab", args: ["t"] },
+      { name: "to", args: ["v"] },
+      { name: "release" },
+      { name: "by", args: ["t", "d"] },
+      { name: "set", args: ["v"] }
+    ],
+    transitions: [
+      { from: "idle", on: "grab", to: "dragging", ctx: [{ target: "active", expr: "t" }] },
+      {
+        from: "dragging",
+        on: "to",
+        to: "dragging",
+        ctx: [{ target: "value[active]", expr: "clamp+snap(v); lo\u2264hi" }],
+        emit: { event: "change", arg: "value" }
+      },
+      { from: "dragging", on: "release", to: "idle", emit: { event: "commit", arg: "value" } },
+      {
+        from: "idle",
+        on: "by",
+        to: "idle",
+        ctx: [{ target: "value[t]", expr: "clamp(value[t]+d)" }],
+        emit: { event: "change", arg: "value" },
+        note: "keyboard"
+      },
+      { from: "any", on: "set", to: "any", ctx: [{ target: "value", expr: "v" }] }
+    ],
+    exposes: [{ state: "active", arg: "t", when: "state==dragging \u2227 active==t" }],
+    emits: [{ name: "change" }, { name: "commit" }],
+    note: "live (change) vs committed (commit)"
+  },
+  {
+    kind: "atom",
+    name: "stepping",
+    doc: "increment/decrement a value",
+    params: [{ name: "value", bind: true }, { name: "min" }, { name: "max" }, { name: "step" }],
+    context: [{ name: "value", type: "number" }],
+    events: [{ name: "inc" }, { name: "dec" }, { name: "set", args: ["v"] }],
+    transitions: [
+      {
+        from: "any",
+        on: "inc",
+        when: "value+step\u2264max",
+        to: "any",
+        ctx: [{ target: "value", expr: "value+step" }],
+        emit: { event: "change", arg: "value" }
+      },
+      {
+        from: "any",
+        on: "dec",
+        when: "value-step\u2265min",
+        to: "any",
+        ctx: [{ target: "value", expr: "value-step" }],
+        emit: { event: "change", arg: "value" }
+      },
+      { from: "any", on: "set", to: "any", ctx: [{ target: "value", expr: "clamp(v)" }] }
+    ],
+    exposes: [
+      { state: "atMin", when: "value\u2264min" },
+      { state: "atMax", when: "value\u2265max" }
+    ],
+    emits: [{ name: "change" }]
+  },
+  {
+    kind: "atom",
+    name: "validation",
+    doc: "valid/invalid against rules (PURE \u2014 does not listen to input)",
+    params: [{ name: "value" }, { name: "rules" }],
+    context: [{ name: "errors", type: "list", init: "[]" }],
+    states: [{ id: "pristine", initial: true }, { id: "valid" }, { id: "invalid" }],
+    events: [{ name: "check" }, { name: "reset" }],
+    transitions: [
+      {
+        from: "any",
+        on: "check",
+        to: { expr: "eval(rules)?valid:invalid" },
+        ctx: [{ target: "errors", expr: "eval(rules).errors" }]
+      },
+      { from: "any", on: "reset", to: "pristine", ctx: [{ target: "errors", expr: "[]" }] }
+    ],
+    exposes: [
+      { state: "invalid", when: "state==invalid" },
+      { state: "valid", when: "state==valid" },
+      { state: "pristine", when: "state==pristine" }
+    ],
+    emits: [{ name: "validity" }],
+    note: "the when:change|blur|submit policy = a wire from value-entry/submission into check"
+  },
+  {
+    kind: "atom",
+    name: "submission",
+    doc: "form-level orchestration: collective validation, submit, focus-first-error",
+    params: [{ name: "fields" }],
+    context: [{ name: "fields", type: "set<validation>" }],
+    states: [{ id: "editing", initial: true }, { id: "submitting" }, { id: "submitted" }],
+    events: [{ name: "submit" }, { name: "success" }, { name: "failure", args: ["e"] }],
+    transitions: [
+      {
+        from: "editing",
+        on: "submit",
+        to: "editing",
+        do: "broadcast fields.check",
+        note: "when allValid \u2192 submitting emit submitStart(values); else \u2192 editing do firstInvalid.focus"
+      },
+      { from: "submitting", on: "success", to: "submitted", emit: { event: "submitSuccess" } },
+      {
+        from: "submitting",
+        on: "failure",
+        to: "editing",
+        emit: { event: "submitError", arg: "e" }
+      }
+    ],
+    exposes: [
+      { state: "loading", when: "state==submitting" },
+      { state: "dirty", when: "any(fields,f\u2192f.dirty)" }
+    ],
+    emits: [{ name: "submitStart" }, { name: "submitSuccess" }, { name: "submitError" }],
+    note: "fields: DYNAMIC set of validation machines; FAN-OUT broadcast + FAN-IN aggregate/select"
+  },
+  {
+    kind: "atom",
+    name: "gesture",
+    doc: "swipe | long-press | pinch | pan | drag | drop",
+    modes: ["swipe", "long-press", "pinch", "pan", "drag", "drop"],
+    requires: [{ anyOf: ["input.touch"], when: "per gesture" }],
+    params: [{ name: "kind" }, { name: "thresholds" }],
+    context: [{ name: "start" }, { name: "current" }, { name: "t0" }],
+    states: [{ id: "idle", initial: true }, { id: "tracking" }, { id: "recognized" }],
+    events: [{ name: "down", args: ["p"] }, { name: "move", args: ["p"] }, { name: "up" }],
+    transitions: [
+      { from: "idle", on: "down", to: "tracking", ctx: [{ target: "start", expr: "p" }] },
+      {
+        from: "tracking",
+        on: "move",
+        to: "tracking",
+        ctx: [{ target: "current", expr: "p" }],
+        when: "exceeds(\u03B8)",
+        emit: { event: "begin" },
+        note: "recognized when threshold exceeded"
+      },
+      {
+        from: "tracking",
+        after: "t",
+        to: "recognized",
+        emit: { event: "begin" },
+        note: "long-press"
+      },
+      { from: "tracking", on: "up", to: "idle", note: "canceled, threshold not met" },
+      { from: "recognized", on: "move", to: "recognized", emit: { event: "update", arg: "delta" } },
+      { from: "recognized", on: "up", to: "idle", emit: { event: "end" } }
+    ],
+    exposes: [{ state: "dragging", when: "state==recognized" }],
+    emits: [{ name: "begin" }, { name: "update" }, { name: "end" }],
+    note: "load-bearing: all drag-based interactions compose from it"
+  },
+  {
+    kind: "atom",
+    name: "async-state",
+    doc: "idle | loading | success | error lifecycle",
+    states: [{ id: "idle", initial: true }, { id: "loading" }, { id: "success" }, { id: "error" }],
+    events: [{ name: "start" }, { name: "resolve", args: ["v"] }, { name: "reject", args: ["e"] }],
+    transitions: [
+      { from: "any", on: "start", to: "loading", do: "run" },
+      { from: "loading", on: "resolve", to: "success", emit: { event: "success", arg: "v" } },
+      { from: "loading", on: "reject", to: "error", emit: { event: "error", arg: "e" } }
+    ],
+    exposes: [
+      { state: "loading", when: "state==loading" },
+      { state: "success", when: "state==success" },
+      { state: "error", when: "state==error" }
+    ],
+    emits: [{ name: "success" }, { name: "error" }]
+  },
+  {
+    kind: "atom",
+    name: "navigation",
+    doc: "switch between destinations (carries a history stack)",
+    params: [{ name: "dests" }],
+    context: [{ name: "stack", type: "list", init: "[root]" }],
+    events: [{ name: "go", args: ["d"] }, { name: "back" }],
+    transitions: [
+      {
+        from: "any",
+        on: "go",
+        to: "any",
+        ctx: [{ target: "stack", expr: "stack.push(d)" }],
+        emit: { event: "navigate", arg: "current" }
+      },
+      {
+        from: "any",
+        on: "back",
+        when: "|stack|>1",
+        to: "any",
+        ctx: [{ target: "stack", expr: "stack.pop()" }],
+        emit: { event: "navigate", arg: "current" }
+      }
+    ],
+    exposes: [{ state: "current", arg: "d", when: "current==d" }],
+    emits: [{ name: "navigate" }],
+    note: "history stack shared with undo/redo, wizard-back; richer than selection.single + activation"
+  },
+  {
+    kind: "atom",
+    name: "scroll",
+    doc: "observe scroll position: infinite-load, scroll-spy, reveal-on-scroll, parallax",
+    params: [{ name: "region" }],
+    context: [{ name: "pos", init: "0" }],
+    events: [{ name: "scrolled", args: ["p"] }],
+    transitions: [
+      {
+        from: "any",
+        on: "scrolled",
+        to: "any",
+        ctx: [{ target: "pos", expr: "p" }],
+        emit: { event: "atEnd", arg: "p" },
+        note: "emit atEnd when p\u2265max, nearEnd when p\u2265max-\u03B8"
+      }
+    ],
+    exposes: [
+      { state: "atStart", when: "pos\u22640" },
+      { state: "atEnd", when: "pos\u2265max" },
+      { state: "scrolled", when: "pos>0" }
+    ],
+    emits: [{ name: "atEnd" }, { name: "nearEnd" }],
+    note: "atEnd \u2192 wire \u2192 async-state.start = infinite-load"
+  },
+  {
+    kind: "atom",
+    name: "progress",
+    doc: "determinate / indeterminate completion",
+    modes: ["determinate", "indeterminate"],
+    params: [{ name: "value" }, { name: "max" }],
+    events: [{ name: "set", args: ["v"] }],
+    transitions: [
+      {
+        from: "any",
+        on: "set",
+        to: "any",
+        ctx: [{ target: "value", expr: "v" }],
+        emit: { event: "change", arg: "value" }
+      }
+    ],
+    exposes: [{ state: "complete", when: "value\u2265max" }],
+    emits: [{ name: "change" }]
+  },
+  {
+    kind: "atom",
+    name: "liveness",
+    doc: "announce dynamic changes (polite/assertive)",
+    modes: ["polite", "assertive"],
+    requires: [{ anyOf: ["a11y.screenreader"] }],
+    events: [{ name: "announce", args: ["msg"] }],
+    transitions: [
+      { from: "any", on: "announce", to: "any", emit: { event: "announced", arg: "msg" } }
+    ],
+    emits: [{ name: "announced" }]
+  }
+];
+var composites = [
+  {
+    kind: "composite",
+    name: "disclosure",
+    builtFrom: ["toggle", "presentation"],
+    uses: [
+      { atom: "toggle", as: "T" },
+      { atom: "presentation", as: "P", params: { surface: "inline" } }
+    ],
+    composition: [{ kind: "wire", from: "T.change", to: "P.toggle" }],
+    note: "\u2248 toggle(expanded) + presentation(inline); exposes expanded"
+  },
+  {
+    kind: "composite",
+    name: "typeahead",
+    builtFrom: ["scheduler", "browse"],
+    uses: [
+      { atom: "scheduler", as: "S", params: { mode: "debounce" } },
+      { atom: "browse", as: "B" }
+    ],
+    note: "jump to a member by typed prefix; requires input.keyboard"
+  },
+  {
+    kind: "composite",
+    name: "dnd",
+    builtFrom: ["gesture", "ordering"],
+    note: "drag-and-drop move/reorder across containers; ordering is a non-behavior (collection mutation)"
+  },
+  {
+    kind: "composite",
+    name: "resize",
+    builtFrom: ["gesture"],
+    uses: [{ atom: "gesture", as: "G", params: { kind: "drag" } }],
+    note: "drag-resize a region/panel; requires input.pointer"
+  },
+  {
+    kind: "composite",
+    name: "auto-dismiss",
+    builtFrom: ["scheduler"],
+    uses: [{ atom: "scheduler", as: "S", params: { mode: "timeout" } }],
+    composition: [{ kind: "wire", from: "S.fire", to: "dismissRequested" }],
+    note: "self-close after a timeout (toast)"
+  },
+  {
+    kind: "composite",
+    name: "stepping-nav",
+    builtFrom: ["navigation"],
+    note: "\u2248 navigation(ordered) + constraint; ordered progress through steps; exposes active, complete"
+  },
+  {
+    kind: "composite",
+    name: "pressability",
+    builtFrom: ["gesture"],
+    note: "press/hover/active feedback (ripple, highlight); contributes pressed/hovered feedback states ONLY \u2014 does not fire the action (that is activation)"
+  }
+];
+var archetypes = [
+  {
+    kind: "archetype",
+    name: "Button",
+    group: "Actions",
+    contract: "label/icon, fires action",
+    produces: { level: "phrase", interactive: true },
+    anatomy: [
+      { name: "icon", role: "icon", optional: true },
+      { name: "label", role: "text" }
+    ],
+    composes: ["activation", "pressability", "async-state?"],
+    realizationNote: "Material FAB/elevated/tonal; iOS .borderedProminent"
+  },
+  {
+    kind: "archetype",
+    name: "ToggleButton",
+    group: "Actions",
+    contract: "on/off action",
+    produces: { level: "phrase", interactive: true },
+    anatomy: [
+      { name: "indicator", role: "icon", optional: true },
+      { name: "label", role: "text" }
+    ],
+    composes: ["toggle", "pressability"]
+  },
+  {
+    kind: "archetype",
+    name: "MenuButton",
+    group: "Actions",
+    contract: "opens a menu of actions",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      {
+        name: "trigger",
+        role: "control",
+        children: [
+          { name: "label", role: "text" },
+          { name: "indicator", role: "icon", optional: true }
+        ]
+      },
+      {
+        name: "surface",
+        role: "container",
+        children: [{ name: "item", role: "item", children: [{ name: "label", role: "text" }] }]
+      }
+    ],
+    composes: ["presentation", "browse", "typeahead?", "dismiss"]
+  },
+  {
+    kind: "archetype",
+    name: "Link",
+    group: "Actions",
+    contract: "navigates",
+    produces: { level: "phrase", interactive: true },
+    anatomy: [
+      { name: "label", role: "text" },
+      { name: "icon", role: "icon", optional: true }
+    ],
+    composes: ["activation", "pressability"]
+  },
+  {
+    kind: "archetype",
+    name: "Form",
+    group: "Inputs",
+    contract: "a set of fields, one submit",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      { name: "content", role: "container" },
+      { name: "submit", role: "control", children: [{ name: "label", role: "text" }] },
+      { name: "error", role: "text", optional: true }
+    ],
+    composes: ["submission"]
+  },
+  {
+    kind: "archetype",
+    name: "Field",
+    group: "Inputs",
+    contract: "label + control + error/help wrapper",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      { name: "label", role: "text" },
+      { name: "control", role: "container" },
+      { name: "help", role: "text", optional: true },
+      { name: "error", role: "text", optional: true }
+    ],
+    composes: ["validation"]
+  },
+  {
+    kind: "archetype",
+    name: "TextField",
+    group: "Inputs",
+    contract: "string value",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      { name: "icon", role: "icon", optional: true },
+      { name: "control", role: "input" }
+    ],
+    composes: ["value-entry", "validation?"]
+  },
+  {
+    kind: "archetype",
+    name: "TextArea",
+    group: "Inputs",
+    contract: "multiline string value",
+    produces: { level: "region", interactive: false },
+    anatomy: [{ name: "control", role: "input" }],
+    composes: ["value-entry", "validation?"]
+  },
+  {
+    kind: "archetype",
+    name: "SearchField",
+    group: "Inputs",
+    contract: "query string + clear",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      { name: "icon", role: "icon", optional: true },
+      { name: "control", role: "input" },
+      { name: "clear", role: "control", optional: true }
+    ],
+    composes: ["value-entry", "filter?"]
+  },
+  {
+    kind: "archetype",
+    name: "BooleanInput",
+    group: "Inputs",
+    contract: "one bool",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      { name: "control", role: "input" },
+      { name: "indicator", role: "icon" },
+      { name: "label", role: "text", optional: true }
+    ],
+    composes: ["toggle"],
+    realizationNote: "iOS: checkbox \u2192 switch (no indeterminate)"
+  },
+  {
+    kind: "archetype",
+    name: "ChoiceGroup",
+    group: "Inputs",
+    contract: "one-of-N",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      {
+        name: "option",
+        role: "item",
+        children: [
+          { name: "indicator", role: "icon" },
+          { name: "label", role: "text" }
+        ]
+      }
+    ],
+    composes: ["selection.single", "browse"],
+    realizationNote: "radio stack | segmented (node.group); iOS: radio \u2192 wheel/segmented"
+  },
+  {
+    kind: "archetype",
+    name: "SingleSelect",
+    group: "Inputs",
+    contract: "one of a known set",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      {
+        name: "trigger",
+        role: "control",
+        children: [
+          { name: "value", role: "text" },
+          { name: "indicator", role: "icon" }
+        ]
+      },
+      {
+        name: "surface",
+        role: "container",
+        children: [
+          {
+            name: "option",
+            role: "item",
+            children: [
+              { name: "check", role: "icon", optional: true },
+              { name: "label", role: "text" }
+            ]
+          }
+        ]
+      }
+    ],
+    composes: ["selection.single", "presentation", "browse", "dismiss", "typeahead?"],
+    uses: [
+      { atom: "activation", as: "A" },
+      { atom: "presentation", as: "P", params: { surface: "popover" } },
+      { atom: "selection", as: "S", params: { mode: "single", over: "options" } },
+      { atom: "browse", as: "B", params: { over: "options", mode: "roving" } },
+      { atom: "dismiss", as: "D", params: { when: "[outside,escape]" } }
+    ],
+    composition: [
+      { kind: "wire", from: "A.invoke", to: "P.toggle" },
+      { kind: "wire", from: "P.opened", to: "B.to", arg: "S.sel ?? first" },
+      { kind: "gate", machine: "D", activeWhen: "P.open" },
+      { kind: "wire", from: "D.dismissRequested", to: "P.close" },
+      { kind: "wire", from: "option-activate", to: "S.select", arg: "B.active" },
+      { kind: "wire", from: "S.change", to: "P.close", when: "closeOnSelect" }
+    ],
+    exposes: [
+      { state: "open", when: "P.open" },
+      { state: "selected", when: "S.selected" },
+      { state: "active", when: "B.active" }
+    ],
+    emits: [{ name: "change", from: "S.change" }],
+    realize: [
+      {
+        target: "web",
+        surface: "popover",
+        browse: "roving",
+        commit: "explicit",
+        note: "place bottom-start; flip; matchWidth; commit on click/enter"
+      },
+      {
+        target: "ios",
+        when: "style=wheel",
+        surface: "inline-wheel",
+        browse: "scroll-detent",
+        commit: "continuous",
+        drop: ["activation", "dismiss"],
+        wire: [{ from: "B.active-changed", to: "S.select", arg: "B.active" }]
+      }
+    ],
+    realizationNote: "web popover-listbox \xB7 Android dropdown/dialog \xB7 iOS menu/sheet/push/wheel"
+  },
+  {
+    kind: "archetype",
+    name: "MultiSelect",
+    group: "Inputs",
+    contract: "subset of a set",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      {
+        name: "trigger",
+        role: "control",
+        children: [
+          { name: "value", role: "text" },
+          { name: "indicator", role: "icon" }
+        ]
+      },
+      {
+        name: "surface",
+        role: "container",
+        children: [
+          {
+            name: "option",
+            role: "item",
+            children: [
+              { name: "check", role: "icon" },
+              { name: "label", role: "text" }
+            ]
+          }
+        ]
+      }
+    ],
+    composes: ["selection.multiple", "presentation", "browse", "dismiss"]
+  },
+  {
+    kind: "archetype",
+    name: "Combobox",
+    group: "Inputs",
+    contract: "filtered single-select w/ entry",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      { name: "control", role: "input" },
+      {
+        name: "surface",
+        role: "container",
+        children: [{ name: "option", role: "item", children: [{ name: "label", role: "text" }] }]
+      }
+    ],
+    composes: ["value-entry", "filter", "selection.single", "browse", "presentation", "dismiss"]
+  },
+  {
+    kind: "archetype",
+    name: "Slider",
+    group: "Inputs",
+    contract: "value(s) on a range",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      {
+        name: "track",
+        role: "container",
+        children: [
+          { name: "range", role: "container", optional: true },
+          { name: "thumb", role: "control" }
+        ]
+      },
+      { name: "value", role: "text", optional: true }
+    ],
+    composes: ["range", "gesture(pan)"]
+  },
+  {
+    kind: "archetype",
+    name: "Stepper",
+    group: "Inputs",
+    contract: "number \xB1",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      { name: "decrement", role: "control", children: [{ name: "icon", role: "icon" }] },
+      { name: "control", role: "input" },
+      { name: "increment", role: "control", children: [{ name: "icon", role: "icon" }] }
+    ],
+    composes: ["stepping", "value-entry"]
+  },
+  {
+    kind: "archetype",
+    name: "DatePicker",
+    group: "Inputs",
+    contract: "date value",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      {
+        name: "trigger",
+        role: "control",
+        children: [
+          { name: "value", role: "text" },
+          { name: "icon", role: "icon" }
+        ]
+      },
+      {
+        name: "surface",
+        role: "container",
+        children: [
+          {
+            name: "header",
+            role: "container",
+            children: [
+              { name: "prev", role: "control" },
+              { name: "title", role: "text" },
+              { name: "next", role: "control" }
+            ]
+          },
+          {
+            name: "grid",
+            role: "container",
+            children: [{ name: "day", role: "item", children: [{ name: "label", role: "text" }] }]
+          }
+        ]
+      }
+    ],
+    composes: ["selection.single", "presentation", "browse", "dismiss", "masking"],
+    realizationNote: "web calendar-grid \xB7 iOS wheel (momentum+detent+haptic) \xB7 Android dialog"
+  },
+  {
+    kind: "archetype",
+    name: "TimePicker",
+    group: "Inputs",
+    contract: "time value",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      {
+        name: "trigger",
+        role: "control",
+        children: [
+          { name: "value", role: "text" },
+          { name: "icon", role: "icon" }
+        ]
+      },
+      {
+        name: "surface",
+        role: "container",
+        children: [
+          {
+            name: "column",
+            role: "item",
+            children: [
+              { name: "option", role: "item", children: [{ name: "label", role: "text" }] }
+            ]
+          }
+        ]
+      }
+    ],
+    composes: ["selection.single", "presentation", "browse", "dismiss", "masking"],
+    realizationNote: "iOS wheel \xB7 Android dialog"
+  },
+  {
+    kind: "archetype",
+    name: "ColorPicker",
+    group: "Inputs",
+    contract: "color value",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      {
+        name: "trigger",
+        role: "control",
+        children: [
+          { name: "swatch", role: "icon" },
+          { name: "value", role: "text" }
+        ]
+      },
+      {
+        name: "surface",
+        role: "container",
+        children: [
+          { name: "area", role: "container" },
+          { name: "hue", role: "container" },
+          { name: "input", role: "input" }
+        ]
+      }
+    ],
+    composes: ["range", "value-entry", "presentation", "dismiss"]
+  },
+  {
+    kind: "archetype",
+    name: "FileUpload",
+    group: "Inputs",
+    contract: "file(s)",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      {
+        name: "dropzone",
+        role: "container",
+        children: [
+          { name: "icon", role: "icon" },
+          { name: "label", role: "text" }
+        ]
+      },
+      { name: "input", role: "input" },
+      {
+        name: "list",
+        role: "container",
+        optional: true,
+        children: [
+          {
+            name: "item",
+            role: "item",
+            children: [
+              { name: "name", role: "text" },
+              { name: "remove", role: "control" }
+            ]
+          }
+        ]
+      }
+    ],
+    composes: ["activation", "gesture(drop)?", "async-state"]
+  },
+  {
+    kind: "archetype",
+    name: "TagsInput",
+    group: "Inputs",
+    contract: "list of tokens",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      {
+        name: "tag",
+        role: "item",
+        children: [
+          { name: "label", role: "text" },
+          { name: "remove", role: "control" }
+        ]
+      },
+      { name: "control", role: "input" }
+    ],
+    composes: ["value-entry", "selection.multiple"]
+  },
+  {
+    kind: "archetype",
+    name: "Rating",
+    group: "Inputs",
+    contract: "discrete score",
+    produces: { level: "region", interactive: false },
+    anatomy: [{ name: "item", role: "item", children: [{ name: "icon", role: "icon" }] }],
+    composes: ["selection.single", "pressability"]
+  },
+  {
+    kind: "archetype",
+    name: "Disclosure",
+    group: "Disclosure",
+    contract: "expand region (a.k.a. Collapsible)",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      {
+        name: "trigger",
+        role: "control",
+        children: [
+          { name: "label", role: "text" },
+          { name: "indicator", role: "icon" }
+        ]
+      },
+      { name: "panel", role: "container" }
+    ],
+    composes: ["disclosure"]
+  },
+  {
+    kind: "archetype",
+    name: "Accordion",
+    group: "Disclosure",
+    contract: "group of disclosures (single/multi)",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      {
+        name: "item",
+        role: "item",
+        children: [
+          {
+            name: "header",
+            role: "control",
+            children: [
+              { name: "label", role: "text" },
+              { name: "indicator", role: "icon" }
+            ]
+          },
+          { name: "panel", role: "container" }
+        ]
+      }
+    ],
+    composes: ["disclosure", "selection"]
+  },
+  {
+    kind: "archetype",
+    name: "Tabs",
+    group: "Disclosure",
+    contract: "switch panels",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      {
+        name: "list",
+        role: "container",
+        children: [{ name: "tab", role: "control", children: [{ name: "label", role: "text" }] }]
+      },
+      { name: "panel", role: "container" }
+    ],
+    composes: ["navigation", "browse"],
+    realizationNote: "mobile: swipe-between; web: no swipe"
+  },
+  {
+    kind: "archetype",
+    name: "Dialog",
+    group: "Disclosure",
+    contract: "blocking layer (a.k.a. Modal)",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      { name: "trigger", role: "control", children: [{ name: "label", role: "text" }] },
+      { name: "backdrop", role: "container", optional: true },
+      {
+        name: "surface",
+        role: "container",
+        children: [
+          { name: "title", role: "text" },
+          { name: "content", role: "container" },
+          { name: "close", role: "control", optional: true }
+        ]
+      }
+    ],
+    composes: ["presentation(dialog)", "focus-scope", "dismiss", "backdrop"],
+    realizationNote: "iOS sheet w/ detents"
+  },
+  {
+    kind: "archetype",
+    name: "Drawer",
+    group: "Disclosure",
+    contract: "edge-anchored panel (a.k.a. Sidebar)",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      { name: "trigger", role: "control" },
+      { name: "backdrop", role: "container", optional: true },
+      {
+        name: "surface",
+        role: "container",
+        children: [
+          { name: "content", role: "container" },
+          { name: "close", role: "control", optional: true }
+        ]
+      }
+    ],
+    composes: ["presentation(sheet)", "focus-scope", "dismiss", "gesture(swipe)?"]
+  },
+  {
+    kind: "archetype",
+    name: "Popover",
+    group: "Disclosure",
+    contract: "anchored transient layer",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      { name: "trigger", role: "control" },
+      { name: "surface", role: "container", children: [{ name: "content", role: "container" }] }
+    ],
+    composes: ["presentation(popover)", "anchoring", "dismiss"]
+  },
+  {
+    kind: "archetype",
+    name: "Tooltip",
+    group: "Disclosure",
+    contract: "hover/focus hint",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      { name: "trigger", role: "control" },
+      { name: "surface", role: "container", children: [{ name: "content", role: "text" }] }
+    ],
+    composes: ["presentation(popover)", "anchoring"],
+    realizationNote: "requires input.pointer \u2192 tap/long-press fallback"
+  },
+  {
+    kind: "archetype",
+    name: "ContextMenu",
+    group: "Disclosure",
+    contract: "secondary-action menu",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      {
+        name: "surface",
+        role: "container",
+        children: [
+          {
+            name: "item",
+            role: "item",
+            children: [
+              { name: "icon", role: "icon", optional: true },
+              { name: "label", role: "text" }
+            ]
+          }
+        ]
+      }
+    ],
+    composes: ["presentation(menu)", "browse", "dismiss"],
+    realizationNote: "right-click / long-press"
+  },
+  {
+    kind: "archetype",
+    name: "Menu",
+    group: "Navigation",
+    contract: "hierarchical actions (a.k.a. MenuBar)",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      {
+        name: "surface",
+        role: "container",
+        children: [
+          {
+            name: "item",
+            role: "item",
+            children: [
+              { name: "icon", role: "icon", optional: true },
+              { name: "label", role: "text" }
+            ]
+          }
+        ]
+      }
+    ],
+    composes: ["presentation", "browse", "typeahead?", "dismiss"]
+  },
+  {
+    kind: "archetype",
+    name: "NavigationBar",
+    group: "Navigation",
+    contract: "top-level destinations",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      {
+        name: "item",
+        role: "item",
+        children: [
+          { name: "icon", role: "icon", optional: true },
+          { name: "label", role: "text" }
+        ]
+      }
+    ],
+    composes: ["navigation"],
+    realizationNote: "web top-nav \xB7 iOS tab-bar \xB7 Android bottom-nav/rail"
+  },
+  {
+    kind: "archetype",
+    name: "Breadcrumbs",
+    group: "Navigation",
+    contract: "path trail",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      { name: "item", role: "item", children: [{ name: "label", role: "text" }] },
+      { name: "separator", role: "icon", optional: true }
+    ],
+    composes: ["navigation"],
+    realizationNote: "iOS: \u2192 nav title + back"
+  },
+  {
+    kind: "archetype",
+    name: "Pagination",
+    group: "Navigation",
+    contract: "page index",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      { name: "previous", role: "control" },
+      { name: "item", role: "item", children: [{ name: "label", role: "text" }] },
+      { name: "next", role: "control" }
+    ],
+    composes: ["navigation", "stepping"]
+  },
+  {
+    kind: "archetype",
+    name: "Tree",
+    group: "Navigation",
+    contract: "hierarchical collection",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      {
+        name: "item",
+        role: "item",
+        children: [
+          { name: "indicator", role: "icon" },
+          { name: "label", role: "text" }
+        ]
+      }
+    ],
+    composes: ["disclosure", "browse", "selection"]
+  },
+  {
+    kind: "archetype",
+    name: "Wizard",
+    group: "Navigation",
+    contract: "ordered flow (a.k.a. Stepper-nav)",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      {
+        name: "step",
+        role: "item",
+        children: [
+          { name: "indicator", role: "icon" },
+          { name: "label", role: "text" }
+        ]
+      },
+      { name: "content", role: "container" },
+      { name: "back", role: "control" },
+      { name: "next", role: "control" }
+    ],
+    composes: ["stepping-nav"]
+  },
+  {
+    kind: "archetype",
+    name: "List",
+    group: "Collections",
+    contract: "ordered items, optional select (a.k.a. ListBox)",
+    produces: { level: "region", interactive: false },
+    anatomy: [{ name: "item", role: "item", children: [{ name: "content", role: "container" }] }],
+    composes: ["browse", "selection?", "virtualization?"],
+    realizationNote: "iOS list: swipe-to-delete (gesture)"
+  },
+  {
+    kind: "archetype",
+    name: "Table",
+    group: "Collections",
+    contract: "rows\xD7cols, sort/select (a.k.a. DataGrid)",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      {
+        name: "header",
+        role: "container",
+        children: [{ name: "column", role: "item", children: [{ name: "label", role: "text" }] }]
+      },
+      {
+        name: "body",
+        role: "container",
+        children: [{ name: "row", role: "item", children: [{ name: "cell", role: "item" }] }]
+      }
+    ],
+    composes: ["selection?", "ordering", "browse", "resize?", "virtualization?"],
+    realizationNote: "aggregation/grouping is data, not a behavior"
+  },
+  {
+    kind: "archetype",
+    name: "Carousel",
+    group: "Collections",
+    contract: "paged horizontal items",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      { name: "viewport", role: "container", children: [{ name: "slide", role: "item" }] },
+      { name: "previous", role: "control", optional: true },
+      { name: "next", role: "control", optional: true }
+    ],
+    composes: ["browse", "momentum-scroll", "gesture(swipe)"]
+  },
+  {
+    kind: "archetype",
+    name: "Grid",
+    group: "Collections",
+    contract: "2D arrangement of items",
+    produces: { level: "region", interactive: false },
+    anatomy: [{ name: "item", role: "item" }],
+    composes: ["browse", "selection?"]
+  },
+  {
+    kind: "archetype",
+    name: "Toast",
+    group: "Feedback",
+    contract: "transient message (a.k.a. Snackbar)",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      { name: "icon", role: "icon", optional: true },
+      { name: "content", role: "text" },
+      { name: "action", role: "control", optional: true },
+      { name: "close", role: "control", optional: true }
+    ],
+    composes: ["presentation", "auto-dismiss", "liveness"],
+    realizationNote: "iOS: top banner; Android: snackbar bottom"
+  },
+  {
+    kind: "archetype",
+    name: "Alert",
+    group: "Feedback",
+    contract: "inline persistent message (a.k.a. Banner)",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      { name: "icon", role: "icon", optional: true },
+      { name: "title", role: "text", optional: true },
+      { name: "content", role: "text" },
+      { name: "close", role: "control", optional: true }
+    ],
+    composes: ["liveness"]
+  },
+  {
+    kind: "archetype",
+    name: "ProgressBar",
+    group: "Feedback",
+    contract: "completion feedback (a.k.a. Spinner)",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      { name: "track", role: "container", children: [{ name: "indicator", role: "container" }] },
+      { name: "label", role: "text", optional: true }
+    ],
+    composes: ["progress", "liveness"]
+  },
+  {
+    kind: "archetype",
+    name: "Skeleton",
+    group: "Feedback",
+    contract: "loading placeholder",
+    produces: { level: "region", interactive: false },
+    composes: ["async-state"]
+  },
+  {
+    kind: "archetype",
+    name: "Badge",
+    group: "Feedback",
+    contract: "numeric/status decoration",
+    produces: { level: "phrase", interactive: false },
+    anatomy: [{ name: "label", role: "text" }],
+    composes: []
+  },
+  {
+    kind: "archetype",
+    name: "Meter",
+    group: "Feedback",
+    contract: "numeric gauge",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      { name: "track", role: "container", children: [{ name: "indicator", role: "container" }] },
+      { name: "label", role: "text", optional: true }
+    ],
+    composes: []
+  },
+  {
+    kind: "archetype",
+    name: "EmptyState",
+    group: "Feedback",
+    contract: "no-content placeholder",
+    produces: { level: "region", interactive: false },
+    anatomy: [
+      { name: "icon", role: "icon", optional: true },
+      { name: "title", role: "text" },
+      { name: "description", role: "text", optional: true },
+      { name: "action", role: "control", optional: true }
+    ],
+    composes: []
+  },
+  {
+    kind: "archetype",
+    name: "Avatar",
+    group: "Media",
+    contract: "identity image/initials",
+    produces: { level: "phrase", interactive: false },
+    anatomy: [
+      { name: "image", role: "content" },
+      { name: "fallback", role: "text", optional: true },
+      { name: "badge", role: "icon", optional: true }
+    ],
+    composes: []
+  },
+  {
+    kind: "archetype",
+    name: "Image",
+    group: "Media",
+    contract: "bitmap w/ alt + fit",
+    produces: { level: "phrase", interactive: false },
+    composes: []
+  },
+  {
+    kind: "archetype",
+    name: "Icon",
+    group: "Media",
+    contract: "vector glyph from a set",
+    produces: { level: "phrase", interactive: false },
+    composes: []
+  },
+  {
+    kind: "archetype",
+    name: "AspectRatio",
+    group: "Media",
+    contract: "ratio-locked box",
+    produces: { level: "region", interactive: false },
+    anatomy: [{ name: "content", role: "container" }],
+    composes: [],
+    realizationNote: "layout facet, not a behavioral archetype"
+  }
+];
+var facets = [
+  { name: "fill", covers: "surface/background" },
+  { name: "ink", covers: "text + icon foreground" },
+  {
+    name: "border",
+    covers: "edge: color + width (hairline|thin|thick) + style",
+    divergence: "iOS often overlay-stroke"
+  },
+  { name: "corner", covers: "corner radius (token role)" },
+  { name: "inset", covers: "internal padding (block/inline)" },
+  { name: "gap", covers: "spacing between children" },
+  {
+    name: "text",
+    covers: "typography role (body|caption|title\u2026) \u2014 bundles size/weight/line/tracking",
+    divergence: "iOS Dynamic Type = OS-resolved role"
+  },
+  {
+    name: "textClamp",
+    covers: "truncate to N lines + ellipsis",
+    divergence: "web -webkit-line-clamp \xB7 .lineLimit \xB7 maxLines+overflow"
+  },
+  { name: "textWrap", covers: "wrap | nowrap | break" },
+  {
+    name: "elevation",
+    covers: "depth",
+    divergence: "web box-shadow \xB7 Android tonal-elevation \xB7 iOS none/sheet"
+  },
+  {
+    name: "overlay",
+    covers: "state layer (Material hover/press tint)",
+    divergence: "Material-specific; web \u2248 bg shift"
+  },
+  { name: "opacity", covers: "transparency" },
+  {
+    name: "ring",
+    covers: "focus indicator",
+    divergence: "desktop ring \xB7 mobile none \xB7 tv strong highlight"
+  },
+  { name: "backdrop", covers: "scrim / blur behind layer", divergence: "iOS material/vibrancy" }
+];
+var states = [
+  { name: "pressed", from: "pressability" },
+  { name: "hovered", from: "pressability" },
+  { name: "focused", from: "value-entry" },
+  { name: "active", from: "browse" },
+  { name: "selected", from: "selection" },
+  { name: "checked", from: "toggle" },
+  { name: "expanded", from: "disclosure" },
+  { name: "open", from: "presentation" },
+  { name: "disabled", from: "ambient (global gate)" },
+  { name: "readonly", from: "ambient" },
+  { name: "loading", from: "async-state" },
+  { name: "error", from: "async-state" },
+  { name: "success", from: "async-state" },
+  { name: "invalid", from: "validation" },
+  { name: "valid", from: "validation" },
+  { name: "indeterminate", from: "toggle (tristate)" },
+  { name: "dragging", from: "gesture" },
+  { name: "empty", from: "value-entry" },
+  { name: "complete", from: "progress / stepping-nav" },
+  { name: "first", from: "collection-position" },
+  { name: "last", from: "collection-position" },
+  { name: "odd", from: "collection-position" },
+  { name: "even", from: "collection-position" }
+];
+var capabilities = [
+  { name: "input.keyboard" },
+  { name: "input.pointer", note: "hover" },
+  { name: "input.touch" },
+  { name: "input.remote", note: "tv focus engine" },
+  {
+    name: "input.voice",
+    status: "aspirational",
+    note: "aspirational \u2014 declared but consumed by no atom yet (no voice/turn-taking machine in v0); see NOTES-modality-coverage"
+  },
+  { name: "motion.haptic" },
+  { name: "runtime.dynamic-color", note: "Material You" },
+  { name: "display.density" },
+  { name: "a11y.screenreader" },
+  { name: "platform.web" },
+  { name: "platform.ios" },
+  { name: "platform.android" },
+  { name: "platform.tvos" }
+];
+var decorations = [
+  {
+    name: "motion",
+    note: "decorates existing transitions (spring/flip/fade+slide); adds no states"
+  },
+  {
+    name: "masking",
+    note: "format/constrain entry (date/phone/currency) \u2014 decorates value-entry draft"
+  },
+  {
+    name: "anchoring",
+    note: "position a surface relative to a reference (placement/flip/offset/match-size) \u2014 decorates presentation(popover|menu)"
+  },
+  {
+    name: "backdrop",
+    note: "scrim / blur behind a layer \u2014 decorates a modal presentation; painted via the `backdrop` facet on the backdrop anatomy part"
+  },
+  {
+    name: "momentum-scroll",
+    note: "inertial scroll with snap / detent \u2014 decorates scroll/browse on touch surfaces"
+  }
+];
+var nonBehaviors = [
+  { name: "filter", note: "derived view over a collection (data, not interaction)" },
+  { name: "virtualization", note: "render windowing" },
+  { name: "ordering", note: "collection mutation (reorder/sort)" },
+  { name: "aggregation", note: "data transformation (grouping/totals) \u2014 DataGrid math" }
+];
+var preludeV0 = {
+  milda: "0.0.1",
+  kind: "prelude",
+  prelude: "0.0.1",
+  meta: {
+    id: "prelude.milda",
+    name: "Milda Prelude",
+    version: "0.0.2",
+    description: "Built-in standard library: atoms, archetypes, facets, states, capabilities."
+  },
+  atoms,
+  composites,
+  archetypes,
+  facets,
+  states,
+  capabilities,
+  decorations,
+  nonBehaviors
+};
+var atomsByName = Object.fromEntries(atoms.map((a) => [a.name, a]));
+var archetypesByName = Object.fromEntries(
+  archetypes.map((a) => [a.name, a])
+);
+
+// engine/resolveToken.ts
+function resolveToken(tokenId, contextIds, layers, _depth = 0) {
+  if (_depth > 20) return null;
+  const ids = typeof contextIds === "string" ? [contextIds] : contextIds;
+  const token = findToken(tokenId, layers)?.token;
+  if (!token) return null;
+  const v = token.value;
+  if (v.kind === "raw") return { kind: "value", type: token.type, value: v.value };
+  if (v.kind === "escape") return { kind: "escape", raw: v.raw, note: v.note };
+  const ref = ids.reduce((found, id) => found ?? v.refs[id], void 0) ?? v.refs["default"] ?? null;
+  if (!ref) return null;
+  return resolveToken(ref, contextIds, layers, _depth + 1);
+}
+function findToken(tokenId, layers) {
+  for (const layer of layers) {
+    const token = layer.tokens.find((t) => t.id === tokenId);
+    if (token) return { token, layerId: layer.id };
+  }
+  return null;
+}
+function allTokensOfType(type, layers) {
+  const sorted = [...layers].sort((a, b) => a.order - b.order);
+  const result = [];
+  for (const layer of sorted) {
+    for (const token of layer.tokens) {
+      if (token.type === type) result.push({ token, layerId: layer.id, layerName: layer.name });
+    }
+  }
+  return result;
+}
+
+// engine/resolveFacets.ts
+function resolveFacets(input) {
+  const { part, activeStates } = input;
+  let result = { ...part.facets ?? {} };
+  const states2 = part.states ?? {};
+  const order = input.stateOrder ?? Object.keys(states2);
+  for (const s of order) {
+    const override = activeStates.has(s) ? states2[s]?.facets : void 0;
+    if (override) result = { ...result, ...override };
+  }
+  return result;
+}
+function resolveLayout(input) {
+  const { part, activeStates } = input;
+  let result = part.layout ? { ...part.layout } : void 0;
+  const states2 = part.states ?? {};
+  const order = input.stateOrder ?? Object.keys(states2);
+  for (const s of order) {
+    const override = activeStates.has(s) ? states2[s]?.layout : void 0;
+    if (override) result = { ...result ?? {}, ...override };
+  }
+  return result;
+}
+function collectActiveStates(flags) {
+  const active = /* @__PURE__ */ new Set();
+  for (const [state, enabled] of Object.entries(flags)) {
+    if (enabled) active.add(state);
+  }
+  return active;
+}
+
+// engine/validate.ts
+function facetTokenRefs(facets2) {
+  if (!facets2) return [];
+  const ids = [];
+  for (const v of Object.values(facets2)) {
+    if (!v) continue;
+    if ("token" in v) ids.push(v.token);
+    else if ("inset" in v) {
+      for (const edge of Object.values(v.inset)) if (typeof edge === "string") ids.push(edge);
+    }
+  }
+  return ids;
+}
+function layoutTokenRefs(layout) {
+  if (!layout) return [];
+  const ids = [];
+  if (layout.gap) ids.push(layout.gap);
+  if (layout.inset) {
+    for (const edge of Object.values(layout.inset)) if (typeof edge === "string") ids.push(edge);
+  }
+  for (const axis of [layout.size?.width, layout.size?.height]) {
+    if (axis && typeof axis === "object") {
+      const intent = "intent" in axis ? axis.intent : axis;
+      if (intent && typeof intent === "object" && "fixed" in intent) ids.push(intent.fixed);
+      if ("min" in axis && axis.min) ids.push(axis.min);
+      if ("max" in axis && axis.max) ids.push(axis.max);
+    }
+  }
+  return ids;
+}
+function validate(doc, prelude) {
+  const issues = [];
+  const archetypeNames = new Set(prelude.archetypes.map((a) => a.name));
+  const facetNames = new Set(prelude.facets.map((f) => f.name));
+  const stateNames = new Set(prelude.states.map((s) => s.name));
+  const groupIds = new Set(doc.foundations.contextGroups.map((g) => g.id));
+  const layers = doc.foundations.layers;
+  for (const layer of layers) {
+    for (const tok of layer.tokens) {
+      if (tok.value.kind === "alias") {
+        const where = `token ${tok.name} (${tok.id})`;
+        if (!groupIds.has(tok.value.by)) {
+          issues.push({
+            severity: "error",
+            code: "alias.unknownGroup",
+            message: `alias by unknown context group "${tok.value.by}"`,
+            where
+          });
+        }
+        for (const refId of Object.values(tok.value.refs)) {
+          if (!findToken(refId, layers)) {
+            issues.push({
+              severity: "error",
+              code: "alias.danglingRef",
+              message: `alias ref points at missing token "${refId}"`,
+              where
+            });
+          }
+        }
+      }
+    }
+  }
+  for (const comp of doc.components) {
+    const where = `component ${comp.name} (${comp.id})`;
+    if (!archetypeNames.has(comp.archetype)) {
+      issues.push({
+        severity: "error",
+        code: "component.unknownArchetype",
+        message: `unknown archetype "${comp.archetype}"`,
+        where
+      });
+    }
+    const propIds = new Set(comp.contract.props.map((p) => p.id));
+    for (const [param, binding] of Object.entries(comp.contract.params)) {
+      if ("prop" in binding && !propIds.has(binding.prop)) {
+        issues.push({
+          severity: "error",
+          code: "param.danglingProp",
+          message: `param "${param}" binds missing prop "${binding.prop}"`,
+          where
+        });
+      }
+    }
+    for (const [partName, part] of Object.entries(comp.anatomy)) {
+      checkPart(comp, partName, part, { facetNames, stateNames, layers, issues });
+    }
+  }
+  return issues;
+}
+function checkPart(comp, partName, part, ctx) {
+  const where = `${comp.name} \u203A part ${partName}`;
+  const { facetNames, stateNames, layers, issues } = ctx;
+  const checkFacets = (facets2, scope) => {
+    if (!facets2) return;
+    for (const name of Object.keys(facets2)) {
+      if (!facetNames.has(name)) {
+        issues.push({
+          severity: "error",
+          code: "facet.unknown",
+          message: `unknown facet "${name}"`,
+          where: scope
+        });
+      }
+    }
+    for (const id of facetTokenRefs(facets2)) {
+      if (!findToken(id, layers)) {
+        issues.push({
+          severity: "error",
+          code: "facet.danglingToken",
+          message: `facet references missing token "${id}"`,
+          where: scope
+        });
+      }
+    }
+  };
+  const checkLayoutRefs = (layout, scope) => {
+    for (const id of layoutTokenRefs(layout)) {
+      if (!findToken(id, layers)) {
+        issues.push({
+          severity: "error",
+          code: "layout.danglingToken",
+          message: `layout references missing token "${id}"`,
+          where: scope
+        });
+      }
+    }
+  };
+  checkFacets(part.facets, where);
+  checkLayoutRefs(part.layout, where);
+  for (const [stateName, override] of Object.entries(part.states ?? {})) {
+    const scope = `${where} [${stateName}]`;
+    if (!stateNames.has(stateName)) {
+      issues.push({
+        severity: "error",
+        code: "state.unknown",
+        message: `unknown state "${stateName}"`,
+        where: scope
+      });
+    }
+    checkFacets(override?.facets, scope);
+    checkLayoutRefs(override?.layout, scope);
+  }
+}
+
+// engine/conformance.ts
+function walkFacets(facets2, where, opts, holes) {
+  if (!facets2) return;
+  for (const [name, value] of Object.entries(facets2)) {
+    if (!value) continue;
+    if ("raw" in value) {
+      holes.push({
+        kind: "facet",
+        name,
+        where,
+        reason: "raw escape-hatch value is a platform-specific leaf"
+      });
+    } else if ("token" in value) {
+      const resolved = resolveToken(value.token, opts.contextIds, opts.layers);
+      if (resolved === null) {
+        holes.push({
+          kind: "facet",
+          name,
+          where,
+          reason: `token "${value.token}" does not resolve for target`
+        });
+      } else if (resolved.kind === "escape") {
+        holes.push({
+          kind: "facet",
+          name,
+          where,
+          reason: `token "${value.token}" resolves to an escape-hatch leaf for this target`
+        });
+      }
+    }
+  }
+}
+function walkPart(comp, partName, part, opts, holes) {
+  const where = `${comp.name} \u203A ${partName}`;
+  walkFacets(part.facets, where, opts, holes);
+  for (const [stateName, override] of Object.entries(part.states ?? {})) {
+    walkFacets(override?.facets, `${where} [${stateName}]`, opts, holes);
+  }
+}
+function conformance(comp, opts) {
+  const holes = [];
+  for (const [partName, part] of Object.entries(comp.anatomy)) {
+    walkPart(comp, partName, part, opts, holes);
+  }
+  const substitutions = [];
+  const realize = comp.realize.find((r) => r.target === opts.target);
+  if (realize) {
+    for (const dropped of realize.drop ?? [])
+      substitutions.push({ behavior: dropped, via: "dropped" });
+    for (const wire of realize.wire ?? [])
+      substitutions.push({ behavior: `${wire.from} \u2192 ${wire.to}`, via: "realize wire" });
+  }
+  return { target: opts.target, complete: holes.length === 0, holes, substitutions };
+}
+
+// dsl/lexer.ts
+var LexError = class extends Error {
+  constructor(message, line, col) {
+    super(`${message} (line ${line}:${col})`);
+    this.line = line;
+    this.col = col;
+    this.name = "LexError";
+  }
+};
+var isWordChar = (c) => /[A-Za-z0-9_./%-]/.test(c);
+var PUNCT = {
+  "{": "lbrace",
+  "}": "rbrace",
+  "(": "lparen",
+  ")": "rparen",
+  "<": "lt",
+  ">": "gt",
+  ":": "colon",
+  "=": "equals",
+  ",": "comma",
+  ";": "semi",
+  "?": "question"
+};
+function lex(src) {
+  const tokens = [];
+  let i = 0;
+  let line = 1;
+  let col = 1;
+  const n = src.length;
+  const advance = (count = 1) => {
+    for (let k = 0; k < count; k++) {
+      if (src[i] === "\n") {
+        line++;
+        col = 1;
+      } else {
+        col++;
+      }
+      i++;
+    }
+  };
+  const push = (type, value, startPos, startLine, startCol) => {
+    tokens.push({ type, value, pos: startPos, line: startLine, col: startCol });
+  };
+  while (i < n) {
+    const c = src[i];
+    const startPos = i;
+    const startLine = line;
+    const startCol = col;
+    if (c === "\n") {
+      advance();
+      if (tokens.length && tokens[tokens.length - 1].type !== "newline") {
+        push("newline", "\n", startPos, startLine, startCol);
+      }
+      continue;
+    }
+    if (c === " " || c === "	" || c === "\r") {
+      advance();
+      continue;
+    }
+    if (c === "#") {
+      while (i < n && src[i] !== "\n") advance();
+      continue;
+    }
+    if (c === '"') {
+      advance();
+      let value = "";
+      while (i < n && src[i] !== '"') {
+        if (src[i] === "\\" && i + 1 < n) {
+          const next = src[i + 1];
+          value += next === "n" ? "\n" : next === "t" ? "	" : next;
+          advance(2);
+          continue;
+        }
+        if (src[i] === "\n") throw new LexError("Unterminated string", startLine, startCol);
+        value += src[i];
+        advance();
+      }
+      if (i >= n) throw new LexError("Unterminated string", startLine, startCol);
+      advance();
+      push("string", value, startPos, startLine, startCol);
+      continue;
+    }
+    if (c === "-" && src[i + 1] === ">") {
+      advance(2);
+      push("arrow", "->", startPos, startLine, startCol);
+      continue;
+    }
+    if (c === "\u2192") {
+      advance();
+      push("arrow", "->", startPos, startLine, startCol);
+      continue;
+    }
+    if (PUNCT[c]) {
+      advance();
+      push(PUNCT[c], c, startPos, startLine, startCol);
+      continue;
+    }
+    if (isWordChar(c)) {
+      let value = "";
+      while (i < n && isWordChar(src[i]) && !(src[i] === "-" && src[i + 1] === ">")) {
+        value += src[i];
+        advance();
+      }
+      push("word", value, startPos, startLine, startCol);
+      continue;
+    }
+    advance();
+  }
+  push("eof", "", i, line, col);
+  return tokens;
+}
+
+// dsl/parse.ts
+var seg = (s) => s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "x";
+var cgId = (name) => `cg.${seg(name)}`;
+var ctxId = (groupName, ctxName) => `ctx.${seg(groupName)}.${seg(ctxName)}`;
+var tokId = (path) => `tok.${path.replace(/\//g, ".")}`;
+var stId = (name) => `st.${seg(name)}`;
+var cmpId = (name) => `cmp.${seg(name)}`;
+var FACET_MAP = {
+  fill: "fill",
+  ink: "ink",
+  border: "border",
+  corner: "corner",
+  inset: "inset",
+  gap: "gap",
+  text: "text",
+  "text.clamp": "textClamp",
+  "text.wrap": "textWrap",
+  elevation: "elevation",
+  overlay: "overlay",
+  opacity: "opacity",
+  ring: "ring",
+  backdrop: "backdrop",
+  weight: null,
+  font: null,
+  slant: null
+};
+var TYPE_MAP = {
+  color: "color",
+  spacing: "spacing",
+  radius: "radius",
+  size: "size",
+  dimension: "size",
+  shadow: "shadow",
+  typography: "typography",
+  "font-family": "fontFamily",
+  fontFamily: "fontFamily",
+  duration: "duration",
+  opacity: "opacity",
+  blur: "blur",
+  tonal: "tonal",
+  border: "border",
+  elevation: "elevation",
+  ring: "ring",
+  backdrop: "backdrop",
+  none: "none"
+};
+var NUMBER_RE = /^-?\d+(\.\d+)?$/;
+var isRawValue = (v) => /^#/.test(v) || /[(%]/.test(v) || /\d(px|rem|em|vh|vw|vmin|vmax|ch|ex|fr|deg|ms|s)$/.test(v);
+function hexToColor(hex) {
+  const m = /^#([0-9a-fA-F]{3,8})$/.exec(hex.trim());
+  if (!m) return null;
+  let h = m[1];
+  if (h.length === 3) h = h.split("").map((c) => c + c).join("");
+  if (h.length !== 6 && h.length !== 8) return null;
+  const byte = (k) => parseInt(h.slice(k * 2, k * 2 + 2), 16) / 255;
+  const value = { space: "srgb", channels: [byte(0), byte(1), byte(2)] };
+  if (h.length === 8) value.alpha = byte(3);
+  return value;
+}
+var Parser = class {
+  constructor(toks) {
+    this.pos = 0;
+    this.issues = [];
+    // Tokens synthesized while parsing (inline literals hoisted out of alias slots —
+    // the canonical AST's `refs` holds only token ids, so an inline value must become
+    // its own token). Deduped by (type, serialized value). Flushed into the layer.
+    this.synth = [];
+    this.synthKeys = /* @__PURE__ */ new Map();
+    this.toks = toks;
+  }
+  // Hoist an inline literal into a synthesized token and return its id.
+  hoistLiteral(astType, raw, tok) {
+    const value = this.typedRaw(astType, raw, tok);
+    const key = `${astType}\0${JSON.stringify(value)}`;
+    const existing = this.synthKeys.get(key);
+    if (existing) return existing;
+    const id = `tok.lit-${seg(String(astType))}-${this.synth.length + 1}`;
+    this.synth.push({ id, name: `(inline ${astType})`, type: astType, value });
+    this.synthKeys.set(key, id);
+    this.issue("warning", "inline-literal", `inline ${astType} literal in an alias slot hoisted to token ${id}`, tok);
+    return id;
+  }
+  peek() {
+    return this.toks[this.pos];
+  }
+  next() {
+    return this.toks[this.pos++];
+  }
+  at(type) {
+    return this.peek().type === type;
+  }
+  // A `word` whose text equals `w` (case-sensitive keyword check).
+  atWord(w) {
+    const t = this.peek();
+    return t.type === "word" && t.value === w;
+  }
+  skipNewlines() {
+    while (this.at("newline") || this.at("semi")) this.pos++;
+  }
+  // Safety net: if a loop body made no progress (a malformed token that no rule
+  // consumed), force one token forward so parsing can never spin. Returns true when
+  // it had to intervene (the caller can also choose to break).
+  ensureProgress(mark) {
+    if (this.pos !== mark) return false;
+    if (!this.at("eof")) this.next();
+    return true;
+  }
+  issue(severity, code, message, tok = this.peek()) {
+    this.issues.push({ severity, code, message, line: tok.line, col: tok.col });
+  }
+  // Consume a token of `type`, or record an error and synthesize one.
+  expect(type, code) {
+    if (this.at(type)) return this.next();
+    const tok = this.peek();
+    this.issue("error", code, `expected ${type}, got ${tok.type} ${JSON.stringify(tok.value)}`);
+    return tok;
+  }
+  // A bare word (ident/path/number token).
+  expectWord(code) {
+    if (this.at("word")) return this.next().value;
+    this.issue("error", code, `expected identifier, got ${this.peek().type}`);
+    return "";
+  }
+  // Skip a balanced `{ … }` block (already positioned at or before the `{`).
+  skipBlock() {
+    while (!this.at("lbrace") && !this.at("eof") && !this.at("newline")) this.next();
+    if (!this.at("lbrace")) return;
+    let depth = 0;
+    do {
+      const t = this.next();
+      if (t.type === "lbrace") depth++;
+      else if (t.type === "rbrace") depth--;
+      else if (t.type === "eof") break;
+    } while (depth > 0);
+  }
+  // ── context-group NAME { ctx ctx … } ──
+  parseContextGroup() {
+    this.next();
+    const name = this.expectWord("cg-name");
+    this.expect("lbrace", "cg-lbrace");
+    const contexts = [];
+    while (!this.at("rbrace") && !this.at("eof")) {
+      if (this.at("newline") || this.at("semi")) {
+        this.pos++;
+        continue;
+      }
+      const ctxName = this.expectWord("cg-ctx");
+      if (!ctxName) break;
+      contexts.push({ id: ctxId(name, ctxName), name: ctxName });
+    }
+    this.expect("rbrace", "cg-rbrace");
+    return { id: cgId(name), name, contexts };
+  }
+  // ── raw value literal → a JS value (string | number | nested object) ──
+  parseRawLiteral() {
+    const t = this.peek();
+    if (t.type === "string") return this.next().value;
+    if (t.type === "lbrace") return this.parseStructured();
+    if (t.type === "word") {
+      const w = this.next().value;
+      return NUMBER_RE.test(w) ? Number(w) : w;
+    }
+    this.issue("error", "raw-value", `expected a value, got ${t.type}`);
+    return "";
+  }
+  parseStructured() {
+    this.expect("lbrace", "struct-lbrace");
+    const obj = {};
+    while (!this.at("rbrace") && !this.at("eof")) {
+      const mark = this.pos;
+      if (this.at("newline") || this.at("semi")) {
+        this.pos++;
+        continue;
+      }
+      const key = this.expectWord("struct-key");
+      this.expect("colon", "struct-colon");
+      const val = this.parseRawLiteral();
+      if (key) obj[key] = val;
+      if (this.at("semi") || this.at("newline")) this.pos++;
+      this.ensureProgress(mark);
+    }
+    this.expect("rbrace", "struct-rbrace");
+    return obj;
+  }
+  // ── convert a raw JS value to the canonical typed value for `astType` ──
+  typedRaw(astType, raw, tok) {
+    if (astType === "color" && typeof raw === "string") {
+      const color = hexToColor(raw);
+      if (color) return { kind: "raw", value: color };
+      this.issue("warning", "color-nonhex", `non-hex color "${raw}" kept as an escape value`, tok);
+      return { kind: "escape", raw, note: "non-hex color literal" };
+    }
+    if (astType === "spacing" || astType === "radius" || astType === "size") {
+      if (typeof raw === "number") return { kind: "raw", value: { value: raw, unit: "scaled" } };
+      if (raw && typeof raw === "object" && "value" in raw) {
+        const r = raw;
+        return { kind: "raw", value: { value: Number(r.value), unit: r.unit ?? "scaled" } };
+      }
+    }
+    if (astType === "opacity" && typeof raw === "number") return { kind: "raw", value: { value: raw } };
+    if (astType === "duration" && typeof raw === "number") return { kind: "raw", value: { ms: raw } };
+    if (astType === "tonal" && typeof raw === "number") return { kind: "raw", value: { level: raw } };
+    return { kind: "raw", value: raw };
+  }
+  // ── alias by GROUP { Ctx -> <path | inline literal> ; default -> … } ──
+  // A slot value is normally a token path (ref). The authored surface also allows an
+  // inline literal (a hex color, a structured value) in a slot; since the AST's `refs`
+  // holds only ids, such literals are hoisted to synthesized tokens (hoistLiteral).
+  parseAlias(astType) {
+    this.next();
+    if (this.atWord("by")) this.next();
+    else this.issue("error", "alias-by", "expected 'by'");
+    const groupName = this.expectWord("alias-group");
+    this.expect("lbrace", "alias-lbrace");
+    const refs = {};
+    while (!this.at("rbrace") && !this.at("eof")) {
+      const mark = this.pos;
+      if (this.at("newline") || this.at("semi")) {
+        this.pos++;
+        continue;
+      }
+      const ctxName = this.expectWord("alias-ctx");
+      this.expect("arrow", "alias-arrow");
+      const slot = this.peek();
+      let refId = "";
+      if (slot.type === "string" || slot.type === "lbrace" || slot.type === "word" && NUMBER_RE.test(slot.value)) {
+        refId = this.hoistLiteral(astType, this.parseRawLiteral(), slot);
+      } else {
+        const refPath = this.expectWord("alias-ref");
+        if (refPath) refId = tokId(refPath);
+      }
+      if (ctxName && refId) {
+        const key = ctxName === "default" ? "default" : ctxId(groupName, ctxName);
+        refs[key] = refId;
+      }
+      if (this.at("semi") || this.at("newline")) this.pos++;
+      this.ensureProgress(mark);
+    }
+    this.expect("rbrace", "alias-rbrace");
+    return { kind: "alias", by: cgId(groupName), refs };
+  }
+  // ── the right-hand side of `token … =` ──
+  parseTokenValue(astType) {
+    const t = this.peek();
+    if (t.type === "word" && t.value === "alias") return this.parseAlias(astType);
+    if (t.type === "word" && t.value === "escape") {
+      this.next();
+      const raw = this.at("string") ? this.next().value : this.expectWord("escape-raw");
+      let escNote;
+      if (this.atWord("note")) {
+        this.next();
+        escNote = this.at("string") ? this.next().value : this.expectWord("escape-note");
+      }
+      const esc = { kind: "escape", raw };
+      if (escNote) esc.note = escNote;
+      return esc;
+    }
+    if (t.type === "word" && t.value === "raw") {
+      this.next();
+      const raw = this.parseRawLiteral();
+      return this.typedRaw(astType, raw, t);
+    }
+    if (t.type === "lbrace") {
+      const raw = this.parseStructured();
+      return this.typedRaw(astType, raw, t);
+    }
+    if (t.type === "word") {
+      const refPath = this.next().value;
+      this.issue("warning", "ref-sugar", `unconditional ref "${refPath}" lowered to a default-only alias`, t);
+      return { kind: "alias", by: "", refs: { default: tokId(refPath) } };
+    }
+    this.issue("error", "token-value", `expected a token value, got ${t.type}`);
+    return { kind: "raw", value: "" };
+  }
+  // ── foundations { token PATH : TYPE = VALUE … } → one Layer ──
+  parseFoundations(layer) {
+    this.next();
+    this.expect("lbrace", "foundations-lbrace");
+    let order = 0;
+    while (!this.at("rbrace") && !this.at("eof")) {
+      const mark = this.pos;
+      if (this.at("newline") || this.at("semi")) {
+        this.pos++;
+        continue;
+      }
+      if (this.atWord("token")) {
+        const tok = this.parseTokenDecl(order);
+        if (tok) {
+          layer.tokens.push(tok);
+          order++;
+        }
+        this.ensureProgress(mark);
+        continue;
+      }
+      this.issue("error", "foundations-stmt", `unexpected ${JSON.stringify(this.peek().value)} in foundations`);
+      while (!this.at("newline") && !this.at("semi") && !this.at("rbrace") && !this.at("eof")) this.next();
+      this.ensureProgress(mark);
+    }
+    this.expect("rbrace", "foundations-rbrace");
+    if (this.synth.length) {
+      layer.tokens.push(...this.synth);
+      this.synth = [];
+    }
+  }
+  parseTokenDecl(_order) {
+    const startTok = this.next();
+    const path = this.expectWord("token-path");
+    if (!path) return null;
+    this.expect("colon", "token-colon");
+    const typeName = this.expectWord("token-type");
+    const astType = TYPE_MAP[typeName];
+    if (!astType) this.issue("warning", "token-type", `non-canonical token type "${typeName}" kept as-is`, startTok);
+    this.expect("equals", "token-equals");
+    const value = this.parseTokenValue(astType ?? typeName);
+    return {
+      id: tokId(path),
+      name: path,
+      type: astType ?? typeName,
+      value
+    };
+  }
+  // ════════════════════════════════════════════════════════════════════════
+  // Slice 2 — shared types
+  // ════════════════════════════════════════════════════════════════════════
+  skipToTerminator() {
+    while (!this.at("newline") && !this.at("semi") && !this.at("rbrace") && !this.at("eof")) this.next();
+  }
+  parseIdentList() {
+    const out = [];
+    if (this.at("word")) out.push(this.next().value);
+    while (this.at("comma")) {
+      this.next();
+      if (this.at("word")) out.push(this.next().value);
+    }
+    return out;
+  }
+  parseObjectType() {
+    this.expect("lbrace", "obj-lbrace");
+    const fields = [];
+    while (!this.at("rbrace") && !this.at("eof")) {
+      const mark = this.pos;
+      if (this.at("newline") || this.at("semi")) {
+        this.pos++;
+        continue;
+      }
+      const name = this.expectWord("field-name");
+      let required = true;
+      if (this.at("question")) {
+        this.next();
+        required = false;
+      }
+      this.expect("colon", "field-colon");
+      const type = this.parseTypeExpr();
+      if (name) fields.push({ id: `fld.${seg(name)}`, name, type, required });
+      if (this.at("semi") || this.at("newline")) this.pos++;
+      this.ensureProgress(mark);
+    }
+    this.expect("rbrace", "obj-rbrace");
+    return { kind: "object", fields };
+  }
+  parseTypeExpr() {
+    const t = this.peek();
+    if (t.type !== "word") {
+      this.issue("error", "type-expr", `expected a type, got ${t.type}`);
+      return { kind: "string" };
+    }
+    const w = t.value;
+    if (w === "string" || w === "number" || w === "boolean") {
+      this.next();
+      return { kind: w };
+    }
+    if (w === "enum") {
+      this.next();
+      this.expect("lparen", "enum-lparen");
+      const values = this.parseIdentList();
+      this.expect("rparen", "enum-rparen");
+      return { kind: "enum", values };
+    }
+    if (w === "ref") {
+      this.next();
+      const name = this.expectWord("ref-name");
+      return { kind: "ref", ref: stId(name) };
+    }
+    if (w === "array") {
+      this.next();
+      this.expect("lt", "array-lt");
+      const item = this.parseTypeExpr();
+      this.expect("gt", "array-gt");
+      return { kind: "array", item };
+    }
+    if (w === "union") {
+      this.next();
+      this.expect("lparen", "union-lparen");
+      const members = [this.parseTypeExpr()];
+      while (this.at("comma")) {
+        this.next();
+        members.push(this.parseTypeExpr());
+      }
+      this.expect("rparen", "union-rparen");
+      return { kind: "union", members };
+    }
+    if (w === "object") {
+      this.next();
+      return this.parseObjectType();
+    }
+    if (w === "component") {
+      this.next();
+      let componentIds;
+      if (this.at("lparen")) {
+        this.next();
+        componentIds = this.parseIdentList().map(cmpId);
+        this.expect("rparen", "component-rparen");
+      }
+      return { kind: "component", componentIds };
+    }
+    if (w === "context") {
+      this.next();
+      const group = this.expectWord("context-type");
+      this.issue("warning", "context-type", `context-typed "${group}" lowered to ref (proposal 0001)`, t);
+      return { kind: "ref", ref: cgId(group) };
+    }
+    this.next();
+    return { kind: "ref", ref: stId(w) };
+  }
+  parseSharedType() {
+    this.next();
+    const name = this.expectWord("type-name");
+    if (!name) return null;
+    this.expect("equals", "type-equals");
+    const definition = this.parseTypeExpr();
+    return { id: stId(name), name, definition };
+  }
+  // ════════════════════════════════════════════════════════════════════════
+  // Slice 3 — components
+  // ════════════════════════════════════════════════════════════════════════
+  // A condition's raw text: `prop` or `prop=value` (reused by wire/gate `when`).
+  parseConditionText() {
+    let text = this.expectWord("cond");
+    if (this.at("equals")) {
+      this.next();
+      const v = this.at("string") ? this.next().value : this.expectWord("cond-val");
+      text += `=${v}`;
+    }
+    return text;
+  }
+  // A prop condition → RealizeCond { prop, eq } (single `prop=value`).
+  parseRealizeCond() {
+    const prop = this.expectWord("rc-prop");
+    let eq = true;
+    if (this.at("equals")) {
+      this.next();
+      if (this.at("string")) eq = this.next().value;
+      else {
+        const v = this.expectWord("rc-val");
+        eq = NUMBER_RE.test(v) ? Number(v) : v === "true" ? true : v === "false" ? false : v;
+      }
+    }
+    return { prop, eq };
+  }
+  parsePropDefault() {
+    const t = this.peek();
+    if (t.type === "string") return this.next().value;
+    if (t.type === "word" && t.value === "alias") {
+      this.next();
+      if (this.atWord("by")) this.next();
+      this.expectWord("alias-group");
+      this.skipBlock();
+      this.issue("warning", "alias-default", "context-aliased prop default skipped (proposal 0001)", t);
+      return void 0;
+    }
+    if (t.type === "word") {
+      this.next();
+      if (NUMBER_RE.test(t.value)) return Number(t.value);
+      if (t.value === "true") return true;
+      if (t.value === "false") return false;
+      return t.value;
+    }
+    this.issue("error", "prop-default", `expected a default value, got ${t.type}`);
+    return void 0;
+  }
+  parsePropDecl() {
+    const name = this.expectWord("prop-name");
+    if (!name) return null;
+    const type = this.parseTypeExpr();
+    const prop = { id: `prop.${seg(name)}`, name, type };
+    if (this.at("equals")) {
+      this.next();
+      const def = this.parsePropDefault();
+      if (def !== void 0) prop.default = def;
+    }
+    if (this.atWord("bind")) {
+      this.next();
+      prop.binding = this.expectWord("bind-target");
+    }
+    return prop;
+  }
+  parseProps(props) {
+    this.next();
+    this.expect("lbrace", "props-lbrace");
+    while (!this.at("rbrace") && !this.at("eof")) {
+      const mark = this.pos;
+      if (this.at("newline") || this.at("semi")) {
+        this.pos++;
+        continue;
+      }
+      const p = this.parsePropDecl();
+      if (p) props.push(p);
+      if (this.at("semi") || this.at("newline")) this.pos++;
+      this.ensureProgress(mark);
+    }
+    this.expect("rbrace", "props-rbrace");
+  }
+  parseEvents(events) {
+    this.next();
+    this.expect("lbrace", "events-lbrace");
+    while (!this.at("rbrace") && !this.at("eof")) {
+      const mark = this.pos;
+      if (this.at("newline") || this.at("semi")) {
+        this.pos++;
+        continue;
+      }
+      const name = this.expectWord("event-name");
+      if (name) {
+        const e = { name };
+        if (this.atWord("from")) {
+          this.next();
+          e.from = this.expectWord("event-from");
+        }
+        events.push(e);
+      }
+      if (this.at("semi") || this.at("newline")) this.pos++;
+      this.ensureProgress(mark);
+    }
+    this.expect("rbrace", "events-rbrace");
+  }
+  // `uses ATOM [ ( params ) ] as ALIAS`
+  parseUses() {
+    this.next();
+    const atom = this.expectWord("uses-atom");
+    if (!atom) return null;
+    if (this.at("lparen")) {
+      this.next();
+      while (!this.at("rparen") && !this.at("eof") && !this.at("newline")) this.next();
+      if (this.at("rparen")) this.next();
+    }
+    if (this.atWord("as")) this.next();
+    else this.issue("warning", "uses-as", "expected 'as' in uses");
+    const as = this.expectWord("uses-alias");
+    return { atom, as };
+  }
+  // The `machineref` target of a wire, with an optional `(arg)`.
+  parseWireEnd(code) {
+    const end = this.expectWord(code);
+    let arg;
+    if (this.at("lparen")) {
+      this.next();
+      if (this.at("word")) arg = this.next().value;
+      while (!this.at("rparen") && !this.at("eof") && !this.at("newline")) this.next();
+      if (this.at("rparen")) this.next();
+    }
+    return { end, arg };
+  }
+  // `wire FROM [when COND] -> TO[(arg)]`
+  parseWire() {
+    this.next();
+    const from = this.expectWord("wire-from");
+    if (!from) return null;
+    let when;
+    if (this.atWord("when")) {
+      this.next();
+      when = this.parseConditionText();
+    }
+    this.expect("arrow", "wire-arrow");
+    const { end: to, arg } = this.parseWireEnd("wire-to");
+    const wire = { kind: "wire", from, to };
+    if (arg) wire.arg = arg;
+    if (when) wire.when = when;
+    return wire;
+  }
+  // `gate MACHINE active when COND`
+  parseGate() {
+    this.next();
+    const machine = this.expectWord("gate-machine");
+    if (!machine) return null;
+    if (this.atWord("active")) this.next();
+    if (this.atWord("when")) this.next();
+    else this.issue("warning", "gate-when", "expected 'when' in gate");
+    const activeWhen = this.parseConditionText();
+    return { kind: "gate", machine, activeWhen };
+  }
+  // ── layout / facet bodies ──
+  parseAxisIntent() {
+    const w = this.expectWord("axis");
+    if (w === "fit" || w === "fill") return w;
+    if (w === "weight") {
+      if (this.at("lparen")) {
+        this.next();
+        const n = Number(this.expectWord("weight-n"));
+        if (this.at("rparen")) this.next();
+        return { weight: n };
+      }
+      return { weight: 1 };
+    }
+    if (w === "fixed") {
+      if (this.at("lparen")) {
+        this.next();
+        const p = this.expectWord("fixed-token");
+        if (this.at("rparen")) this.next();
+        return { fixed: tokId(p) };
+      }
+      this.issue("warning", "axis-fixed", "bare 'fixed' axis has no dimension; treated as fit");
+      return "fit";
+    }
+    this.issue("warning", "axis-unknown", `unknown size intent "${w}"; treated as fit`);
+    return "fit";
+  }
+  parseInsetArgs() {
+    const args = [];
+    while (this.at("word") && args.length < 2) args.push(this.next().value);
+    if (args.length >= 2) return { block: tokId(args[0]), inline: tokId(args[1]) };
+    if (args.length === 1) return { all: tokId(args[0]) };
+    return { all: "" };
+  }
+  parseLayoutBody() {
+    this.expect("lbrace", "layout-lbrace");
+    const spec = {};
+    while (!this.at("rbrace") && !this.at("eof")) {
+      const mark = this.pos;
+      if (this.at("newline") || this.at("semi")) {
+        this.pos++;
+        continue;
+      }
+      const key = this.expectWord("layout-key");
+      switch (key) {
+        case "stack":
+          spec.stack = this.expectWord("stack");
+          break;
+        case "flow":
+          spec.flow = true;
+          break;
+        case "gap":
+          spec.gap = tokId(this.expectWord("gap"));
+          break;
+        case "align":
+          spec.align = this.expectWord("align");
+          break;
+        case "distribute":
+          spec.distribute = this.expectWord("distribute");
+          break;
+        case "wrap": {
+          const w = this.expectWord("wrap");
+          if (w === "wrap" || w === "wrap-reverse") spec.flow = true;
+          break;
+        }
+        case "position": {
+          const p = this.expectWord("position");
+          spec.position = p === "overlay" || p === "flow" ? p : { pinned: p };
+          break;
+        }
+        case "size": {
+          const width = this.parseAxisIntent();
+          const height = this.parseAxisIntent();
+          spec.size = { width, height };
+          break;
+        }
+        case "ratio": {
+          const wv = Number(this.expectWord("ratio-w"));
+          const hv = Number(this.expectWord("ratio-h"));
+          spec.size = { ...spec.size ?? {}, width: { ratio: { w: wv, h: hv } } };
+          break;
+        }
+        case "inset":
+          spec.inset = this.parseInsetArgs();
+          break;
+        default:
+          this.issue("warning", "layout-key", `unknown layout key "${key}" skipped`);
+          this.skipToTerminator();
+      }
+      if (this.at("semi") || this.at("newline")) this.pos++;
+      this.ensureProgress(mark);
+    }
+    this.expect("rbrace", "layout-rbrace");
+    return spec;
+  }
+  // A single facet statement `facetname value+` → [FacetName, FacetValue] | null.
+  parseFacetStmt() {
+    const raw = this.expectWord("facet-name");
+    const mapped = FACET_MAP[raw];
+    if (mapped === void 0) {
+      this.issue("warning", "facet-unknown", `unknown facet "${raw}" skipped`);
+      this.skipToTerminator();
+      return null;
+    }
+    if (mapped === null) {
+      this.issue("warning", "facet-nohome", `facet "${raw}" has no AST FacetMap home (\xA73) \u2014 skipped`);
+      this.skipToTerminator();
+      return null;
+    }
+    if (mapped === "inset") {
+      return { name: "inset", value: { inset: this.parseInsetArgs() } };
+    }
+    const t = this.peek();
+    let value;
+    if (t.type === "string") {
+      value = { raw: this.next().value };
+    } else if (t.type === "word") {
+      const v = this.next().value;
+      if (NUMBER_RE.test(v)) value = { literal: Number(v) };
+      else if (isRawValue(v)) value = { raw: v };
+      else value = { token: tokId(v) };
+    } else {
+      this.issue("error", "facet-value", `expected a facet value, got ${t.type}`);
+      this.skipToTerminator();
+      return null;
+    }
+    if (!this.at("semi") && !this.at("newline") && !this.at("rbrace")) this.skipToTerminator();
+    return { name: mapped, value };
+  }
+  // `state NAME [when COND] { … }` → a PartVariant with one interaction state.
+  parseStateBlock() {
+    this.next();
+    const name = this.expectWord("state-name");
+    const variant = { states: [name] };
+    if (this.atWord("when")) {
+      this.next();
+      variant.when = this.parseRealizeCond();
+    }
+    this.applyStyleBody(variant);
+    return variant;
+  }
+  // `when COND { … }` → a state-less prop-conditioned PartVariant (proposal 0025).
+  parseWhenBlock() {
+    this.next();
+    const when = this.parseRealizeCond();
+    const variant = { when };
+    this.applyStyleBody(variant);
+    return variant;
+  }
+  // Parse a `{ facet… / layout… }` style body into a variant's facets/layout.
+  applyStyleBody(target) {
+    this.expect("lbrace", "style-lbrace");
+    const facets2 = {};
+    while (!this.at("rbrace") && !this.at("eof")) {
+      const mark = this.pos;
+      if (this.at("newline") || this.at("semi")) {
+        this.pos++;
+        continue;
+      }
+      if (this.atWord("layout")) {
+        this.next();
+        target.layout = this.parseLayoutBody();
+      } else {
+        const f = this.parseFacetStmt();
+        if (f) facets2[f.name] = f.value;
+      }
+      if (this.at("semi") || this.at("newline")) this.pos++;
+      this.ensureProgress(mark);
+    }
+    this.expect("rbrace", "style-rbrace");
+    if (Object.keys(facets2).length) target.facets = facets2;
+  }
+  // `part NAME { pstmt* }` → [name, Part]
+  parsePart() {
+    this.next();
+    const name = this.expectWord("part-name");
+    if (!name) return null;
+    this.expect("lbrace", "part-lbrace");
+    const part = {};
+    const facets2 = {};
+    const variants = [];
+    while (!this.at("rbrace") && !this.at("eof")) {
+      const mark = this.pos;
+      if (this.at("newline") || this.at("semi")) {
+        this.pos++;
+        continue;
+      }
+      if (this.atWord("layout")) {
+        this.next();
+        if (this.atWord("when")) {
+          this.next();
+          const when = this.parseRealizeCond();
+          variants.push({ when, layout: this.parseLayoutBody() });
+        } else {
+          part.layout = this.parseLayoutBody();
+        }
+      } else if (this.atWord("state")) {
+        variants.push(this.parseStateBlock());
+      } else if (this.atWord("when")) {
+        variants.push(this.parseWhenBlock());
+      } else if (this.atWord("slot")) {
+        this.issue("warning", "slot", "part `slot` has no AST Part field yet \u2014 skipped");
+        this.skipToTerminator();
+      } else {
+        const f = this.parseFacetStmt();
+        if (f) facets2[f.name] = f.value;
+      }
+      if (this.at("semi") || this.at("newline")) this.pos++;
+      this.ensureProgress(mark);
+    }
+    this.expect("rbrace", "part-rbrace");
+    if (Object.keys(facets2).length) part.facets = facets2;
+    if (variants.length) part.variants = variants;
+    return [name, part];
+  }
+  // `realize TARGET [when COND] { rstmt* }`
+  parseRealize() {
+    this.next();
+    const target = this.expectWord("realize-target");
+    if (!target) return null;
+    let when = null;
+    if (this.atWord("when")) {
+      this.next();
+      when = this.parseRealizeCond();
+    }
+    const r = { target, when };
+    this.expect("lbrace", "realize-lbrace");
+    const wires = [];
+    while (!this.at("rbrace") && !this.at("eof")) {
+      const mark = this.pos;
+      if (this.at("newline") || this.at("semi")) {
+        this.pos++;
+        continue;
+      }
+      const kw = this.peek().value;
+      if (this.atWord("presentation")) {
+        this.next();
+        const surface = this.at("word") ? this.next().value : void 0;
+        const pres = {};
+        if (surface) pres.surface = surface;
+        if (this.at("lbrace")) this.parsePresentationBody(pres);
+        r.presentation = pres;
+      } else if (this.atWord("browse")) {
+        this.next();
+        const mode = this.at("word") ? this.next().value : void 0;
+        r.browse = { mode };
+        if (this.at("lbrace")) this.skipBlock();
+      } else if (this.atWord("commit")) {
+        this.next();
+        r.commit = this.parseCommit();
+      } else if (this.atWord("drop")) {
+        this.next();
+        r.drop = this.parseIdentListWords();
+      } else if (this.atWord("note")) {
+        this.next();
+        r.note = this.at("string") ? this.next().value : this.expectWord("note");
+      } else if (this.atWord("wire")) {
+        const w = this.parseWire();
+        if (w && w.kind === "wire") wires.push({ from: w.from, to: w.to, ...w.arg ? { arg: w.arg } : {} });
+      } else {
+        this.issue("warning", "realize-stmt", `unknown realize statement "${kw}" skipped`);
+        if (this.at("lbrace")) this.skipBlock();
+        else this.skipToTerminator();
+      }
+      if (this.at("semi") || this.at("newline")) this.pos++;
+      this.ensureProgress(mark);
+    }
+    this.expect("rbrace", "realize-rbrace");
+    if (wires.length) r.wire = wires;
+    return r;
+  }
+  parsePresentationBody(pres) {
+    this.expect("lbrace", "pres-lbrace");
+    while (!this.at("rbrace") && !this.at("eof")) {
+      const mark = this.pos;
+      if (this.at("newline") || this.at("semi")) {
+        this.pos++;
+        continue;
+      }
+      const key = this.expectWord("pres-key");
+      if (key === "place") pres.place = this.expectWord("place");
+      else if (key === "flip") pres.flip = true;
+      else if (key === "matchWidth") pres.matchWidth = true;
+      else this.skipToTerminator();
+      if (this.at("semi") || this.at("newline")) this.pos++;
+      this.ensureProgress(mark);
+    }
+    this.expect("rbrace", "pres-rbrace");
+  }
+  parseCommit() {
+    const modeWord = this.expectWord("commit-mode");
+    const mode = modeWord === "continuous" ? "continuous" : "explicit";
+    const commit = { mode };
+    if (this.atWord("on")) {
+      this.next();
+      commit.on = this.parseIdentListWords();
+    }
+    return commit;
+  }
+  // A run of bare words up to a terminator (for `drop a b c`, `commit … on click enter`).
+  parseIdentListWords() {
+    const out = [];
+    while (this.at("word")) out.push(this.next().value);
+    return out;
+  }
+  parseComponent() {
+    this.next();
+    const name = this.expectWord("component-name");
+    if (!name) return null;
+    let description;
+    if (this.at("string")) description = this.next().value;
+    this.expect("lbrace", "component-lbrace");
+    let archetype = "";
+    const props = [];
+    const events = [];
+    const uses = [];
+    const coordination = [];
+    const anatomy = {};
+    const realize = [];
+    while (!this.at("rbrace") && !this.at("eof")) {
+      const mark = this.pos;
+      if (this.at("newline") || this.at("semi")) {
+        this.pos++;
+        continue;
+      }
+      if (this.atWord("archetype")) {
+        this.next();
+        archetype = this.expectWord("archetype");
+      } else if (this.atWord("props")) {
+        this.parseProps(props);
+      } else if (this.atWord("events")) {
+        this.parseEvents(events);
+      } else if (this.atWord("uses")) {
+        const u = this.parseUses();
+        if (u) uses.push(u);
+      } else if (this.atWord("wire")) {
+        const w = this.parseWire();
+        if (w) coordination.push(w);
+      } else if (this.atWord("gate")) {
+        const g = this.parseGate();
+        if (g) coordination.push(g);
+      } else if (this.atWord("motion")) {
+        this.issue("warning", "motion", "component-level motion parsed as a note \u2014 skipped");
+        this.skipToTerminator();
+      } else if (this.atWord("requires")) {
+        this.next();
+        this.parseIdentListWords();
+        this.issue("warning", "requires", "component `requires` (capability gate) has no AST field \u2014 skipped");
+      } else if (this.atWord("part")) {
+        const p = this.parsePart();
+        if (p) anatomy[p[0]] = p[1];
+      } else if (this.atWord("realize")) {
+        const r = this.parseRealize();
+        if (r) realize.push(r);
+      } else {
+        this.issue("error", "component-stmt", `unexpected ${JSON.stringify(this.peek().value)} in component`);
+        if (this.at("lbrace")) this.skipBlock();
+        else this.skipToTerminator();
+      }
+      this.ensureProgress(mark);
+    }
+    this.expect("rbrace", "component-rbrace");
+    const component = {
+      id: cmpId(name),
+      name,
+      archetype,
+      contract: { params: {}, props, events },
+      anatomy,
+      realize
+    };
+    if (description) component.description = description;
+    if (uses.length || coordination.length) {
+      const composition = { uses, coordination };
+      component.composition = composition;
+    }
+    return component;
+  }
+  // ── top-level document driver ──
+  parseDocument(opts) {
+    const contextGroups = [];
+    const layer = { id: "layer.foundations", name: "Foundations", order: 0, tokens: [] };
+    const sharedTypes = [];
+    const components = [];
+    this.skipNewlines();
+    while (!this.at("eof")) {
+      const mark = this.pos;
+      if (this.atWord("context-group")) {
+        const cg = this.parseContextGroup();
+        if (cg) contextGroups.push(cg);
+      } else if (this.atWord("foundations")) {
+        this.parseFoundations(layer);
+      } else if (this.atWord("type")) {
+        const st = this.parseSharedType();
+        if (st) sharedTypes.push(st);
+      } else if (this.atWord("component")) {
+        const c = this.parseComponent();
+        if (c) components.push(c);
+      } else {
+        const tok = this.peek();
+        this.issue("error", "top-level", `unexpected top-level ${JSON.stringify(tok.value || tok.type)}`);
+        this.next();
+      }
+      this.ensureProgress(mark);
+      this.skipNewlines();
+    }
+    return {
+      milda: opts.milda ?? "0.1",
+      kind: "design-system",
+      prelude: opts.prelude ?? "0.0.2",
+      meta: {
+        id: `ds.${seg(opts.name ?? "design-system")}`,
+        name: opts.name ?? "Design system",
+        version: "0.0.0"
+      },
+      foundations: {
+        contextGroups,
+        layers: layer.tokens.length ? [layer] : [],
+        sharedTypes,
+        metadata: []
+      },
+      components
+    };
+  }
+};
+function parseMildaDocument(src, opts = {}) {
+  let toks;
+  try {
+    toks = lex(src);
+  } catch (e) {
+    const le = e;
+    return {
+      document: emptyDocument(opts),
+      issues: [{ severity: "error", code: "lex", message: le.message, line: le.line ?? 1, col: le.col ?? 1 }]
+    };
+  }
+  const p = new Parser(toks);
+  const document = p.parseDocument(opts);
+  return { document, issues: p.issues };
+}
+function emptyDocument(opts) {
+  return {
+    milda: opts.milda ?? "0.1",
+    kind: "design-system",
+    prelude: opts.prelude ?? "0.0.2",
+    meta: { id: `ds.${seg(opts.name ?? "design-system")}`, name: opts.name ?? "Design system", version: "0.0.0" },
+    foundations: { contextGroups: [], layers: [], sharedTypes: [], metadata: [] },
+    components: []
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  LexError,
+  TOKEN_VALUE_KIND,
+  allTokensOfType,
+  archetypesByName,
+  atomsByName,
+  collectActiveStates,
+  conformance,
+  findToken,
+  lex,
+  parseMildaDocument,
+  preludeV0,
+  resolveFacets,
+  resolveLayout,
+  resolveToken,
+  validate
+});