@astryxdesign/cli 0.4.6 → 0.4.7-canary.019ae5a

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @xds/cli
 
+# 0.4.7
+
+---
+
 # 0.4.6
 
 #### New Features

package/README.md

@@ -383,51 +383,52 @@ Every response has a `type` discriminant. The full set is below (generated from
 
 <!-- BEGIN GENERATED: response-types -->
 
-| Type                        | What `data` carries                                                                                                                                                                                                                                 |
-| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `component.list`            | The component catalog grouped by category: `detail` (the level: names \| compact \| full) and `components`, the grouped map of names+package, brief entries, or a full ComponentDoc per entry.                                                      |
-| `component.detail`          | One component's authored ComponentDoc plus ownership metadata (owner package, import specifier, and whether source is available).                                                                                                                   |
-| `component.detail.props`    | Just one component's props table (ComponentPropDoc[]).                                                                                                                                                                                              |
-| `component.detail.source`   | One component's source file, as {component, source}.                                                                                                                                                                                                |
-| `component.detail.showcase` | One component's showcase example, as {component, aspectRatio, source}.                                                                                                                                                                              |
-| `component.detail.blocks`   | One component's example blocks, as {component, showcase, examples, related} of BlockEntry.                                                                                                                                                          |
-| `docs.list`                 | All reference-doc topics as DocsListEntry[] ({topic, description}), in discovery order.                                                                                                                                                             |
-| `docs.detail`               | One topic's full ReferenceDoc, with token-ref blocks inlined.                                                                                                                                                                                       |
-| `docs.detail.section`       | A single ReferenceSection of a topic: the first whose title contains the section query.                                                                                                                                                             |
-| `blog.list`                 | The feed URL plus every post parsed from the RSS feed, each with slug, title, description, date, type, authors, link, and plaintext URL.                                                                                                            |
-| `blog.detail`               | One post's metadata plus the feed URL and the post's full plaintext body.                                                                                                                                                                           |
-| `discover.list`             | The configured external packages (name, category, components, version, description); when empty it carries meta.configured to tell "nothing configured" from "nothing discovered".                                                                  |
-| `discover.detail`           | A single external package entry, for an @scope/name query.                                                                                                                                                                                          |
-| `discover.detail.doc`       | The validated ComponentDoc for one external component: an @scope/name/Component query, or a free-text term resolving to exactly one component.                                                                                                      |
-| `discover.search`           | The echoed query plus the matching {package, component} pairs, when a free-text term matches several components.                                                                                                                                    |
-| `search`                    | The echoed query plus a ranked SearchResultEntry[] (domain, name, score, reason, description, follow-up command, and import path where relevant).                                                                                                   |
-| `build.help`                | A marker (`playbook: true`) that the renderer expands into the how-to-build-a-page workflow; emitted when no query is given.                                                                                                                        |
-| `build.kit`                 | The grouped composition kit: echoed query, hasResults/directMatch flags, the closest page templates, drop-in block patterns, idea-specific components/hooks, and the always-on frame + foundation component-name arrays.                            |
-| `swizzle.list`              | The names of swizzlable components discoverable from cwd's @astryxdesign/core.                                                                                                                                                                      |
-| `swizzle.copy`              | An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and an optional maintainer note.                                                                      |
-| `template.list`             | Every discovered template (page + block); each entry carries id, name, description, kind, owning package, optional category and componentsUsed, and readiness flags.                                                                                |
-| `template.show`             | The resolved template's raw source plus its description, kind, and the component names it composes.                                                                                                                                                 |
-| `template.skeleton`         | A layout skeleton (structural tags with spatial annotations) plus the template's description and the components it composes.                                                                                                                        |
-| `template.copy`             | A scaffold receipt: template id, output directory, written file name, and file count.                                                                                                                                                               |
-| `template.cdn`              | A write receipt for the no-build-step CDN starter page: the path (relative to cwd), the Astryx version every CDN URL was pinned to, whether it was written, and the reason it was not — `exists` when a file was already there, which is a success. |
-| `hook.list`                 | The hook catalog grouped by category: `detail` (the level: names \| compact \| full) and `components`, the grouped map of hook names, brief entries, or a full HookDoc per entry.                                                                   |
-| `hook.detail`               | One hook's full authored HookDoc.                                                                                                                                                                                                                   |
-| `hook.detail.params`        | Just one hook's parameters table (HookParamDoc[]).                                                                                                                                                                                                  |
-| `theme.build`               | A theme build receipt: name, token- and component-override counts, output size, the written outputs {css, js, dts, and variantsDts when applicable}, and any validation warnings.                                                                   |
-| `theme.build.check`         | The --check receipt: theme name, an upToDate flag, the stale outputs (each {path, reason: missing \| outdated}), and the full list of checked paths. Writes nothing.                                                                                |
-| `theme.build.batch`         | Several themes built in one invocation: `count` plus one {file, receipt} per theme in argument order, where receipt is that theme's theme.build (or theme.build.check) envelope, or null when it produced no CSS.                                   |
-| `theme.list`                | Every bundled theme as a ThemeListEntry[]: each with slug, displayName, description, and a maintained flag.                                                                                                                                         |
-| `theme.add`                 | A scaffold receipt: resolved slug, displayName, maintained flag, outputDir (relative to cwd), the theme entry file, its exportName, and the files written.                                                                                          |
-| `theme.template`            | A write receipt for the annotated theme template: the path (relative to cwd), whether it was written, and the reason it was not — `exists` when a file was already there, which is a success.                                                       |
-| `upgrade.list`              | Every available codemod, oldest→newest, as {name, title, version, optional}; returned for --list without running anything.                                                                                                                          |
-| `upgrade.status`            | A short-circuit outcome with no codemods run (up_to_date, no_codemods, or config_fixable), each carrying the agent-docs summary.                                                                                                                    |
-| `upgrade.run`               | The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, and (apply mode) filesChanged, transformsApplied, and per-codemod errors.                                                                         |
-| `manifest`                  | The self-describing CLI capability manifest: name, version, apiVersion, global options, the command tree (args, options, json flag, response types, examples), the jsonSupported allowlist, and the flat responseTypes index.                       |
-| `doctor`                    | The health-check report: `checks` (each with id, label, status: pass \| warn \| fail \| info, a message, and a fix when not passing) plus a `summary` of counts per status.                                                                         |
-| `integration.validate`      | The validation result: the package name and version (both null when no local manifest is found) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning \| error, message}.                                                            |
-| `layout.expand`             | The expansion: parsed form, generated TSX code, componentsUsed, states (count of useState hooks scaffolded), todos, blocksReferenced (each {name, mode}), warnings, and written (the output path, or null when nothing was written).                |
-| `layout.check`              | The validation result: a valid flag, the detected form, errors (each with line/col, message, formatted text, and suggestions), warnings, and the expression re-printed in both canonical surfaces (compact and outline).                            |
-| `layout.grammar`            | The XLE/XLO grammar cheatsheet: a text field with the full reference plus an aliases map (short name → canonical component) generated from this install's registry.                                                                                 |
+| Type                        | What `data` carries                                                                                                                                                                                                                                |
+| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `component.list`            | The component catalog grouped by category: `detail` (the level: names \| compact \| full) and `components`, the grouped map of names+package, brief entries, or a full ComponentDoc per entry.                                                     |
+| `component.detail`          | One component's authored ComponentDoc plus ownership metadata (owner package, import specifier, and whether source is available).                                                                                                                  |
+| `component.detail.props`    | Just one component's props table (ComponentPropDoc[]).                                                                                                                                                                                             |
+| `component.detail.source`   | One component's source file, as {component, source}.                                                                                                                                                                                               |
+| `component.detail.showcase` | One component's showcase example, as {component, aspectRatio, source}.                                                                                                                                                                             |
+| `component.detail.blocks`   | One component's example blocks, as {component, showcase, examples, related} of BlockEntry.                                                                                                                                                         |
+| `docs.list`                 | All reference-doc topics as DocsListEntry[] ({topic, description}), in discovery order.                                                                                                                                                            |
+| `docs.detail`               | One topic's full ReferenceDoc, with token-ref blocks inlined.                                                                                                                                                                                      |
+| `docs.detail.section`       | A single ReferenceSection of a topic: the first whose title contains the section query.                                                                                                                                                            |
+| `blog.list`                 | The feed URL plus every post parsed from the RSS feed, each with slug, title, description, date, type, authors, link, and plaintext URL.                                                                                                           |
+| `blog.detail`               | One post's metadata plus the feed URL and the post's full plaintext body.                                                                                                                                                                          |
+| `discover.list`             | The configured external packages (name, category, components, version, description); when empty it carries meta.configured to tell "nothing configured" from "nothing discovered".                                                                 |
+| `discover.detail`           | A single external package entry, for an @scope/name query.                                                                                                                                                                                         |
+| `discover.detail.doc`       | The validated ComponentDoc for one external component: an @scope/name/Component query, or a free-text term resolving to exactly one component.                                                                                                     |
+| `discover.search`           | The echoed query plus the matching {package, component} pairs, when a free-text term matches several components.                                                                                                                                   |
+| `search`                    | The echoed query plus a ranked SearchResultEntry[] (domain, name, score, reason, description, follow-up command, and import path where relevant).                                                                                                  |
+| `build.help`                | A marker (`playbook: true`) that the renderer expands into the how-to-build-a-page workflow; emitted when no query is given.                                                                                                                       |
+| `build.kit`                 | The grouped composition kit: echoed query, hasResults/directMatch flags, the closest page templates, drop-in block patterns, idea-specific components/hooks, and the always-on frame + foundation component-name arrays.                           |
+| `swizzle.list`              | The names of swizzlable components discoverable from cwd's @astryxdesign/core.                                                                                                                                                                     |
+| `swizzle.copy`              | An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and an optional maintainer note.                                                                     |
+| `template.list`             | Every discovered template (page + block); each entry carries id, name, description, kind, owning package, optional category and componentsUsed, and readiness flags.                                                                               |
+| `template.show`             | The resolved template's raw source plus its description, kind, and the component names it composes.                                                                                                                                                |
+| `template.skeleton`         | A layout skeleton (structural tags with spatial annotations) plus the template's description and the components it composes.                                                                                                                       |
+| `template.copy`             | A scaffold receipt: template id, output directory, written file name, and file count.                                                                                                                                                              |
+| `template.cdn`              | A write receipt for the no-build-step CDN starter page: the path (relative to cwd), the Astryx version every CDN URL was pinned to, whether it was written, and the reason it was not. `exists` when a file was already there, which is a success. |
+| `hook.list`                 | The hook catalog grouped by category: `detail` (the level: names \| compact \| full) and `components`, the grouped map of hook names, brief entries, or a full HookDoc per entry.                                                                  |
+| `hook.detail`               | One hook's full authored HookDoc.                                                                                                                                                                                                                  |
+| `hook.detail.params`        | Just one hook's parameters table (HookParamDoc[]).                                                                                                                                                                                                 |
+| `theme.build`               | A theme build receipt: name, token- and component-override counts, output size, the written outputs {css, js, dts, and variantsDts when applicable}, and any validation warnings.                                                                  |
+| `theme.build.check`         | The --check receipt: theme name, an upToDate flag, the stale outputs (each {path, reason: missing \| outdated}), and the full list of checked paths. Writes nothing.                                                                               |
+| `theme.build.batch`         | Several themes built in one invocation: `count` plus one {file, receipt} per theme in argument order, where receipt is that theme's theme.build (or theme.build.check) envelope, or null when it produced no CSS.                                  |
+| `theme.list`                | Every bundled theme as a ThemeListEntry[]: each with slug, displayName, description, and a maintained flag.                                                                                                                                        |
+| `theme.add`                 | A scaffold receipt: resolved slug, displayName, maintained flag, outputDir (relative to cwd), the theme entry file, its exportName, and the files written.                                                                                         |
+| `theme.template`            | A write receipt for the annotated theme template: the path (relative to cwd), whether it was written, and the reason it was not. `exists` when a file was already there, which is a success.                                                       |
+| `theme.targets`             | The whole themeable surface: the echoed filter, the component count, and one entry per theming target — {key, className, component, props, states}, where props and states are its legal override keys.                                            |
+| `upgrade.list`              | Every available codemod, oldest→newest, as {name, title, version, optional}; returned for --list without running anything.                                                                                                                         |
+| `upgrade.status`            | A short-circuit outcome with no codemods run (up_to_date, no_codemods, or config_fixable), each carrying the agent-docs summary.                                                                                                                   |
+| `upgrade.run`               | The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, and (apply mode) filesChanged, transformsApplied, and per-codemod errors.                                                                        |
+| `manifest`                  | The self-describing CLI capability manifest: name, version, apiVersion, global options, the command tree (args, options, json flag, response types, examples), the jsonSupported allowlist, and the flat responseTypes index.                      |
+| `doctor`                    | The health-check report: `checks` (each with id, label, status: pass \| warn \| fail \| info, a message, and a fix when not passing) plus a `summary` of counts per status.                                                                        |
+| `integration.validate`      | The validation result: the package name and version (both null when no local manifest is found) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning \| error, message}.                                                           |
+| `layout.expand`             | The expansion: parsed form, generated TSX code, componentsUsed, states (count of useState hooks scaffolded), todos, blocksReferenced (each {name, mode}), warnings, and written (the output path, or null when nothing was written).               |
+| `layout.check`              | The validation result: a valid flag, the detected form, errors (each with line/col, message, formatted text, and suggestions), warnings, and the expression re-printed in both canonical surfaces (compact and outline).                           |
+| `layout.grammar`            | The XLE/XLO grammar cheatsheet: a text field with the full reference plus an aliases map (short name → canonical component) generated from this install's registry.                                                                                |
 
 <!-- END GENERATED: response-types -->
 <!-- Generated by scripts/generate-cli-readme.mjs from the response-types EnumDoc. Run `pnpm -F @astryxdesign/cli readme`. -->
