@astryxdesign/cli 0.3.0-canary.d52d2cb → 0.3.0-canary.d790582

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

@@ -52,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/docs/browser-support.doc.mjs

@@ -15,7 +15,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Astryx is built on modern web platform features: the Popover API, CSS anchor positioning, and CSS `light-dark()`. These let components stay small, accessible, and dependency-free, but they also set a floor on which browsers render everything correctly.',
+          text: 'Astryx is built on modern web platform features: the [`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) API, CSS anchor positioning, and CSS `light-dark()`. These let components stay small, accessible, and dependency-free, but they also set a floor on which browsers render everything correctly.',
         },
         {
           type: 'prose',
@@ -73,7 +73,7 @@ export const docs = {
               'Baseline 2026: the tightest requirement.',
             ],
             [
-              'Popover API',
+              '[`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) API',
               'Opens, stacks, and light-dismisses layered surfaces via the top layer.',
               'Baseline 2025.',
             ],
@@ -86,7 +86,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'The gap that matters is between Tier 1 and Tier 2: the Popover API and `light-dark()` reached wide availability well before anchor positioning. So in Tier 2 browsers, layered surfaces open and dismiss correctly; they just are not positioned. This is the one feature most consumers will need to reason about.',
+          text: 'The gap that matters is between Tier 1 and Tier 2: the [`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) API and `light-dark()` reached wide availability well before anchor positioning. So in Tier 2 browsers, layered surfaces open and dismiss correctly; they just are not positioned. This is the one feature most consumers will need to reason about.',
         },
       ],
     },
@@ -112,7 +112,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'If your product does not use any of these, it has no anchor-positioning requirement at all; it needs only `light-dark()` (Tier 2 and up) for correct theme colors. Layout, typography, forms, buttons, cards, tables, and navigation all work down to Tier 2 with no special handling.',
+          text: 'If your product does not use any of these, it has no anchor-positioning requirement at all; it needs only `light-dark()` (Tier 2 and up) for correct theme colors. Page layout, typography, forms, buttons, cards, tables, and navigation all work down to Tier 2 with no special handling.',
         },
       ],
     },
@@ -123,7 +123,7 @@ export const docs = {
           type: 'list',
           style: 'do',
           items: [
-            'Components never throw on missing platform APIs. Where a browser lacks the Popover API, layers fall back to plain visibility instead of crashing.',
+            'Components never throw on missing platform APIs. Where a browser lacks the [`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) API, layers fall back to plain visibility instead of crashing.',
             'Tier 1 and Tier 2 are officially supported and tested.',
             'Non-layered components render correctly down to Tier 2.',
           ],
@@ -192,7 +192,7 @@ const hasLightDark = CSS.supports('color', 'light-dark(#000, #fff)');`,
         },
         {
           type: 'prose',
-          text: 'This is not an arbitrary window: Baseline − 2 is close to where anchor positioning stops being available while the Popover API and `light-dark()` still are, so the tier boundary tracks a real capability edge, not a guessed date. The version floors above are reviewed and advanced roughly once a year as new Baseline years land. Always feature-detect rather than hardcoding version numbers, so your app adapts automatically as the platform moves.',
+          text: 'This is not an arbitrary window: Baseline − 2 is close to where anchor positioning stops being available while the [`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) API and `light-dark()` still are, so the tier boundary tracks a real capability edge, not a guessed date. The version floors above are reviewed and advanced roughly once a year as new Baseline years land. Always feature-detect rather than hardcoding version numbers, so your app adapts automatically as the platform moves.',
         },
       ],
     },

package/assets/docs/icons.doc.mjs

@@ -114,9 +114,9 @@ export const brandTheme = defineTheme({
           type: 'list',
           style: 'ordered',
           items: [
-            'Add the name to IconName type in packages/core/src/Icon/globalIconRegistry.tsx',
-            'Add the default SVG to packages/core/src/Icon/defaultIcons.tsx',
-            'Add a row to the Available Names table in packages/cli/docs/icons.doc.mjs',
+            'Add the name to IconName type in `packages/core/src/Icon/globalIconRegistry.tsx`',
+            'Add the default SVG to `packages/core/src/Icon/defaultIcons.tsx`',
+            'Add a row to the Available Names table in `packages/cli/assets/docs/icons.doc.mjs`',
           ],
         },
       ],

