@mildastudio/milda 0.1.0 → 0.1.1

package/dist/index.js

@@ -26,6 +26,7 @@ __export(index_exports, {
   archetypesByName: () => archetypesByName,
   atomsByName: () => atomsByName,
   collectActiveStates: () => collectActiveStates,
+  compositesByName: () => compositesByName,
   conformance: () => conformance,
   findToken: () => findToken,
   lex: () => lex,
@@ -47,6 +48,7 @@ var TOKEN_VALUE_KIND = {
   shadow: "shadow",
   typography: "typography",
   fontFamily: "fontFamily",
+  fontWeight: "fontWeight",
   duration: "duration",
   opacity: "opacity",
   blur: "blur",
@@ -576,6 +578,7 @@ var composites = [
       { atom: "presentation", as: "P", params: { surface: "inline" } }
     ],
     composition: [{ kind: "wire", from: "T.change", to: "P.toggle" }],
+    emits: [{ name: "toggle" }],
     note: "\u2248 toggle(expanded) + presentation(inline); exposes expanded"
   },
   {
@@ -613,6 +616,7 @@ var composites = [
     kind: "composite",
     name: "stepping-nav",
     builtFrom: ["navigation"],
+    emits: [{ name: "stepChange" }, { name: "complete" }],
     note: "\u2248 navigation(ordered) + constraint; ordered progress through steps; exposes active, complete"
   },
   {
@@ -966,7 +970,11 @@ var archetypes = [
       }
     ],
     composes: ["selection.single", "presentation", "browse", "dismiss", "masking"],
-    realizationNote: "web calendar-grid \xB7 iOS wheel (momentum+detent+haptic) \xB7 Android dialog"
+    // Behavior is the shared framework-agnostic calendar core (proposal 0029,
+    // targets/behavior/calendar.ts); node.calendar picks single|range + weekStartsOn
+    // + disabledWeekdays. The `day` grid cell carries calendar states (today,
+    // outsideMonth, selected, rangeStart, rangeEnd, inRange) rendered as data-* attrs.
+    realizationNote: "web calendar-grid (single|range via node.calendar) \xB7 iOS wheel (momentum+detent+haptic) \xB7 Android dialog"
   },
   {
     kind: "archetype",
@@ -998,7 +1006,10 @@ var archetypes = [
       }
     ],
     composes: ["selection.single", "presentation", "browse", "dismiss", "masking"],
-    realizationNote: "iOS wheel \xB7 Android dialog"
+    // Behavior is the shared framework-agnostic time core (proposal 0029,
+    // targets/behavior/timepicker.ts); node.timePicker picks the slot step + 12/24h.
+    // Web realization = a listbox of time slots; iOS wheel is a per-platform view.
+    realizationNote: "web time-slot listbox (step via node.timePicker) \xB7 iOS wheel \xB7 Android dialog"
   },
   {
     kind: "archetype",
@@ -1021,11 +1032,25 @@ var archetypes = [
         children: [
           { name: "area", role: "container" },
           { name: "hue", role: "container" },
-          { name: "input", role: "input" }
+          { name: "alpha", role: "container" },
+          { name: "eyedropper", role: "control" },
+          { name: "input", role: "input" },
+          {
+            name: "swatches",
+            role: "container",
+            children: [{ name: "swatch", role: "item" }]
+          }
         ]
       }
     ],
-    composes: ["range", "value-entry", "presentation", "dismiss"]
+    composes: ["range", "value-entry", "presentation", "dismiss"],
+    // Behavior is the shared framework-agnostic color core (proposal 0029/0035,
+    // targets/behavior/color.ts): HSV<->RGB<->hex + OKLCH math and the area/hue/alpha
+    // geometry, so every target computes an identical picker. node.colorPicker (0035)
+    // picks the working space (srgb|oklch), the editable format tabs (hex/rgb/hsl/hsb),
+    // opacity, eyedropper, preset swatches, and popover-vs-inline layout. The `alpha`,
+    // `eyedropper` and `swatches` parts render only when their config flag is on.
+    realizationNote: "web: SV/OKLCH area + hue + optional alpha, format tabs, eyedropper, swatches, popover|inline \xB7 native color input fallback"
   },
   {
     kind: "archetype",
@@ -1502,10 +1527,11 @@ var archetypes = [
   },
   {
     kind: "archetype",
-    name: "Image",
+    name: "Media",
     group: "Media",
-    contract: "bitmap w/ alt + fit",
+    contract: "image/video/audio/embed w/ alt + fit (proposal 0028)",
     produces: { level: "phrase", interactive: false },
+    anatomy: [{ name: "media", role: "content" }],
     composes: []
   },
   {
@@ -1535,6 +1561,14 @@ var facets = [
     covers: "edge: color + width (hairline|thin|thick) + style",
     divergence: "iOS often overlay-stroke"
   },
+  { name: "border.top", covers: "top edge (physical side)" },
+  { name: "border.right", covers: "right edge (physical side)" },
+  { name: "border.bottom", covers: "bottom edge (physical side)" },
+  { name: "border.left", covers: "left edge (physical side)" },
+  { name: "border.inline-start", covers: "leading edge (logical, writing-direction)" },
+  { name: "border.inline-end", covers: "trailing edge (logical, writing-direction)" },
+  { name: "border.block-start", covers: "block-start edge (logical)" },
+  { name: "border.block-end", covers: "block-end edge (logical)" },
   { name: "corner", covers: "corner radius (token role)" },
   { name: "inset", covers: "internal padding (block/inline)" },
   { name: "gap", covers: "spacing between children" },
@@ -1549,6 +1583,17 @@ var facets = [
     divergence: "web -webkit-line-clamp \xB7 .lineLimit \xB7 maxLines+overflow"
   },
   { name: "textWrap", covers: "wrap | nowrap | break" },
+  {
+    name: "weight",
+    covers: "font-weight (typography axis \xA73, split out of the `text` role bundle)",
+    divergence: "web font-weight \xB7 .fontWeight \xB7 TextStyle.fontWeight"
+  },
+  {
+    name: "font",
+    covers: "font-family (typography axis \xA73)",
+    divergence: "web font-family \xB7 UIFont \xB7 Typeface"
+  },
+  { name: "slant", covers: "font-style: normal | italic | oblique (typography axis \xA73)" },
   {
     name: "elevation",
     covers: "depth",
@@ -1659,6 +1704,9 @@ var preludeV0 = {
   nonBehaviors
 };
 var atomsByName = Object.fromEntries(atoms.map((a) => [a.name, a]));
+var compositesByName = Object.fromEntries(
+  composites.map((c) => [c.name, c])
+);
 var archetypesByName = Object.fromEntries(
   archetypes.map((a) => [a.name, a])
 );
@@ -1734,6 +1782,8 @@ function facetTokenRefs(facets2) {
     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);
+    } else if ("border" in v) {
+      if (v.border.color) ids.push(v.border.color);
     }
   }
   return ids;
@@ -1766,12 +1816,13 @@ function validate(doc, prelude) {
     for (const tok of layer.tokens) {
       if (tok.value.kind === "alias") {
         const where = `token ${tok.name} (${tok.id})`;
-        if (!groupIds.has(tok.value.by)) {
+        if (tok.value.by !== "" && !groupIds.has(tok.value.by)) {
           issues.push({
             severity: "error",
             code: "alias.unknownGroup",
             message: `alias by unknown context group "${tok.value.by}"`,
-            where
+            where,
+            id: tok.id
           });
         }
         for (const refId of Object.values(tok.value.refs)) {
@@ -1780,7 +1831,8 @@ function validate(doc, prelude) {
               severity: "error",
               code: "alias.danglingRef",
               message: `alias ref points at missing token "${refId}"`,
-              where
+              where,
+              id: tok.id
             });
           }
         }
@@ -1789,12 +1841,13 @@ function validate(doc, prelude) {
   }
   for (const comp of doc.components) {
     const where = `component ${comp.name} (${comp.id})`;
-    if (!archetypeNames.has(comp.archetype)) {
+    if (comp.archetype !== "" && !archetypeNames.has(comp.archetype)) {
       issues.push({
         severity: "error",
         code: "component.unknownArchetype",
         message: `unknown archetype "${comp.archetype}"`,
-        where
+        where,
+        id: comp.id
       });
     }
     const propIds = new Set(comp.contract.props.map((p) => p.id));
@@ -1804,7 +1857,8 @@ function validate(doc, prelude) {
           severity: "error",
           code: "param.danglingProp",
           message: `param "${param}" binds missing prop "${binding.prop}"`,
-          where
+          where,
+          id: comp.id
         });
       }
     }
@@ -1825,7 +1879,8 @@ function checkPart(comp, partName, part, ctx) {
           severity: "error",
           code: "facet.unknown",
           message: `unknown facet "${name}"`,
-          where: scope
+          where: scope,
+          id: comp.id
         });
       }
     }
