@astryxdesign/cli 0.1.1 → 0.1.2-canary.2149fa3

package/src/lib/xle/print.mjs

@@ -0,0 +1,174 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file XLE canonical printers — AST → compact (XLE) or outline (XLO) text.
+ *
+ * Used by `astryx layout check --form …` so either party (agent or human)
+ * can request the other surface, and by round-trip conformance tests.
+ * Printing is best-effort canonical: spelling variants the lexer
+ * normalized are emitted in canonical form.
+ *
+ * @input  parse() AST (binding not required)
+ * @output toCompact(doc) / toOutline(doc)
+ * @position lib/xle — inverse of parse.mjs
+ */
+
+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 (Array.isArray(value)) return `[${value.map(valueText).join(',')}]`;
+  if (typeof value === 'object' && value !== null) {
+    return `{${Object.entries(value)
+      .map(([k, v]) => (v === true ? k : `${k}:${valueText(v)}`))
+      .join(',')}}`;
+  }
+  return String(value);
+}
+
+function hintText(hint) {
+  let out = hint.name;
+  for (const flag of hint.flags || []) out += ` +${flag}`;
+  if (hint.arg) out += `:${hint.arg}`;
+  return `{${out}}`;
+}
+
+function attrTokens(node) {
+  const tokens = [];
+  for (const attr of node.attrs) {
+    if (attr.kind === 'kv') tokens.push(`${attr.key}=${valueText(attr.value)}`);
+    else if (attr.kind === 'flag') tokens.push(attr.key);
+    else if (attr.kind === 'neg') tokens.push(`!${attr.key}`);
+  }
+  return tokens;
+}
+
+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)})`;
+    return `@${slot.key}`;
+  });
+}
+
+function nodeCompact(node) {
+  let out = node.name || '';
+  if (node.id) out += `#${node.id}`;
+  for (const mod of node.enumMods) out += `.${mod}`;
+  if (node.payload != null) out += `"${node.payload}"`;
+  if (node.payload2 != null) out += `:"${node.payload2}"`;
+  const attrs = [...attrTokens(node), ...slotTokensCompact(node)];
+  if (attrs.length > 0) out += `[${attrs.join(' ')}]`;
+  if (node.hint) out += hintText(node.hint);
+  if (node.selected) out += '!';
+  if (node.repeat) out += `*${node.repeat}`;
+  if (node.children.length > 0) {
+    const inner = siblingsCompact(node.children);
+    out += node.children.length === 1 ? ` > ${inner}` : ` > ${inner}`;
+  }
+  return out;
+}
+
+function termCompact(item) {
+  if (item.kind === 'group') {
+    let out = `(${siblingsCompact(item.children)})`;
+    if (item.repeat) out += `*${item.repeat}`;
+    return out;
+  }
+  // Multi-sibling children need grouping when this node is itself a sibling.
+  return nodeCompact(item);
+}
+
+function siblingsCompact(items) {
+  return items
+    .map((item, i) => {
+      const text = termCompact(item);
+      // `a > b + c` binds b and c to a; if a itself has a following
+      // sibling, the next `+` would rebind into a's children — wrap any
+      // non-last sibling that opens a `>` chain in a group.
+      const needsGroup =
+        i < items.length - 1 && item.kind === 'node' && item.children.length > 0;
+      return needsGroup ? `(${text})` : text;
+    })
+    .join(' + ');
+}
+
+export function toCompact(doc) {
+  let out = siblingsCompact(doc.roots);
+  for (const overlay of doc.overlays) {
+    out += ` ;; ${termCompact(overlay)}`;
+  }
+  return out;
+}
+
+// ── outline ────────────────────────────────────────────────────────────────
+
+function nodeOutlineLines(node, depth) {
+  const pad = '  '.repeat(depth);
+  let line = node.name || '';
+  if (node.id) line += `#${node.id}`;
+  for (const mod of node.enumMods) line += `.${mod}`;
+  if (node.payload != null) line += ` "${node.payload}"`;
+  if (node.payload2 != null) line += ` :"${node.payload2}"`;
+  const attrs = attrTokens(node);
+  if (attrs.length > 0) line += ' ' + attrs.join(' ');
+  if (node.hint) line += ' ' + hintText(node.hint);
+  if (node.selected) line += ' !';
+  if (node.repeat) line += ` x${node.repeat}`;
+
+  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];
+        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));
+      }
+    } 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 {
+      lines.push(`${pad}  ${slot.key}:`);
+    }
+  }
+  for (const child of node.children) lines.push(...itemOutlineLines(child, depth + 1));
+  return lines;
+}
+
+function isSimpleNode(item) {
+  return item.kind === 'node' && item.children.length === 0 && item.slots.length === 0;
+}
+
+function itemOutlineLines(item, depth) {
+  if (item.kind === 'group') {
+    // A repeat-less group exists only to disambiguate compact-form
+    // sibling chains — indentation already does that, so inline it.
+    if (!item.repeat || item.repeat === 1) {
+      return item.children.flatMap(child => itemOutlineLines(child, depth));
+    }
+    const pad = '  '.repeat(depth);
+    const lines = [`${pad}repeat ${item.repeat}:`];
+    for (const child of item.children) lines.push(...itemOutlineLines(child, depth + 1));
+    return lines;
+  }
+  return nodeOutlineLines(item, depth);
+}
+
+export function toOutline(doc) {
+  const lines = [];
+  for (const item of doc.roots) lines.push(...itemOutlineLines(item, 0));
+  if (doc.overlays.length > 0) {
+    lines.push('', 'overlays:');
+    for (const item of doc.overlays) lines.push(...itemOutlineLines(item, 1));
+  }
+  return lines.join('\n');
+}

