@astryxdesign/cli 0.6.4 → 0.6.5-canary.00f1ed9

package/authoring/doctypes/_schema.mjs

@@ -307,6 +307,7 @@ const ComponentBaseSchema = z
     theming: z.unknown().optional(),
     playground: z.unknown().optional(),
     examples: z.array(z.unknown()).optional(),
+    replaces: z.string().min(1).optional(),
   })
   .passthrough();
 
@@ -414,6 +415,9 @@ export const GenericDocKindSchema = z
     ...BaseDocFields,
     type: z.literal('generic'),
     title: nonEmptyString.optional(),
+    // Search terms the title and sections do not use; `astryx search` matches
+    // them as keywords of the whole topic (ReferenceDoc `keywords`).
+    keywords: z.array(z.string()).optional(),
     sections: z.array(ReferenceSectionSchema).min(1).optional(),
     replaces: nonEmptyString.optional(),
     extends: nonEmptyString.optional(),
@@ -730,6 +734,8 @@ const LegacyBaseDocSchema = z.object({
 const LegacyReferenceDocSchema = LegacyBaseDocSchema.extend({
   title: nonEmptyString,
   description: z.string(),
+  // As on the stamped schema: search terms for the whole topic.
+  keywords: z.array(z.string()).optional(),
   sections: z.array(ReferenceSectionSchema).min(1),
   replaces: nonEmptyString.optional(),
   extends: nonEmptyString.optional(),

package/authoring/doctypes/base/graph-fields.doc.mjs

@@ -12,7 +12,7 @@ export const doc = {
   displayName: 'Authored doc graph fields',
   namespace: 'authoring',
   description:
-    "Placement, compatibility aliases, and audience: fields every authored doc kind declares for the docs tree. The docs tree reads `placement` for every guide, the CLI's and each integration's; aliases and audience are not built yet. A reference topic outside the docs tree that sets one fails to load, and other doc kinds accept them and ignore them.",
+    "Fields every authored doc kind can declare for the docs tree: `placement`, plus two reserved fields, `aliases` and `audience`. The docs tree reads `placement` for every guide, the CLI's and each integration's. Nothing reads `aliases` or `audience` today: a reference topic outside the docs tree that sets one fails to load, and other doc kinds accept them and ignore them.",
   appliesTo: 'Every supported .doc.mjs object',
   fields: [
     {
@@ -45,13 +45,13 @@ export const doc = {
       name: 'aliases',
       type: 'string[]',
       description:
-        'Prior names or routes the docs tree will keep resolving to this doc, without creating another identity. Not read yet: a topic that sets it fails to load.',
+        'Reserved: prior names or routes the docs tree will keep resolving to this doc, without creating another identity. Nothing reads it today, and a topic that sets it fails to load.',
     },
     {
       name: 'audience',
       type: "'public' | 'internal'",
       description:
-        "Which docs bundle includes this doc ('public' when omitted). Not read yet: a topic that sets it fails to load.",
+        "Reserved: which docs bundle includes this doc ('public' when omitted). Nothing reads it today, and a topic that sets it fails to load.",
       default: "'public'",
     },
   ],

package/authoring/doctypes/base/type.ts

@@ -39,9 +39,11 @@ export interface DocPlacement {
 export interface AuthoredDocGraphFields {
   /** The doc's one parent in the docs tree: a namespace of its own package. */
   placement?: DocPlacement;
-  /** Prior routes or names the docs tree will keep resolving. Not read yet. */
+  /** Reserved: prior routes or names the docs tree will keep resolving.
+   *  Nothing reads it yet. */
   aliases?: string[];
-  /** Docs bundle audience; omit for public docs. Not read yet. */
+  /** Reserved: docs bundle audience; omit for public docs. Nothing reads it
+   *  yet. */
   audience?: DocAudience;
 }
 

package/authoring/doctypes/component/component.doc.mjs

@@ -52,6 +52,12 @@ export const doc = {
       description:
         'Exact public package specifier consumers use to import an integration-owned component. The packed-package gate resolves this specifier and verifies it exports the component name.',
     },
+    {
+      name: 'replaces',
+      type: 'string',
+      description:
+        "Integration components only: the exact `name` of the Core ComponentDoc this component takes over for unqualified lookup, so every app that loads the integration gets it from component detail, lists, search, swizzle, and issue routing. The Core original stays reachable with `--package @astryxdesign/core`. Set it only to intentionally own a Core identity; give an alternative or variant its own name instead.",
+    },
     {
       name: 'keywords',
       type: 'string[]',

package/authoring/doctypes/component/type.ts

@@ -48,6 +48,14 @@ export interface ComponentBaseDoc extends AuthoredDocGraphFields {
   displayName: string;
   /** Exact consumer import specifier for integration-owned components. */
   import?: string;
+  /** Integration components only: the exact `name` of the Core ComponentDoc
+   *  this component takes over for unqualified lookup, so every app that loads
+   *  the integration gets this component from component detail, lists, search,
+   *  swizzle, and issue routing. The Core original stays reachable with
+   *  `--package @astryxdesign/core`. Set it only to intentionally own a Core
+   *  identity; give an alternative or variant its own name instead. Older CLIs
+   *  that do not read `replaces` keep the component under its own name. */
+  replaces?: string;
   /** Search keywords for CLI discovery. Terms a developer might type when
    *  looking for this component: synonyms, related UI concepts, and common
    *  names from other design systems (MUI, Chakra, Radix, and others).

package/authoring/doctypes/reference/reference.doc.mjs

@@ -51,6 +51,13 @@ export const doc = {
       type: 'string',
       description: "Navigation category: 'guide' or 'foundations'.",
     },
+    {
+      name: 'keywords',
+      type: 'string[]',
+      description:
+        "Words a reader may search for that the title and sections do not use: a synonym, a task, or another library's name for the same thing. `astryx search` matches each as a keyword of the whole topic, so an exact one ranks the topic like its own title does.",
+      example: "['dark mode', 'color scheme']",
+    },
     {
       name: 'replaces',
       type: 'string',

package/authoring/doctypes/reference/type.ts

@@ -127,6 +127,11 @@ export interface ReferenceDoc extends AuthoredDocGraphFields {
   description: string;
   /** Navigation category: 'guide' or 'foundations'. */
   category?: string;
+  /** Words a reader may search for that the title and sections do not use:
+   *  a synonym, a task ("dark mode"), or another library's name for the same
+   *  thing. `astryx search` matches each as a keyword of the whole topic, so
+   *  an exact one ranks the topic like its own title does. */
+  keywords?: string[];
   /** Name of an existing topic this doc takes the place of. Authored by an
    *  integration whose guide should be served instead of the built-in one —
    *  `replaces: 'getting-started'` on a doc named `getting-started` swaps the

package/authoring/doctypes/schema/schema.doc.mjs

@@ -49,7 +49,7 @@ export const doc = {
       name: 'namespace',
       type: 'string',
       description:
-        "The group that reads this doc: 'authoring' for a file an author writes (a section of `astryx docs authoring`), or 'cli/api' for a shape the CLI returns (the docs tree adopts it by kind, as the leaf `cli/api/schemas/<name>`). Every schema doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads.",
+        "The group that reads this doc: 'authoring' for a file an author writes (a section of {@link generic:authoring}), or 'cli/api' for a shape the CLI returns (the docs tree adopts it by kind, as the leaf `cli/api/schemas/<name>`). Every schema doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads.",
     },
     {
       name: 'aliases',
@@ -162,7 +162,7 @@ export const doc = {
       type: '{ dir: string }',
       description: 'Where component sources live.',
       fields: [
-        {name: 'components.dir', type: 'string', description: 'Glob root for XDS*.tsx files.', required: true},
+        {name: 'components.dir', type: 'string', description: 'Glob root for Acme*.tsx files.', required: true},
       ],
     },
   ],

package/authoring/doctypes/template/parse.d.mts

@@ -43,6 +43,7 @@ declare const pageTemplateSchema: z.ZodObject<{
     name: z.ZodString;
     displayName: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
     category: z.ZodOptional<z.ZodString>;
     componentsUsed: z.ZodOptional<z.ZodArray<z.ZodString>>;
     preview: z.ZodOptional<z.ZodObject<{
@@ -79,6 +80,7 @@ declare const blockTemplateSchema: z.ZodObject<{
     name: z.ZodString;
     displayName: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
     category: z.ZodOptional<z.ZodString>;
     componentsUsed: z.ZodOptional<z.ZodArray<z.ZodString>>;
     preview: z.ZodOptional<z.ZodObject<{

package/authoring/doctypes/template/parse.mjs

@@ -44,6 +44,7 @@ const baseTemplateFields = {
   name: z.string().min(1, 'name is required'),
   displayName: z.string().min(1).optional(),
   description: z.string().min(1, 'description is required').optional(),
+  keywords: z.array(z.string().min(1)).optional(),
   category: z.string().optional(),
   componentsUsed: z.array(z.string()).optional(),
   preview: previewSchema.optional(),

package/authoring/doctypes/template/parse.test.mjs

@@ -34,6 +34,27 @@ describe('parseTemplate (load boundary)', () => {
     }
   });
 
+  it('accepts keywords on page and block templates', () => {
+    for (const type of ['page', 'block']) {
+      const parsed = parseTemplate({
+        type,
+        name: 'Acme health',
+        description: 'Status tiles over time charts.',
+        keywords: ['uptime', 'on-call'],
+      });
+      expect(parsed.keywords).toEqual(['uptime', 'on-call']);
+    }
+  });
+
+  it('rejects keywords that are not a list of words', () => {
+    expect(
+      reason({type: 'page', name: 'Acme health', keywords: 'uptime'}),
+    ).toMatch(/keywords/);
+    expect(reason({type: 'page', name: 'Acme health', keywords: ['']})).toMatch(
+      /keywords/,
+    );
+  });
+
   it('rejects an empty replaces', () => {
     expect(reason({type: 'page', name: 'Acme shell', replaces: ''})).toMatch(
       /replaces must name a Core template id/,

package/authoring/doctypes/template/template.doc.mjs

@@ -52,11 +52,17 @@ export const doc = {
       type: 'string',
       description: 'One-sentence description of what the template provides.',
     },
+    {
+      name: 'keywords',
+      type: 'string[]',
+      description:
+        "Search keywords for CLI discovery: the ideas, domains, and other names a builder might use for what the template serves (e.g. ['monitoring', 'uptime', 'on-call'] for a service-health dashboard). Lowercase. `astryx search` matches them as it matches the description and `astryx build` ranks page templates on them, so keep them out of `description`. Integration templates need @astryxdesign/cli 0.7.0 or later: earlier CLIs reject the field, drop that template, and hide the package's doc topics.",
+    },
     {
       name: 'replaces',
       type: 'string',
       description:
-        "Integration templates only: the exact id of the Core template this one replaces for unqualified lookup. Find it with `astryx --json template --list --package @astryxdesign/core`; the Core original stays selectable with `--package @astryxdesign/core`. A page replaces only a Core page and a block only a Core block. Needs @astryxdesign/cli 0.7.0 or later: earlier CLIs reject the field and withhold the package's templates and doc topics.",
+        "Integration templates only: the exact id of the Core template this one replaces for unqualified lookup. Find it with `astryx --json template --list --package @astryxdesign/core`; the Core original stays selectable with `--package @astryxdesign/core`. A page replaces only a Core page and a block only a Core block. Needs @astryxdesign/cli 0.7.0 or later: earlier CLIs reject the field, drop that template, and hide the package's doc topics.",
     },
     {
       name: 'isReady',

package/authoring/doctypes/template/type.ts

@@ -26,6 +26,16 @@ export interface BaseTemplateDoc extends AuthoredDocGraphFields {
   /** One-sentence description of what the template provides. */
   description?: string;
 
+  /** Search keywords for CLI discovery: the ideas, domains, and other names a
+   *  builder might use for what this template serves (e.g. `['monitoring',
+   *  'uptime', 'on-call']` for a service-health dashboard). Lowercase.
+   *  `astryx search` matches them as it matches the description, and
+   *  `astryx build` ranks page templates on them, so the `description` can
+   *  stay a description of the layout. Integration templates need
+   *  `@astryxdesign/cli` 0.7.0 or later: earlier CLIs reject the field, drop
+   *  that template, and hide the package's doc topics. */
+  keywords?: string[];
+
   /** Optional stable slug override and prior aliases for registry output. */
   registry?: RegistryDocIdentity;
 
@@ -33,8 +43,8 @@ export interface BaseTemplateDoc extends AuthoredDocGraphFields {
    *  replaces for unqualified lookup (find it with
    *  `astryx --json template --list --package @astryxdesign/core`). The Core
    *  original stays selectable with `--package @astryxdesign/core`. Needs
-   *  `@astryxdesign/cli` 0.7.0 or later: earlier CLIs reject the field and
-   *  withhold the package's templates and doc topics. */
+   *  `@astryxdesign/cli` 0.7.0 or later: earlier CLIs reject the field,
+   *  drop that template, and hide the package's doc topics. */
   replaces?: string;
   /** Whether this template is ready for use. Templates with
    *  isReady: false show as "(WIP)" in the gallery and CLI. */

package/authoring/index.d.mts

@@ -3,6 +3,7 @@
 
 export { parseConfig } from "./config/parse.mjs";
 export { parseIntegration } from "./integration/parse.mjs";
+export { parseDiscoverCatalog } from "./discover/parse.mjs";
 export { parseCodemod } from "./codemod/parse.mjs";
 export { parseDebugEvent } from "./debug/parse.mjs";
 export { parseDoc } from "./doctypes/parse.mjs";

package/authoring/index.d.ts

@@ -44,6 +44,15 @@ export type {
   GapReportTarget,
   GapReportHandlerReceipt,
 } from './gap-report/type.js'; // gap-report handler contract
+export type {
+  DiscoverSource,
+  DiscoverSourceContext,
+  DiscoverCatalog,
+  DiscoverPackage,
+  DiscoverVersion,
+  DiscoverContribution,
+  DiscoverKind,
+} from './discover/type.js'; // discover source contract
 export type {AstryxCodemod, AstryxConfigCodemod} from './codemod/type.js'; // codemods/*
 
 // ═══════════════════════════════════════════════════════════════════════
@@ -67,6 +76,7 @@ export {
   parseGapReportHandler,
   parseGapReportReceipt,
 } from './gap-report/parse.mjs';
+export {parseDiscoverCatalog} from './discover/parse.mjs';
 export {parseCodemod} from './codemod/parse.mjs';
 export {parseDebugEvent} from './debug/parse.mjs';
 

package/authoring/index.mjs

@@ -20,6 +20,7 @@ export {
   parseGapReportHandler,
   parseGapReportReceipt,
 } from './gap-report/parse.mjs';
+export {parseDiscoverCatalog} from './discover/parse.mjs';
 export {parseCodemod} from './codemod/parse.mjs';
 export {parseDebugEvent} from './debug/parse.mjs';
 export {parseDoc} from './doctypes/parse.mjs';

package/authoring/integration/integration.doc.mjs

@@ -23,48 +23,49 @@ export const doc = {
       name: 'providerId',
       type: 'string',
       description:
-        'Stable logical provider ID. Omit to use package.json#name; set it to the prior package name only when an explicit rename must preserve artifact IDs. If two packages claim the same ID, the package being authored is used, otherwise the first-loaded one, and the CLI warns about the other.',
+        'The name that marks this package as the source of everything it contributes. Leave it out to use the package name from package.json. Set it to the old name only during a rename, so the IDs of what the package already contributed stay the same. If two packages use the same name here, the one you are working on wins; otherwise the one the CLI reads first wins, and the CLI warns about the other.',
       example: "'@acme/widgets'",
     },
     {
       name: 'components',
       type: 'string',
       description:
-        'Relative path to the components/docs root (resolved to absolute).',
+        'The folder that holds your components and their docs, relative to package.json.',
       example: "'./src/components'",
     },
     {
       name: 'templates',
       type: 'string',
       description:
-        'Relative path to the templates root (resolved to absolute).',
+        'The folder that holds your templates, relative to package.json.',
       example: "'./src/templates'",
     },
     {
       name: 'codemods',
       type: 'string',
-      description: 'Relative path to the codemods root (resolved to absolute).',
+      description:
+        'The folder that holds your codemods, relative to package.json.',
       example: "'./codemods'",
     },
     {
       name: 'docs',
       type: 'string',
       description:
-        'Relative path to the reference-docs (topics) root (resolved to absolute). Every {topic}.doc.{ts,mjs,js} under it is served by `astryx docs` beside the built-in topics; a topic may also declare `replaces` or `extends` to take the place of a built-in one or merge onto it.',
+        'The folder that holds your doc topics, relative to package.json. Every {topic}.doc.{ts,mjs,js} in it shows up in `astryx docs` next to the built-in topics; a topic can also set `replaces` or `extends` to take over a built-in topic or add to it.',
       example: "'./docs'",
     },
     {
       name: 'themes',
       type: 'string',
       description:
-        'Relative path to a source-theme root with one directory per theme slug. Each directory contains a source module and mandatory same-stem, strongly typed .doc.mjs descriptor. Installed themes appear in `astryx theme list` and can be copied with `astryx theme add`.',
+        'The folder that holds your themes, relative to package.json, with one folder per theme. Each theme folder has the theme source and a matching .doc.mjs file with the same name. Installed themes show up in `astryx theme list` and can be copied with `astryx theme add`.',
       example: "'./themes'",
     },
     {
       name: 'agentDocs',
       type: '{ append?: readonly string[] }',
       description:
-        'Static package guidance appended to the end of the managed agent block. The CLI owns the section heading, package labels, bullets, target files, and writes.',
+        'Lines of guidance your package adds to the end of the agent instructions the CLI manages. The CLI owns the heading, labels, bullets, and which files it writes.',
       example: "{ append: ['Run acme verify.'] }",
     },
     {
@@ -94,9 +95,10 @@ export const doc = {
     {
       type: 'prose',
       text:
-        'Provider identity defaults to package.json#name. During an explicit ' +
-        'package rename, set `providerId` to the prior canonical package name so ' +
-        'existing artifact IDs remain stable. Package version always comes from package.json.',
+        'The provider name defaults to the package name in package.json. ' +
+        'During a rename, set `providerId` to the old package name so the IDs ' +
+        'of what the package already contributed stay the same. The package ' +
+        'version always comes from package.json.',
     },
     {
       type: 'prose',

package/clients/cli/commands/component/index.mjs

@@ -38,6 +38,7 @@ import {doc as componentFn} from '../../../../api/component/component.doc.mjs';
  *
  * @typedef {(
  *   | import('../../../../api/component/component.type.mjs').ComponentListResponse
+ *   | import('../../../../api/component/component.type.mjs').ComponentBatchResponse
  *   | import('../../../../api/component/component.type.mjs').ComponentDetailResponse
  *   | import('../../../../api/component/component.type.mjs').ComponentDetailPropsResponse
  *   | import('../../../../api/component/component.type.mjs').ComponentDetailSourceResponse
@@ -67,6 +68,11 @@ function summarize(result) {
       );
       return resultSet({count, resultKind: 'component'});
     }
+    case 'component.batch':
+      return resultSet({
+        count: result.data.results.filter(row => row.status === 'found').length,
+        resultKind: 'component',
+      });
     case 'component.detail':
     case 'component.detail.props':
     case 'component.detail.source':
@@ -82,19 +88,103 @@ function summarize(result) {
   }
 }
 
+/**
+ * Project one single-component API result through the existing formatter kit.
+ * @param {import('../../../../api/component/component.type.mjs').ComponentSingleResponse} result
+ * @param {string} requestedName
+ * @param {'full'|'compact'|'brief'} detail
+ * @param {ReturnType<typeof resolveTheme>} themeData
+ * @returns {import('../../formatters/index.mjs').Block[]}
+ */
+function componentDetailBlocks(result, requestedName, detail, themeData) {
+  const resolvedName = (requestedName.split('/').pop() ?? requestedName).replace(
+    /^XDS/,
+    '',
+  );
+  switch (result.type) {
+    case 'component.detail': {
+      /** @type {import('../../formatters/index.mjs').Block[]} */
+      const out = [];
+      if (result.data.parentDoc) {
+        out.push(record(result.data, {fields: ['parentDoc']}));
+      }
+      out.push(
+        detail === 'brief'
+          ? code(
+              formatBrief(result.data, resolvedName, result.data.import, {
+                themeData,
+              }),
+            )
+          : detail === 'compact'
+            ? code(
+                formatCompact(result.data, resolvedName, result.data.import),
+              )
+            : code(
+                formatFull(result.data, {
+                  themeData,
+                  importHint: result.data.import,
+                }),
+              ),
+      );
+      return out;
+    }
+    case 'component.detail.props':
+      return [code(formatProps({props: result.data}, resolvedName))];
+    case 'component.detail.source':
+    case 'component.detail.showcase':
+      return [code(result.data.source)];
+    case 'component.detail.blocks': {
+      const {showcase, examples, related} = result.data;
+      /** @type {import('../../formatters/index.mjs').Block[]} */
+      const out = [];
+      if (showcase) {
+        out.push(
+          section('Showcase'),
+          record(showcase, {fields: ['displayName', 'description']}),
+        );
+      }
+      if (examples.length > 0) {
+        out.push(
+          section('Examples'),
+          records(examples, {fields: ['name', 'description']}),
+        );
+      }
+      if (related.length > 0) {
+        out.push(
+          section(
+            `Related: ${related.length} blocks that use ${result.data.component}`,
+          ),
+          list(related.map(block => block.name)),
+        );
+      }
+      if (!showcase && examples.length === 0 && related.length === 0) {
+        out.push(text(`No blocks found for ${result.data.component}`));
+      }
+      return out;
+    }
+    default:
+      return [];
+  }
+}
+
 /**
  * @param {import('commander').Command} program
  */
 export function registerComponent(program) {
   defineCommand(program, componentCommand, {
     fn: componentFn,
-    action: async (/** @type {string | undefined} */ name, /** @type {{list?: boolean, category?: string, props?: boolean, source?: boolean, showcase?: boolean, blocks?: boolean, package?: string}} */ options) => {
+    action: async (
+      /** @type {string[] | undefined} */ names,
+      /** @type {{list?: boolean, category?: string, props?: boolean, source?: boolean, showcase?: boolean, blocks?: boolean, package?: string}} */ options,
+    ) => {
       const run = getCliInvocation();
+      const name = names?.length === 1 ? names[0] : undefined;
+      const apiInput = !names?.length ? undefined : name ?? names;
       const zh = program.opts().zh || false;
       const dense = program.opts().dense || false;
       const lang = program.opts().lang || null;
       const detailSource = program.getOptionValueSource('detail');
-      const isListView = options.list || options.category || !name;
+      const isListView = options.list || options.category || !names?.length;
       // Default detail level is full for single-component view, brief for list views.
       // (List views are scannable name lists; users can opt into compact/full.)
       let detail = program.opts().detail || 'full';
@@ -119,7 +209,7 @@ export function registerComponent(program) {
       /** @type {ComponentResult} */
       let result;
       try {
-        result = /** @type {ComponentResult} */ (await componentApi(name, {
+        result = /** @type {ComponentResult} */ (await componentApi(apiInput, {
           cwd: process.cwd(),
           list: options.list,
           category: options.category,
@@ -137,6 +227,12 @@ export function registerComponent(program) {
       }
 
       const answered = summarize(result);
+      if (
+        result.type === 'component.batch' &&
+        result.data.results.some(row => row.status !== 'found')
+      ) {
+        process.exitCode = 1;
+      }
       if (json) {
         jsonOut(result);
         return answered;
@@ -152,7 +248,7 @@ export function registerComponent(program) {
       const listFooter = text(
         [
           `Import from the path shown (e.g. import {Button} from '@astryxdesign/core/Button')`,
-          `Usage: ${run} component <name>`,
+          `Usage: ${run} component <name> [name...]`,
         ].join('\n'),
       );
 
@@ -231,64 +327,65 @@ export function registerComponent(program) {
           break;
         }
 
-        case 'component.detail': {
-          const resolvedName = (name || '').replace(/^XDS/, '');
-          const importHint = result.data.import;
-          if (result.data.parentDoc) emit(record(result.data, {fields: ['parentDoc']}));
-          const doc =
-            detail === 'brief'
-              ? code(formatBrief(result.data, resolvedName, importHint, {themeData}))
-              : detail === 'compact'
-                ? code(formatCompact(result.data, resolvedName, importHint))
-                : code(formatFull(result.data, {themeData, importHint}));
-          emit(doc);
-          break;
-        }
-
-        case 'component.detail.props': {
-          const resolvedName = (name || '').replace(/^XDS/, '');
-          emit(code(formatProps({props: result.data}, resolvedName)));
-          break;
-        }
-
-        case 'component.detail.source': {
-          emit(code(result.data.source));
-          break;
-        }
-
-        case 'component.detail.showcase': {
-          emit(code(result.data.source));
-          break;
-        }
-
-        case 'component.detail.blocks': {
-          const {showcase, examples, related} = result.data;
+        case 'component.batch': {
           /** @type {import('../../formatters/index.mjs').Block[]} */
-          const out = [];
-          if (showcase) {
-            out.push(
-              section('Showcase'),
-              record(showcase, {fields: ['displayName', 'description']}),
-            );
-          }
-          if (examples.length > 0) {
-            out.push(
-              section('Examples'),
-              records(examples, {fields: ['name', 'description']}),
-            );
-          }
-          if (related.length > 0) {
+          const out = [
+            section('Component batch'),
+            record({count: result.data.count}),
+            section('Results'),
+          ];
+          for (const row of result.data.results) {
+            out.push(section(row.selector));
+            if (row.status === 'found') {
+              out.push(
+                record(row, {fields: ['selector', 'status']}),
+                section('Result'),
+                ...componentDetailBlocks(
+                  row.result,
+                  row.selector,
+                  detail,
+                  themeData,
+                ),
+              );
+              continue;
+            }
             out.push(
-              section(`Related: ${related.length} blocks that use ${result.data.component}`),
-              list(related.map(b => b.name)),
+              record(row, {
+                fields: ['selector', 'status', 'code', 'error'],
+              }),
             );
-          }
-          if (!showcase && examples.length === 0 && related.length === 0) {
-            out.push(text(`No blocks found for ${result.data.component}`));
+            if (row.status === 'ambiguous') {
+              out.push(
+                section('Candidates'),
+                records(row.candidates, {
+                  fields: ['package', 'component', 'kind', 'installed'],
+                }),
+              );
+            } else if (row.suggestions?.length) {
+              out.push(
+                section('Suggestions'),
+                records(row.suggestions, {fields: ['name', 'reason']}),
+              );
+            }
           }
           emit(...out);
           break;
         }
+
+        case 'component.detail':
+        case 'component.detail.props':
+        case 'component.detail.source':
+        case 'component.detail.showcase':
+        case 'component.detail.blocks':
+          emit(
+            ...componentDetailBlocks(
+              result,
+              name ?? '',
+              detail,
+              themeData,
+            ),
+          );
+          break;
       }
       return answered;
     },