@astryxdesign/cli 0.1.5 → 0.1.6-canary.02f2602

package/src/lib/component-format.test.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 import {describe, it, expect} from 'vitest';
-import {formatFull} from './component-format.mjs';
+import {formatBrief, formatFull} from './component-format.mjs';
 
 describe('formatFull sub-component rendering', () => {
   // Regression guard: sub-components are sometimes declared as a bare
@@ -93,3 +93,97 @@ describe('formatFull theming override keys', () => {
     expect(out).not.toContain("'astryx-table-cell': {");
   });
 });
+
+/** Pipes that actually separate cells — a `\|` is content, not a separator. */
+function cellPipes(row) {
+  return (row.match(/(?<!\\)\|/g) || []).length;
+}
+
+describe('markdown table cells escape their pipes', () => {
+  // A prop type is a union, and a union is spelled with `|` — the very
+  // character GFM uses to separate cells. Backticks do not protect it: a row
+  // with more cells than the header has columns gets its excess *discarded*,
+  // so an unescaped `gap: 0 | 0.5 | ...` silently eats its own Default and
+  // Description columns. See packages/core/src/Markdown/parser.ts, which
+  // splits on unescaped pipes and preserves `\|` as literal.
+  it('keeps a union-typed prop row at four cells', () => {
+    const docs = {
+      name: 'Grid',
+      description: 'A grid.',
+      props: [
+        {
+          name: 'gap',
+          type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+          default: '2',
+          description: 'Spacing between all items.',
+        },
+      ],
+    };
+    const row = formatFull(docs)
+      .split('\n')
+      .find(l => l.startsWith('| `gap`'));
+
+    // A 4-column row has exactly 5 separators. Unescaped, this row had 15.
+    expect(cellPipes(row)).toBe(5);
+    expect(row).toContain('\\|');
+    // The columns the unescaped pipes were swallowing.
+    expect(row).toContain('`2`');
+    expect(row).toContain('Spacing between all items.');
+  });
+
+  it('escapes pipes in a description too', () => {
+    const docs = {
+      name: 'AppShell',
+      description: 'A shell.',
+      props: [
+        {
+          name: 'mobileNav',
+          type: 'ReactNode',
+          description: "Config. breakpoint is 'sm' | 'md' | 'lg' | 'none'.",
+        },
+      ],
+    };
+    const row = formatFull(docs)
+      .split('\n')
+      .find(l => l.startsWith('| `mobileNav`'));
+
+    expect(cellPipes(row)).toBe(5);
+  });
+});
+
+describe('formatBrief signature stays terse', () => {
+  // `--detail brief` exists to be token-cheap. It hoists union-typed props into
+  // the signature because a short enum reads at a glance — but an 11-member
+  // spacing scale does not, and Stack carries four of them (gap, padding,
+  // paddingInline, paddingBlock), so the same scale got printed four times.
+  // Long unions stay in the terse prop list, exactly as they did when the type
+  // was still the bare name `SpacingStep`.
+  it('hoists a short enum but not a long scale', () => {
+    const docs = {
+      name: 'HStack',
+      description: 'A stack.',
+      props: [
+        {
+          name: 'gap',
+          type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+          description: 'Gap.',
+        },
+        {name: 'wrap', type: "'nowrap' | 'wrap' | 'wrap-reverse'", description: 'Wrap.'},
+        {
+          name: 'hAlign',
+          type: "'start' | 'center' | 'end' | 'between' | 'around' | 'evenly'",
+          description: 'Align.',
+        },
+      ],
+    };
+    const signature = formatBrief(docs, 'HStack', '').split('\n')[0];
+
+    // Short enums still earn their place in the signature.
+    expect(signature).toContain('wrap: nowrap|wrap|wrap-reverse');
+    expect(signature).toContain('hAlign: start|center|end|between|around|evenly');
+    // The long scale does not.
+    expect(signature).not.toContain('0|0.5|1|1.5|2|3|4|5|6|8|10');
+    // But the prop is still named, so it is not lost.
+    expect(formatBrief(docs, 'HStack', '')).toContain('gap');
+  });
+});

package/src/lib/component-loader.mjs

@@ -5,6 +5,59 @@
  */
 
 import {pathToFileURL} from 'node:url';