package/src/lib/xle/registry-core.mjs

@@ -0,0 +1,170 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file XLE registry — pure core (no Node deps).
+ *
+ * The fs-bound builder lives in registry.mjs; everything here is
+ * environment-agnostic so it can run in the browser playground too.
+ * This holds the alias table, enum parsing, the component-entry shape,
+ * name resolution, and the serialize/hydrate pair that lets a Node
+ * build step ship a registry to the browser as plain JSON.
+ *
+ * @input  doc.mjs-shaped prop arrays (from registry.mjs) or serialized JSON
+ * @output ALIAS_TABLE, parseEnumValues, toComponentEntry, resolveComponent,
+ *         serializeRegistry, hydrateRegistry
+ * @position lib/xle — imported by registry.mjs (Node) and the browser barrel
+ */
+
+/**
+ * Curated alias table (from the XLE research, paste P2376666892 §2).
+ * Single letters reserved for the highest-frequency structural set.
+ * Collision policy: case-only pairs forbidden; HTML mnemonics win the
+ * Table family; form-frequency wins contested pairs (CB, NI).
+ *
+ * Aliases are validated against the discovered registry — an alias whose
+ * component doesn't exist on this branch is silently dropped.
+ */
+export const ALIAS_TABLE = {
+  // Layout core
+  A: 'AppShell', L: 'Layout', LH: 'LayoutHeader', LC: 'LayoutContent',
+  LF: 'LayoutFooter', LP: 'LayoutPanel', V: 'VStack', H: 'HStack',
+  SI: 'StackItem', G: 'Grid', GS: 'GridSpan', S: 'Section', Ctr: 'Center',
+  F: 'FormLayout', D: 'Divider', Tbar: 'Toolbar', AR: 'AspectRatio',
+  // Navigation
+  TN: 'TopNav', TNH: 'TopNavHeading', TNI: 'TopNavItem',
+  SN: 'SideNav', SNI: 'SideNavItem', SNS: 'SideNavSection', SNH: 'SideNavHeading',
+  MN: 'MobileNav', MNT: 'MobileNavToggle',
+  BC: 'Breadcrumbs', BCI: 'BreadcrumbItem',
+  TL: 'TabList', Tab: 'Tab', PG: 'Pagination',
+  SG: 'SegmentedControl', SGI: 'SegmentedControlItem',
+  // Data display
+  T: 'Table', TH: 'TableHeader', TB: 'TableBody', TF: 'TableFooter',
+  TR: 'TableRow', TC: 'TableCell', TD: 'TableCell', THC: 'TableHeaderCell',
+  UL: 'List', LI: 'ListItem', ML: 'MetadataList', MLI: 'MetadataListItem',
+  C: 'Card', CC: 'ClickableCard', ES: 'EmptyState', Bd: 'Badge',
+  SD: 'StatusDot', Av: 'Avatar', AvG: 'AvatarGroup', Tmb: 'Thumbnail',
+  Ts: 'Timestamp', OFL: 'OverflowList', Cs: 'Carousel', It: 'Item',
+  // Forms & inputs
+  Fd: 'Field', IG: 'InputGroup', IGT: 'InputGroupText',
+  TI: 'TextInput', TA: 'TextArea', NI: 'NumberInput',
+  DI: 'DateInput', DR: 'DateRangeInput', DT: 'DateTimeInput', TM: 'TimeInput',
+  FI: 'FileInput', CB: 'CheckboxInput', CL: 'CheckboxList', CLI: 'CheckboxListItem',
+  RL: 'RadioList', RLI: 'RadioListItem', SW: 'Switch', SL: 'Slider',
+  SE: 'Selector', MS: 'MultiSelector', TY: 'Typeahead', Tkz: 'Tokenizer',
+  PS: 'PowerSearch', CAL: 'Calendar',
+  // Overlay & feedback
+  Dlg: 'Dialog', DH: 'DialogHeader', AD: 'AlertDialog',
+  Po: 'Popover', HC: 'HoverCard', Tt: 'Tooltip', Bn: 'Banner', Ov: 'Overlay',
+  CM: 'ContextMenu', DM: 'DropdownMenu', MM: 'MoreMenu', CP: 'CommandPalette',
+  Col: 'Collapsible', ColG: 'CollapsibleGroup',
+  Sp: 'Spinner', PB: 'ProgressBar', Sk: 'Skeleton',
+  // Content & chat
+  Tx: 'Text', Hd: 'Heading', MD: 'Markdown', Cd: 'CodeBlock', BQ: 'Blockquote',
+  K: 'Kbd', Ic: 'Icon', Lk: 'Link', Tk: 'Token',
+  B: 'Button', IB: 'IconButton', BG: 'ButtonGroup', Tg: 'ToggleButton', TgG: 'ToggleButtonGroup',
+  ChL: 'ChatLayout', ChML: 'ChatMessageList', ChM: 'ChatMessage',
+  ChB: 'ChatMessageBubble', ChC: 'ChatComposer', ChCD: 'ChatComposerDrawer',
+  ChS: 'ChatSystemMessage', ChT: 'ChatToolCalls',
+};
+
+/** SpacingStep — the canonical spacing enum (matches the doc.mjs prose). */
+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.
+ */
+export function parseEnumValues(type) {
+  if (!type || typeof type !== 'string') return null;
+  const t = type.trim();
+  if (t === 'SpacingStep' || /^0\|0\.5\|/.test(t.replace(/\s+/g, ''))) {
+    return SPACING_STEPS;
+  }
+  const parts = t.split('|').map(p => p.trim());
+  if (parts.length < 2) return null;
+  const values = [];
+  for (const part of parts) {
+    const str = part.match(/^'([^']*)'$/) || part.match(/^"([^"]*)"$/);
+    if (str) { values.push(str[1]); continue; }
+    if (/^\d+(\.\d+)?$/.test(part)) { values.push(Number(part)); continue; }
+    return null; // union of non-literal types (e.g. number|string) — not an enum
+  }
+  return values;
+}
+
+export function normalizeName(name) {
+  return name.replace(/^XDS/, '');
+}
+
+/**
+ * Index one doc entry's props into the registry component shape.
+ */
+export function toComponentEntry(name, props, dirName, importPath) {
+  const propMap = new Map();
+  for (const p of props || []) {
+    propMap.set(p.name, {
+      name: p.name,
+      type: p.type || '',
+      required: p.required === true,
+      enumValues: parseEnumValues(p.type),
+      isBoolean: (p.type || '').trim() === 'boolean',
+      isFunction: /^\(/.test((p.type || '').trim()),
+      isNode: /ReactNode|ReactElement/.test(p.type || ''),
+    });
+  }
+  return {name, exportName: `XDS${name}`, dirName, importPath, props: propMap};
+}
+
+/**
+ * Resolve a node name (alias, bare name, or XDS-prefixed name) to a
+ * registry component entry, or null.
+ */
+export function resolveComponent(registry, name) {
+  const viaAlias = registry.aliases.get(name);
+  if (viaAlias) return registry.components.get(viaAlias);
+  const bare = normalizeName(name);
+  return registry.components.get(bare) || null;
+}
+
+/**
+ * Serialize a built registry (with Map fields) to a plain JSON-safe object
+ * so a Node build step can ship it to the browser.
+ */
+export function serializeRegistry(registry) {
+  return {
+    components: [...registry.components.values()].map(c => ({
+      name: c.name,
+      exportName: c.exportName,
+      dirName: c.dirName,
+      importPath: c.importPath,
+      undocumented: c.undocumented || false,
+      props: [...c.props.values()],
+    })),
+    aliases: [...registry.aliases.entries()],
+    componentNames: registry.componentNames,
+  };
+}
+
+/**
+ * Hydrate a serialized registry back into the Map-bearing shape that
+ * validate()/expand() expect. Inverse of serializeRegistry.
+ */
+export function hydrateRegistry(json) {
+  const components = new Map();
+  for (const c of json.components) {
+    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])),
+    });
+  }
+  return {
+    components,
+    aliases: new Map(json.aliases),
+    componentNames: json.componentNames || [...components.keys()].sort(),
+  };
+}