@@ -1835,7 +1890,8 @@ function checkPart(comp, partName, part, ctx) {
           severity: "error",
           code: "facet.danglingToken",
           message: `facet references missing token "${id}"`,
-          where: scope
+          where: scope,
+          id: comp.id
         });
       }
     }
@@ -1847,7 +1903,8 @@ function checkPart(comp, partName, part, ctx) {
           severity: "error",
           code: "layout.danglingToken",
           message: `layout references missing token "${id}"`,
-          where: scope
+          where: scope,
+          id: comp.id
         });
       }
     }
@@ -1861,7 +1918,8 @@ function checkPart(comp, partName, part, ctx) {
         severity: "error",
         code: "state.unknown",
         message: `unknown state "${stateName}"`,
-        where: scope
+        where: scope,
+        id: comp.id
       });
     }
     checkFacets(override?.facets, scope);
@@ -1939,13 +1997,16 @@ var PUNCT = {
   "}": "rbrace",
   "(": "lparen",
   ")": "rparen",
+  "[": "lbracket",
+  "]": "rbracket",
   "<": "lt",
   ">": "gt",
   ":": "colon",
   "=": "equals",
   ",": "comma",
   ";": "semi",
-  "?": "question"
+  "?": "question",
+  "@": "at"
 };
 function lex(src) {
   const tokens = [];
@@ -2016,6 +2077,21 @@ function lex(src) {
       push("arrow", "->", startPos, startLine, startCol);
       continue;
     }
+    if (c === "!" && src[i + 1] === "=") {
+      advance(2);
+      push("ne", "!=", startPos, startLine, startCol);
+      continue;
+    }
+    if (c === "<" && src[i + 1] === "=") {
+      advance(2);
+      push("lte", "<=", startPos, startLine, startCol);
+      continue;
+    }
+    if (c === ">" && src[i + 1] === "=") {
+      advance(2);
+      push("gte", ">=", startPos, startLine, startCol);
+      continue;
+    }
     if (PUNCT[c]) {
       advance();
       push(PUNCT[c], c, startPos, startLine, startCol);
@@ -2043,10 +2119,24 @@ 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)}`;
+function metaValueType(v) {
+  if (typeof v === "number") return { kind: "number" };
+  if (typeof v === "boolean") return { kind: "boolean" };
+  if (Array.isArray(v)) return { kind: "array", item: { kind: "string" } };
+  return { kind: "string" };
+}
 var FACET_MAP = {
   fill: "fill",
   ink: "ink",
   border: "border",
+  "border.top": "border.top",
+  "border.right": "border.right",
+  "border.bottom": "border.bottom",
+  "border.left": "border.left",
+  "border.inline-start": "border.inline-start",
+  "border.inline-end": "border.inline-end",
+  "border.block-start": "border.block-start",
+  "border.block-end": "border.block-end",
   corner: "corner",
   inset: "inset",
   gap: "gap",
@@ -2058,9 +2148,9 @@ var FACET_MAP = {
   opacity: "opacity",
   ring: "ring",
   backdrop: "backdrop",
-  weight: null,
-  font: null,
-  slant: null
+  weight: "weight",
+  font: "font",
+  slant: "slant"
 };
 var TYPE_MAP = {
   color: "color",
@@ -2072,6 +2162,8 @@ var TYPE_MAP = {
   typography: "typography",
   "font-family": "fontFamily",
   fontFamily: "fontFamily",
+  "font-weight": "fontWeight",
+  fontWeight: "fontWeight",
   duration: "duration",
   opacity: "opacity",
   blur: "blur",
@@ -2095,10 +2187,34 @@ function hexToColor(hex) {
   if (h.length === 8) value.alpha = byte(3);
   return value;
 }
+var COLOR_FNS = /* @__PURE__ */ new Set(["hex", "srgb", "rgb", "p3", "oklch", "hsl"]);
+var UNIT_RE = /^(-?\d*\.?\d+)(px|rem|em|%|ms|s)$/;
+function unitToValue(n, unit) {
+  switch (unit) {
+    case "px":
+      return { value: n, unit: "fixed" };
+    case "em":
+      return { value: n, unit: "em" };
+    case "%":
+      return { value: n, unit: "percent" };
+    case "ms":
+      return { ms: n };
+    case "s":
+      return { ms: n * 1e3 };
+    default:
+      return { value: n, unit: "scaled" };
+  }
+}
 var Parser = class {
   constructor(toks) {
     this.pos = 0;
     this.issues = [];
+    // Source spans for declared entities (see NodeSpan). Populated as declarations are
+    // parsed; the AST itself never gains position fields.
+    this.spans = [];
+    // The component currently being parsed, so nested part/prop/event spans can point
+    // back at it via `parentId`.
+    this.currentComponentId = null;
     // 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.
@@ -2118,6 +2234,73 @@ var Parser = class {
     this.issue("warning", "inline-literal", `inline ${astType} literal in an alias slot hoisted to token ${id}`, tok);
     return id;
   }
+  // Hoist an already-typed token value (an inline literal in an alias slot) into a
+  // synthesized token and return its id.
+  hoistValue(astType, value, tok) {
+    const key = `${astType} ${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;
+  }
+  // A self-typing value literal: a color-space function (`oklch(…)`, `hex(rrggbb)`, …)
+  // or a unit-suffixed number (`8px`, `150ms`). Returns a raw TokenValue, or null if the
+  // cursor isn't at such a literal (then it consumes nothing).
+  tryParseLiteralValue() {
+    const t = this.peek();
+    if (t.type !== "word") return null;
+    if (COLOR_FNS.has(t.value) && this.toks[this.pos + 1]?.type === "lparen") {
+      return { kind: "raw", value: this.parseColorFn(t.value) };
+    }
+    const m = UNIT_RE.exec(t.value);
+    if (m) {
+      this.next();
+      return { kind: "raw", value: unitToValue(Number(m[1]), m[2]) };
+    }
+    return null;
+  }
+  // `fn( a b c [alpha] )` — space-separated numeric channels (hex takes raw digits).
+  parseColorFn(fn) {
+    this.next();
+    this.expect("lparen", "color-lparen");
+    const nums = [];
+    let hex = "";
+    while (!this.at("rparen") && !this.at("eof")) {
+      const w = this.next().value;
+      if (fn === "hex") hex += w;
+      else {
+        const n = Number(w);
+        if (!Number.isNaN(n)) nums.push(n);
+      }
+    }
+    this.expect("rparen", "color-rparen");
+    if (fn === "hex") {
+      return hexToColor(hex.startsWith("#") ? hex : `#${hex}`) ?? { space: "srgb", channels: [0, 0, 0] };
+    }
+    const c = (i) => nums[i] ?? 0;
+    let cv;
+    if (fn === "rgb") cv = { space: "srgb", channels: [c(0) / 255, c(1) / 255, c(2) / 255] };
+    else if (fn === "p3") cv = { space: "display-p3", channels: [c(0), c(1), c(2)] };
+    else cv = { space: fn, channels: [c(0), c(1), c(2)] };
+    if (nums.length >= 4) cv.alpha = nums[3];
+    return cv;
+  }
+  // Self-typing literals let us check the value's inherent kind against the token's
+  // declared type (e.g. `token x : color = 8px` is a dimension in a color slot).
+  checkLiteralType(astType, lit, tok) {
+    if (lit.kind !== "raw") return;
+    const v = lit.value;
+    if (typeof v !== "object" || v === null) return;
+    const cat = "space" in v ? "color" : "ms" in v ? "duration" : "unit" in v ? "dimension" : null;
+    if (!cat) return;
+    const expected = astType === "color" ? "color" : astType === "duration" ? "duration" : astType === "spacing" || astType === "radius" || astType === "size" ? "dimension" : null;
+    if (expected && cat !== expected) {
+      this.issue("error", "value-type", `${cat} literal in a "${astType}" token`, tok);
+    }
+  }
   peek() {
     return this.toks[this.pos];
   }
