@astryxdesign/cli 0.6.4 → 0.6.5-canary.01972bc

package/api/build/kit/rank.test.mjs

@@ -2,14 +2,15 @@
 
 /**
  * @file Tests for build's page ranker: long ideas, head nouns, family bases,
- * rare-word weighting, and family words taken from the templates themselves.
+ * rare-word weighting, keywords, family words taken from the templates
+ * themselves, and parts told from pages by the system's own components.
  */
 
 import {describe, it, expect} from 'vitest';
 import * as path from 'node:path';
 import {fileURLToPath} from 'node:url';
-import {pickStart, rankPages} from './rank.mjs';
-import {loadPageTemplates} from '../_adapter.mjs';
+import {ideaKind, pickStart, rankPages} from './rank.mjs';
+import {loadComponents, loadPageTemplates} from '../_adapter.mjs';
 
 // api/build/kit/ -> up 5 = repo root (has packages/core and the templates).
 const REPO = path.resolve(
@@ -17,14 +18,24 @@ const REPO = path.resolve(
   '../../../../..',
 );
 
-/** @param {string} name @param {string} category @param {string} description */
-const page = (name, category, description) => ({
+/**
+ * @param {string} name
+ * @param {string} category
+ * @param {string} description
+ * @param {string[]} [keywords]
+ */
+const page = (name, category, description, keywords = []) => ({
   name,
   displayName: name,
   category,
   description,
+  keywords,
+  command: `astryx template ${name} --type page`,
 });
 
+/** @param {string} name @param {string[]} [keywords] */
+const component = (name, keywords = []) => ({name, keywords});
+
 describe('rankPages on the shipped page templates', () => {
   /** @param {string} query */
   const start = async query =>
@@ -49,6 +60,19 @@ describe('rankPages on the shipped page templates', () => {
     );
   });
 
+  it('keeps the family base when a variant shares one incidental word', async () => {
+    // "comparison" and "cohort" name dashboard variants, but here each is one
+    // small part of a general dashboard.
+    expect(
+      await start(
+        'support dashboard with ticket volume charts and a small comparison note',
+      ),
+    ).toBe('dashboard');
+    expect(
+      await start('sales dashboard with a cohort filter and weekly charts'),
+    ).toBe('dashboard');
+  });
+
   it('lets the head noun decide between families', async () => {
     // Both ideas mention a table and summary numbers; the head says which
     // page it is.
@@ -64,6 +88,14 @@ describe('rankPages on the shipped page templates', () => {
     ).toMatch(/^table-/);
   });
 
+  it('keeps a variant that leads when its family base cannot start alone', async () => {
+    // The dashboard base matches only the family word here; the funnel
+    // dashboard matches the idea.
+    expect(await start('a funnel for a dashboard')).toBe(
+      'dashboard-cohort-funnel',
+    );
+  });
+
   it('does not start from one rare word', async () => {
     // "board" is the kanban board's own word; a game board is not a kanban.
     expect(
@@ -75,11 +107,10 @@ describe('rankPages on the shipped page templates', () => {
 describe('rankPages on any catalog', () => {
   it('ranks only the templates it is given', () => {
     const ranked = rankPages('dashboard', [
-      page(
+      page('dashboard', 'Dashboard - Analytics', 'Tiles, charts, tables.', [
         'dashboard',
-        'Dashboard - Analytics',
-        'Tiles, charts, tables. Dashboard, metrics.',
-      ),
+        'metrics',
+      ]),
     ]);
     expect(ranked.map(r => r.name)).toEqual(['dashboard']);
   });
@@ -88,17 +119,14 @@ describe('rankPages on any catalog', () => {
     // An integration's family: its word is in two of its ids, so an idea
     // naming it picks the family, and its base template leads it.
     const catalog = [
-      page(
+      page('dashboard', 'Dashboard - Analytics', 'Tiles, charts, tables.', [
         'dashboard',
-        'Dashboard - Analytics',
-        'Tiles, charts, tables. Dashboard, metrics.',
-      ),
-      page('widget', 'Widget - Basic', 'One compact card. Widget, tile.'),
-      page(
-        'widget-grid',
-        'Widget - Grid',
-        'Many compact cards in a grid. Widget wall.',
-      ),
+        'metrics',
+      ]),
+      page('widget', 'Widget - Basic', 'One compact card.', ['widget', 'tile']),
+      page('widget-grid', 'Widget - Grid', 'Many compact cards in a grid.', [
+        'widget wall',
+      ]),
     ];
     const ranked = rankPages('weather widget with charts', catalog);
     expect(ranked[0].name).toBe('widget');
@@ -106,15 +134,41 @@ describe('rankPages on any catalog', () => {
     expect(pickStart(ranked)?.name).toBe('widget');
   });
 
+  it("counts a template's keywords above words in its description", () => {
+    // Both mention uptime; only one names it as an idea it serves.
+    const catalog = [
+      page('ops', 'Dashboard - Ops', 'Uptime strips beside alert rows.'),
+      page('health', 'Dashboard - Health', 'Status tiles over time charts.', [
+        'uptime',
+      ]),
+    ];
+    expect(rankPages('uptime overview', catalog)[0].name).toBe('health');
+  });
+
+  it("lets a variant displace its family's base only with two words of its own", () => {
+    const catalog = [
+      page('widget', 'Widget - Basic', 'One compact card.', ['widget']),
+      page('widget-weather', 'Widget - Weather', 'A forecast card.', [
+        'weather',
+        'forecast',
+        'radar',
+      ]),
+    ];
+    // One word of the variant's own: still the family's base.
+    expect(rankPages('weather widget', catalog)[0].name).toBe('widget');
+    // Two: the variant.
+    expect(rankPages('weather widget with radar', catalog)[0].name).toBe(
+      'widget-weather',
+    );
+  });
+
   it('weighs a word by how rare it is among page templates', () => {
     const catalog = [
-      page('alpha', 'Dashboard - Alpha', 'Status tiles. Status overview.'),
-      page('beta', 'Dashboard - Beta', 'Status rows. Status list.'),
-      page(
-        'gamma',
-        'Dashboard - Gamma',
-        'Funnel of stages. Funnel conversion.',
-      ),
+      page('alpha', 'Dashboard - Alpha', 'Status tiles.', ['status overview']),
+      page('beta', 'Dashboard - Beta', 'Status rows.', ['status list']),
+      page('gamma', 'Dashboard - Gamma', 'Funnel of stages.', [
+        'funnel conversion',
+      ]),
     ];
     // "status" is on two templates, "funnel" on one: the rare word wins.
     const ranked = rankPages('status funnel', catalog);
@@ -127,22 +181,24 @@ describe('rankPages structure signals', () => {
     page(
       'dialog-panel',
       'Settings - Dialog',
-      'Preferences inside a modal container. Settings, or modal dialog.',
-    ),
-    page(
-      'tree-table',
-      'Table - Tree',
-      'Nested rows under parents. Tree, nested rows, file browser.',
-    ),
-    page(
-      'item-detail',
-      'Content - Item Detail',
-      'One item with its media. Product, listing, or item detail.',
+      'Preferences inside a modal container.',
+      ['settings', 'modal dialog'],
     ),
+    page('tree-table', 'Table - Tree', 'Nested rows under parents.', [
+      'tree',
+      'nested rows',
+      'file browser',
+    ]),
+    page('item-detail', 'Content - Item Detail', 'One item with its media.', [
+      'product',
+      'listing',
+      'item detail',
+    ]),
     page(
       'docs-catalog',
       'Content - Documentation Catalog',
-      'A grid of category cards. Documentation, docs, or API index.',
+      'A grid of category cards.',
+      ['documentation', 'docs', 'api index'],
     ),
   ];
 
@@ -179,18 +235,145 @@ describe('rankPages structure signals', () => {
   it('does not treat a synonym as a family name', () => {
     // "landing" is a synonym of "hero" in search, not a family word here.
     const heroes = [
-      page(
-        'hero-centered',
-        'Gallery - Hero',
-        'A centered hero. Hero, banner, or landing.',
-      ),
-      page(
-        'hero-split',
-        'Gallery - Hero Split',
-        'A split hero. Hero or splash.',
-      ),
+      page('hero-centered', 'Gallery - Hero', 'A centered hero.', [
+        'hero',
+        'banner',
+        'landing',
+      ]),
+      page('hero-split', 'Gallery - Hero Split', 'A split hero.', [
+        'hero',
+        'splash',
+      ]),
     ];
     const ranked = rankPages('internal landing page', heroes);
     expect(ranked.every(r => !r.familyNamed)).toBe(true);
   });
 });
+
+describe('ideaKind: a part of a page, told by the components the system ships', () => {
+  const pages = [
+    page('table', 'Table - Basic', 'Rows of records.'),
+    page('table-filter', 'Table - Filtering', 'Rows narrowed by filters.'),
+    page('settings', 'Settings', 'Grouped preferences.'),
+  ];
+  const components = [
+    component('DateRangeInput', ['date picker']),
+    component('Tooltip'),
+    component('Calendar'),
+    component('Table'),
+    component('Dialog', ['modal']),
+  ];
+  /** @param {string} idea @param {object[]} [using] */
+  const kind = (idea, using = components) => ideaKind(idea, pages, using);
+
+  it('takes a part from a component name or keyword at the head', () => {
+    expect(kind('a date range input')).toBe('part');
+    expect(kind('a date picker with presets')).toBe('part');
+    expect(kind('a tooltip')).toBe('part');
+  });
+
+  it('takes a page word or a family word at the head as a page', () => {
+    expect(kind('a calendar')).toBe('part');
+    expect(kind('a team calendar page')).toBe('page');
+    // Table is a component, but table is also a family of page templates.
+    expect(kind('a data table with filters')).toBe('page');
+  });
+
+  it("reads parts from the project's own components", () => {
+    // An integration's component joins the vocabulary by existing.
+    expect(kind('a revenue gauge')).toBe('page');
+    expect(
+      kind('a revenue gauge', [...components, component('AcmeGauge')]),
+    ).toBe('part');
+  });
+
+  it("takes an idea that lists a page's worth of pieces as a page", () => {
+    expect(kind('a calendar with a tooltip')).toBe('part');
+    expect(kind('a calendar, a tooltip, and a date range input')).toBe('page');
+  });
+
+  it('takes the frame of a container phrase as the frame, not the head', () => {
+    expect(kind('a dialog')).toBe('part');
+    expect(kind('saved drafts in a modal')).toBe('page');
+  });
+
+  it('takes a change to an existing page or part as an edit', () => {
+    expect(kind('add a sort toggle to the existing reports table')).toBe(
+      'edit',
+    );
+    expect(kind('reuse the existing tooltip on the chart')).toBe('edit');
+  });
+
+  it('does not take "existing" that names no page or part as an edit', () => {
+    expect(kind('a new settings page inspired by the existing one')).toBe(
+      'page',
+    );
+    expect(kind('show existing users in a settings page')).toBe('page');
+  });
+
+  it('does not take a request for a new page as an edit', () => {
+    expect(
+      kind('a new settings page based on the existing settings page'),
+    ).toBe('page');
+    expect(kind('clone the existing table as a new page')).toBe('page');
+    // "A new column" asks for a part, so the change stays a change.
+    expect(kind('add a new column to the existing reports table')).toBe('edit');
+  });
+});
+
+describe('pickStart on parts and edits (spec:AST-048/FR3)', () => {
+  const shipped = Promise.all([loadPageTemplates(REPO), loadComponents(REPO)]);
+  /** @param {string} query */
+  const start = async query => {
+    const [catalog, components] = await shipped;
+    const kind = ideaKind(query, catalog, components);
+    return pickStart(rankPages(query, catalog), kind)?.name ?? null;
+  };
+
+  it('starts a part from the page it names, else from the app shell', async () => {
+    expect(await start('an empty state for a settings page')).toBe('settings');
+    expect(await start('a date range picker')).toBeNull();
+    expect(await start('compact status pill with a tooltip')).toBeNull();
+  });
+
+  it('starts an edit of an existing page or part from the app shell', async () => {
+    for (const idea of [
+      'add a sparkline column to the existing incidents table',
+      'add a sort toggle to the existing reports dashboard',
+      'swap the existing banner for a toast',
+    ]) {
+      expect(await start(idea)).toBeNull();
+    }
+  });
+
+  it('starts a new page that mentions something existing from its template', async () => {
+    expect(await start('a new dashboard inspired by the existing one')).toBe(
+      'dashboard',
+    );
+    expect(await start('show existing users in a table page')).toMatch(
+      /^table/,
+    );
+  });
+
+  it('starts a new page that names an existing one from its template', async () => {
+    for (const idea of [
+      'a new dashboard based on the existing dashboard',
+      'a new dashboard like the existing dashboard',
+      'clone the existing dashboard as a new page',
+    ]) {
+      expect(await start(idea)).toBe('dashboard');
+    }
+  });
+
+  it('reads a bare "existing" phrase that names a page as the builder\'s page', async () => {
+    expect(
+      await start('existing reports dashboard with a date filter'),
+    ).toBeNull();
+  });
+
+  it('still starts a whole page from its template', async () => {
+    expect(
+      await start('saved drafts in a modal with resume and delete row actions'),
+    ).toBe('settings-dialog');
+  });
+});

package/api/component/_adapter.d.mts

@@ -68,6 +68,16 @@ export function requireCoreDir(cwd: string): string;
  * @returns {Promise<import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]>}
  */
 export function loadIntegrationsSafely(cwd: string): Promise<import("../../foundation/integrations/integrations.mjs").LoadedIntegration[]>;
+/**
+ * Read the exact installed version available to a package-qualified component
+ * selector. Legacy docs packages do not expose a reliable version here, so a
+ * version-qualified lookup never falls through to them.
+ * @param {string} coreDir
+ * @param {import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]} loadedIntegrations
+ * @param {string} packageName
+ * @returns {string|null}
+ */
+export function installedComponentPackageVersion(coreDir: string, loadedIntegrations: import("../../foundation/integrations/integrations.mjs").LoadedIntegration[], packageName: string): string | null;
 /**
  * Build the set of OWNER packages that provide a component with this name
  * across core + every loaded integration. This is what lets the CLI
@@ -180,6 +190,20 @@ export function scopeSubComponent(docs: LoadedComponentDoc, dirName: string, cor
     matchingComponent: any;
 } | null;
 export { CORE_PACKAGE };
+/**
+ * Internal ambiguity marker. Single-component callers still receive the same
+ * AstryxError code, message, and suggestions; batch callers can additionally
+ * project every installed candidate without parsing prose.
+ */
+export class ComponentAmbiguityError extends AstryxError {
+    /**
+     * @param {ComponentOwner[]} owners
+     * @param {string} dirName
+     */
+    constructor(owners: ComponentOwner[], dirName: string);
+    /** @type {import('./component.type.mjs').ComponentBatchCandidate[]} */
+    candidates: import("./component.type.mjs").ComponentBatchCandidate[];
+}
 /**
  * A loaded component doc. The shared validated loader accepts stamped and legacy
  * component docs; this loose view captures the fields the API reads across both.
@@ -258,3 +282,4 @@ export type ResolvedUnscopedDoc = {
     resolvedSourcePath: string | null;
 };
 import { CORE_PACKAGE } from '../../foundation/discovery/component-discovery.mjs';
+import { AstryxError } from '../error.mjs';

package/api/component/_adapter.mjs

@@ -18,6 +18,8 @@
  * deduped, so each leaf stays a thin projection.
  */
 
+import * as fs from 'node:fs';
+import * as path from 'node:path';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 import {
   findCoreDir,
@@ -146,6 +148,34 @@ function findLoadedIntegration(loadedIntegrations, packageName) {
   return loadedIntegrations.find(i => i.name === packageName) ?? null;
 }
 
+/**
+ * Read the exact installed version available to a package-qualified component
+ * selector. Legacy docs packages do not expose a reliable version here, so a
+ * version-qualified lookup never falls through to them.
+ * @param {string} coreDir
+ * @param {import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]} loadedIntegrations
+ * @param {string} packageName
+ * @returns {string|null}
+ */
+export function installedComponentPackageVersion(
+  coreDir,
+  loadedIntegrations,
+  packageName,
+) {
+  if (packageName === CORE_PACKAGE) {
+    try {
+      const pkg = JSON.parse(
+        fs.readFileSync(path.join(coreDir, 'package.json'), 'utf8'),
+      );
+      return typeof pkg.version === 'string' ? pkg.version : null;
+    } catch {
+      return null;
+    }
+  }
+  const integration = findLoadedIntegration(loadedIntegrations, packageName);
+  return typeof integration?.version === 'string' ? integration.version : null;
+}
+
 /**
  * Resolve an external package by name from the discovered externals list.
  * @param {string} packageName - e.g. '@acme/xds-widgets'
@@ -244,6 +274,34 @@ export function classifyScope(
   return {kind: 'legacy', ext};
 }
 
+/**
+ * Internal ambiguity marker. Single-component callers still receive the same
+ * AstryxError code, message, and suggestions; batch callers can additionally
+ * project every installed candidate without parsing prose.
+ */
+export class ComponentAmbiguityError extends AstryxError {
+  /** @type {import('./component.type.mjs').ComponentBatchCandidate[]} */
+  candidates;
+
+  /**
+   * @param {ComponentOwner[]} owners
+   * @param {string} dirName
+   */
+  constructor(owners, dirName) {
+    super(
+      `Component "${dirName}" is provided by multiple packages. Re-run with --package <pkg> to choose one.`,
+      owners.map(o => ({name: o.package, reason: 'provides this component'})),
+      ERROR_CODES.ERR_UNKNOWN_COMPONENT,
+    );
+    this.candidates = owners.map(owner => ({
+      package: owner.package,
+      component: dirName,
+      kind: 'component',
+      installed: true,
+    }));
+  }
+}
+
 /**
  * Refuse to guess when the name is owned by MORE THAN ONE package (core and/or
  * integrations) and the caller did not scope with --package. Legacy
@@ -254,11 +312,7 @@ export function classifyScope(
  */
 export function assertUnambiguousOwners(owners, dirName) {
   if (owners.length > 1) {
-    throw new AstryxError(
-      `Component "${dirName}" is provided by multiple packages. Re-run with --package <pkg> to choose one.`,
-      owners.map(o => ({name: o.package, reason: 'provides this component'})),
-      ERROR_CODES.ERR_UNKNOWN_COMPONENT,
-    );
+    throw new ComponentAmbiguityError(owners, dirName);
   }
 }
 

package/api/component/component.d.mts

@@ -2,7 +2,7 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * @param {string} [name]
+ * @param {string|string[]} [name]
  * @param {object} [options]
  * @param {string} [options.cwd]
  * @param {boolean} [options.list]
@@ -18,6 +18,7 @@
  * @param {boolean} [options.dense]
  * @returns {Promise<(
  *   import('./component.type.mjs').ComponentListResponse
+ *   | import('./component.type.mjs').ComponentBatchResponse
  *   | import('./component.type.mjs').ComponentDetailResponse
  *   | import('./component.type.mjs').ComponentDetailPropsResponse
  *   | import('./component.type.mjs').ComponentDetailSourceResponse
@@ -25,7 +26,7 @@
  *   | import('./component.type.mjs').ComponentDetailBlocksResponse
  * )>}
  */
-export function component(name?: string, options?: {
+export function component(name?: string | string[], options?: {
     cwd?: string | undefined;
     list?: boolean | undefined;
     category?: string | undefined;
@@ -38,4 +39,6 @@ export function component(name?: string, options?: {
     lang?: string | undefined;
     zh?: boolean | undefined;
     dense?: boolean | undefined;
-}): Promise<(import("./component.type.mjs").ComponentListResponse | import("./component.type.mjs").ComponentDetailResponse | import("./component.type.mjs").ComponentDetailPropsResponse | import("./component.type.mjs").ComponentDetailSourceResponse | import("./component.type.mjs").ComponentDetailShowcaseResponse | import("./component.type.mjs").ComponentDetailBlocksResponse)>;
+}): Promise<(import("./component.type.mjs").ComponentListResponse | import("./component.type.mjs").ComponentBatchResponse | import("./component.type.mjs").ComponentDetailResponse | import("./component.type.mjs").ComponentDetailPropsResponse | import("./component.type.mjs").ComponentDetailSourceResponse | import("./component.type.mjs").ComponentDetailShowcaseResponse | import("./component.type.mjs").ComponentDetailBlocksResponse)>;
+/** Maximum selectors accepted before any component resolution starts. */
+export const COMPONENT_BATCH_SELECTOR_LIMIT: 100;

package/api/component/component.doc.mjs

@@ -15,16 +15,16 @@ export const doc = {
   namespace: 'cli/api',
   displayName: 'component()',
   summary:
-    'Resolve a component by name, or list the catalog, with optional focused slices (props, source, showcase, blocks).',
+    'Resolve one or several components by name, or list the catalog, with optional focused slices (props, source, showcase, blocks).',
   description:
-    'Routes on its arguments: a name resolves that component across core and ' +
-    'integration packages and returns its authored ComponentDoc plus ownership ' +
-    'metadata; no name (or `list`/`category`) returns the catalog grouped by ' +
-    'category. Boolean flags narrow a single component to just its props, ' +
-    'source, showcase, or example blocks.',
+    'Routes on its arguments: one string resolves that component across core and ' +
+    'integration packages; an array returns one ordered result row per selector at ' +
+    'every array length; and no name returns the catalog grouped by category. ' +
+    'Boolean flags narrow each resolved component to just its props, source, ' +
+    'showcase, or example blocks.',
   importPath: '@astryxdesign/cli/api',
   signature:
-    'component(name?: string, options?: ComponentOptions): Promise<ComponentListResponse | ComponentDetailResponse | ComponentDetailPropsResponse | ComponentDetailSourceResponse | ComponentDetailShowcaseResponse | ComponentDetailBlocksResponse>',
+    'component(name?: string | string[], options?: ComponentOptions): Promise<ComponentListResponse | ComponentBatchResponse | ComponentDetailResponse | ComponentDetailPropsResponse | ComponentDetailSourceResponse | ComponentDetailShowcaseResponse | ComponentDetailBlocksResponse>',
   keywords: [
     'component',
     'components',
@@ -37,14 +37,15 @@ export const doc = {
   params: [
     {
       name: 'name',
-      type: 'string',
+      type: 'string | string[]',
       description:
-        "Component name to resolve (e.g. 'Button'). Omit to list the catalog.",
+        "Pass one selector string for the existing single-result response, or an array of at most 100 selectors for an ordered component.batch response. The limit counts duplicates in every projection mode. An array always requests a batch, including [] and ['Button']. Use 'Button', 'widgets/Button', '@acme/widgets/Button', or '@acme/widgets@1.2.3/Button'. A version applies to the package and must match the installed version. Omit the argument to list the catalog.",
     },
     {
       name: 'options.cwd',
       type: 'string',
       description: 'Directory to resolve @astryxdesign/core from.',
+      default: 'process.cwd()',
     },
     {
       name: 'options.list',
@@ -54,13 +55,14 @@ export const doc = {
     {
       name: 'options.category',
       type: 'string',
-      description: 'List only components in this category.',
+      description:
+        "List only the components in this group: a key of the unfiltered list (each component's group field), such as 'Layout' or 'Button'. It is not the category field of a component detail.",
     },
     {
       name: 'options.package',
       type: 'string',
       description:
-        "Scope lookup to a specific external package (e.g. '@acme/xds-widgets').",
+        "Scope lookup to a specific external package (e.g. '@acme/widgets').",
     },
     {
       name: 'options.props',
@@ -87,7 +89,8 @@ export const doc = {
       name: 'options.detail',
       type: "'full' | 'compact' | 'brief'",
       description: 'Detail level for list views.',
-      default: "'full' for a named component, 'brief' for list views",
+      default:
+        "'full' for a named component; 'brief' for lists (returned as data.detail: 'names')",
     },
     {
       name: 'options.lang',
@@ -110,7 +113,12 @@ export const doc = {
     {
       type: 'component.list',
       description:
-        "The catalog grouped by category. data.detail is the level ('names' | 'compact' | 'full') and data.components is the grouped map: names entries with name, package, and an optional canonical import for integration and legacy package components; brief entries; or full ComponentDoc entries.",
+        "The catalog grouped by component group. data.detail is the level ('names' | 'compact' | 'full') and data.components is the grouped map: names entries with name, package, and an optional canonical import for integration and legacy package components; brief entries; or full ComponentDoc entries.",
+    },
+    {
+      type: 'component.batch',
+      description:
+        'An explicit selector array returns one ordered receipt at every array length: count and one results row per selector, including duplicates. ComponentBatchResponse specializes the shared BatchResponse and BatchRow types. Each row carries selector and status (found, not_found, ambiguous, or error); found rows carry the single-selector result, ambiguous rows carry installed candidates ({package, component, kind, installed}), and failed rows carry code, error, and optional suggestions.',
     },
     {
       type: 'component.detail',
@@ -137,6 +145,10 @@ export const doc = {
     },
   ],
   throws: [
+    {
+      code: 'ERR_INVALID_ARGUMENT',
+      when: 'a selector array has more than 100 entries, a package-shaped selector has no component item, or its package conflicts with options.package',
+    },
     {
       code: 'ERR_INVALID_DETAIL',
       when: "options.detail is not 'full', 'compact', or 'brief'",
@@ -151,7 +163,7 @@ export const doc = {
     },
     {
       code: 'ERR_UNKNOWN_CATEGORY',
-      when: 'options.category is not a string or matches no known category',
+      when: 'options.category is not a string or matches no component group',
     },
     {
       code: 'ERR_UNKNOWN_COMPONENT',
@@ -159,12 +171,16 @@ export const doc = {
     },
     {
       code: 'ERR_UNKNOWN_PACKAGE',
-      when: 'options.package names a legacy external package that cannot be found',
+      when: 'options.package names a legacy external package that cannot be found, or a package-qualified selector requests a version that is not installed',
     },
     {
       code: 'ERR_NO_DOC',
       when: 'the resolved component has no .doc.mjs typed doc file',
     },
+    {
+      code: 'ERR_INVALID_DOC',
+      when: "the resolved component's .doc.mjs fails to load or validate",
+    },
     {
       code: 'ERR_NO_SOURCE',
       when: 'options.source is set but the component has no source file',
@@ -179,10 +195,14 @@ export const doc = {
       label: 'Look up a component',
       code: "const r = await component('Button');",
     },
+    {
+      label: 'Look up several components',
+      code: "await component(['Button', 'Badge']);",
+    },
     {label: 'Props only', code: "await component('Button', {props: true});"},
     {
-      label: 'Browse a category',
-      code: "await component(undefined, {category: 'Form', detail: 'compact'});",
+      label: 'Browse one group',
+      code: "await component(undefined, {category: 'Layout', detail: 'compact'});",
     },
   ],
   command: 'component',