@astryxdesign/cli 0.4.7 → 0.5.0-canary.009bcb3

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # @xds/cli
 
+# 0.5.0
+
+#### Breaking Changes
+
+- Banner: the collapse axis moves onto one `collapsible` prop, and content can opt out of collapsing (#5255)
+  Banner inferred its disclosure from its content: any `children` got a chevron in the header and were hidden until it was pressed. There was no way to show content without a toggle — the case a banner most often wants, a list of the three fields that failed validation — and `defaultIsExpanded` was the only knob, with no controlled mode.
+
+  The whole axis is now one `boolean | CollapsibleConfig` prop, following the boolean-or-config convention `SideNav.collapsible` set, and backed by the shared `useCollapsible` hook rather than Banner's own state:
+
+  ```tsx
+  <Banner status="error" title="3 fields need attention">…</Banner>  // unchanged: collapsible, starts closed
+  <Banner collapsible={false}>…</Banner>                             // new: always visible, no toggle
+  <Banner collapsible={{defaultIsOpen: true}}>…</Banner>             // replaces defaultIsExpanded
+  <Banner collapsible={{isOpen, onOpenChange}}>…</Banner>            // new: controlled
+  ```
+
+  **The default is unchanged** — a banner that never mentioned `defaultIsExpanded` behaves exactly as it did. The breaking part is the prop itself: `defaultIsExpanded` is removed in favour of the config, which is a type error at every JSX call site that names it.
+
+  **Codemod:** `npx astryx upgrade --codemod banner-collapsible-content`
+
+  It rewrites `defaultIsExpanded` to `collapsible={{defaultIsOpen: true}}` and drops `defaultIsExpanded={false}`, which is now the default. Banners that never set the prop are left alone.
+
+  **One case the codemod and the compiler both miss: a spread.** `defaultIsExpanded` inside a props object is out of the transform's scope. A props object in a typed position still fails to compile — but an inferred one that is spread, `<Banner {...args} />`, does not, because TypeScript does not excess-property-check a spread. The prop then falls through to the DOM and the banner quietly starts collapsed. **Grep for `defaultIsExpanded` after running the codemod** and migrate any spread sites by hand.
+
+#### New Components
+
+- Promote `Stepper` and `Step` from the canary-only Lab package to Core. The stable package now ships their existing horizontal/vertical layouts, separated and on-track indicators, semantic status, density, and non-linear navigation, plus Core documentation and rendered examples. The default `aria-label` is now localized.
+  Advancing one step now animates the connector. Every connector the four layouts draw — the separated bars and the on-track segments alike — grows its accent fill out of the segment's leading edge instead of swapping a background color, so moving forward reads as progress travelling the track. That one gesture is the only thing that animates: going back, jumping forward by more than one step, and mounting mid-flow all apply at once, as does any change under `prefers-reduced-motion`. Retreats are deliberately instant — run in reverse the same transition ends on a shrinking stub of accent, and a remnant still on the track reads as unfinished where the identical curve growing forward reads as arrived — and multi-step jumps are instant because a jump is a navigation rather than a progression, so sweeping a front across the crossed segments only makes the user sit out a journey they asked to skip. Where one span is drawn by several segments (the on-track layouts split a span between two steps, three when a content slot sits between them) the segments take abutting slices of the span's time and run linearly, so the fill reads as one line growing at a constant speed rather than pieces lighting in turn.
+
+  Five visual fixes land with the promotion. Horizontal steps now divide the track evenly instead of sizing to their own labels, so every progress segment is the same width regardless of how long a step is named. Number indicators shrink from 20px to 16px to match the check, ring, and custom-icon indicators, so a step swapping its number for a check as it completes no longer nudges the label beside it. A step description now occupies a 16px box rather than a 24px one — it previously inherited the page's line box instead of applying its own leading, which opened an 8px gap under the label. A step's content slot now starts flush with the label above it at every density: the slot renders outside the density-padded label area, so it was hanging one pad short of it. And a vertical on-track step carrying content keeps its connector unbroken — the content renders below the row that draws the line, so the track used to split open around any step with content (#5201).
+
+#### New Features
+
+- AspectRatio: emit `ratio` as a class-level declaration instead of a hard inline style, so the ratio can be overridden responsively: StyleX consumers pass an `aspect-ratio` rule via `xstyle` (including under `@media`/`@container` conditions), and plain-CSS/Tailwind consumers override `aspect-ratio` from their own unlayered rules, which beat the `astryx-base` cascade layer regardless of specificity. The mixed-gallery template's hero now switches 3:1 to 3:2 when the grid stacks with a one-line override on a single element, replacing the duplicated hero markup the fixed inline ratio previously forced (#3883, closes #2798)
+- CLI: `astryx theme targets` lists every component theming target — the `defineTheme` key, the class it paints, and the props and states it accepts — for one component or the whole system, with `--json` for lint and audit scripts. `astryx theme --help` now points at component overrides instead of reading as a build-tool menu. The listing and `theme build`'s override validation share one enumeration of the component docs, so neither can drift from the components (#5115).
+
+#### Fixes
+
+- neutral theme: darken the light-mode error red from `#e33f4a` to `#c9303a` so the filled `Badge variant="error"` label clears WCAG 2.1 AA. White on `#e33f4a` is 4.14:1 and the badge label is 12px/weight 500, so the 4.5:1 normal-text threshold applies rather than the 3:1 large-text allowance; `#c9303a` gives 5.29:1 while holding the hue (OKLCH H 21.9 -> 22.8, C 0.200 -> 0.189). StatusDot and the ProgressBar `--color-error` rebinding move with it — both are documented as tracking the badge fill so the dot and its badge read as one status language. Dark mode is untouched (dark text on `#ff705d`, 6.60:1). Adds `scripts/check-badge-contrast.test.mjs`, which resolves every theme's badge label/fill pair through `light-dark()`, `var()` indirection and alpha compositing, and holds all of them to 4.5:1 (#4446).
+- Unified search and build now include components contributed by integrations, so a component registered through an integration is findable and buildable alongside the built-in set instead of silently missing from both (#5259).
+- Table - Grouped page template: wrap the rows in `TableBody`
+  The template rendered `<TableRow>` straight into `<Table>`, so the emitted DOM was `<table><tr>`. `<table>` cannot contain a row directly: the HTML parser inserts an implied `<tbody>` when it parses server-rendered markup and React does not when it renders on the client, so anyone who copied the template into an app as a server-rendered page inherited a hydration mismatch in their own app. Client-only the DOM is still invalid — nothing reparents the rows, so the table ends up with `<tr>` children and no `<tbody>` at all, and any CSS or query aimed at `tbody` silently misses.
+
+  The rows now sit in `<TableBody>`, the same element the data-driven `data={...}` path renders, so styling, dividers, and column widths are unchanged (#5278).
+
+#### Other Changes
+
+- Public component theming vars are enumerable, and guarded against being documented but unsettable
+  `collectThemingVars` joins `collectThemingTargets` as part of the one enumeration the theming surface is read from. Two guards ride on it: a documented public var no component reads compiles to a declaration that never applies, and a var the component writes inline outranks every cascade layer, so no theme can reach it. Both had shipped; neither is visible in the generated theme CSS the jsdom suites assert on (#5409).
+
+#### Contributors
+
+Thanks to everyone who contributed to this release:
+
+- @AKnassa
+- @andrskr
+- @cixzhang
+- @ernestt
+- @freddymeta
+- @jiunshinn
+- @rubyycheung
+
+---
+
 # 0.4.7
 
 ---

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/data-token-fallbacks.test.mjs

@@ -0,0 +1,85 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Asserts every `var(--color-data-*, <hex>)` fallback in the dashboard
+ * templates equals the token's own default.
+ *
+ * The fallback is what paints when the token does not resolve, so a fallback
+ * that differs from its token makes the same chart series two different colours
+ * depending on whether a theme is present. Three of them had drifted
+ * (`#22c55e`, `#E5484D`, `#008E80`), which is also why "the defaults are
+ * byte-identical to the template fallbacks" was not true.
+ */
+
+import {describe, it, expect} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {dataTokenDefaults} from '@astryxdesign/core/theme';
+
+const TEMPLATES_DIR = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../assets/templates',
+);
+const CALL_SITE = /var\(\s*(--color-data-[a-z0-9-]+)\s*,\s*([^)]+?)\s*\)/g;
+
+/** The light side of a `light-dark(a, b)` pair — what a template falls back to. */
+function lightSide(value) {
+  const match = /^light-dark\(\s*([^,]+?)\s*,/.exec(value);
+  return match ? match[1] : value;
+}
+
+function walk(dir) {
+  return fs.readdirSync(dir, {withFileTypes: true}).flatMap(entry => {
+    const full = path.join(dir, entry.name);
+    return entry.isDirectory() ? walk(full) : [full];
+  });
+}
+
+function callSites() {
+  const sites = [];
+  for (const file of walk(TEMPLATES_DIR)) {
+    if (!/\.(tsx|ts|jsx|js|mjs|css)$/.test(file)) {
+      continue;
+    }
+    fs.readFileSync(file, 'utf-8')
+      .split('\n')
+      .forEach((line, index) => {
+        for (const match of line.matchAll(CALL_SITE)) {
+          sites.push({
+            where: `${path.relative(TEMPLATES_DIR, file)}:${index + 1}`,
+            token: match[1],
+            fallback: match[2],
+          });
+        }
+      });
+  }
+  return sites;
+}
+
+describe('template --color-data-* fallbacks', () => {
+  const sites = callSites();
+
+  it('finds the call sites at all', () => {
+    expect(sites.length).toBeGreaterThan(40);
+  });
+
+  it('names a real token at every call site', () => {
+    const unknown = sites.filter(site => !dataTokenDefaults[site.token]);
+    expect(unknown.map(site => `${site.where} ${site.token}`)).toEqual([]);
+  });
+
+  it('matches each token default exactly', () => {
+    const drifted = sites
+      .filter(site => dataTokenDefaults[site.token])
+      .filter(
+        site => site.fallback !== lightSide(dataTokenDefaults[site.token]),
+      )
+      .map(
+        site =>
+          `${site.where} ${site.token}: ${site.fallback} != ${lightSide(dataTokenDefaults[site.token])}`,
+      );
+
+    expect(drifted).toEqual([]);
+  });
+});

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: [