@@ -2143,6 +2326,28 @@ var Parser = class {
     if (!this.at("eof")) this.next();
     return true;
   }
+  // ─── span recording (source positions for tooling) ─────────────────────────
+  recordSpan(span) {
+    this.spans.push(span);
+  }
+  startPos(tok) {
+    return { line: tok.line, col: tok.col };
+  }
+  // End position of a token = its start advanced past its source text. Strings add 2
+  // for the surrounding quotes (escape sequences make this a slight over-estimate,
+  // affecting only a rarely-used string span — never an identifier or brace).
+  endPos(tok) {
+    const len = tok.type === "newline" || tok.type === "eof" ? 0 : tok.type === "string" ? tok.value.length + 2 : tok.value.length;
+    return { line: tok.line, col: tok.col + len };
+  }
+  rangeOf(start, end) {
+    return { start: this.startPos(start), end: this.endPos(end) };
+  }
+  // The most-recently-consumed token — closes a span that has no trailing brace
+  // (a single-line `token`/`type` declaration ends at its value).
+  lastTok() {
+    return this.toks[Math.max(0, this.pos - 1)];
+  }
   issue(severity, code, message, tok = this.peek()) {
     this.issues.push({ severity, code, message, line: tok.line, col: tok.col });
   }
@@ -2173,7 +2378,8 @@ var Parser = class {
   }
   // ── context-group NAME { ctx ctx … } ──
   parseContextGroup() {
-    this.next();
+    const kw = this.next();
+    const nameTok = this.peek();
     const name = this.expectWord("cg-name");
     this.expect("lbrace", "cg-lbrace");
     const contexts = [];
@@ -2182,11 +2388,27 @@ var Parser = class {
         this.pos++;
         continue;
       }
+      const ctxTok = this.peek();
       const ctxName = this.expectWord("cg-ctx");
       if (!ctxName) break;
       contexts.push({ id: ctxId(name, ctxName), name: ctxName });
+      this.recordSpan({
+        id: ctxId(name, ctxName),
+        kind: "context",
+        name: ctxName,
+        nameRange: this.rangeOf(ctxTok, ctxTok),
+        fullRange: this.rangeOf(ctxTok, ctxTok),
+        parentId: cgId(name)
+      });
     }