@@ -580,12 +581,13 @@ export default {
 };
 ```
 
-| Field        | Type     | Purpose                                                               |
-| ------------ | -------- | --------------------------------------------------------------------- |
-| `components` | `string` | Directory holding the package's components and their `.doc.*` files.  |
-| `templates`  | `string` | Directory holding the package's page/block templates.                 |
-| `codemods`   | `string` | Directory holding upgrade codemods run by `astryx upgrade`.           |
-| `issuesUrl`  | `string` | Where "report an issue" links for this package's contributions point. |
+| Field        | Type     | Purpose                                                                           |
+| ------------ | -------- | --------------------------------------------------------------------------------- |
+| `components` | `string` | Directory holding the package's components and their `.doc.*` files.              |
+| `templates`  | `string` | Directory holding the package's page/block templates.                             |
+| `codemods`   | `string` | Directory holding upgrade codemods run by `astryx upgrade`.                       |
+| `docs`       | `string` | Directory of reference docs; each `{topic}.doc.*` becomes a topic the CLI serves. |
+| `issuesUrl`  | `string` | Where "report an issue" links for this package's contributions point.             |
 
 Every field is optional; declare only the roots the package ships. There is no
 factory: write a plain object, and annotate it with the `AstryxIntegration` type

package/api/docs/docs.doc.mjs

@@ -19,8 +19,8 @@ export const doc = {
     'returns that full ReferenceDoc (with token-ref blocks inlined); a topic ' +
     'plus a section returns the first section whose title contains the ' +
     '(case-insensitive) query. The topic set is the CLI\'s own docs plus the ' +
-    'ones the project\'s configured integrations contribute — including any ' +
-    'topic an integration replaces or extends — so it depends on the cwd. ' +
+    'ones the project\'s configured integrations contribute, including any ' +
+    'topic an integration replaces or extends, so it depends on the cwd. ' +
     'Overlay options select localized or dense variants.',
   importPath: '@astryxdesign/cli/api',
   signature:

package/api/index.d.mts

@@ -31,6 +31,6 @@ export * from "./doctor/doctor.type.mjs";
 export * from "./layout/layout.type.mjs";
 export * from "./integration/validate-integration.type.mjs";
 export type Logger = import("./logger.mjs").Logger;
-export { themeBuild, themeAdd, themeList, listThemes } from "./theme/theme.mjs";
+export { themeBuild, themeAdd, themeList, themeTargets, listThemes } from "./theme/theme.mjs";
 export { layoutExpand, layoutCheck, layoutGrammar } from "./layout/layout.mjs";
 export { validateIntegration, summarizeIssues } from "./integration/validate-integration.mjs";

package/api/index.mjs

@@ -25,7 +25,7 @@ export {docs} from './docs/docs.mjs';
 export {blog} from './blog/blog.mjs';
 export {discover} from './discover/discover.mjs';
 export {template} from './template/template.mjs';
-export {themeBuild, themeAdd, themeList, listThemes} from './theme/theme.mjs';
+export {themeBuild, themeAdd, themeList, themeTargets, listThemes} from './theme/theme.mjs';
 export {hook} from './hook/hook.mjs';
 export {search} from './search/search.mjs';
 export {build} from './build/build.mjs';

package/api/search/search.mjs

@@ -34,10 +34,12 @@ import {pathToFileURL} from 'node:url';
 import {findCoreDir} from '../../foundation/fs/paths.mjs';
 import {
   discoverComponents,
+  discoverIntegrationComponents,
   findComponentReadme,
   resolveImportPath,
 } from '../../foundation/discovery/component-discovery.mjs';
 import {discoverHooks, findHookDoc} from '../../foundation/discovery/hook-discovery.mjs';
+import {loadIntegrationsSafely} from '../component/_adapter.mjs';
 import {levenshteinDistance} from '../../foundation/text/string-utils.mjs';
 import {discoverTemplates, extractComponents} from '../template/template.mjs';
 import {loadDocsCatalog, loadTopicDoc} from '../docs/_adapter.mjs';
@@ -350,12 +352,12 @@ async function loadModuleDoc(docPath, exportName = 'docs') {
 }
 
 /**
- * Build component candidates: name + keywords + usage/description from the
- * component's .doc.mjs.
+ * Build component candidates from core's own tree: name + keywords +
+ * usage/description from the component's .doc.mjs.
  * @param {string} coreDir
  * @returns {Promise<Candidate[]>}
  */
-async function gatherComponents(coreDir) {
+async function gatherCoreComponents(coreDir) {
   const grouped = discoverComponents(coreDir);
   const names = Object.values(grouped).flat();
   /** @type {Candidate[]} */
@@ -383,6 +385,50 @@ async function gatherComponents(coreDir) {
   return candidates;
 }
 
+/**
+ * Build component candidates contributed by the project's configured
+ * integrations (astryx.config's `integrations`): name + keywords +
+ * usage/description from each component's .doc.mjs, same as core. Without
+ * this, an integration component is invisible to `search`/`build` even
+ * though `component --list`/`component <Name>` already resolve it — the two
+ * discovery paths silently disagreed.
+ * @param {string} cwd
+ * @returns {Promise<Candidate[]>}
+ */
+async function gatherIntegrationComponents(cwd) {
+  const loadedIntegrations = await loadIntegrationsSafely(cwd);
+  /** @type {Candidate[]} */
+  const candidates = [];
+  for (const integration of loadedIntegrations) {
+    for (const rec of discoverIntegrationComponents(integration)) {
+      const doc = await loadModuleDoc(rec.docPath);
+      candidates.push({
+        domain: 'component',
+        name: rec.name,
+        keywords: doc && Array.isArray(doc.keywords) ? doc.keywords : [],
+        description: doc ? doc.usage?.description || doc.description || '' : '',
+        _import: rec.package,
+      });
+    }
+  }
+  return candidates;
+}
+
+/**
+ * Build component candidates: core's own tree plus every configured
+ * integration's components.
+ * @param {string} coreDir
+ * @param {string} cwd
+ * @returns {Promise<Candidate[]>}
+ */
+async function gatherComponents(coreDir, cwd) {
+  const [core, integrations] = await Promise.all([
+    gatherCoreComponents(coreDir),
+    gatherIntegrationComponents(cwd),
+  ]);
+  return [...core, ...integrations];
+}
+
 /**
  * Build hook candidates: name + keywords + usage/description from the hook's
  * .doc.mjs.
@@ -611,7 +657,7 @@ export async function search(query, options = {}) {
   /** @param {string} d */
   const wants = d => !type || type === d;
   const [components, hooks, docTopics, templates] = await Promise.all([
-    wants('component') ? gatherComponents(coreDir) : [],
+    wants('component') ? gatherComponents(coreDir, cwd) : [],
     wants('hook') ? gatherHooks(coreDir) : [],
     wants('doc') ? gatherDocs(cwd) : [],
     wants('template') ? gatherTemplates(cwd) : [],

package/api/search/search.test.mjs

@@ -10,9 +10,17 @@
  * `limit`, an empty query, and a bad `--type` all throw AstryxError with the
  * ERR_INVALID_ARGUMENT code, so a direct `@astryxdesign/cli/api` caller gets the
  * same contract as `astryx search` on the command line.
+ *
+ * The last describe block covers integration-contributed components, using the
+ * same temp-consumer harness as template-integration.test.mjs. Before this,
+ * `search`/`build` only ever scanned @astryxdesign/core — an integration's own
+ * components were invisible to both, even though `component --list` and
+ * `component <Name>` already resolved them. The two discovery paths silently
+ * disagreed.
  */
 
 import {describe, it, expect} from 'vitest';
+import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {search, SEARCH_DOMAINS} from './search.mjs';
@@ -92,3 +100,66 @@ describe('search leaf — limit validation (API matches the CLI contract)', () =
     });
   }, SLOW);
 });
+
+describe('search leaf — integration components', () => {
+  /**
+   * A minimal consumer project: a stub `@astryxdesign/core` (so `findCoreDir`
+   * resolves without needing the real package) plus an installed
+   * `@acme/widgets` integration that contributes one component.
+   */
+  function makeConsumerWithIntegrationComponent() {
+    const dir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-search-it-'));
+    fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({name: 'consumer'}));
+    fs.writeFileSync(
+      path.join(dir, 'astryx.config.mjs'),
+      `export default { integrations: ['@acme/widgets'] };\n`,
+    );
+
+    // Stub core: just needs to exist with an (empty) src/ so discoverComponents
+    // doesn't throw. Its own component list is irrelevant to this test.
+    const coreDir = path.join(dir, 'node_modules', '@astryxdesign', 'core');
+    fs.mkdirSync(path.join(coreDir, 'src'), {recursive: true});
+
+    const widgetsDir = path.join(dir, 'node_modules', '@acme', 'widgets');
+    fs.mkdirSync(path.join(widgetsDir, 'components'), {recursive: true});
+    fs.writeFileSync(
+      path.join(widgetsDir, 'package.json'),
+      JSON.stringify({name: '@acme/widgets', version: '1.0.0'}),
+    );
+    fs.writeFileSync(
+      path.join(widgetsDir, 'astryx.integration.mjs'),
+      `export default { components: './components' };\n`,
+    );
+    fs.writeFileSync(
+      path.join(widgetsDir, 'components', 'FancyGizmo.doc.mjs'),
+      `export const docs = {
+        name: 'FancyGizmo',
+        keywords: ['gizmo', 'widget'],
+        usage: {description: 'A fancy gizmo widget.'},
+      };\n`,
+    );
+
+    return dir;
+  }
+
+  it('includes a component contributed by a configured integration', async () => {
+    const dir = makeConsumerWithIntegrationComponent();
+    try {
+      const r = await search('gizmo', {cwd: dir, type: 'component'});
+      expect(r.data.results.some(x => x.name === 'FancyGizmo')).toBe(true);
+    } finally {
+      fs.rmSync(dir, {recursive: true, force: true});
+    }
+  }, SLOW);
+
+  it('reports the contributing package as the import hint', async () => {
+    const dir = makeConsumerWithIntegrationComponent();
+    try {
+      const r = await search('FancyGizmo', {cwd: dir, type: 'component'});
+      const hit = r.data.results.find(x => x.name === 'FancyGizmo');
+      expect(hit?.import).toBe('@acme/widgets');
+    } finally {
+      fs.rmSync(dir, {recursive: true, force: true});
+    }
+  }, SLOW);
+});

package/api/template/template.doc.mjs

@@ -104,7 +104,7 @@ export const doc = {
     {
       type: 'template.skeleton',
       description:
-        "A layout skeleton — structural tags with spatial annotations — plus the template's description and the components it composes.",
+        "A layout skeleton (structural tags with spatial annotations) plus the template's description and the components it composes.",
     },
     {
       type: 'template.copy',
@@ -114,7 +114,7 @@ export const doc = {
     {
       type: 'template.cdn',
       description:
-        'A write receipt for the CDN starter page: the path (relative to cwd), the Astryx version every CDN URL was pinned to, whether it was written, and the reason it was not — `exists` when a file was already there, which is a success.',
+        'A write receipt for the CDN starter page: the path (relative to cwd), the Astryx version every CDN URL was pinned to, whether it was written, and the reason it was not. `exists` when a file was already there, which is a success.',
     },
   ],
   throws: [

package/api/theme/build/build.mjs

@@ -43,6 +43,10 @@ import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {AstryxError} from '../../error.mjs';
 import {logger} from '../../logger.mjs';
 import {loadComponentDoc} from '../../../foundation/discovery/component-loader.mjs';
+import {
+  collectThemingTargets,
+  targetsByKey,
+} from '../../../foundation/discovery/theming-targets.mjs';
 import {
   collectUnloadedFonts,
   formatFontLoadingHelp,
@@ -882,6 +886,9 @@ ${iconType}export declare const ${toIdentifier(themeDef.name)}Theme: DefinedThem
  * Returns null when docs are unavailable so validation can skip unknown-key
  * warnings rather than guessing from a second registry.
  *
+ * Shares its enumeration with `theme targets`, so what a theme author can list
+ * is exactly what this validator accepts.
+ *
  * @returns {Promise<Record<string, string[]> | null>}
  */
 async function loadKnownComponents() {
@@ -889,44 +896,7 @@ async function loadKnownComponents() {
   const coreSrc = coreRoot ? path.join(coreRoot, 'src') : null;
   if (!coreSrc || !fs.existsSync(coreSrc)) return null;
 
-  /** @type {Record<string, string[]>} */
-  const targets = {};
-
-  /** @param {string} dir */
-  async function scan(dir) {
-    const entries = fs.readdirSync(dir, {withFileTypes: true});
-    for (const entry of entries) {
-      const full = path.join(dir, entry.name);
-      if (entry.isDirectory()) {
-        if (entry.name === 'node_modules' || entry.name === '__tests__') continue;
-        await scan(full);
-        continue;
-      }
-      if (!entry.name.endsWith('.doc.mjs')) continue;
-
-      /** @type {any} */
-      let doc;
-      try {
-        doc = await loadComponentDoc(full);
-      } catch {
-        continue;
-      }
-
-      for (const target of doc?.theming?.targets || []) {
-        const className = target?.className;
-        if (typeof className !== 'string') continue;
-        const key = className.replace(/^astryx-/, '');
-        if (!key) continue;
-        const props = [target.visualProps, target.states]
-          .filter(list => Array.isArray(list))
-          .flat()
-          .filter((/** @type {unknown} */ p) => typeof p === 'string');
-        targets[key] = [...new Set([...(targets[key] || []), ...props])];
-      }
-    }
-  }
-
-  await scan(coreSrc);
+  const targets = targetsByKey(await collectThemingTargets(coreSrc));
   return Object.keys(targets).length > 0 ? targets : null;
 }
 

package/api/theme/targets/targets.d.mts

@@ -0,0 +1,18 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * List every component theming target — the `defineTheme` `components` keys,
+ * with the props and states each one accepts.
+ *
+ * A filter naming a component exactly wins over a substring search, so
+ * `theme targets Button` is Button's own set (what `astryx component Button`
+ * prints) rather than every key that happens to contain "button".
+ *
+ * @param {string} [filter] - component name, or a substring of a target key
+ * @param {{cwd?: string}} [ctx]
+ * @returns {Promise<import('../theme.type.mjs').ThemeTargetsResponse>}
+ */
+export function themeTargets(filter?: string, { cwd }?: {
+    cwd?: string;
+}): Promise<import("../theme.type.mjs").ThemeTargetsResponse>;

package/api/theme/targets/targets.mjs

@@ -0,0 +1,87 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx theme targets` leaf — the whole themeable surface, enumerated.
+ *
+ * @input  a cwd (to resolve the project's `@astryxdesign/core`) and an optional
+ *         component/key filter
+ * @output the `theme.targets` envelope: one row per theming target
+ * @position api/theme/targets — projection over
+ *           foundation/discovery/theming-targets.mjs, the same component docs
+ *           `astryx component <Name>` prints its Theming table from.
+ */
+
+import * as path from 'node:path';
+import {findCoreDir} from '../../../foundation/fs/paths.mjs';
+import {collectThemingTargets} from '../../../foundation/discovery/theming-targets.mjs';
+import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
+import {AstryxError} from '../../error.mjs';
+
+/**
+ * Whether a target matches the caller's filter loosely: any target whose key,
+ * class, or component contains it — so `theme targets thumb` finds the switch
+ * thumb without knowing which component owns it.
+ * @param {import('../../../foundation/discovery/theming-targets.mjs').ThemingTarget} target
+ * @param {string} filter - already lowercased
+ * @returns {boolean}
+ */
+function matchesLoosely(target, filter) {
+  return (
+    target.key.toLowerCase().includes(filter) ||
+    target.className.toLowerCase().includes(filter) ||
+    target.component.toLowerCase().includes(filter)
+  );
+}
+
+/**
+ * List every component theming target — the `defineTheme` `components` keys,
+ * with the props and states each one accepts.
+ *
+ * A filter naming a component exactly wins over a substring search, so
+ * `theme targets Button` is Button's own set (what `astryx component Button`
+ * prints) rather than every key that happens to contain "button".
+ *
+ * @param {string} [filter] - component name, or a substring of a target key
+ * @param {{cwd?: string}} [ctx]
+ * @returns {Promise<import('../theme.type.mjs').ThemeTargetsResponse>}
+ */
+export async function themeTargets(filter, {cwd = process.cwd()} = {}) {
+  const coreDir = findCoreDir(cwd);
+  if (!coreDir) {
+    throw new AstryxError(
+      'Could not find @astryxdesign/core package',
+      undefined,
+      ERROR_CODES.ERR_CORE_NOT_FOUND,
+    );
+  }
+
+  const all = await collectThemingTargets(path.join(coreDir, 'src'));
+  const needle = filter ? String(filter).toLowerCase() : null;
+  let targets = all;
+  if (needle) {
+    const named = all.filter(t => t.component.toLowerCase() === needle);
+    targets = named.length > 0 ? named : all.filter(t => matchesLoosely(t, needle));
+  }
+
+  if (needle && targets.length === 0) {
+    const near = [...new Set(all.map(t => t.component))]
+      .filter(name => name.toLowerCase().startsWith(needle.slice(0, 3)))
+      .sort()
+      .slice(0, 5)
+      .map(name => ({name, reason: 'has theming targets'}));
+    throw new AstryxError(
+      `No theming target matches "${filter}". Run \`theme targets\` with no filter for the whole list.`,
+      near.length > 0 ? near : undefined,
+      ERROR_CODES.ERR_UNKNOWN_COMPONENT,
+    );
+  }
+
+  return {
+    type: 'theme.targets',
+    data: {
+      filter: filter ?? null,
+      componentCount: new Set(targets.map(t => t.component)).size,
+      targets,
+    },
+  };
+}

package/api/theme/targets/targets.test.mjs

@@ -0,0 +1,65 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Direct-API tests for the `theme targets` leaf. Runs against the real
+ * core docs, so it doubles as a guard that the themeable surface stays
+ * readable and shaped as `theme.targets` promises.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {themeTargets} from './targets.mjs';
+
+describe('themeTargets (api/theme/targets)', () => {
+  it('returns a theme.targets envelope covering the whole surface', async () => {
+    const result = await themeTargets();
+    expect(result.type).toBe('theme.targets');
+    expect(result.data.filter).toBeNull();
+    expect(result.data.targets.length).toBeGreaterThan(100);
+    expect(result.data.componentCount).toBeGreaterThan(50);
+    for (const t of result.data.targets) {
+      expect(Object.keys(t).sort()).toEqual([
+        'className',
+        'component',
+        'key',
+        'props',
+        'states',
+      ]);
+    }
+  }, 60_000);
+
+  it('scopes to one component by name', async () => {
+    const {data} = await themeTargets('Switch');
+    expect(data.filter).toBe('Switch');
+    expect(data.componentCount).toBe(1);
+    expect(data.targets.map(t => t.key)).toEqual([
+      'switch',
+      'switch-field',
+      'switch-thumb',
+    ]);
+  }, 60_000);
+
+  // Half the system's keys contain "button" (chat-send-button, toggle-button,
+  // …). A component name has to mean the component, or `theme targets Button`
+  // answers a different question than `component Button` and the two views
+  // look like they disagree.
+  it('prefers an exact component name over a substring match', async () => {
+    const {data} = await themeTargets('Button');
+    expect(data.targets.map(t => t.key)).toEqual(['button']);
+  }, 60_000);
+
+  // This command answers "which theme slot paints the switch thumb?" — a
+  // question you can only ask by the part, not the component, until you
+  // already know which component owns it.
+  it('searches keys by substring, across components', async () => {
+    const {data} = await themeTargets('thumb');
+    expect(data.componentCount).toBeGreaterThan(1);
+    expect(data.targets.map(t => t.key)).toContain('switch-thumb');
+    for (const t of data.targets) expect(t.key).toContain('thumb');
+  }, 60_000);
+
+  it('rejects a filter that matches nothing, with components to try', async () => {
+    await expect(themeTargets('nosuchthing')).rejects.toMatchObject({
+      code: 'ERR_UNKNOWN_COMPONENT',
+    });
+  }, 60_000);
+});