@astryxdesign/cli 0.1.7 → 0.1.8-canary.07362a9

package/{src/lib → lib}/xle/parse.mjs

@@ -17,6 +17,11 @@
  */
 
 export class XLEParseError extends Error {
+  /**
+   * @param {string} message
+   * @param {number} line
+   * @param {number} col
+   */
   constructor(message, line, col) {
     super(message);
     this.name = 'XLEParseError';
@@ -25,7 +30,10 @@ export class XLEParseError extends Error {
   }
 }
 
-/** Keys that expand to full prop names before validation. */
+/**
+ * Keys that expand to full prop names before validation.
+ * @type {Record<string, string>}
+ */
 export const KEY_ALIASES = {
   p: 'padding', pad: 'padding', g: 'gap', c: 'columns', cols: 'columns',
   w: 'width', h: 'height', cp: 'contentPadding', mw: 'maxWidth',
@@ -38,6 +46,12 @@ export const KEY_ALIASES = {
 /** Fused shorthand letters (`p6`, `g4`, `cp2`…) — letter must be a KEY_ALIAS. */
 const FUSED = new Set(['p', 'g', 'c', 'w', 'h', 'cp', 'mw', 'mh', 'rg', 'cg']);
 
+/**
+ * @param {string|null} name
+ * @param {number} line
+ * @param {number} col
+ * @returns {import('./xle-ast').XLENode}
+ */
 export function makeNode(name, line, col) {
   return {
     kind: 'node',
@@ -57,20 +71,30 @@ export function makeNode(name, line, col) {
   };
 }
 
+/**
+ * @param {number} line
+ * @param {number} col
+ * @returns {import('./xle-ast').XLEGroup}
+ */
 function makeGroup(line, col) {
   return {kind: 'group', repeat: null, children: [], line, col};
 }
 
 // ─── shared low-level helpers ──────────────────────────────────────────────
 
-const isIdentStart = (ch) => /[A-Za-z]/.test(ch);
-const isIdent = (ch) => /[A-Za-z0-9_-]/.test(ch);
+const isIdentStart = (/** @type {string} */ ch) => /[A-Za-z]/.test(ch);
+const isIdent = (/** @type {string} */ ch) => /[A-Za-z0-9_-]/.test(ch);
 
 /**
  * Split a string into tokens at depth-0 whitespace, where (), [], {} and
  * quotes raise depth. Used for attr blocks and outline lines.
+ * @param {string} str
+ * @param {number} line
+ * @param {number} startCol
+ * @returns {Array<{text: string, col: number}>}
  */
 function tokenize(str, line, startCol) {
+  /** @type {Array<{text: string, col: number}>} */
   const tokens = [];
   let i = 0;
   while (i < str.length) {
@@ -78,6 +102,7 @@ function tokenize(str, line, startCol) {
     if (i >= str.length) break;
     const start = i;
     let depth = 0;
+    /** @type {string|null} */
     let quote = null;
     while (i < str.length) {
       const ch = str[i];
@@ -101,7 +126,11 @@ function tokenize(str, line, startCol) {
   return tokens;
 }
 
-/** Parse a scalar/object/list attr value string into a JS value. */
+/**
+ * Parse a scalar/object/list attr value string into a JS value.
+ * @param {string} raw
+ * @returns {import('./xle-ast').XLEValue}
+ */
 export function parseValue(raw) {
   const s = raw.trim();
   if (/^(['"]).*\1$/.test(s)) return s.slice(1, -1);
@@ -110,6 +139,7 @@ export function parseValue(raw) {
   if (s === 'false') return false;
   if (s.startsWith('#')) return {idref: s.slice(1)};
   if (s.startsWith('{') && s.endsWith('}')) {
+    /** @type {Record<string, import('./xle-ast').XLEValue>} */
     const obj = {};
     for (const part of splitTop(s.slice(1, -1), ',')) {
       const idx = part.indexOf(':');
@@ -125,10 +155,16 @@ export function parseValue(raw) {
   return s; // bare ident — enum string
 }
 
-/** Split on a separator at bracket/quote depth 0. */
+/**
+ * Split on a separator at bracket/quote depth 0.
+ * @param {string} str
+ * @param {string} sep
+ * @returns {string[]}
+ */
 function splitTop(str, sep) {
   const parts = [];
   let depth = 0;
+  /** @type {string|null} */
   let quote = null;
   let cur = '';
   for (const ch of str) {
@@ -151,7 +187,13 @@ function splitTop(str, sep) {
   return parts.map(p => p.trim()).filter(Boolean);
 }
 
-/** Parse `{name +flag +flag2 :arg}` hint body (without braces). */
+/**
+ * Parse `{name +flag +flag2 :arg}` hint body (without braces).
+ * @param {string} body
+ * @param {number} line
+ * @param {number} col
+ * @returns {import('./xle-ast').Hint}
+ */
 function parseHintBody(body, line, col) {
   const m = body.trim().match(/^([a-z0-9][a-z0-9-]*)((?:\s*\+[a-z0-9-]+)*)(?:\s*:(.*))?$/);
   if (!m) {
@@ -169,8 +211,10 @@ function parseHintBody(body, line, col) {
 }
 
 /**
- * Interpret one attribute token. Returns an attr record or mutates node
- * for special tokens (slots are returned as {kind:'slot'} records too).
+ * Interpret one attribute token. Returns an attr record or a slot record.
+ * @param {{text: string, col: number}} token
+ * @param {number} line
+ * @returns {import('./xle-ast').Attr | import('./xle-ast').Slot}
  */
 function parseAttrToken(token, line) {
   const {text, col} = token;
@@ -182,6 +226,7 @@ function parseAttrToken(token, line) {
     }
     const name = text.slice(1, eq);
     const rest = text.slice(eq + 1);
+    /** @type {import('./xle-ast').SlotValue} */
     let value;
     if (rest.startsWith('(') && rest.endsWith(')')) {
       value = {subexpr: parseCompactSiblings(new CompactStream(rest.slice(1, -1), line, col + eq + 2))};
@@ -203,6 +248,7 @@ function parseAttrToken(token, line) {
 
   // key=value (split at first depth-0 '=')
   let depth = 0;
+  /** @type {string|null} */
   let quote = null;
   for (let i = 0; i < text.length; i++) {
     const ch = text[i];
@@ -240,6 +286,11 @@ function parseAttrToken(token, line) {
 // ─── compact (XLE) surface ─────────────────────────────────────────────────
 
 class CompactStream {
+  /**
+   * @param {string} src
+   * @param {number} [line]
+   * @param {number} [col]
+   */
   constructor(src, line = 1, col = 1) {
     this.src = src;
     this.i = 0;
@@ -253,21 +304,29 @@ class CompactStream {
     const col = (lines.length === 1 ? this.baseCol : 1) + lines[lines.length - 1].length;
     return {line, col};
   }
+  /** @param {number} [offset] */
   peek(offset = 0) { return this.src[this.i + offset]; }
   next() { return this.src[this.i++]; }
   eof() { return this.i >= this.src.length; }
   skipWs() { while (!this.eof() && /\s/.test(this.peek())) this.i++; }
+  /** @param {string} message */
   error(message) {
     const {line, col} = this.pos();
     throw new XLEParseError(message, line, col);
   }
-  /** Consume through the matching close bracket; returns inner text. */
+  /**
+   * Consume through the matching close bracket; returns inner text.
+   * @param {string} open
+   * @param {string} close
+   * @returns {string}
+   */
   readBalanced(open, close) {
     const startPos = this.pos();
     if (this.peek() !== open) this.error(`Expected '${open}'`);
     this.next();
     const start = this.i;
     let depth = 1;
+    /** @type {string|null} */
     let quote = null;
     while (!this.eof()) {
       const ch = this.next();
@@ -292,6 +351,10 @@ class CompactStream {
   }
 }
 
+/**
+ * @param {CompactStream} s
+ * @returns {import('./xle-ast').XLENode}
+ */
 function parseCompactNode(s) {
   const {line, col} = s.pos();
   let name = '';
@@ -359,6 +422,10 @@ function parseCompactNode(s) {
   return node;
 }
 
+/**
+ * @param {CompactStream} s
+ * @returns {import('./xle-ast').XLEItem}
+ */
 function parseCompactTerm(s) {
   s.skipWs();
   if (s.peek() === '(') {
@@ -387,11 +454,20 @@ function parseCompactTerm(s) {
   return parseCompactNode(s);
 }
 
+/**
+ * @param {import('./xle-ast').XLEItem} node
+ * @returns {import('./xle-ast').XLENode}
+ */
 function structuredCloneNode(node) {
   return JSON.parse(JSON.stringify(node));
 }
 
+/**
+ * @param {CompactStream} s
+ * @returns {import('./xle-ast').XLEItem[]}
+ */
 function parseCompactSiblings(s) {
+  /** @type {import('./xle-ast').XLEItem[]} */
   const terms = [];
   for (;;) {
     s.skipWs();
@@ -410,12 +486,17 @@ function parseCompactSiblings(s) {
   return terms;
 }
 
+/**
+ * @param {string} source
+ * @returns {import('./xle-ast').XLEDoc}
+ */
 export function parseCompact(source) {
   const parts = source.split(/;;/);
   const main = new CompactStream(parts[0]);
   const roots = parseCompactSiblings(main);
   main.skipWs();
   if (!main.eof()) main.error(`Unexpected '${main.peek()}'`);
+  /** @type {import('./xle-ast').XLEItem[]} */
   const overlays = [];
   for (const part of parts.slice(1)) {
     const s = new CompactStream(part);
@@ -428,20 +509,35 @@ export function parseCompact(source) {
 
 // ─── outline (XLO) surface ─────────────────────────────────────────────────
 
-/** Parse one outline line's node chain: `Layout > LayoutContent pad=0 !scroll`. */
+/**
+ * Parse one outline line's node chain: `Layout > LayoutContent pad=0 !scroll`.
+ * @param {string} text
+ * @param {number} line
+ * @returns {{head: import('./xle-ast').XLENode, tail: import('./xle-ast').XLENode}}
+ */
 function parseOutlineChain(text, line) {
   const segments = splitTop(text, '>');
+  /** @type {import('./xle-ast').XLENode | null} */
   let head = null;
+  /** @type {import('./xle-ast').XLENode | null} */
   let tail = null;
   for (const segment of segments) {
     const node = parseOutlineNodeSegment(segment, line);
     if (!head) head = node;
-    else tail.children.push(node);
+    else /** @type {import('./xle-ast').XLENode} */ (tail).children.push(node);
     tail = node;
   }
-  return {head, tail};
+  return /** @type {{head: import('./xle-ast').XLENode, tail: import('./xle-ast').XLENode}} */ ({
+    head,
+    tail,
+  });
 }
 
+/**
+ * @param {string} segment
+ * @param {number} line
+ * @returns {import('./xle-ast').XLENode}
+ */
 function parseOutlineNodeSegment(segment, line) {
   const tokens = tokenize(segment, line, 0);
   if (tokens.length === 0) throw new XLEParseError('Empty node', line, 1);
@@ -487,10 +583,17 @@ function parseOutlineNodeSegment(segment, line) {
   return node;
 }
 
+/**
+ * @param {string} source
+ * @returns {import('./xle-ast').XLEDoc}
+ */
 export function parseOutline(source) {
+  /** @type {import('./xle-ast').XLEItem[]} */
   const roots = [];
+  /** @type {import('./xle-ast').XLEItem[]} */
   const overlays = [];
   // Stack frames: {indent, container: array, node|null}
+  /** @type {Array<{indent: number, container: import('./xle-ast').XLEItem[], node: import('./xle-ast').XLENode | null}>} */
   const stack = [{indent: -1, container: roots, node: null}];
   let inOverlays = false;
 
@@ -499,7 +602,7 @@ export function parseOutline(source) {
     const raw = lines[li];
     const lineNo = li + 1;
     if (raw.trim() === '' || raw.trim().startsWith('#') || raw.trim().startsWith('//')) continue;
-    const indent = raw.match(/^[ \t]*/)[0].replace(/\t/g, '  ').length;
+    const indent = /** @type {RegExpMatchArray} */ (raw.match(/^[ \t]*/))[0].replace(/\t/g, '  ').length;
     const text = raw.trim();
 
     if (text === 'overlays:') {
@@ -530,6 +633,7 @@ export function parseOutline(source) {
           `Slot '${slotMatch[1]}:' has no parent component`, lineNo, indent + 1,
         );
       }
+      /** @type {import('./xle-ast').Slot & {value: {subexpr: import('./xle-ast').XLEItem[]}}} */
       const slot = {kind: 'slot', key: slotMatch[1], value: {subexpr: []}, line: lineNo, col: indent + 1};
       parent.node.slots.push(slot);
       const inline = slotMatch[2].trim();
@@ -557,6 +661,8 @@ export function parseOutline(source) {
  * Detect which surface the source uses. Multi-line input is outline
  * unless every line break sits inside an operator chain (trailing
  * `>`/`+`/`;;` or unclosed brackets), which is multi-line compact.
+ * @param {string} source
+ * @returns {'compact'|'outline'}
  */
 export function detectForm(source) {
   const lines = source.split('\n').map(l => l.trim()).filter(l => l !== '' && !l.startsWith('#') && !l.startsWith('//'));

package/{src/lib → lib}/xle/print.mjs

@@ -13,10 +13,14 @@
  * @position lib/xle — inverse of parse.mjs
  */
 
+/**
+ * @param {import('./xle-ast').XLEValue} value
+ * @returns {string}
+ */
 function valueText(value) {
   if (typeof value === 'string') return /[\s,'"]/.test(value) ? `'${value}'` : value;
   if (typeof value === 'number' || typeof value === 'boolean') return String(value);
-  if (value && value.idref) return `#${value.idref}`;
+  if (value && /** @type {any} */ (value).idref) return `#${/** @type {any} */ (value).idref}`;
   if (Array.isArray(value)) return `[${value.map(valueText).join(',')}]`;
   if (typeof value === 'object' && value !== null) {
     return `{${Object.entries(value)
@@ -26,6 +30,10 @@ function valueText(value) {
   return String(value);
 }
 
+/**
+ * @param {import('./xle-ast').Hint} hint
+ * @returns {string}
+ */
 function hintText(hint) {
   let out = hint.name;
   for (const flag of hint.flags || []) out += ` +${flag}`;
@@ -33,6 +41,7 @@ function hintText(hint) {
   return `{${out}}`;
 }
 
+/** @param {import('./xle-ast').XLENode} node */
 function attrTokens(node) {
   const tokens = [];
   for (const attr of node.attrs) {
@@ -43,17 +52,22 @@ function attrTokens(node) {
   return tokens;
 }
 
+/** @param {import('./xle-ast').XLENode} node */
 function slotTokensCompact(node) {
   return node.slots.map(slot => {
     if (slot.value == null) return `@${slot.key}`;
     if (typeof slot.value === 'string') return `@${slot.key}='${slot.value}'`;
-    if (slot.value.hint) return `@${slot.key}=${hintText(slot.value.hint)}`;
-    if (slot.value.idref) return `@${slot.key}=#${slot.value.idref}`;
-    if (slot.value.subexpr) return `@${slot.key}=(${siblingsCompact(slot.value.subexpr)})`;
+    if ('hint' in slot.value) return `@${slot.key}=${hintText(slot.value.hint)}`;
+    if (/** @type {any} */ (slot.value).idref) return `@${slot.key}=#${/** @type {any} */ (slot.value).idref}`;
+    if ('subexpr' in slot.value) return `@${slot.key}=(${siblingsCompact(slot.value.subexpr)})`;
     return `@${slot.key}`;
   });
 }
 
+/**
+ * @param {import('./xle-ast').XLENode} node
+ * @returns {string}
+ */
 function nodeCompact(node) {
   let out = node.name || '';
   if (node.id) out += `#${node.id}`;
@@ -72,6 +86,10 @@ function nodeCompact(node) {
   return out;
 }
 
+/**
+ * @param {import('./xle-ast').XLEItem} item
+ * @returns {string}
+ */
 function termCompact(item) {
   if (item.kind === 'group') {
     let out = `(${siblingsCompact(item.children)})`;
@@ -82,6 +100,10 @@ function termCompact(item) {
   return nodeCompact(item);
 }
 
+/**
+ * @param {import('./xle-ast').XLEItem[]} items
+ * @returns {string}
+ */
 function siblingsCompact(items) {
   return items
     .map((item, i) => {
@@ -96,6 +118,7 @@ function siblingsCompact(items) {
     .join(' + ');
 }
 
+/** @param {import('./xle-ast').XLEDoc} doc */
 export function toCompact(doc) {
   let out = siblingsCompact(doc.roots);
   for (const overlay of doc.overlays) {
@@ -106,6 +129,11 @@ export function toCompact(doc) {
 
 // ── outline ────────────────────────────────────────────────────────────────
 
+/**
+ * @param {import('./xle-ast').XLENode} node
+ * @param {number} depth
+ * @returns {string[]}
+ */
 function nodeOutlineLines(node, depth) {
   const pad = '  '.repeat(depth);
   let line = node.name || '';
@@ -121,21 +149,23 @@ function nodeOutlineLines(node, depth) {
 
   const lines = [pad + line.trimStart()];
   for (const slot of node.slots) {
-    if (slot.value && slot.value.subexpr) {
-      if (slot.value.subexpr.length === 1 && isSimpleNode(slot.value.subexpr[0])) {
-        const sub = nodeOutlineLines(slot.value.subexpr[0], 0)[0];
+    const sv = slot.value;
+    if (sv && typeof sv === 'object' && 'subexpr' in sv) {
+      const first = sv.subexpr[0];
+      if (sv.subexpr.length === 1 && first && isSimpleNode(first)) {
+        const sub = nodeOutlineLines(first, 0)[0];
         lines.push(`${pad}  ${slot.key}: ${sub}`);
         // simple = no children, so the single line is complete
       } else {
         lines.push(`${pad}  ${slot.key}:`);
-        for (const sub of slot.value.subexpr) lines.push(...itemOutlineLines(sub, depth + 2));
+        for (const sub of sv.subexpr) lines.push(...itemOutlineLines(sub, depth + 2));
       }
-    } else if (typeof slot.value === 'string') {
-      lines.push(`${pad}  ${slot.key}: "${slot.value}"`);
-    } else if (slot.value && slot.value.hint) {
-      lines.push(`${pad}  ${slot.key}: ${hintText(slot.value.hint)}`);
-    } else if (slot.value && slot.value.idref) {
-      lines.push(`${pad}  ${slot.key}: #${slot.value.idref}`);
+    } else if (typeof sv === 'string') {
+      lines.push(`${pad}  ${slot.key}: "${sv}"`);
+    } else if (sv && typeof sv === 'object' && 'hint' in sv) {
+      lines.push(`${pad}  ${slot.key}: ${hintText(sv.hint)}`);
+    } else if (sv && /** @type {any} */ (sv).idref) {
+      lines.push(`${pad}  ${slot.key}: #${/** @type {any} */ (sv).idref}`);
     } else {
       lines.push(`${pad}  ${slot.key}:`);
     }
@@ -144,10 +174,19 @@ function nodeOutlineLines(node, depth) {
   return lines;
 }
 
+/**
+ * @param {import('./xle-ast').XLEItem} item
+ * @returns {item is import('./xle-ast').XLENode}
+ */
 function isSimpleNode(item) {
   return item.kind === 'node' && item.children.length === 0 && item.slots.length === 0;
 }
 
+/**
+ * @param {import('./xle-ast').XLEItem} item
+ * @param {number} depth
+ * @returns {string[]}
+ */
 function itemOutlineLines(item, depth) {
   if (item.kind === 'group') {
     // A repeat-less group exists only to disambiguate compact-form
@@ -163,6 +202,7 @@ function itemOutlineLines(item, depth) {
   return nodeOutlineLines(item, depth);
 }
 
+/** @param {import('./xle-ast').XLEDoc} doc */
 export function toOutline(doc) {
   const lines = [];
   for (const item of doc.roots) lines.push(...itemOutlineLines(item, 0));

package/{src/lib → lib}/xle/registry-core.mjs

@@ -74,6 +74,8 @@ export const SPACING_STEPS = [0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10];
  * Parse enum values from a doc.mjs prop type string.
  * "'a' | 'b' | 'c'" → ['a','b','c'];  "1|2|3" → [1,2,3];
  * "SpacingStep" → SPACING_STEPS. Mixed/non-enum types → null.
+ * @param {string | undefined | null} type
+ * @returns {Array<string | number> | null}
  */
 export function parseEnumValues(type) {
   if (!type || typeof type !== 'string') return null;
@@ -83,6 +85,7 @@ export function parseEnumValues(type) {
   }
   const parts = t.split('|').map(p => p.trim());
   if (parts.length < 2) return null;
+  /** @type {Array<string | number>} */
   const values = [];
   for (const part of parts) {
     const str = part.match(/^'([^']*)'$/) || part.match(/^"([^"]*)"$/);
@@ -93,14 +96,21 @@ export function parseEnumValues(type) {
   return values;
 }
 
+/** @param {string} name */
 export function normalizeName(name) {
   return name.replace(/^XDS/, '');
 }
 
 /**
  * Index one doc entry's props into the registry component shape.
+ * @param {string} name
+ * @param {import('./xle-ast').DocProp[]} props
+ * @param {string} dirName
+ * @param {string} importPath
+ * @returns {import('./xle-ast').RegistryComponent}
  */
 export function toComponentEntry(name, props, dirName, importPath) {
+  /** @type {Map<string, import('./xle-ast').RegistryProp>} */
   const propMap = new Map();
   for (const p of props || []) {
     propMap.set(p.name, {
@@ -119,10 +129,14 @@ export function toComponentEntry(name, props, dirName, importPath) {
 /**
  * Resolve a node name (alias, bare name, or XDS-prefixed name) to a
  * registry component entry, or null.
+ * @param {import('./xle-ast').Registry} registry
+ * @param {string | null} name
+ * @returns {import('./xle-ast').RegistryComponent | null}
  */
 export function resolveComponent(registry, name) {
+  if (name == null) return null;
   const viaAlias = registry.aliases.get(name);
-  if (viaAlias) return registry.components.get(viaAlias);
+  if (viaAlias) return registry.components.get(viaAlias) ?? null;
   const bare = normalizeName(name);
   return registry.components.get(bare) || null;
 }
@@ -130,6 +144,8 @@ export function resolveComponent(registry, name) {
 /**
  * Serialize a built registry (with Map fields) to a plain JSON-safe object
  * so a Node build step can ship it to the browser.
+ * @param {import('./xle-ast').Registry} registry
+ * @returns {import('./browser').SerializedRegistry}
  */
 export function serializeRegistry(registry) {
   return {
@@ -139,7 +155,7 @@ export function serializeRegistry(registry) {
       dirName: c.dirName,
       importPath: c.importPath,
       undocumented: c.undocumented || false,
-      props: [...c.props.values()],
+      props: /** @type {Array<Record<string, unknown>>} */ (/** @type {unknown} */ ([...c.props.values()])),
     })),
     aliases: [...registry.aliases.entries()],
     componentNames: registry.componentNames,
@@ -149,17 +165,26 @@ export function serializeRegistry(registry) {
 /**
  * Hydrate a serialized registry back into the Map-bearing shape that
  * validate()/expand() expect. Inverse of serializeRegistry.
+ * @param {import('./browser').SerializedRegistry} json
+ * @returns {import('./xle-ast').Registry}
  */
 export function hydrateRegistry(json) {
+  /** @type {Map<string, import('./xle-ast').RegistryComponent>} */
   const components = new Map();
   for (const c of json.components) {
+    /** @type {Map<string, import('./xle-ast').RegistryProp>} */
+    const props = new Map();
+    for (const p of c.props) {
+      const prop = /** @type {import('./xle-ast').RegistryProp} */ (/** @type {unknown} */ (p));
+      props.set(String(p.name), prop);
+    }
     components.set(c.name, {
       name: c.name,
       exportName: c.exportName,
       dirName: c.dirName,
       importPath: c.importPath,
       undocumented: c.undocumented || false,
-      props: new Map(c.props.map(p => [p.name, p])),
+      props,
     });
   }
   return {

package/{src/lib → lib}/xle/registry.mjs

@@ -40,6 +40,11 @@ export {
   hydrateRegistry,
 } from './registry-core.mjs';
 
+/**
+ * @param {Record<string, string[]>} grouped
+ * @param {string} member
+ * @returns {string|null}
+ */
 function findDirFor(grouped, member) {
   for (const [dir, members] of Object.entries(grouped)) {
     if (members.includes(member)) return dir;
@@ -90,7 +95,7 @@ function readDirExportedComponents(coreDir, dirName) {
   return [...names];
 }
 
-let cachedRegistry = null;
+let cachedRegistry = /** @type {import('./xle-ast').Registry | null} */ (null);
 
 /**
  * Build (and cache) the registry: every documented component keyed by its
@@ -123,7 +128,7 @@ export async function buildRegistry({cwd = process.cwd()} = {}) {
     }
     const importPath = resolveImportPath(coreDir, dirName);
 
-    const register = (rawName, props) => {
+    const register = (/** @type {string} */ rawName, /** @type {import('./xle-ast').DocProp[]} */ props) => {
       const name = normalizeName(rawName);
       const entry = toComponentEntry(name, props, dirName, importPath);
       const existing = components.get(name);
@@ -147,7 +152,7 @@ export async function buildRegistry({cwd = process.cwd()} = {}) {
   // props go missing and valid attrs (e.g. Heading[level=2]) get rejected.
   // Read every .doc.mjs in each contributing dir and upgrade props, keyed to
   // each component's own export subpath. Props-only: never adds empty entries.
-  const upgradeFromDoc = (rawName, props, fallbackDir) => {
+  const upgradeFromDoc = (/** @type {string} */ rawName, /** @type {import('./xle-ast').DocProp[]} */ props, /** @type {string} */ fallbackDir) => {
     if (!props || props.length === 0) return;
     const name = normalizeName(rawName);
     // Prefer the component's own export subpath (Heading → @astryxdesign/core/Heading);
@@ -193,7 +198,7 @@ export async function buildRegistry({cwd = process.cwd()} = {}) {
   //     (TableHeader/Body/Footer became bare files with no own .doc.mjs after
   //     the un-prefix migration), so we recover them from the real export
   //     surface here.
-  const registerUndocumented = (name, dirName) => {
+  const registerUndocumented = (/** @type {string} */ name, /** @type {string} */ dirName) => {
     if (components.has(name)) return;
     const entry = toComponentEntry(name, [], dirName, resolveImportPath(coreDir, name));
     entry.undocumented = true;