-    this.expect("rbrace", "cg-rbrace");
+    const close = this.expect("rbrace", "cg-rbrace");
+    this.recordSpan({
+      id: cgId(name),
+      kind: "contextGroup",
+      name,
+      nameRange: this.rangeOf(nameTok, nameTok),
+      fullRange: this.rangeOf(kw, close)
+    });
     return { id: cgId(name), name, contexts };
   }
   // ── raw value literal → a JS value (string | number | nested object) ──
@@ -2195,6 +2417,12 @@ var Parser = class {
     if (t.type === "string") return this.next().value;
     if (t.type === "lbrace") return this.parseStructured();
     if (t.type === "word") {
+      if (COLOR_FNS.has(t.value) && this.toks[this.pos + 1]?.type === "lparen") return this.parseColorFn(t.value);
+      const m = UNIT_RE.exec(t.value);
+      if (m) {
+        this.next();
+        return unitToValue(Number(m[1]), m[2]);
+      }
       const w = this.next().value;
       return NUMBER_RE.test(w) ? Number(w) : w;
     }
@@ -2236,6 +2464,7 @@ var Parser = class {
       }
     }
     if (astType === "opacity" && typeof raw === "number") return { kind: "raw", value: { value: raw } };
+    if (astType === "fontWeight" && typeof raw === "number") return { kind: "raw", value: { weight: 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 };
@@ -2261,7 +2490,11 @@ var Parser = class {
       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)) {
+      const lit = this.tryParseLiteralValue();
+      if (lit) {
+        this.checkLiteralType(astType, lit, slot);
+        refId = this.hoistValue(astType, lit, slot);
+      } else 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");
@@ -2303,6 +2536,15 @@ var Parser = class {
       return this.typedRaw(astType, raw, t);
     }
     if (t.type === "word") {
+      const lit = this.tryParseLiteralValue();
+      if (lit) {
+        this.checkLiteralType(astType, lit, t);
+        return lit;
+      }
+      if (NUMBER_RE.test(t.value)) {
+        this.next();
+        return this.typedRaw(astType, Number(t.value), t);
+      }
       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) } };
