@astryxdesign/cli 0.6.3-canary.98a2e4e → 0.6.3-canary.9c4d44d

package/authoring/index.d.ts

@@ -23,18 +23,19 @@
 // ═══════════════════════════════════════════════════════════════════════
 // AUTHOR THESE — each is the default export of one authored file.
 // ═══════════════════════════════════════════════════════════════════════
-export type {ComponentDoc} from './doctypes/types'; //   Button.doc.{ts,mjs}
-export type {HookDoc} from './doctypes/types'; //         useToast.doc.{ts,mjs}
-export type {FunctionDoc} from './doctypes/types'; //     search.doc.mjs (hook | api)
-export type {ReferenceDoc} from './doctypes/types'; //    theming.doc.{ts,mjs}
-export type {TemplateDoc} from './doctypes/types'; //     Foo.template.{ts,mjs}
-export type {SchemaDoc} from './doctypes/types'; //       config.doc.mjs (object shape)
-export type {CommandDoc} from './doctypes/types'; //      search.doc.mjs (CLI command)
-export type {EnumDoc} from './doctypes/types'; //         error-codes.doc.mjs (vocabulary)
-export type {NamespaceDoc} from './doctypes/types'; //    cli.doc.mjs (hierarchy)
-export type {AstryxConfig} from './config/type'; //       astryx.config.{ts,mjs}
-export type {DebugEvent} from './debug/type'; //          one recorded CLI run
-export type {AstryxIntegration} from './integration/type'; // astryx.integration.{ts,mjs}
+export type {ComponentDoc} from './doctypes/types.js'; //   Button.doc.mjs
+export type {HookDoc} from './doctypes/types.js'; //         useToast.doc.mjs
+export type {FunctionDoc} from './doctypes/types.js'; //     search.doc.mjs (hook | api)
+export type {ReferenceDoc} from './doctypes/types.js'; //    theming.doc.mjs
+export type {TemplateDoc} from './doctypes/types.js'; //     Foo.doc.mjs
+export type {SchemaDoc} from './doctypes/types.js'; //       config.doc.mjs (object shape)
+export type {CommandDoc} from './doctypes/types.js'; //      search.doc.mjs (CLI command)
+export type {EnumDoc} from './doctypes/types.js'; //         error-codes.doc.mjs (vocabulary)
+export type {NamespaceDoc} from './doctypes/types.js'; //    cli.doc.mjs (hierarchy)
+export type {ThemeDoc} from './doctypes/types.js'; //        oceanTheme.doc.mjs
+export type {AstryxConfig} from './config/type.js'; //       astryx.config.{ts,mjs}
+export type {DebugEvent} from './debug/type.js'; //          one recorded CLI run
+export type {AstryxIntegration} from './integration/type.js'; // astryx.integration.{ts,mjs}
 export type {
   GapReportHandler,
   GapReportHandlerContext,
@@ -42,8 +43,17 @@ export type {
   GapReportCategory,
   GapReportTarget,
   GapReportHandlerReceipt,
-} from './gap-report/type'; // gap-report handler contract
-export type {AstryxCodemod, AstryxConfigCodemod} from './codemod/type'; // codemods/*
+} from './gap-report/type.js'; // gap-report handler contract
+export type {
+  DiscoverSource,
+  DiscoverSourceContext,
+  DiscoverCatalog,
+  DiscoverPackage,
+  DiscoverVersion,
+  DiscoverContribution,
+  DiscoverKind,
+} from './discover/type.js'; // discover source contract
+export type {AstryxCodemod, AstryxConfigCodemod} from './codemod/type.js'; // codemods/*
 
 // ═══════════════════════════════════════════════════════════════════════
 // PARSERS — the CLI's load boundary (types come from each parser's JSDoc).
@@ -58,6 +68,7 @@ export {parseSchema} from './doctypes/schema/parse.mjs';
 export {parseCommand} from './doctypes/command/parse.mjs';
 export {parseEnum} from './doctypes/enum/parse.mjs';
 export {parseNamespace} from './doctypes/namespace/parse.mjs';
+export {parseTheme} from './doctypes/theme/parse.mjs';
 export {parseLegacyDoc} from './doctypes/legacy.mjs';
 export {parseConfig} from './config/parse.mjs';
 export {parseIntegration} from './integration/parse.mjs';