+import {importUserModule} from './module-loader.mjs';
+import {formatZodError} from './config-schema.mjs';
+import {ComponentDocSchema} from '../schemas/doc-schema.mjs';
+
+/**
+ * Load a component doc through the shared load/validation boundary.
+ *
+ * This is the typed counterpart to {@link loadDocs}: it loads `.doc.ts` via
+ * jiti (and `.doc.mjs`/`.doc.js` via native import) and validates against
+ * {@link ComponentDocSchema}. That schema accepts BOTH formats, so this loader
+ * reads whichever the file uses:
+ *   - NEW: the factory default export
+ *     (`export default createComponentDoc({...})` / `createFunctionDoc` /
+ *     `createDoc`) — the same single-export convention
+ *     {@link loadModuleWithSchema} uses for config/integration/template. These
+ *     carry a stamped `type` and validate against the matching per-kind schema.
+ *   - OLD: the legacy loose `export const docs = {...}` (no `type`), validated
+ *     against the permissive legacy union.
+ * The default export wins when both are present. Throws a readable
+ * `formatZodError`-style message on failure. Translations (`docsZh`/
+ * `docsDense`) are merged exactly as {@link loadDocs} does so callers see
+ * identical output.
+ *
+ * @param {string} docPath absolute path to a `.doc.{ts,mjs,js}` file
+ * @param {{zh?: boolean, dense?: boolean, lang?: string}} [opts]
+ * @returns {Promise<object>} the validated (and optionally translated) doc
+ */
+export async function loadComponentDoc(
+  docPath,
+  {zh = false, dense = false, lang} = {},
+) {
+  const mod = await importUserModule(docPath);
+  const authored = mod?.default ?? mod?.docs;
+
+  const result = ComponentDocSchema.safeParse(authored);
+  if (!result.success) {
+    throw new Error(formatZodError(docPath, result.error));
+  }
+  const docs = authored;
+
+  const locale = lang || (dense ? 'dense' : zh ? 'zh' : null);
+  if (!locale) return docs;
+
+  const translationKey =
+    locale === 'zh' ? 'docsZh' : locale === 'dense' ? 'docsDense' : null;
+  if (!translationKey || !mod[translationKey]) return docs;
+
+  const translation = mod[translationKey];
+  if (translation.props || translation.components?.some(c => c.props)) {
+    return translation;
+  }
+  return mergeTranslation(docs, translation);
+}
 
 export function mergeTranslation(docs, translation) {
   if (!translation) return docs;
@@ -91,15 +144,64 @@ export async function loadDocs(readmePath, {zh = false, dense = false, lang} = {
 
   const translation = mod[translationKey];
 
-  // If the translation is a full ComponentDoc (legacy docsZh shape), return it directly
+  // A full ComponentDoc-shaped translation (legacy docsZh shape) used to be
+  // returned wholesale. That made it a REPLACEMENT, not an overlay: any prop
+  // the translation had not caught up with simply ceased to exist —
+  // `component Button --zh` silently omitted `isInterruptible` and
+  // `isIconOnly`. A reader of the translated docs cannot discover a prop that
+  // is not there. Overlay it instead, so an untranslated prop falls back to
+  // its English entry. (Same principle as the reference-doc overlays, #2182.)
   if (translation.props || translation.components?.some(c => c.props)) {
-    return translation;
+    return overlayComponentDoc(docs, translation);
   }
 
   // Otherwise it's a TranslationDoc — merge it onto docs
   return mergeTranslation(docs, translation);
 }
 
+/**
+ * Overlay a full-ComponentDoc-shaped translation onto the English doc.
+ *
+ * Base order and completeness win; the translation supplies text for the
+ * entries it covers. Props are matched by name, never by position, so a
+ * translation that is missing entries (or lists them in another order) can no
+ * longer drop or misattribute one.
+ *
+ * @param {any} docs Base (English) component doc.
+ * @param {any} translation Translated doc, possibly covering only some props.
+ * @returns {any} Merged doc with every base prop present.
+ */
+function overlayComponentDoc(docs, translation) {
+  /** Merge one prop list: keep base entries and order, translate what's covered. */
+  const overlayProps = (baseProps, tProps) => {
+    if (!baseProps) return baseProps;
+    const byName = new Map((tProps ?? []).map(p => [p.name, p]));
+    return baseProps.map(prop => {
+      const t = byName.get(prop.name);
+      // Take the translated text, but never let it drop the prop's contract
+      // (type/default/required stay authoritative from the English doc).
+      return t ? {...prop, ...t, name: prop.name, type: prop.type} : prop;
+    });
+  };
+
+  const merged = {...docs, ...translation};
+
+  merged.props = overlayProps(docs.props, translation.props);
+
+  if (docs.components) {
+    const tByName = new Map(
+      (translation.components ?? []).map(c => [c.name, c]),
+    );
+    merged.components = docs.components.map(base => {
+      const t = tByName.get(base.name);
+      if (!t) return base;
+      return {...base, ...t, props: overlayProps(base.props, t.props)};
+    });
+  }
+
+  return merged;
+}
+
 /**
  * Find the doc file for a component, checking both top-level
  * and nested directories. Prefers {Name}.doc.mjs, then README.md

package/src/lib/componentDocOverlay.test.mjs

@@ -0,0 +1,111 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Guards translated/compressed component docs against dropping props.
+ * @input packages/core/src/{Name}/{Name}.doc.mjs — its `docs`, `docsZh`, `docsDense`.
+ * @output Vitest failures naming every prop that exists in `docs` but vanishes
+ *   from a translated view.
+ * @position Regression gate for component-loader.mjs.
+ *
+ * A `docsZh` that carries its own `props` array used to REPLACE the base doc
+ * wholesale, so any prop the translation had not caught up with simply ceased
+ * to exist: `astryx component Button --zh` silently omitted `isInterruptible`
+ * and `isIconOnly`. A reader of the translated docs cannot discover a prop that
+ * is not there, and CLAUDE.md tells every AI agent to read these docs.
+ *
+ * Translations are now an overlay: a prop the translation does not cover falls
+ * back to its English entry rather than disappearing. Same principle as the
+ * reference-doc overlays in #2182 — an overlay covering a subset must not
+ * destroy what it does not cover.
+ */
+
+import {describe, it, expect} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {pathToFileURL} from 'node:url';
+import {loadDocs} from './component-loader.mjs';
+
+const CORE_SRC = path.join(
+  import.meta.dirname,
+  '..',
+  '..',
+  '..',
+  'core',
+  'src',
+);
+
+/** Component dirs that ship a doc file. */
+function componentDocs() {
+  const out = [];
+  for (const dir of fs.readdirSync(CORE_SRC)) {
+    const docPath = path.join(CORE_SRC, dir, `${dir}.doc.mjs`);
+    if (!fs.existsSync(docPath)) continue;
+    if (!fs.readdirSync(path.join(CORE_SRC, dir)).includes(`${dir}.doc.mjs`)) {
+      continue; // case-exact match only
+    }
+    out.push({name: dir, docPath});
+  }
+  return out;
+}
+
+/** Prop names on a doc, across single- and multi-component shapes. */
+function propNames(doc) {
+  const names = new Set();
+  for (const p of doc?.props ?? []) names.add(p.name);
+  for (const c of doc?.components ?? []) {
+    for (const p of c.props ?? []) names.add(`${c.name ?? '?'}.${p.name}`);
+  }
+  return names;
+}
+
+describe('translated component docs never drop a prop', () => {
+  const comps = componentDocs();
+
+  it('finds component docs to check', () => {
+    expect(comps.length).toBeGreaterThan(0);
+  });
+
+  for (const {name, docPath} of comps) {
+    for (const locale of ['zh', 'dense']) {
+      it(`${name} --${locale}: documents every prop the English doc documents`, async () => {
+        const mod = await import(pathToFileURL(docPath).href);
+        const key = locale === 'zh' ? 'docsZh' : 'docsDense';
+        if (!mod[key]) return; // no overlay, nothing to drift
+
+        const english = propNames(mod.docs);
+        const translated = propNames(
+          await loadDocs(docPath, {[locale]: true}),
+        );
+
+        const dropped = [...english].filter(p => !translated.has(p));
+        expect(
+          dropped,
+          `${name}.doc.mjs ${key} drops ${dropped.length} prop(s) from the ` +
+            `--${locale} view: ${dropped.join(', ')}. A reader of the ` +
+            `translated docs cannot discover a prop that is not there. An ` +
+            `untranslated prop must fall back to its English entry, not vanish.`,
+        ).toEqual([]);
+      });
+    }
+  }
+});
+
+describe('the reported symptom', () => {
+  it('astryx component Button --zh still lists isInterruptible and isIconOnly', async () => {
+    const docPath = path.join(CORE_SRC, 'Button', 'Button.doc.mjs');
+    const zh = await loadDocs(docPath, {zh: true});
+    const names = propNames(zh);
+    expect(names.has('isInterruptible')).toBe(true);
+    expect(names.has('isIconOnly')).toBe(true);
+  });
+
+  it('keeps the translated descriptions it does have', async () => {
+    const docPath = path.join(CORE_SRC, 'Button', 'Button.doc.mjs');
+    const mod = await import(pathToFileURL(docPath).href);
+    const zh = await loadDocs(docPath, {zh: true});
+
+    const translated = mod.docsZh.props.find(p => p.name === 'variant');
+    const merged = zh.props.find(p => p.name === 'variant');
+    expect(merged.description).toBe(translated.description);
+  });
+});

package/src/lib/config-schema.mjs

@@ -73,33 +73,3 @@ export function formatZodError(label, error) {
     .join('; ');
   return `${label} is invalid: ${issues}`;
 }
-
-/**
- * @param {unknown} config
- * @returns {import('../types/config').AstryxConfig}
- */
-export function validateConfig(config) {
-  const result = AstryxConfigSchema.safeParse(config);
-  if (!result.success) {
-    throw new Error(
-      formatZodError('astryx.config default export', result.error),
-    );
-  }
-  return result.data;
-}
-
-/**
- * @param {unknown} integration
- * @param {string} [label]
- * @returns {import('../types/integration').AstryxIntegration}
- */
-export function validateIntegration(
-  integration,
-  label = 'integration manifest',
-) {
-  const result = AstryxIntegrationSchema.safeParse(integration);
-  if (!result.success) {
-    throw new Error(formatZodError(label, result.error));
-  }
-  return result.data;
-}

package/src/lib/hook-format.mjs

@@ -11,6 +11,7 @@
 
 import {discoverHooks, findHookDoc} from './hook-discovery.mjs';
 import {loadDocs} from './component-loader.mjs';
+import {mdCell} from './component-format.mjs';
 
 /**
  * Build a signature string from hook docs.
@@ -51,9 +52,11 @@ function formatParamsTable(params) {
   lines.push('| Param | Type | Default | Description |');
   lines.push('|-------|------|---------|-------------|');
   for (const p of params) {
-    const def = p.default ? `\`${p.default}\`` : '\u2014';
+    const def = p.default ? `\`${mdCell(p.default)}\`` : '\u2014';
     const req = p.required ? ' **(required)**' : '';
-    lines.push(`| \`${p.name}\` | \`${p.type}\` | ${def} | ${p.description}${req} |`);
+    lines.push(
+      `| \`${mdCell(p.name)}\` | \`${mdCell(p.type)}\` | ${def} | ${mdCell(p.description)}${req} |`,
+    );
   }
   return lines.join('\n');
 }
@@ -67,7 +70,9 @@ function formatReturnsTable(returns) {
   lines.push('| Field | Type | Description |');
   lines.push('|-------|------|-------------|');
   for (const r of returns) {
-    lines.push(`| \`${r.name}\` | \`${r.type}\` | ${r.description} |`);
+    lines.push(
+      `| \`${mdCell(r.name)}\` | \`${mdCell(r.type)}\` | ${mdCell(r.description)} |`,
+    );
   }
   return lines.join('\n');
 }

package/src/lib/xle/registry.mjs

@@ -230,8 +230,3 @@ export async function buildRegistry({cwd = process.cwd()} = {}) {
   };
   return cachedRegistry;
 }
-
-/** Test seam — drop the module-level cache. */
-export function resetRegistryCache() {
-  cachedRegistry = null;
-}

package/src/schemas/doc-schema.mjs

@@ -0,0 +1,226 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Doc load-boundary schemas.
+ *
+ * The Zod schemas doc discovery runs a loaded doc value through (see
+ * `loadComponentDoc`). {@link ComponentDocSchema} accepts BOTH the new stamped
+ * formats and the legacy loose `export const docs = {...}` shape, so existing
+ * docs keep loading unchanged. Kept free of any `@astryxdesign/core` import so
+ * the hot path that loads them (doc discovery, `astryx init`) does not require
+ * core's built `dist/`. The authoring factories live in
+ * `@astryxdesign/core/authoring` and are re-exported from `../doc.mjs` for the
+ * public `@astryxdesign/cli/doc` surface.
+ */
+
+import {z} from 'zod';
+
+/**
+ * A single documented prop. Mirrors `PropDoc` from
+ * `@astryxdesign/core/docs-types`. Only `name`, `type`, and `description` are
+ * required; everything else is optional. Extra fields (e.g. `slotElements`)
+ * pass through so the schema does not have to track every evolution of the
+ * rich playground/element surface.
+ */
+const PropSchema = z
+  .object({
+    name: z.string().min(1, 'prop name is required'),
+    type: z.string().min(1, 'prop type is required'),
+    description: z.string(),
+    default: z.string().optional(),
+    required: z.boolean().optional(),
+  })
+  .passthrough();
+
+/** A single documented function/hook parameter (mirrors `HookParamDoc`). */
+const ParamSchema = z
+  .object({
+    name: z.string().min(1, 'param name is required'),
+    type: z.string().min(1, 'param type is required'),
+    description: z.string(),
+    default: z.string().optional(),
+    required: z.boolean().optional(),
+  })
+  .passthrough();
+
+/** A single documented function/hook return field (mirrors `HookReturnDoc`). */
+const ReturnSchema = z
+  .object({
+    name: z.string().min(1, 'return name is required'),
+    type: z.string().min(1, 'return type is required'),
+    description: z.string(),
+  })
+  .passthrough();
+
+/**
+ * Fields shared by every doc kind. Deliberately permissive on the rich blobs
+ * (usage/theming/playground) — those are large and still evolving, so they are
+ * `z.unknown()` passthrough rather than enumerated.
+ *
+ * `group` vs `parent` are distinct concepts and intentionally separate fields:
+ *   - `group` is a FLAT sidebar bucket label. Many docs can share a group; it
+ *     is not an inheritance key.
+ *   - `parent` is a DIRECTED inheritance/composition pointer — a doc naming the
+ *     doc it belongs to (e.g. a sub-component naming its parent component). The
+ *     legacy `subComponentOf` field is a synonym; both map to the same concept.
+ *
+ * `relatedDocs` is a single flat curated cross-reference list. It replaces the
+ * legacy split `relatedComponents` + `relatedHooks`; a downstream reader can
+ * merge the legacy pair into it.
+ */
+const BaseDocFields = {
+  /** Name of the documented unit, without any prefix. Required. */
+  name: z.string().min(1, 'name is required'),
+  /** Human-readable display name for gallery/sidebar. */
+  displayName: z.string().optional(),
+  /** One-line/short description. */
+  description: z.string().optional(),
+  /** Usage documentation (description, best practices, anatomy, slotElements). */
+  usage: z.unknown().optional(),
+  /** Flat sidebar grouping label (not an inheritance key). */
+  group: z.string().optional(),
+  /** Overview-page functional category. */
+  category: z.string().optional(),
+  /** CLI fuzzy-search keywords. */
+  keywords: z.array(z.string()).optional(),
+  /** Directed inheritance/composition pointer to the doc this belongs to. */
+  parent: z.string().optional(),
+  /** Flat curated cross-reference list of related doc names. */
+  relatedDocs: z.array(z.string()).optional(),
+  /** Hide the whole doc from human-facing UI (stays importable/discoverable). */
+  hidden: z.boolean().optional(),
+  /** Exclude from the categorized overview page (kept in sidebar/CLI). */
+  isHiddenFromOverview: z.boolean().optional(),
+};
+
+/**
+ * New-format schema for a stamped component doc (`type: 'component'`). The
+ * top-level component keys are enumerated, but nested blobs stay loose so real
+ * docs are not rejected. `.passthrough()` keeps unknown top-level fields
+ * (translations, element descriptors, ...) flowing through.
+ */
+export const ComponentDocKindSchema = z
+  .object({
+    ...BaseDocFields,
+    type: z.literal('component'),
+    props: z.array(PropSchema),
+    theming: z.unknown().optional(),
+    playground: z.unknown().optional(),
+    examples: z.array(z.unknown()).optional(),
+  })
+  .passthrough();
+
+/**
+ * New-format schema for a stamped function doc (`type: 'function'`). Covers any
+ * function, including hooks: an inputs (`params`) + outputs (`returns`) surface.
+ */
+export const FunctionDocKindSchema = z
+  .object({
+    ...BaseDocFields,
+    type: z.literal('function'),
+    params: z.array(ParamSchema),
+    returns: z.array(ReturnSchema),
+  })
+  .passthrough();
+
+/**
+ * New-format schema for a stamped generic doc (`type: 'generic'`) — reference
+ * and topic docs. Just the shared base plus the discriminant.
+ */
+export const GenericDocKindSchema = z
+  .object({
+    ...BaseDocFields,
+    type: z.literal('generic'),
+  })
+  .passthrough();
+
+/**
+ * The stamped-doc contract: one of the three new per-kind schemas, discriminated
+ * by the injected `type`. Used when a loaded doc carries a `type` field.
+ */
+export const StampedDocSchema = z.discriminatedUnion('type', [
+  ComponentDocKindSchema,
+  FunctionDocKindSchema,
+  GenericDocKindSchema,
+]);
+
+// ── Legacy loose format (unchanged, kept for back-compat) ─────────────
+//
+// The pre-factory docs are authored as a loose, untyped object with no `type`
+// discriminant and validated by shape. Enumerated top-level fields observed
+// across the existing loose docs:
+//   name, displayName, description, group, category, keywords,
+//   isHiddenFromOverview, hidden, hiddenComponents, usage, props, components,
+//   subComponentOf, playground, theming, examples, params, returns,
+//   relatedComponents, relatedHooks, relatedDocs, parent, importPath.
+
+const LegacyBaseDocSchema = z.object({
+  name: z.string().min(1, 'name is required'),
+  displayName: z.string().optional(),
+  description: z.string().optional(),
+  group: z.string().optional(),
+  category: z.string().optional(),
+  keywords: z.array(z.string()).optional(),
+  isHiddenFromOverview: z.boolean().optional(),
+  hidden: z.boolean().optional(),
+  hiddenComponents: z.array(z.string()).optional(),
+  usage: z.unknown().optional(),
+  playground: z.unknown().optional(),
+  theming: z.unknown().optional(),
+  examples: z.array(z.unknown()).optional(),
+  showcase: z.unknown().optional(),
+  // `parent` and legacy `subComponentOf` are synonyms; both accepted here so a
+  // parent-based doc that omits a stamped `type` still validates.
+  parent: z.string().optional(),
+  relatedDocs: z.array(z.string()).optional(),
+  relatedComponents: z.array(z.string()).optional(),
+  relatedHooks: z.array(z.string()).optional(),
+});
+
+/** Legacy: directory exporting a single primary component (props inline). */
+const LegacySingleComponentDocSchema = LegacyBaseDocSchema.extend({
+  props: z.array(PropSchema),
+}).passthrough();
+
+/** Legacy: directory exporting multiple components (props on each entry). */
+const LegacyMultiComponentDocSchema = LegacyBaseDocSchema.extend({
+  components: z.array(z.unknown()),
+}).passthrough();
+
+/** Legacy: a standalone hook doc — inputs (`params`) + outputs (`returns`). */
+const LegacyHookDocSchema = LegacyBaseDocSchema.extend({
+  params: z.array(ParamSchema),
+  returns: z.array(ReturnSchema),
+}).passthrough();
+
+/** Legacy: a sub-component doc parented via `subComponentOf`. */
+const LegacySubComponentDocSchema = LegacyBaseDocSchema.extend({
+  subComponentOf: z.string().min(1, 'subComponentOf is required'),
+  description: z.string(),
+  props: z.array(PropSchema),
+}).passthrough();
+
+/**
+ * The permissive legacy union. `subComponentOf` is listed first so a doc that
+ * carries both `subComponentOf` and `props` is validated as a sub-component
+ * (the more specific shape); hook (`params`/`returns`) before multi/single.
+ */
+export const LegacyDocSchema = z.union([
+  LegacySubComponentDocSchema,
+  LegacyHookDocSchema,
+  LegacyMultiComponentDocSchema,
+  LegacySingleComponentDocSchema,
+]);
+
+/**
+ * The LOAD-boundary contract for a doc. Handles BOTH formats:
+ *   - NEW: a stamped doc (`type: 'component' | 'function' | 'generic'`,
+ *     produced by the factories) is validated against the matching per-kind
+ *     schema in {@link StampedDocSchema}.
+ *   - OLD: a loose, unstamped doc is validated against the permissive
+ *     {@link LegacyDocSchema} union (the three legacy shapes + standalone hook).
+ *
+ * Discovery validates the SHAPE, not "was it made by the factory". Both formats
+ * normalize into the same internal shape consumers already expect.
+ */
+export const ComponentDocSchema = z.union([StampedDocSchema, LegacyDocSchema]);