@@ -2342,6 +2584,7 @@ var Parser = class {
   }
   parseTokenDecl(_order) {
     const startTok = this.next();
+    const nameTok = this.peek();
     const path = this.expectWord("token-path");
     if (!path) return null;
     this.expect("colon", "token-colon");
@@ -2350,6 +2593,13 @@ var Parser = class {
     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);
+    this.recordSpan({
+      id: tokId(path),
+      kind: "token",
+      name: path,
+      nameRange: this.rangeOf(nameTok, nameTok),
+      fullRange: this.rangeOf(startTok, this.lastTok())
+    });
     return {
       id: tokId(path),
       name: path,
@@ -2461,11 +2711,19 @@ var Parser = class {
     return { kind: "ref", ref: stId(w) };
   }
   parseSharedType() {
-    this.next();
+    const kw = this.next();
+    const nameTok = this.peek();
     const name = this.expectWord("type-name");
     if (!name) return null;
     this.expect("equals", "type-equals");
     const definition = this.parseTypeExpr();
+    this.recordSpan({
+      id: stId(name),
+      kind: "sharedType",
+      name,
+      nameRange: this.rangeOf(nameTok, nameTok),
+      fullRange: this.rangeOf(kw, this.lastTok())
+    });
     return { id: stId(name), name, definition };
   }
   // ════════════════════════════════════════════════════════════════════════
@@ -2495,6 +2753,125 @@ var Parser = class {
     }
     return { prop, eq };
   }
+  // ── Predicate expression parser (proposal 0032) ─────────────────────────────
+  // Recursive-descent over the surface predicate grammar emitted by @mildastudio/
+  // generate's `predToDsl` (targets/dsl/emit.ts). Precedence, lowest → highest:
+  //   or  →  and  →  unary(`not`)  →  primary(`( … )` | leaf)
+  // A leaf names a source (`state s` / `context g` / `ancestor id s` / a bare prop path)
+  // then an optional operator + value: a bare leaf is `set`, `not <leaf>` is `unset`, and
+  // a parenthesized `not ( … )` negates a whole group. Values are bare idents/numbers/
+  // bools or quoted strings (mirroring the emitter's `predValue`), coerced to a JS type.
+  parsePredicate() {
+    return this.parsePredOr();
+  }
+  parsePredOr() {
+    const first = this.parsePredAnd();
+    if (!this.atWord("or")) return first;
+    const items = [first];
+    while (this.atWord("or")) {
+      this.next();
+      items.push(this.parsePredAnd());
+    }
+    return { kind: "any", items };
+  }
+  parsePredAnd() {
+    const first = this.parsePredUnary();
+    if (!this.atWord("and")) return first;
+    const items = [first];
+    while (this.atWord("and")) {
+      this.next();
+      items.push(this.parsePredUnary());
+    }
+    return { kind: "all", items };
+  }
+  parsePredUnary() {
+    if (this.atWord("not")) {
+      this.next();
+      if (this.at("lparen")) {
+        this.next();
+        const item = this.parsePredOr();
+        this.expect("rparen", "pred-not-rparen");
+        return { kind: "not", item };
+      }
+      return { kind: "cmp", ref: this.parsePredRef(), op: "unset" };
+    }
+    return this.parsePredPrimary();
+  }
+  parsePredPrimary() {
+    if (this.at("lparen")) {
+      this.next();
+      const inner = this.parsePredOr();
+      this.expect("rparen", "pred-rparen");
+      return inner;
+    }
+    return this.parsePredLeaf();
+  }
+  // A comparison leaf: a source, then an optional operator + value. No operator ⇒ `set`.
+  parsePredLeaf() {
+    const ref = this.parsePredRef();
+    const op = this.predOp();
+    if (!op) return { kind: "cmp", ref, op: "set" };
+    return { kind: "cmp", ref, op, value: this.parsePredValue() };
+  }
+  // The source of a leaf: `state <s>` / `context <g>` / `ancestor <id> <s>` / bare prop path.
+  parsePredRef() {
+    if (this.atWord("state")) {
+      this.next();
+      return { kind: "state", state: this.expectWord("pred-state") };
+    }
+    if (this.atWord("context")) {
+      this.next();
+      return { kind: "context", group: this.expectWord("pred-context") };
+    }
+    if (this.atWord("ancestor")) {
+      this.next();
+      const nodeId = this.expectWord("pred-ancestor-id");
+      const state = this.expectWord("pred-ancestor-state");
+      return { kind: "ancestor", nodeId, state };
+    }
+    return { kind: "prop", path: this.expectWord("pred-prop") };
+  }
+  // A comparison operator token → CompareOp, or null when the next token isn't one.
+  predOp() {
+    switch (this.peek().type) {
+      case "equals":
+        this.next();
+        return "eq";
+      case "ne":
+        this.next();
+        return "ne";
+      case "lt":
+        this.next();
+        return "lt";
+      case "lte":
+        this.next();
+        return "lte";
+      case "gt":
+        this.next();
+        return "gt";
+      case "gte":
+        this.next();
+        return "gte";
+      default:
+        if (this.atWord("contains")) {
+          this.next();
+          return "contains";
+        }
+        return null;
+    }
+  }
+  // A leaf value: a quoted string, or a bare word coerced to number / boolean / string
+  // (mirrors `parseRealizeCond` and the emitter's bare-vs-quoted `predValue`).
+  parsePredValue() {
+    const t = this.peek();
+    if (t.type === "string") return this.next().value;
+    if (t.type === "word") {
+      const w = this.next().value;
+      return NUMBER_RE.test(w) ? Number(w) : w === "true" ? true : w === "false" ? false : w;
+    }
+    this.issue("error", "pred-value", `expected a comparison value, got ${t.type}`);
+    return "";
+  }
   parsePropDefault() {
     const t = this.peek();
     if (t.type === "string") return this.next().value;
@@ -2517,6 +2894,7 @@ var Parser = class {
     return void 0;
   }
   parsePropDecl() {
+    const nameTok = this.peek();
     const name = this.expectWord("prop-name");
     if (!name) return null;
     const type = this.parseTypeExpr();
@@ -2530,6 +2908,28 @@ var Parser = class {
       this.next();
       prop.binding = this.expectWord("bind-target");
     }
+    const meta = {};
+    while (this.at("at")) {
+      this.next();
+      const key = this.expectWord("annot-key");
+      const t = this.peek();
+      let value = true;
+      if (t.type === "string") value = this.next().value;
+      else if (t.type === "word") {
+        const w = this.next().value;
+        value = NUMBER_RE.test(w) ? Number(w) : w === "true" ? true : w === "false" ? false : w;
+      }
+      if (key) meta[key] = value;
+    }
+    if (Object.keys(meta).length) prop.meta = meta;
+    this.recordSpan({
+      id: `${this.currentComponentId ?? ""}#prop.${seg(name)}`,
+      kind: "prop",
+      name,
+      nameRange: this.rangeOf(nameTok, nameTok),
+      fullRange: this.rangeOf(nameTok, this.lastTok()),
+      parentId: this.currentComponentId ?? void 0
+    });
     return prop;
   }
   parseProps(props) {
@@ -2557,6 +2957,7 @@ var Parser = class {
         this.pos++;
         continue;
       }
+      const nameTok = this.peek();
       const name = this.expectWord("event-name");
       if (name) {
         const e = { name };
@@ -2565,6 +2966,14 @@ var Parser = class {
           e.from = this.expectWord("event-from");
         }
         events.push(e);
+        this.recordSpan({
+          id: `${this.currentComponentId ?? ""}#event.${seg(name)}`,
+          kind: "event",
+          name,
+          nameRange: this.rangeOf(nameTok, nameTok),
+          fullRange: this.rangeOf(nameTok, this.lastTok()),
+          parentId: this.currentComponentId ?? void 0
+        });
       }
       if (this.at("semi") || this.at("newline")) this.pos++;
       this.ensureProgress(mark);
@@ -2737,6 +3146,16 @@ var Parser = class {
     if (mapped === "inset") {
       return { name: "inset", value: { inset: this.parseInsetArgs() } };
     }
+    if (mapped === "border" || mapped.startsWith("border.")) {
+      const border = {};
+      while (this.at("word")) {
+        const w = this.next().value;
+        if (w === "solid" || w === "dashed" || w === "dotted") border.style = w;
+        else if (w.includes(".")) border.color = tokId(w);
+        else border.width = tokId(w);
+      }
+      return { name: mapped, value: { border } };
+    }
     const t = this.peek();
     let value;
     if (t.type === "string") {
@@ -2745,6 +3164,7 @@ var Parser = class {
       const v = this.next().value;
       if (NUMBER_RE.test(v)) value = { literal: Number(v) };
       else if (isRawValue(v)) value = { raw: v };
+      else if (!v.includes(".")) value = { raw: v };
       else value = { token: tokId(v) };
     } else {
       this.issue("error", "facet-value", `expected a facet value, got ${t.type}`);
@@ -2766,11 +3186,13 @@ var Parser = class {
     this.applyStyleBody(variant);
     return variant;
   }
-  // `when COND { … }` → a state-less prop-conditioned PartVariant (proposal 0025).
+  // `when <predicate> { … }` → a state-less predicate-conditioned PartVariant. The rich
+  // predicate grammar (proposal 0032) supersedes the flat single-condition form: it carries
+  // OR / NOT / operators / state·context·ancestor leaves. A plain `when prop = value` parses
+  // to the degenerate single-`eq` predicate, so the legacy one-condition case still works.
   parseWhenBlock() {
     this.next();
-    const when = this.parseRealizeCond();
-    const variant = { when };
+    const variant = { whenPredicate: this.parsePredicate() };
     this.applyStyleBody(variant);
     return variant;
   }
@@ -2797,9 +3219,26 @@ var Parser = class {
     this.expect("rbrace", "style-rbrace");
     if (Object.keys(facets2).length) target.facets = facets2;
   }
+  // `slot [single|optional|many] [of content | of TYPE]` — a content slot on a part.
+  // Bare `slot` defaults to a single content slot.
+  parseSlot() {
+    let arity = "single";
+    if (this.atWord("single") || this.atWord("optional") || this.atWord("many")) {
+      arity = this.next().value;
+    }
+    let accepts = { kind: "content" };
+    if (this.atWord("of")) {
+      this.next();
+      const w = this.expectWord("slot-accepts");
+      if (w && w !== "content") accepts = { kind: "type", ref: w };
+    }
+    this.skipToTerminator();
+    return { arity, accepts };
+  }
   // `part NAME { pstmt* }` → [name, Part]
   parsePart() {
-    this.next();
+    const kw = this.next();
+    const nameTok = this.peek();
     const name = this.expectWord("part-name");
     if (!name) return null;
     this.expect("lbrace", "part-lbrace");
@@ -2821,13 +3260,18 @@ var Parser = class {
         } else {
           part.layout = this.parseLayoutBody();
         }
+      } else if (this.atWord("present")) {
+        this.next();
+        if (this.atWord("when")) this.next();
+        else this.issue("warning", "present-when", "expected 'when' after 'present'");
+        part.presence = this.parsePredicate();
       } 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();
+        this.next();
+        part.slot = this.parseSlot();
       } else {
         const f = this.parseFacetStmt();
         if (f) facets2[f.name] = f.value;
@@ -2835,9 +3279,17 @@ var Parser = class {
       if (this.at("semi") || this.at("newline")) this.pos++;
       this.ensureProgress(mark);
     }
-    this.expect("rbrace", "part-rbrace");
+    const close = this.expect("rbrace", "part-rbrace");
     if (Object.keys(facets2).length) part.facets = facets2;
     if (variants.length) part.variants = variants;
+    this.recordSpan({
+      id: `${this.currentComponentId ?? ""}#part.${seg(name)}`,
+      kind: "part",
+      name,
+      nameRange: this.rangeOf(nameTok, nameTok),
+      fullRange: this.rangeOf(kw, close),
+      parentId: this.currentComponentId ?? void 0
+    });
     return [name, part];
   }
   // `realize TARGET [when COND] { rstmt* }`
@@ -2881,6 +3333,14 @@ var Parser = class {
       } else if (this.atWord("note")) {
         this.next();
         r.note = this.at("string") ? this.next().value : this.expectWord("note");
+      } else if (this.atWord("dismiss")) {
+        this.next();
+        const words = this.parseIdentListWords();
+        r.dismiss = words.length === 1 && words[0] === "none" ? [] : words;
+      } else if (this.atWord("backdrop")) {
+        this.next();
+        r.backdrop = this.at("word") ? this.next().value : void 0;
+        this.skipToTerminator();
       } 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 } : {} });
@@ -2922,6 +3382,21 @@ var Parser = class {
       this.next();
       commit.on = this.parseIdentListWords();
     }
+    if (this.at("lbrace")) {
+      this.next();
+      while (!this.at("rbrace") && !this.at("eof")) {
+        if (this.at("newline") || this.at("semi")) {
+          this.pos++;
+          continue;
+        }
+        const key = this.expectWord("commit-key");
+        const val = this.at("word") ? this.next().value : void 0;
+        if (key === "live" && val) commit.live = val;
+        else if (key === "settled" && val) commit.settled = val;
+        else this.skipToTerminator();
+      }
+      this.expect("rbrace", "commit-rbrace");
+    }
     return commit;
   }
   // A run of bare words up to a terminator (for `drop a b c`, `commit … on click enter`).
@@ -2931,13 +3406,18 @@ var Parser = class {
     return out;
   }
   parseComponent() {
-    this.next();
+    const kw = this.next();
+    const nameTok = this.peek();
     const name = this.expectWord("component-name");
     if (!name) return null;
+    const componentId = cmpId(name);
+    const prevComponentId = this.currentComponentId;
+    this.currentComponentId = componentId;
     let description;
     if (this.at("string")) description = this.next().value;
     this.expect("lbrace", "component-lbrace");
     let archetype = "";
+    let meta;
     const props = [];
     const events = [];
     const uses = [];
@@ -2953,6 +3433,8 @@ var Parser = class {
       if (this.atWord("archetype")) {
         this.next();
         archetype = this.expectWord("archetype");
+      } else if (this.atWord("meta")) {
+        meta = this.parseMetaBlock();
       } else if (this.atWord("props")) {
         this.parseProps(props);
       } else if (this.atWord("events")) {
@@ -2986,9 +3468,17 @@ var Parser = class {
       }
       this.ensureProgress(mark);
     }
-    this.expect("rbrace", "component-rbrace");
+    const close = this.expect("rbrace", "component-rbrace");
+    this.currentComponentId = prevComponentId;
+    this.recordSpan({
+      id: componentId,
+      kind: "component",
+      name,
+      nameRange: this.rangeOf(nameTok, nameTok),
+      fullRange: this.rangeOf(kw, close)
+    });
     const component = {
-      id: cmpId(name),
+      id: componentId,
       name,
       archetype,
       contract: { params: {}, props, events },
@@ -3000,18 +3490,91 @@ var Parser = class {
       const composition = { uses, coordination };
       component.composition = composition;
     }
+    if (meta && Object.keys(meta).length) component.meta = meta;
     return component;
   }
+  // ════════════════════════════════════════════════════════════════════════
+  // Header & metadata (proposal 0026)
+  // ════════════════════════════════════════════════════════════════════════
+  parseMetaValue() {
+    const t = this.peek();
+    if (t.type === "string") return this.next().value;
+    if (t.type === "lbracket") {
+      this.next();
+      const arr = [];
+      while (!this.at("rbracket") && !this.at("eof")) {
+        const mark = this.pos;
+        if (this.at("comma") || this.at("newline") || this.at("semi")) {
+          this.pos++;
+          continue;
+        }
+        const it = this.peek();
+        if (it.type === "string") arr.push(this.next().value);
+        else if (it.type === "word") {
+          const w = this.next().value;
+          arr.push(NUMBER_RE.test(w) ? Number(w) : w === "true" ? true : w === "false" ? false : w);
+        } else this.next();
+        this.ensureProgress(mark);
+      }
+      if (this.at("rbracket")) this.next();
+      return arr;
+    }
+    if (t.type === "word") {
+      this.next();
+      return NUMBER_RE.test(t.value) ? Number(t.value) : t.value === "true" ? true : t.value === "false" ? false : t.value;
+    }
+    this.issue("error", "meta-value", `expected a metadata value, got ${t.type}`);
+    return "";
+  }
+  parseMetaBlock() {
+    this.next();
+    this.expect("lbrace", "meta-lbrace");
+    const out = {};
+    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("meta-key");
+      const val = this.parseMetaValue();
+      if (key) out[key] = val;
+      if (this.at("semi") || this.at("newline")) this.pos++;
+      this.ensureProgress(mark);
+    }
+    this.expect("rbrace", "meta-rbrace");
+    return out;
+  }
   // ── top-level document driver ──
   parseDocument(opts) {
     const contextGroups = [];
     const layer = { id: "layer.foundations", name: "Foundations", order: 0, tokens: [] };
     const sharedTypes = [];
     const components = [];
+    const metadata = [];
+    let mildaVer = opts.milda ?? "0.1";
+    let preludeVer = opts.prelude ?? "0.0.2";
+    let docName = opts.name ?? "Design system";
+    let docVersion = "0.0.0";
+    let docDescription;
     this.skipNewlines();
     while (!this.at("eof")) {
       const mark = this.pos;
-      if (this.atWord("context-group")) {
+      if (this.atWord("milda")) {
+        this.next();
+        mildaVer = this.expectWord("milda-version") || mildaVer;
+      } else if (this.atWord("prelude")) {
+        this.next();
+        preludeVer = this.expectWord("prelude-version") || preludeVer;
+      } else if (this.atWord("meta")) {
+        const m = this.parseMetaBlock();
+        for (const [k, v] of Object.entries(m)) {
+          if (k === "name") docName = String(v);
+          else if (k === "version") docVersion = String(v);
+          else if (k === "description") docDescription = String(v);
+          else metadata.push({ id: `md.${seg(k)}`, key: k, type: metaValueType(v), value: v });
+        }
+      } else if (this.atWord("context-group")) {
         const cg = this.parseContextGroup();
         if (cg) contextGroups.push(cg);
       } else if (this.atWord("foundations")) {
@@ -3031,19 +3594,20 @@ var Parser = class {
       this.skipNewlines();
     }
     return {
-      milda: opts.milda ?? "0.1",
+      milda: mildaVer,
       kind: "design-system",
-      prelude: opts.prelude ?? "0.0.2",
+      prelude: preludeVer,
       meta: {
-        id: `ds.${seg(opts.name ?? "design-system")}`,
-        name: opts.name ?? "Design system",
-        version: "0.0.0"
+        id: `ds.${seg(docName)}`,
+        name: docName,
+        version: docVersion,
+        ...docDescription ? { description: docDescription } : {}
       },
       foundations: {
         contextGroups,
         layers: layer.tokens.length ? [layer] : [],
         sharedTypes,
-        metadata: []
+        metadata
       },
       components
     };
@@ -3057,12 +3621,13 @@ function parseMildaDocument(src, opts = {}) {
     const le = e;
     return {
       document: emptyDocument(opts),
-      issues: [{ severity: "error", code: "lex", message: le.message, line: le.line ?? 1, col: le.col ?? 1 }]
+      issues: [{ severity: "error", code: "lex", message: le.message, line: le.line ?? 1, col: le.col ?? 1 }],
+      spans: []
     };
   }
   const p = new Parser(toks);
   const document = p.parseDocument(opts);
-  return { document, issues: p.issues };
+  return { document, issues: p.issues, spans: p.spans };
 }
 function emptyDocument(opts) {
   return {
@@ -3082,6 +3647,7 @@ function emptyDocument(opts) {
   archetypesByName,
   atomsByName,
   collectActiveStates,
+  compositesByName,
   conformance,
   findToken,
   lex,