@@ -65,6 +76,7 @@ export {
   parseGapReportHandler,
   parseGapReportReceipt,
 } from './gap-report/parse.mjs';
+export {parseDiscoverCatalog} from './discover/parse.mjs';
 export {parseCodemod} from './codemod/parse.mjs';
 export {parseDebugEvent} from './debug/parse.mjs';
 
@@ -87,7 +99,7 @@ export type {
   AuthoredDocSnapshot,
   AuthoredDocSource,
   AuthoredDocEntry,
-} from './identity/type';
+} from './identity/type.js';
 export type {
   // shared graph
   AuthoredDocKind,
@@ -129,6 +141,7 @@ export type {
   // reference
   ReferenceSection,
   ReferenceContentBlock,
+  GraphContentBlock,
   ReferenceTokenPreviewType,
   ReferenceTranslationDoc,
   WorkflowStep,
@@ -151,8 +164,8 @@ export type {
   CommandExampleDoc,
   // enum
   EnumMemberDoc,
-} from './doctypes/types';
-export type {PostCodemodHook, DebugConfig} from './config/type';
+} from './doctypes/types.js';
+export type {PostCodemodHook, DebugConfig} from './config/type.js';
 export type {
   // debug
   DebugSchemaVersion,
@@ -165,11 +178,11 @@ export type {
   DebugEventEnv,
   DebugEventProject,
   DebugEventHandler,
-} from './debug/type';
+} from './debug/type.js';
 export type {
   AstryxCodemodDef,
   AstryxConfigCodemodDef,
   AstryxCodemodFile,
   AstryxCodemodApi,
   AstryxCodemodTransform,
-} from './codemod/type';
+} from './codemod/type.js';

package/authoring/index.mjs

@@ -11,7 +11,7 @@
  * `type` directly.
  *
  * Types (config, integration, codemod, and the doc vocabulary —
- * component/hook/reference/template) are re-exported via `./index.ts`.
+ * component/hook/reference/template/theme) are re-exported via `./index.ts`.
  */
 
 export {parseConfig} from './config/parse.mjs';
@@ -20,6 +20,7 @@ export {
   parseGapReportHandler,
   parseGapReportReceipt,
 } from './gap-report/parse.mjs';
+export {parseDiscoverCatalog} from './discover/parse.mjs';
 export {parseCodemod} from './codemod/parse.mjs';
 export {parseDebugEvent} from './debug/parse.mjs';
 export {parseDoc} from './doctypes/parse.mjs';
@@ -32,4 +33,5 @@ export {parseSchema} from './doctypes/schema/parse.mjs';
 export {parseCommand} from './doctypes/command/parse.mjs';
 export {parseEnum} from './doctypes/enum/parse.mjs';
 export {parseNamespace} from './doctypes/namespace/parse.mjs';
+export {parseTheme} from './doctypes/theme/parse.mjs';
 export {parseLegacyDoc} from './doctypes/legacy.mjs';

package/authoring/integration/integration.doc.mjs