package/assets/docs/illustrations.doc.mjs

@@ -40,7 +40,7 @@ export const docs = {
             'Keep illustrations consistent in style across the product.',
             'Use simple, flat illustrations that work in both light and dark mode.',
             'Size illustrations proportionally to the container, typically 120\u2013240px.',
-            'Center illustrations with supporting text below.',
+            'Place illustrations centered with supporting text below.',
           ],
         },
         {
@@ -59,7 +59,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Center illustrations inside Center with supporting text stacked below. Typical illustration sizes range from 120px for inline empty states to 240px for full-page onboarding screens. Always pair the illustration with a heading and optional body text to explain what the user should do next.',
+          text: 'Place illustrations inside Center with supporting text stacked below. Typical illustration sizes range from 120px for inline empty states to 240px for full-page onboarding screens. Always pair the illustration with a heading and optional body text to explain what the user should do next.',
         },
         {
           type: 'code',

package/assets/docs/internationalization.doc.mjs

@@ -300,7 +300,7 @@ export default function App() {
       content: [
         {
           type: 'prose',
-          text: 'Astryx generates a `pseudo` locale that wraps every string in `⟦…⟧` and replaces letters with accented look-alikes. Switch to it in development to catch hardcoded astryx strings and layout issues caused by longer text.',
+          text: 'Astryx generates a `pseudo` locale that wraps every string in `⟦…⟧` and replaces letters with accented look-alikes. Turn it on in development to catch hardcoded astryx strings and layout issues caused by longer text.',
         },
         {
           type: 'code',

package/assets/docs/migration.doc.mjs

@@ -350,7 +350,7 @@ if (getComputedStyle(button).paddingInline === '0px') {
             'Run the app in light and dark mode and check that surfaces, borders, text, icons, hover states, focus rings, and status colors flow together.',
             'Open the command palette from the shell, type into it, select items by keyboard, and confirm focus returns to the trigger.',
             'Check the SideNav at collapsed, expanded, active, hover, nested, and mobile states.',
-            'Verify settings popovers and dialogs in jsdom and in a real browser because native dialog and Popover APIs may need test shims.',
+            'Verify settings popovers and dialogs in jsdom and in a real browser because the native dialog and [`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) APIs may need test shims.',
             'Search for leftover hardcoded Tailwind colors, arbitrary hex values, and one-off hover colors after each route migration.',
             'Run component tests, build, and at least one browser screenshot pass for each migrated route.',
           ],

package/assets/docs/principles.doc.mjs

@@ -39,7 +39,7 @@ export const docs = {
           style: 'ordered',
           items: [
             'Use components for everything they cover',
-            'Layout is frame-first: pick the shell and budget regions before writing content (see \`astryx docs layout\`)',
+            'Page layout is frame-first: pick the shell and budget regions before writing content (see \`astryx docs layout\`)',
             'Dense data renders as rows (Table, List/Item), edge-to-edge with dividers; Card is for widgets, galleries, and settings groups',
             'StyleX or Tailwind for custom styling; both are first-class (see \`astryx docs styling\`)',
             'Semantic tokens, not hardcoded values (see \`astryx docs tokens\`)',

package/assets/docs/styling-libraries.doc.mjs

@@ -56,7 +56,7 @@ export const docs = {
               '`@astryxdesign/core/tailwind-theme.css`',
             ],
             [
-              'Token resolver APIs',
+              'Design token resolver APIs',
               'JavaScript needs token values for charts, canvas, SVG, or config objects',
               "`resolveThemeToken(theme, '--color-data-categorical-blue', {mode})`",
             ],

package/assets/docs/styling.doc.mjs

@@ -22,10 +22,10 @@ export const docs = {
           type: 'table',
           headers: ['Approach', 'Use for', 'Example'],
           rows: [
-            ['StyleX', 'Component-specific overrides, reusable styles, pseudo-classes, and typed tokens', 'const styles = stylex.create(...); <Button xstyle={styles.save} />'],
-            ['Tailwind utilities', 'Layout, wrappers, and utility styling', 'className="flex gap-3 p-4"'],
-            ['className', 'Integrating with external CSS or Tailwind on components', 'className="my-card shadow-lg"'],
-            ['Styling-library token aliases', 'Keeping Panda, Chakra, MUI, Emotion, styled-components, UnoCSS, CSS Modules, or Sass in sync with the system', "colors.surface = 'var(--color-background-surface)'"],
+            ['StyleX', 'Component-specific overrides, reusable styles, pseudo-classes, and typed tokens', '`const styles = stylex.create(...); <Button xstyle={styles.save} />`'],
+            ['Tailwind utilities', 'Page layout, wrappers, and utility styling', '`className="flex gap-3 p-4"`'],
+            ['className', 'Integrating with external CSS or Tailwind on components', '`className="my-card shadow-lg"`'],
+            ['Styling-library token aliases', 'Keeping Panda, Chakra, MUI, Emotion, styled-components, UnoCSS, CSS Modules, or Sass in sync with the system', "`colors.surface = 'var(--color-background-surface)'`"],
           ],
         },
         {

package/assets/docs/theme.doc.mjs

@@ -106,7 +106,7 @@ function App() {
             [
               'Y2K',
               "import {y2kTheme} from '@astryxdesign/theme-y2k'",
-              'Playful Y2K pop; periwinkle body, holographic accents, Poppins + Crimson Text.',
+              'Playful Y2K pop; periwinkle body, holographic accents, Poppins + `Crimson Text`.',
             ],
           ],
         },
@@ -510,7 +510,7 @@ import './themes/ocean.css';
       content: [
         {
           type: 'prose',
-          text: 'Wrap different sections in separate <Theme> providers.',
+          text: 'Wrap different sections in separate [`<Theme>`](/components/Theme) providers.',
         },
         {
           type: 'code',
@@ -606,7 +606,7 @@ function ChartConfig() {
         },
         {
           type: 'prose',
-          text: 'Prefer CSS variables, StyleX token imports, xstyle, or className for ordinary styling. To change the theme or mode, manage state at the app level and pass it to <Theme>.',
+          text: 'Prefer CSS variables, StyleX token imports, xstyle, or className for ordinary styling. To change the theme or mode, manage state at the app level and pass it to `<Theme>`.',
         },
         {
           type: 'prose',

package/assets/docs/typography.doc.mjs

@@ -122,7 +122,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'Display text often needs heading semantics for accessibility. Use the type prop on Heading to apply display styling while preserving the correct HTML element: <Heading level={1} type="display-1"> gives you display-1 styling with an <h1> tag, so screen readers see the correct document outline.',
+          text: 'Display text often needs heading semantics for accessibility. Use the type prop on Heading to apply display styling while preserving the correct HTML element: `<Heading level={1} type="display-1">` gives you display-1 styling with an `<h1>` tag, so screen readers see the correct document outline.',
         },
       ],
     },
@@ -205,7 +205,7 @@ const denseTheme = defineTheme({
           items: [
             'Use Heading for document headings and Text for everything else; they apply the full type scale automatically.',
             'Adjust typography holistically: change base and ratio in defineTheme to shift the entire ramp (e.g. { base: 16, ratio: 1.25 } for editorial, { base: 12, ratio: 1.125 } for dense UI).',
-            'Use display types with as="h1" (or h2/h3) when display text is a page heading; this preserves accessibility while giving you display-level sizing. Or better, use <Heading level={1} type="display-1"> which handles both semantics and styling.',
+            'Use display types with as="h1" (or h2/h3) when display text is a page heading; this preserves accessibility while giving you display-level sizing. Or better, use `<Heading level={1} type="display-1">` which handles both semantics and styling.',
             'Let line-height snap to the 4px grid via the type scale; expandTypeScale computes leading automatically from base and ratio.',
             'Use the supporting type for secondary information: timestamps, helper text, metadata, captions.',
             'Use accessibilityLevel on Heading when the visual hierarchy doesn\u0027t match the document outline (e.g. sidebar or card headings).',