package/src/lib/xle/registry.mjs

@@ -0,0 +1,237 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file XLE component registry — built from @astryxdesign/core .doc.mjs metadata.
+ *
+ * Everything the layout language knows about components (valid names,
+ * aliases, props, enums, slots) is derived from the same .doc.mjs files
+ * that power `xds component`, so the notation can never drift from the
+ * branch's actual API. The pure pieces (alias table, enum parsing,
+ * resolution, serialize/hydrate) live in registry-core.mjs so they can
+ * run in the browser; this module adds the fs-bound builder.
+ *
+ * @input  packages/core/src/(star)/(star).doc.mjs via component-discovery
+ * @output buildRegistry() → { components, aliases, componentNames }
+ * @position lib/xle — shared by parse/validate/expand; no CLI concerns here
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {findCoreDir} from '../../utils/paths.mjs';
+import {
+  discoverComponents,
+  findComponentReadme,
+  resolveImportPath,
+} from '../component-discovery.mjs';
+import {loadDocs} from '../component-loader.mjs';
+import {
+  ALIAS_TABLE,
+  normalizeName,
+  toComponentEntry,
+} from './registry-core.mjs';
+
+// Re-export the pure surface so existing importers (and tests) keep working.
+export {
+  ALIAS_TABLE,
+  SPACING_STEPS,
+  parseEnumValues,
+  resolveComponent,
+  serializeRegistry,
+  hydrateRegistry,
+} from './registry-core.mjs';
+
+function findDirFor(grouped, member) {
+  for (const [dir, members] of Object.entries(grouped)) {
+    if (members.includes(member)) return dir;
+  }
+  return null;
+}
+
+// Match bare `export {Name}` / `export {Name, Other}` named re-exports in a
+// component directory's index.ts. PascalCase only — hooks (useX), lowercase
+// helpers, and `type` exports are skipped via the caller's filters.
+const NAMED_EXPORT_RE = /export\s*\{([^}]*)\}/g;
+
+/**
+ * Read the PascalCase component names re-exported from a component directory's
+ * `index.ts`. Used to recover structural sub-components that ship without their
+ * own `.doc.mjs` (e.g. TableHeader, TableBody, TableFooter) — the doc-driven
+ * discoverComponents() intentionally skips those, but the layout language still
+ * needs to name and emit them.
+ *
+ * @param {string} coreDir
+ * @param {string} dirName
+ * @returns {string[]} bare PascalCase export names
+ */
+function readDirExportedComponents(coreDir, dirName) {
+  const indexPath = path.join(coreDir, 'src', dirName, 'index.ts');
+  let content;
+  try {
+    content = fs.readFileSync(indexPath, 'utf-8');
+  } catch {
+    return [];
+  }
+  const names = new Set();
+  for (const match of content.matchAll(NAMED_EXPORT_RE)) {
+    for (const raw of match[1].split(',')) {
+      // `Name`, `Name as Alias`, ` type Name ` — keep the exported (left) name,
+      // drop `type` and aliases.
+      const token = raw.trim();
+      if (!token || token.startsWith('type ')) continue;
+      const name = token.split(/\s+as\s+/)[0].trim().replace(/^XDS/, '');
+      // PascalCase components only — skip hooks (useX), lowercase utils, and
+      // non-rendering exports (Context/Provider) that discoverComponents()
+      // also excludes.
+      if (!/^[A-Z][A-Za-z0-9]*$/.test(name)) continue;
+      if (/(?:Context|Provider)$/.test(name)) continue;
+      names.add(name);
+    }
+  }
+  return [...names];
+}
+
+let cachedRegistry = null;
+
+/**
+ * Build (and cache) the registry: every documented component keyed by its
+ * un-prefixed name, plus the validated alias map.
+ *
+ * @param {object} [options]
+ * @param {string} [options.cwd]
+ * @returns {Promise<{components: Map<string, object>, aliases: Map<string, string>, componentNames: string[]}>}
+ */
+export async function buildRegistry({cwd = process.cwd()} = {}) {
+  if (cachedRegistry) return cachedRegistry;
+
+  const coreDir = findCoreDir(cwd);
+  if (!coreDir) {
+    throw new Error('Could not find @astryxdesign/core package — run from an XDS workspace');
+  }
+
+  const components = new Map();
+  const grouped = discoverComponents(coreDir);
+  const dirNames = [...new Set(Object.values(grouped).flat())];
+
+  for (const dirName of dirNames) {
+    const readme = findComponentReadme(coreDir, dirName);
+    if (!readme || !readme.endsWith('.doc.mjs')) continue;
+    let docs;
+    try {
+      docs = await loadDocs(readme, {});
+    } catch {
+      continue; // a malformed doc must not take down the whole language
+    }
+    const importPath = resolveImportPath(coreDir, dirName);
+
+    const register = (rawName, props) => {
+      const name = normalizeName(rawName);
+      const entry = toComponentEntry(name, props, dirName, importPath);
+      const existing = components.get(name);
+      // Some docs list related components with empty prop arrays
+      // (e.g. Layout's references to Card) — prefer the richer entry.
+      if (!existing || entry.props.size > existing.props.size) {
+        components.set(name, entry);
+      }
+    };
+
+    if (docs.props) register(docs.name || dirName, docs.props);
+    for (const sub of docs.components || []) {
+      if (sub?.name) register(sub.name, sub.props);
+    }
+  }
+
+  // Some components are documented in a sibling `<Name>.doc.mjs` inside another
+  // component's dir (e.g. Text/Heading.doc.mjs documents Heading, with its own
+  // props like `level`). The per-dir main-doc read above only sees the bare
+  // `{name: 'Heading'}` cross-reference stub (no props), so without this those
+  // 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) => {
+    if (!props || props.length === 0) return;
+    const name = normalizeName(rawName);
+    // Prefer the component's own export subpath (Heading → @astryxdesign/core/Heading);
+    // fall back to the dir it was found in, then any existing entry's path.
+    const ip =
+      resolveImportPath(coreDir, name) ||
+      resolveImportPath(coreDir, fallbackDir) ||
+      components.get(name)?.importPath;
+    const entry = toComponentEntry(name, props, name, ip);
+    const existing = components.get(name);
+    if (!existing || entry.props.size > existing.props.size) components.set(name, entry);
+  };
+  for (const dirName of dirNames) {
+    const dirPath = path.join(coreDir, 'src', dirName);
+    let files;
+    try {
+      files = fs.readdirSync(dirPath).filter(f => f.endsWith('.doc.mjs'));
+    } catch {
+      continue;
+    }
+    for (const file of files) {
+      let docs;
+      try {
+        docs = await loadDocs(path.join(dirPath, file), {});
+      } catch {
+        continue;
+      }
+      if (docs.props) upgradeFromDoc(docs.name || file.replace(/\.doc\.mjs$/, ''), docs.props, dirName);
+      for (const sub of docs.components || []) {
+        if (sub?.name && sub.props?.length) upgradeFromDoc(sub.name, sub.props, dirName);
+      }
+    }
+  }
+
+  // Exported components without their own doc entry (e.g. TableHeader,
+  // TableBody) still get minimal registry entries so they can be named in
+  // expressions — the validator warns rather than validates their props.
+  //
+  // Two sources:
+  //  1. Members discovered alongside a documented sibling (legacy path).
+  //  2. Bare PascalCase re-exports in each component dir's index.ts. The
+  //     doc-driven discoverComponents() skips doc-less structural pieces
+  //     (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) => {
+    if (components.has(name)) return;
+    const entry = toComponentEntry(name, [], dirName, resolveImportPath(coreDir, name));
+    entry.undocumented = true;
+    components.set(name, entry);
+  };
+
+  for (const [, members] of Object.entries(grouped)) {
+    for (const member of members) {
+      registerUndocumented(normalizeName(member), findDirFor(grouped, member) || member);
+    }
+  }
+
+  // Walk every component directory (those that contributed at least one
+  // documented component) and backfill its index.ts exports.
+  const docDirs = new Set();
+  for (const c of components.values()) {
+    if (c.dirName) docDirs.add(c.dirName);
+  }
+  for (const dirName of docDirs) {
+    for (const name of readDirExportedComponents(coreDir, dirName)) {
+      registerUndocumented(name, dirName);
+    }
+  }
+
+  const aliases = new Map();
+  for (const [alias, target] of Object.entries(ALIAS_TABLE)) {
+    if (components.has(target)) aliases.set(alias, target);
+  }
+
+  cachedRegistry = {
+    components,
+    aliases,
+    componentNames: [...components.keys()].sort(),
+  };
+  return cachedRegistry;
+}
+
+/** Test seam — drop the module-level cache. */
+export function resetRegistryCache() {
+  cachedRegistry = null;
+}