@@ -11,7 +11,7 @@ export const doc = {
   type: 'schema',
   name: 'integration',
   displayName: 'Astryx Integration',
-  namespace: 'cli',
+  namespace: 'authoring',
   description:
     'The astryx.integration.* manifest that sits beside an integration ' +
     "package's package.json. It can preserve a stable provider identity across a package rename, " +
@@ -57,7 +57,7 @@ export const doc = {
       name: 'themes',
       type: 'string',
       description:
-        'Relative path to a source-theme catalog root containing manifest.json plus one directory per theme slug. Installed themes appear in `astryx theme list` and can be copied with `astryx theme add`.',
+        'Relative path to a source-theme root with one directory per theme slug. Each directory contains a source module and mandatory same-stem, strongly typed .doc.mjs descriptor. Installed themes appear in `astryx theme list` and can be copied with `astryx theme add`.',
       example: "'./themes'",
     },
     {

package/authoring/integration/parse.d.mts

@@ -1,7 +1,7 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/** @typedef {import('./type').AstryxIntegration} AstryxIntegration */
+/** @typedef {import('./type.js').AstryxIntegration} AstryxIntegration */
 /**
  * Validate an unknown value as an Astryx integration manifest, or throw.
  *
@@ -14,4 +14,4 @@
  * @returns {AstryxIntegration}
  */
 export function parseIntegration(input: unknown, label?: string): AstryxIntegration;
-export type AstryxIntegration = import("./type").AstryxIntegration;
+export type AstryxIntegration = import("./type.js").AstryxIntegration;

package/authoring/integration/parse.mjs

@@ -14,7 +14,7 @@
 import {formatZodError} from '../_shared/errors.mjs';
 import {integrationSchema} from './schema.mjs';
 
-/** @typedef {import('./type').AstryxIntegration} AstryxIntegration */
+/** @typedef {import('./type.js').AstryxIntegration} AstryxIntegration */
 
 /**
  * Validate an unknown value as an Astryx integration manifest, or throw.

package/authoring/integration/schema.d.mts

@@ -55,8 +55,8 @@ export const integrationSchema: z.ZodObject<{
 /**
  * Compile-time drift-lock: sealed schema must infer exactly {@link AstryxIntegration}.
  *
- * @typedef {import('../_shared/contract').Expect<
- *   import('../_shared/contract').Equal<z.infer<typeof integrationSchema>, AstryxIntegration>
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').Equal<z.infer<typeof integrationSchema>, AstryxIntegration>
  * >} _IntegrationDriftLock
  */
 /**
@@ -69,9 +69,9 @@ export const integrationSchema: z.ZodObject<{
  * @type {string[]}
  */
 export const KNOWN_INTEGRATION_KEYS: string[];
-export type AstryxIntegration = import("./type").AstryxIntegration;
+export type AstryxIntegration = import("./type.js").AstryxIntegration;
 /**
  * Compile-time drift-lock: sealed schema must infer exactly {@link AstryxIntegration}.
  */
-export type _IntegrationDriftLock = import("../_shared/contract").Expect<import("../_shared/contract").Equal<z.infer<typeof integrationSchema>, AstryxIntegration>>;
+export type _IntegrationDriftLock = import("../_shared/contract.js").Expect<import("../_shared/contract.js").Equal<z.infer<typeof integrationSchema>, AstryxIntegration>>;
 import { z } from 'zod';

package/authoring/integration/schema.mjs

@@ -16,7 +16,7 @@
 import {z} from 'zod';
 import {formatZodError} from '../_shared/errors.mjs';
 
-/** @typedef {import('./type').AstryxIntegration} AstryxIntegration */
+/** @typedef {import('./type.js').AstryxIntegration} AstryxIntegration */
 
 const MAX_AGENT_DOC_LINES = 8;
 const MAX_AGENT_DOC_LINE_CODE_POINTS = 240;
@@ -121,8 +121,8 @@ export function parseAgentDocsField(input, label) {
 /**
  * Compile-time drift-lock: sealed schema must infer exactly {@link AstryxIntegration}.
  *
- * @typedef {import('../_shared/contract').Expect<
- *   import('../_shared/contract').Equal<z.infer<typeof integrationSchema>, AstryxIntegration>
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').Equal<z.infer<typeof integrationSchema>, AstryxIntegration>
  * >} _IntegrationDriftLock
  */
 

package/authoring/integration/type.ts

@@ -11,7 +11,7 @@
  * The manifest module may also carry `debug` and `gapReport` NAMED exports.
  * They are not fields here on purpose: a CLI released before a given manifest
  * field existed could reject it and lose every contribution, while an unknown
- * named export is simply not read. See the `cli-integrations` doc topic.
+ * named export is simply not read. See `astryx docs cli/integrations`.
  */
 export interface AstryxIntegration {
   /** Stable logical provider ID. Omit to use package.json#name. Set this only
@@ -34,15 +34,9 @@ export interface AstryxIntegration {
    *  serves from `astryx docs`, alongside the built-in ones. A topic may also
    *  `replace` or `extend` a built-in topic; see the ReferenceDoc type. */
   docs?: string;
-  /** Relative path to the source-theme catalog root (resolved to absolute).
-   *  The root contains `manifest.json` plus one directory per theme slug.
-   *  `manifest.json` is `{ "version": 1, "themes": [...] }` where each
-   *  entry requires `slug`, `displayName`, `description` (string),
-   *  `maintained` (boolean), `entry` (source file relative to `themes/<slug>/`),
-   *  `exportName` (a valid JS identifier naming the runtime export), and
-   *  `files` (non-empty array of filenames relative to `themes/<slug>/`).
-   *  Every file listed must exist on disk; the entry file must also appear
-   *  in `files`. */
+  /** Relative path to the source-theme root (resolved to absolute). Each
+   *  lower-kebab theme directory contains a source module and mandatory
+   *  same-stem, strongly typed `.doc.mjs` descriptor. */
   themes?: string;
   /** Static package guidance appended to the CLI-owned managed agent block. */
   agentDocs?: {
@@ -66,4 +60,4 @@ export type {
   GapReportCategory,
   GapReportTarget,
   GapReportHandlerReceipt,
-} from '../gap-report/type';
+} from '../gap-report/type.js';

package/clients/cli/__tests__/cliManifest.test.ts

@@ -3,37 +3,35 @@
 import fs from 'fs';
 import path from 'path';
 import {describe, it, expect} from 'vitest';
-
-describe('@astryxdesign/cli Theme Manifest & Template Validation', () => {
-  const manifestPath = path.resolve(
-    'packages/cli/assets/templates/themes/manifest.json',
-  );
-
-  it('validates theme manifest existence and structure', () => {
-    expect(fs.existsSync(manifestPath)).toBe(true);
-    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-
-    expect(manifest.version).toBe(1);
-    expect(Array.isArray(manifest.themes)).toBe(true);
-    expect(manifest.themes.length).toBeGreaterThan(0);
-  });
-
-  it('verifies all referenced theme files exist', () => {
-    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-    const themesDir = path.dirname(manifestPath);
-
-    for (const theme of manifest.themes) {
-      expect(theme.slug).toBeDefined();
-      expect(theme.displayName).toBeDefined();
-      expect(theme.entry).toBeDefined();
-
-      const entryPath = path.join(themesDir, theme.slug, theme.entry);
-      expect(fs.existsSync(entryPath)).toBe(true);
-
+import {discoverBundledThemes} from '../../../foundation/discovery/theme-discovery.mjs';
+
+describe('@astryxdesign/cli bundled theme descriptor validation', () => {
+  it('discovers typed descriptors and their same-stem source files', () => {
+    const themes = discoverBundledThemes();
+    expect(themes.length).toBeGreaterThan(0);
+
+    for (const theme of themes) {
+      expect(theme.slug).toBeTruthy();
+      expect(theme.displayName).toBeTruthy();
+      expect(theme.docPath).toBe(
+        path.join(
+          theme.sourceDir,
+          `${path.basename(theme.entry, path.extname(theme.entry))}.doc.mjs`,
+        ),
+      );
+      expect(fs.existsSync(theme.docPath)).toBe(true);
+      expect(fs.existsSync(path.join(theme.sourceDir, theme.entry))).toBe(true);
       for (const file of theme.files) {
-        const filePath = path.join(themesDir, theme.slug, file);
-        expect(fs.existsSync(filePath)).toBe(true);
+        expect(fs.existsSync(path.join(theme.sourceDir, file))).toBe(true);
       }
     }
   });
+
+  it('does not ship the obsolete central theme catalog', () => {
+    expect(
+      fs.existsSync(
+        path.resolve('packages/cli/assets/templates/themes/manifest.json'),
+      ),
+    ).toBe(false);
+  });
 });

package/clients/cli/command-load-failure.test.mjs

@@ -0,0 +1,83 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file A command whose module fails to import still answers: with --json, one
+ * error envelope on stdout; without it, the error on stderr. Exit 1 either way.
+ *
+ * The failure is injected with a module-load hook in a real subprocess, so the
+ * lazy command registry in index.mjs sees what a broken install would give it.
+ */
+
+import {describe, it, expect, beforeAll, afterAll} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {fileURLToPath, pathToFileURL} from 'node:url';
+
+const BIN = fileURLToPath(new URL('./bin/astryx.mjs', import.meta.url));
+
+/** @type {string} */
+let dir;
+/** @type {string} */
+let register;
+
+beforeAll(() => {
+  dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-load-failure-'));
+  const hooks = path.join(dir, 'hooks.mjs');
+  fs.writeFileSync(
+    hooks,
+    [
+      'export async function load(url, context, nextLoad) {',
+      "  if (url.endsWith('/clients/cli/commands/blog.mjs')) {",
+      "    throw new Error('simulated load failure');",
+      '  }',
+      '  return nextLoad(url, context);',
+      '}',
+      '',
+    ].join('\n'),
+  );
+  register = path.join(dir, 'register.mjs');
+  fs.writeFileSync(
+    register,
+    `import {register} from 'node:module';\nregister(${JSON.stringify(pathToFileURL(hooks).href)});\n`,
+  );
+});
+
+afterAll(() => {
+  fs.rmSync(dir, {recursive: true, force: true});
+});
+
+/** @param {string[]} args */
+function run(args) {
+  const res = spawnSync(
+    process.execPath,
+    ['--import', pathToFileURL(register).href, BIN, ...args],
+    {cwd: dir, encoding: 'utf-8', timeout: 20_000},
+  );
+  return {status: res.status, stdout: res.stdout, stderr: res.stderr};
+}
+
+describe('a command that fails to load', () => {
+  it('answers --json with one error envelope, exit 1', () => {
+    const {status, stdout, stderr} = run(['blog', '--json']);
+    expect(status).toBe(1);
+    expect(stderr).toBe('');
+    const envelope = JSON.parse(stdout);
+    expect(envelope).toMatchObject({apiVersion: 1, code: 'ERR_UNKNOWN'});
+    expect(envelope.error).toMatch(/blog.*simulated load failure/);
+  });
+
+  it('reports the failure on stderr without --json, exit 1', () => {
+    const {status, stdout, stderr} = run(['blog']);
+    expect(status).toBe(1);
+    expect(stdout).toBe('');
+    expect(stderr).toMatch(/blog.*failed to load.*simulated load failure/s);
+  });
+
+  it('leaves the other commands working', () => {
+    const {status, stdout} = run(['docs', '--json']);
+    expect(status).toBe(0);
+    expect(JSON.parse(stdout).type).toMatch(/^docs\./);
+  });
+});

package/clients/cli/commands/blog.doc.mjs

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'blog',
   displayName: 'astryx blog',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Read the Astryx blog from the published feed',
   description:
     'Reads the design-system blog over its published RSS feed (never the source ' +

package/clients/cli/commands/blog.mjs

@@ -24,6 +24,18 @@ import {resultSet} from '../../../foundation/debug/index.mjs';
 import {doc as blogCommand} from './blog.doc.mjs';
 import {doc as blogFn} from '../../../api/blog/blog.doc.mjs';
 
+/** Every field of a post in the JSON, in order; record() skips empty ones. */
+const POST_FIELDS = [
+  'slug',
+  'title',
+  'description',
+  'date',
+  'type',
+  'authors',
+  'link',
+  'textUrl',
+];
+
 /**
  * @param {import('commander').Command} program
  */
@@ -62,22 +74,25 @@ export function registerBlog(program) {
         const {feedUrl, posts} = result.data;
         if (posts.length === 0) {
           emit(
-            section('Astryx blog', `feed: ${feedUrl}`),
+            section('Astryx blog'),
+            record({feedUrl}),
             text('No posts found in the feed.'),
           );
           return answered;
         }
-        // One record per post — fields mirror the JSON post shape; empty
-        // fields (type/textUrl) are skipped by record().
         emit(
-          section('Astryx blog', `feed: ${feedUrl}`),
-          records(posts, {fields: ['slug', 'title', 'type', 'textUrl']}),
+          section('Astryx blog'),
+          record({feedUrl}),
+          records(posts, {fields: POST_FIELDS}),
           text(`Read one: ${run} astryx blog <slug>`),
         );
       } else {
-        // blog.detail — the feed URL, then the post body emitted verbatim
-        // (code() so article typography/spacing isn't ASCII-normalized).
-        emit(record({feed: result.data.feedUrl}), code(result.data.text));
+        // blog.detail — the post's fields and the feed URL, then the body
+        // verbatim (code() so article typography/spacing isn't ASCII-normalized).
+        emit(
+          record(result.data, {fields: [...POST_FIELDS, 'feedUrl']}),
+          code(result.data.text),
+        );
       }
       return answered;
     },

package/clients/cli/commands/blog.test.mjs

@@ -19,7 +19,10 @@ const FEED = `<?xml version="1.0" encoding="UTF-8"?>
     <item>
       <title>How Astryx works</title>
       <link>${SITE_URL}/blog/how-astryx-works</link>
+      <description>Under the hood &amp; more</description>
       <category>engineering</category>
+      <author>Ada</author>
+      <author>Grace</author>
       <pubDate>Mon, 29 Jun 2026 00:00:00 GMT</pubDate>
       <atom:link rel="alternate" type="text/plain" href="${SITE_URL}/blog/how-astryx-works.txt" />
     </item>
@@ -39,6 +42,23 @@ function stubFetch(routes) {
   });
 }
 
+/**
+ * Every non-empty field prints as a `key: value` line under its JSON key.
+ * @param {string} stdout
+ * @param {Record<string, unknown>} fields
+ */
+function expectFields(stdout, fields) {
+  const lines = stdout.split('\n');
+  for (const [key, value] of Object.entries(fields)) {
+    if (value == null || value === '' || (Array.isArray(value) && !value.length)) continue;
+    const shown = Array.isArray(value) ? value.join(', ') : String(value);
+    expect(
+      lines.some(line => line.startsWith(`${key}:`) && line.trimEnd().endsWith(shown)),
+      `${key}: ${shown}`,
+    ).toBe(true);
+  }
+}
+
 beforeEach(() => {
   vi.stubGlobal(
     'fetch',
@@ -83,10 +103,31 @@ describe('blog CLI — json-enabled', () => {
     const {status, stdout} = await runCli(['blog']);
     expect(status).toBe(0);
     expect(stdout).toMatch(/Astryx blog/);
-    expect(stdout).toMatch(/feed:/);
+    expect(stdout).toMatch(/^feedUrl:/m);
     expect(stdout).toMatch(/how-astryx-works/);
   });
 
+  it('the text list projects every JSON field under its JSON key', async () => {
+    const env = JSON.parse((await runCli(['blog', '--json'])).stdout);
+    const {status, stdout} = await runCli(['blog']);
+    expect(status).toBe(0);
+    expectFields(stdout, {feedUrl: env.data.feedUrl});
+    for (const post of env.data.posts) expectFields(stdout, post);
+    expect(stdout).not.toMatch(/^feed:/m);
+  });
+
+  it('the text detail projects every JSON field, then the post body', async () => {
+    const env = JSON.parse(
+      (await runCli(['blog', 'how-astryx-works', '--json'])).stdout,
+    );
+    const {status, stdout} = await runCli(['blog', 'how-astryx-works']);
+    expect(status).toBe(0);
+    const {text, ...fields} = env.data;
+    expectFields(stdout, fields);
+    expect(stdout).toContain(text);
+    expect(stdout).not.toMatch(/^feed:/m);
+  });
+
   it('surfaces the API error code and exits non-zero for an unknown slug (--json)', async () => {
     const {status, stdout} = await runCli(['blog', 'no-such-post', '--json']);
     expect(status).not.toBe(0);

package/clients/cli/commands/build-theme.adaptations.test.mjs

@@ -3,7 +3,8 @@
 /**
  * @file Ensures `astryx theme build` preserves AST-012 adaptation semantics.
  * Runtime and static output share core's compiler; this suite guards the CLI
- * loading, diagnostics, serialization, and extension boundaries around it.
+ * loading, diagnostics, serialization, and extension boundaries around it,
+ * including root component overrides underneath adapted typography scales.
  */
 
 import {afterEach, beforeAll, beforeEach, describe, expect, it} from 'vitest';
@@ -94,6 +95,104 @@ describe('theme build adaptations', () => {
     );
   });
 
+  it.each([
+    ['defined', writeTheme],
+    ['plain', writePlainTheme],
+  ])(
+    'preserves component pins in %s themes and built extensions',
+    async (_kind, write) => {
+      const {defineTheme, generateAdaptationCSS, generateThemeCSS} =
+        await import('@astryxdesign/core/theme');
+      const project = path.join(tmpDir, 'project');
+      const themesDir = path.join(project, 'themes');
+      const displayFamily =
+        'Sarina, "Brush Script MT", "Snell Roundhand", cursive';
+      const input = {
+        name: 'adaptive-display',
+        typography: {
+          scale: {base: 16, ratio: 1.25},
+          body: {family: 'Outfit', fallbacks: 'sans-serif'},
+        },
+        components: {
+          text: Object.fromEntries(
+            ['display-1', 'display-2', 'display-3'].map(type => [
+              `type:${type}`,
+              {fontFamily: displayFamily},
+            ]),
+          ),
+          button: {base: {borderRadius: '12px'}},
+        },
+        adaptations: {
+          rules: [
+            {
+              when: {width: {below: 'md'}, pointer: 'coarse'},
+              value: {typography: {scale: {base: 14, ratio: 1.2}}},
+            },
+            {
+              when: {contrast: 'more'},
+              value: {
+                typography: {scale: {base: 15}},
+                components: {
+                  text: {'type:display-1': {fontFamily: 'monospace'}},
+                },
+              },
+            },
+          ],
+        },
+      };
+      const themeFile = write(themesDir, input.name, JSON.stringify(input));
+      const result = await build(project, themeFile);
+      expect(result.code, result.stderr).toBe(0);
+      const css = fs.readFileSync(
+        path.join(themesDir, 'adaptive-display.css'),
+        'utf8',
+      );
+      const compact = value => value.replace(/\s+/g, ' ').trim();
+      const source = defineTheme(input);
+      const runtime = generateThemeCSS(source);
+      // The CLI wraps root, adaptation, and surface CSS in separate @layer
+      // blocks; their contents and order must still match runtime output.
+      const adaptationCSS = generateAdaptationCSS(source).component;
+      const [rootCSS, surfaceCSS] = runtime.component.split(adaptationCSS);
+      const blocks = [rootCSS, adaptationCSS, surfaceCSS].map(compact);
+      let previousIndex = -1;
+      for (const block of blocks) {
+        expect(compact(css)).toContain(block);
+        const index = compact(css).indexOf(block);
+        expect(index).toBeGreaterThan(previousIndex);
+        previousIndex = index;
+      }
+      expect(compact(css)).toContain(compact(runtime.prose));
+      const scaleBlock = css.slice(
+        css.indexOf('@media (width < 768px) and (pointer: coarse)'),
+        css.indexOf('@media (prefers-contrast: more)'),
+      );
+      expect(scaleBlock).toContain('--font-size-base: 0.875rem');
+      expect(scaleBlock).not.toContain('.astryx-text');
+      expect(scaleBlock).not.toContain('.astryx-heading');
+      expect(scaleBlock).not.toContain('.astryx-button');
+      expect(css).toContain(`font-family: ${displayFamily};`);
+      expect(css).toContain('font-family: monospace;');
+
+      const {adaptiveDisplayTheme: builtTheme} = await import(
+        pathToFileURL(path.join(themesDir, 'adaptive-display.js')).href
+      );
+      expect(builtTheme.__adaptationRules).toBeUndefined();
+      expect(generateThemeCSS(builtTheme)).toEqual(runtime);
+      const childInput = {
+        name: 'display-child',
+        components: {text: {'type:display-2': {fontFamily: 'serif'}}},
+      };
+      const fromSource = defineTheme({...childInput, extends: source});
+      const fromBuilt = defineTheme({...childInput, extends: builtTheme});
+      expect(generateThemeCSS(fromBuilt)).toEqual(generateThemeCSS(fromSource));
+      expect(fromBuilt.__adaptationRules[0].components).toBeUndefined();
+      expect(fromBuilt.components.text['type:display-2'].fontFamily).toBe(
+        'serif',
+      );
+    },
+  );
+
   it('resolves a plain object whose only input-only field is adaptations', async () => {
     const project = path.join(tmpDir, 'project');
     const themesDir = path.join(project, 'themes');