@astryxdesign/cli 0.3.0-canary.fbc60c5 → 0.3.0-canary.fcbc342

package/README.md

@@ -72,7 +72,7 @@ Options:
 | `search`               | Search components, hooks, docs, and templates in one ranked list              |
 | `swizzle`              | Copy component source for customization                                       |
 | `template`             | Inject a page or block template                                               |
-| `theme`                | Theme tools — build, export, and manage themes                                |
+| `theme`                | Theme tools: build, export, and manage themes                                 |
 | `upgrade`              | Run codemods to migrate between versions                                      |
 | `validate-integration` | Validate an Astryx integration package (manifest + contributions)             |
 
@@ -385,7 +385,7 @@ Every response has a `type` discriminant. The full set is below (generated from
 
 | 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.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}.                                                                                                                                                                                 |
@@ -393,12 +393,12 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `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.                                                                                            |
+| `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.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.                                                                                                         |
@@ -409,15 +409,15 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `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.                                                                                                                                                |
-| `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.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.list`                | Every bundled theme as a ThemeListEntry[] — each with slug, displayName, description, and a maintained flag.                                                                                                                         |
+| `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.                                                                           |
 | `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.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.                                                          |

package/api/blog/blog.doc.mjs

@@ -14,7 +14,7 @@ export const doc = {
   displayName: 'blog()',
   summary: 'List blog posts, or read one, from the published RSS feed.',
   description:
-    'Reads the design system blog the same way any feed reader does — over the ' +
+    'Reads the design system blog the same way any feed reader does, over the ' +
     "published RSS feed, never the blog's source files. With no slug it lists every " +
     "post parsed from the feed; with a slug it reads that post's full plaintext body " +
     'via the .txt alternate the feed advertises. Both envelopes carry feedUrl so a ' +
@@ -35,7 +35,7 @@ export const doc = {
     {
       type: 'blog.list',
       description:
-        'The feed URL plus every post parsed from the feed — each with slug, title, description, date, type, authors, link, and its plaintext URL.',
+        'The feed URL plus every post parsed from the feed, each with slug, title, description, date, type, authors, link, and its plaintext URL.',
     },
     {
       type: 'blog.detail',

package/api/build/build.doc.mjs

@@ -54,7 +54,7 @@ export const doc = {
     {
       type: 'build.help',
       description:
-        'Emitted when the query is omitted — a pure marker (`data.playbook: true`) that the command renderer expands into the page-building workflow prose.',
+        'Emitted when the query is omitted: a pure marker (`data.playbook: true`) that the command renderer expands into the page-building workflow prose.',
     },
     {
       type: 'build.kit',

package/api/component/component.doc.mjs

@@ -108,7 +108,7 @@ export const doc = {
     {
       type: 'component.list',
       description:
-        "The catalog grouped by category. data.detail is the level ('names' | 'compact' | 'full') and data.components is the grouped map — names+package, brief entries, or full ComponentDoc per entry.",
+        "The catalog grouped by category. data.detail is the level ('names' | 'compact' | 'full') and data.components is the grouped map: names+package, brief entries, or full ComponentDoc per entry.",
     },
     {
       type: 'component.detail',

package/api/discover/discover.doc.mjs

@@ -15,7 +15,7 @@ export const doc = {
   summary: 'Browse and search components from configured external packages.',
   description:
     'Explores components contributed by configured external packages and integrations ' +
-    '— the ones that declare a components root. With no query it lists those packages; ' +
+    'the ones that declare a components root. With no query it lists those packages; ' +
     'an @scope/name query browses one package; @scope/name/Component (or a free-text ' +
     "term that resolves to a single component) returns that component's validated doc; " +
     'a free-text term with several matches returns the candidate list.',
@@ -68,7 +68,7 @@ export const doc = {
     {
       type: 'discover.detail.doc',
       description:
-        'The validated ComponentDoc for one external component — an @scope/name/Component query, or a free-text term that resolves to exactly one component.',
+        'The validated ComponentDoc for one external component: an @scope/name/Component query, or a free-text term that resolves to exactly one component.',
     },
     {
       type: 'discover.search',

package/api/docs/docs.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   name: 'docs',
   displayName: 'docs()',
   summary:
-    'Read the reference docs — list every topic, one topic, or a single section of a topic.',
+    'Read the reference docs: list every topic, one topic, or a single section of a topic.',
   description:
     'Routes on its arguments: no topic lists every reference-doc topic; a topic ' +
     'returns that full ReferenceDoc (with token-ref blocks inlined); a topic ' +
@@ -75,7 +75,7 @@ export const doc = {
     {
       type: 'docs.detail.section',
       description:
-        'A single ReferenceSection of the topic — the first whose title contains the section query.',
+        'A single ReferenceSection of the topic: the first whose title contains the section query.',
     },
   ],
   throws: [

package/api/doctor/doctor.doc.mjs

@@ -14,10 +14,10 @@ export const doc = {
   displayName: 'doctor()',
   summary: 'Read-only project + environment health check.',
   description:
-    'Runs a series of side-effect-free diagnostics — Node version, ' +
+    'Runs a series of side-effect-free diagnostics: Node version, ' +
     '@astryxdesign/core install and version alignment with the CLI, installed ' +
     'themes and wiring, astryx.config validity, agent docs, core peer ' +
-    'dependencies, and the detected package manager — and returns a structured ' +
+    'dependencies, and the detected package manager, and returns a structured ' +
     'report. It only reads (never installs, writes, or mutates), so it is safe ' +
     'as a CI gate and for agents to invoke.',
   importPath: '@astryxdesign/cli/api',
@@ -34,7 +34,7 @@ export const doc = {
     {
       type: 'doctor',
       description:
-        'The diagnostic report: `data.checks` — each with a stable id, label, `status` (`pass` | `warn` | `fail` | `info`), a one-line message, and a `fix` when the status is not `pass` — plus `data.summary` with counts per status.',
+        'The diagnostic report: `data.checks`, each with a stable id, label, `status` (`pass` | `warn` | `fail` | `info`), a one-line message, and a `fix` when the status is not `pass`; plus `data.summary` with counts per status.',
     },
   ],
   examples: [

package/api/hook/hook.doc.mjs

@@ -70,7 +70,7 @@ export const doc = {
     {
       type: 'hook.list',
       description:
-        "The catalog grouped by category. data.detail is the level ('names' | 'compact' | 'full') and data.components is the grouped map — hook names, brief entries, or full HookDoc per entry.",
+        "The catalog grouped by category. data.detail is the level ('names' | 'compact' | 'full') and data.components is the grouped map: hook names, brief entries, or full HookDoc per entry.",
     },
     {
       type: 'hook.detail',

package/api/init/init.doc.mjs

@@ -69,7 +69,7 @@ export const doc = {
     {
       type: 'init.remove',
       description:
-        'Confirmation that the managed agent-docs block was removed (`data.removed: true`) — returned when `removeAgents` is set.',
+        'Confirmation that the managed agent-docs block was removed (`data.removed: true`), returned when `removeAgents` is set.',
     },
   ],
   throws: [

package/api/integration/summarizeIssues.doc.mjs

@@ -17,7 +17,7 @@ export const doc = {
     'Tally integration issues by severity into error and warning counts.',
   description:
     'A synchronous helper that reduces an AstryxIntegrationIssue[] (as returned ' +
-    'by validateIntegration) to counts of errors and warnings — the seam a ' +
+    'by validateIntegration) to counts of errors and warnings: the seam a ' +
     'caller uses to decide an exit code or print a summary line. Issues of any ' +
     'other severity are ignored.',
   importPath: '@astryxdesign/cli/api',

package/api/integration/validateIntegration.doc.mjs

@@ -45,7 +45,7 @@ export const doc = {
     {
       type: 'integration.validate',
       description:
-        'The result envelope: `data.name` and `data.version` of the validated package (both null when no local manifest is found), plus `data.issues` — an AstryxIntegrationIssue[] of {code, severity: `warning` | `error`, message}.',
+        'The result envelope: `data.name` and `data.version` of the validated package (both null when no local manifest is found), plus `data.issues`, an AstryxIntegrationIssue[] of {code, severity: `warning` | `error`, message}.',
     },
   ],
   examples: [

package/api/json/assertResponse.doc.mjs

@@ -27,7 +27,7 @@ export const doc = {
       name: 'raw',
       type: 'unknown',
       description:
-        'The CLI stdout to parse — a JSON string, or an object that was already parsed.',
+        'The CLI stdout to parse: a JSON string, or an object that was already parsed.',
       required: true,
     },
     {
@@ -42,7 +42,7 @@ export const doc = {
     {
       type: 'any',
       description:
-        'The parsed envelope, guaranteed at runtime to carry the requested `type`. The published signature is untyped — cast to the matching *Response type for typed access.',
+        'The parsed envelope, guaranteed at runtime to carry the requested `type`. The published signature is untyped; cast to the matching *Response type for typed access.',
     },
   ],
   throws: [

package/api/json/isError.doc.mjs

@@ -14,7 +14,7 @@ export const doc = {
   displayName: 'isError()',
   summary: 'Did the CLI return an error envelope?',
   description:
-    'Tests a parsed response for an `error` key. Branch on this before touching `data` — ' +
+    'Tests a parsed response for an `error` key. Branch on this before touching `data`: ' +
     'and prefer the stable `code` field over matching the human-readable message, which is ' +
     'not a contract. Note this returns a plain boolean, not a TypeScript type predicate, so ' +
     'it does not narrow on its own: cast to the matching *Response type to get typed access.',

package/api/json/parseResponse.doc.mjs

@@ -26,7 +26,7 @@ export const doc = {
       name: 'raw',
       type: 'unknown',
       description:
-        'The CLI stdout to parse — a JSON string, or an object that was already parsed.',
+        'The CLI stdout to parse: a JSON string, or an object that was already parsed.',
       required: true,
     },
   ],
@@ -34,7 +34,7 @@ export const doc = {
     {
       type: 'any',
       description:
-        'The { type, data, meta? } envelope, or a CLIError envelope. The published signature is intentionally untyped — narrow it by casting to the matching *Response type exported from @astryxdesign/cli/json.',
+        'The { type, data, meta? } envelope, or a CLIError envelope. The published signature is intentionally untyped; narrow it by casting to the matching *Response type exported from @astryxdesign/cli/json.',
     },
   ],
   throws: [

package/api/layout/layoutCheck.doc.mjs

@@ -18,7 +18,7 @@ export const doc = {
     'The validator behind `astryx layout check`. Parses and validates a compressed XLE/XLO ' +
     'expression without generating any TSX, and echoes it back in both canonical surfaces ' +
     '(compact and outline). Validation failures are reported in the layout.check envelope ' +
-    '(valid: false) with line/col and suggestions — not thrown — so callers can lint an ' +
+    '(valid: false) with line/col and suggestions (not thrown) so callers can lint an ' +
     'expression and surface fixes.',
   importPath: '@astryxdesign/cli/api',
   signature:

package/api/layout/layoutExpand.doc.mjs

@@ -16,7 +16,7 @@ export const doc = {
   summary: 'Expand a validated layout expression into XDS TSX.',
   description:
     'The generator behind `astryx layout expand`. Parses and validates a compressed XLE/XLO ' +
-    'expression, then expands it into ready-to-use XDS TSX — auto-routing structural children ' +
+    'expression, then expands it into ready-to-use XDS TSX, auto-routing structural children ' +
     'into the right slots, scaffolding typed useState for interactive controls, and splicing or ' +
     'importing any referenced template blocks. Returns the code (and metadata) in a layout.expand ' +
     'envelope, optionally writing it to a path within cwd.',

package/api/layout/layoutGrammar.doc.mjs

@@ -15,7 +15,7 @@ export const doc = {
   displayName: 'layoutGrammar()',
   summary: 'Return the XLE/XLO grammar cheatsheet for this install.',
   description:
-    'The reference behind `astryx layout grammar` — the agent cheatsheet for writing XLE/XLO ' +
+    'The reference behind `astryx layout grammar`: the agent cheatsheet for writing XLE/XLO ' +
     "layout expressions, with the alias table generated from this branch's registry rather than " +
     'hand-maintained, so short names always reflect the components actually installed.',
   importPath: '@astryxdesign/cli/api',

package/api/swizzle/swizzle.doc.mjs

@@ -88,7 +88,7 @@ export const doc = {
     },
     {
       code: 'ERR_AMBIGUOUS_COMPONENT',
-      when: 'more than one package provides the component — choose one with package',
+      when: 'more than one package provides the component; choose one with package',
     },
     {
       code: 'ERR_NO_SOURCE',

package/api/template/template.test.mjs

@@ -4,36 +4,35 @@ import {describe, it, expect} from 'vitest';
 import {stripTemplateAssetRefs, template} from './template.mjs';
 
 describe('stripTemplateAssetRefs', () => {
-  it('replaces a lookaside astryx image URL with an inline data URI', () => {
+  it('replaces a /template-assets image path with an inline data URI', () => {
     const src =
-      "const hero = 'https://lookaside.facebook.com/assets/astryx/colorful-home-horizontal-1.png';";
+      "const hero = '/template-assets/colorful-home-horizontal-1.png';";
     const out = stripTemplateAssetRefs(src);
-    expect(out).not.toContain('lookaside.facebook.com');
+    expect(out).not.toContain('/template-assets/');
     expect(out).toContain('data:image/svg+xml,');
   });
 
-  it('replaces a lookaside block-avatar image URL', () => {
-    const src =
-      'src="https://lookaside.facebook.com/assets/astryx/avatar-profile-05.jpg"';
+  it('replaces a /template-assets block-avatar image path', () => {
+    const src = 'src="/template-assets/avatar-profile-05.jpg"';
     const out = stripTemplateAssetRefs(src);
-    expect(out).not.toContain('lookaside.facebook.com');
+    expect(out).not.toContain('/template-assets/');
     expect(out).toContain('data:image/svg+xml,');
   });
 
-  it('replaces every lookaside reference, not just the first', () => {
+  it('replaces every /template-assets reference, not just the first', () => {
     const src = [
-      "'https://lookaside.facebook.com/assets/astryx/colorful-home-horizontal-1.png'",
-      "'https://lookaside.facebook.com/assets/astryx/illustrative-horizontal-3.png'",
-      "'https://lookaside.facebook.com/assets/astryx/moody-scene-horizontal-1.png'",
+      "'/template-assets/colorful-home-horizontal-1.png'",
+      "'/template-assets/illustrative-horizontal-3.png'",
+      "'/template-assets/moody-scene-horizontal-1.png'",
     ].join('\n');
     const out = stripTemplateAssetRefs(src);
-    expect(out).not.toContain('lookaside.facebook.com');
+    expect(out).not.toContain('/template-assets/');
     expect(out.match(/data:image\/svg\+xml,/g)).toHaveLength(3);
   });
 
   it('preserves surrounding source structure', () => {
     const src =
-      "const data = [{src: 'https://lookaside.facebook.com/assets/astryx/x.png', alt: 'X'}];";
+      "const data = [{src: '/template-assets/x.png', alt: 'X'}];";
     const out = stripTemplateAssetRefs(src);
     expect(out).toContain("alt: 'X'");
     expect(out).toContain('const data = [{src:');
@@ -53,6 +52,32 @@ describe('stripTemplateAssetRefs', () => {
     const out = stripTemplateAssetRefs(src);
     expect(out).toBe(src);
   });
+
+  it('strips a /template-assets .mp4 source to an empty string, not the image data URI (#4780)', () => {
+    const src = "src: '/template-assets/Nature-1.mp4',";
+    const out = stripTemplateAssetRefs(src);
+    expect(out).toBe("src: '',");
+    expect(out).not.toContain('data:image/svg+xml,');
+    expect(out).not.toContain('/template-assets/');
+  });
+
+  it('strips other video extensions (.webm, .mov, .ogv) the same way', () => {
+    for (const ext of ['webm', 'mov', 'ogv']) {
+      const src = `src: '/template-assets/clip.${ext}',`;
+      const out = stripTemplateAssetRefs(src);
+      expect(out).toBe("src: '',");
+    }
+  });
+
+  it('still replaces an adjacent image reference with the placeholder when a video reference is also present', () => {
+    const src = [
+      "poster: '/template-assets/Nature-1-poster.jpg',",
+      "src: '/template-assets/Nature-1.mp4',",
+    ].join('\n');
+    const out = stripTemplateAssetRefs(src);
+    expect(out).toContain('data:image/svg+xml,');
+    expect(out).toContain("src: '',");
+  });
 });
 
 describe('template --skeleton component extraction (prefix-agnostic)', () => {

package/api/theme/listThemes.doc.mjs

@@ -16,7 +16,7 @@ export const doc = {
   displayName: 'listThemes()',
   summary: 'Read the bundled-theme manifest and return its raw entries.',
   description:
-    "The shared data layer behind theme list/add — reads the CLI's bundled-theme manifest " +
+    "The shared data layer behind theme list/add: reads the CLI's bundled-theme manifest " +
     '(templates/themes/manifest.json, generated by scripts/generate-cli-themes.mjs) and returns ' +
     'the parsed entries. themeList() projects this into the theme.list envelope; themeAdd() ' +
     'resolves a slug against it. Returns synchronously.',
@@ -28,7 +28,7 @@ export const doc = {
     {
       type: 'BundledTheme[]',
       description:
-        'The parsed themes array from the bundle manifest — each BundledTheme has slug, displayName, description, maintained, entry, exportName, and files. Empty when the manifest has not been generated.',
+        'The parsed themes array from the bundle manifest: each BundledTheme has slug, displayName, description, maintained, entry, exportName, and files. Empty when the manifest has not been generated.',
     },
   ],
   throws: [

package/api/theme/themeAdd.doc.mjs

@@ -16,7 +16,7 @@ export const doc = {
   summary: 'Scaffold a bundled theme into a project as editable source.',
   description:
     "Copies a bundled theme's source (from the CLI's templates/themes/<slug>) into the " +
-    "consumer's project so they own it — no theme package needed. Writes are staged to temp " +
+    "consumer's project so they own it, no theme package needed. Writes are staged to temp " +
     'files then renamed, rolling back partials on failure so a failed write never leaves a ' +
     'half-written theme. Returns a theme.add receipt describing where the files landed and how ' +
     'to import them.',

package/api/theme/themeBuild.doc.mjs

@@ -20,7 +20,7 @@ export const doc = {
     'emits the exact CSS the <Theme> runtime does), writes a scoped CSS file, a JS module ' +
     'that re-exports the built theme, and a .d.ts (plus an optional .variants.d.ts when the ' +
     'theme adds custom prop values). With {check: true} it writes nothing and instead compares ' +
-    'each output against disk, returning the drift — the CI guard for committed, generated theme CSS.',
+    'each output against disk, returning the drift: the CI guard for committed, generated theme CSS.',
   importPath: '@astryxdesign/cli/api',
   signature:
     'themeBuild(file: string, options?: {out?: string, check?: boolean}, ctx?: {cwd?: string}): Promise<ThemeBuildResponse | ThemeBuildCheckResponse | null>',
@@ -51,7 +51,7 @@ export const doc = {
       name: 'options.check',
       type: 'boolean',
       description:
-        'Compile in memory and compare each output against what is on disk instead of writing — the CI drift guard.',
+        'Compile in memory and compare each output against what is on disk instead of writing: the CI drift guard.',
       default: 'false',
     },
     {
@@ -86,7 +86,7 @@ export const doc = {
     },
     {
       code: 'ERR_CORE_NOT_FOUND',
-      when: '@astryxdesign/core/theme cannot be imported — a built, resolvable @astryxdesign/core is required',
+      when: '@astryxdesign/core/theme cannot be imported; a built, resolvable @astryxdesign/core is required',
     },
     {
       code: 'ERR_WRITE_FAILED',

package/api/theme/themeList.doc.mjs

@@ -15,7 +15,7 @@ export const doc = {
   displayName: 'themeList()',
   summary: 'List the themes bundled with this CLI build.',
   description:
-    'Projects the bundled-theme manifest into the theme.list envelope — the themes that themeAdd ' +
+    'Projects the bundled-theme manifest into the theme.list envelope: the themes that themeAdd ' +
     'can scaffold. A pure projection of the manifest read by listThemes(); no I/O beyond that read, ' +
     'and it returns synchronously.',
   importPath: '@astryxdesign/cli/api',
@@ -26,7 +26,7 @@ export const doc = {
     {
       type: 'theme.list',
       description:
-        'Every bundled theme as a ThemeListEntry[] — each entry has slug, displayName, description, and a maintained flag.',
+        'Every bundled theme as a ThemeListEntry[]: each entry has slug, displayName, description, and a maintained flag.',
     },
   ],
   throws: [

package/api/upgrade/upgrade.doc.mjs

@@ -86,7 +86,7 @@ export const doc = {
     {
       type: 'upgrade.list',
       description:
-        'Every available codemod, oldest→newest, as {name, title, version, optional} — returned when `list` is set; nothing is run.',
+        'Every available codemod, oldest→newest, as {name, title, version, optional}, returned when `list` is set; nothing is run.',
     },
     {
       type: 'upgrade.status',

package/assets/codemods/transforms/next/__tests__/next-codemods.test.mjs

@@ -0,0 +1,92 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Unit tests for the staged (next-release) codemods.
+ *
+ * Mirrors v0.3.0/__tests__/next-codemods.test.mjs, which covers the codemods
+ * after promotion. Keeping a copy here means a staged transform is tested from
+ * the day it is written rather than the day it is released.
+ */
+
+import {describe, expect, it} from 'vitest';
+import jscodeshift from 'jscodeshift';
+
+const j = jscodeshift.withParser('tsx');
+const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+
+async function apply(name, source) {
+  const {default: transform} = await import(`../${name}.mjs`);
+  return transform({source, path: 'test.tsx'}, api) ?? source;
+}
+
+const TRANSFORM = 'rename-dropdown-menu-radio-dot-target';
+
+describe('rename-dropdown-menu-radio-dot-target', () => {
+  it('renames the theme target key in a defineTheme components map', async () => {
+    const input = `import {defineTheme} from '@astryxdesign/core/theme';
+export const theme = defineTheme({
+  name: 'brand',
+  components: {
+    'dropdown-menu-radio-dot': {base: {backgroundColor: 'var(--color-accent)'}},
+  },
+});`;
+    const output = await apply(TRANSFORM, input);
+    expect(output).toContain("'radio-indicator-dot':");
+    // The old name survives only inside the TODO comment the rename attaches.
+    expect(output).not.toContain("'dropdown-menu-radio-dot':");
+  });
+
+  it('warns that the new target is app-wide, not menu-only', async () => {
+    const input = `const components = {
+  'dropdown-menu-radio-dot': {base: {width: '10px'}},
+};`;
+    const output = await apply(TRANSFORM, input);
+    // The rename cannot preserve scope — there is no menu-only dot element
+    // left — so the author has to decide, and must be told.
+    expect(output).toContain('TODO(astryx upgrade)');
+    expect(output).toContain('EVERY radio dot');
+  });
+
+  it('renames the rendered class inside a selector string', async () => {
+    const input = `const sel = '.astryx-dropdown-menu-radio-dot';
+const nested = '.astryx-dropdown-menu-radio .astryx-dropdown-menu-radio-dot';`;
+    const output = await apply(TRANSFORM, input);
+    expect(output).toContain("'.astryx-radio-indicator-dot'");
+    expect(output).toContain(
+      '.astryx-dropdown-menu-radio .astryx-radio-indicator-dot',
+    );
+  });
+
+  it('renames the class inside a template literal', async () => {
+    const input =
+      'const css = `.astryx-dropdown-menu-radio-dot { background: ${c}; }`;';
+    const output = await apply(TRANSFORM, input);
+    expect(output).toContain('.astryx-radio-indicator-dot {');
+    expect(output).not.toContain('astryx-dropdown-menu-radio-dot');
+  });
+
+  it('leaves the surviving dropdown-menu-radio target alone', async () => {
+    // Only the DOT target was removed; the circle still carries the
+    // menu-specific target, so a theme keyed on it must not be rewritten.
+    const input = `const components = {
+  'dropdown-menu-radio': {base: {borderWidth: '2px'}},
+};`;
+    const output = await apply(TRANSFORM, input);
+    expect(output).toContain("'dropdown-menu-radio'");
+    expect(output).not.toContain('radio-indicator');
+    expect(output).not.toContain('TODO(astryx upgrade)');
+  });
+
+  it('is a no-op on files that never mention the target', async () => {
+    const input = `const components = {button: {base: {fontWeight: '600'}}};`;
+    expect(await apply(TRANSFORM, input)).toBe(input);
+  });
+
+  it('is idempotent', async () => {
+    const input = `const components = {
+  'dropdown-menu-radio-dot': {base: {width: '10px'}},
+};`;
+    const once = await apply(TRANSFORM, input);
+    expect(await apply(TRANSFORM, once)).toBe(once);
+  });
+});

package/assets/codemods/transforms/next/index.mjs

@@ -7,4 +7,14 @@
  * this file into the resolved version folder.
  */
 
-export default [];
+import renameDropdownMenuRadioDotTarget, {
+  meta as renameDropdownMenuRadioDotTargetMeta,
+} from './rename-dropdown-menu-radio-dot-target.mjs';
+
+export default [
+  {
+    name: 'rename-dropdown-menu-radio-dot-target',
+    transform: renameDropdownMenuRadioDotTarget,
+    meta: renameDropdownMenuRadioDotTargetMeta,
+  },
+];