@astryxdesign/cli 0.6.3-canary.db4e378 → 0.6.3-canary.db52d98

package/api/template/template-suffix.test.mjs

@@ -1,25 +1,20 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file The canonical `.template.{ts,mjs,js}` suffix is discovered identically
- * to the legacy `.doc.{ts,mjs,js}` suffix.
+ * @file The canonical `.doc.{mjs,ts,js}` suffix is discovered identically
+ * to the released `.template.{ts,mjs,js}` compatibility suffix.
  *
- * Template-spec files are named for what they are: a scaffoldable TEMPLATE
- * stamped with `type: 'page' | 'block'`. The `.doc.*` suffix was
- * inherited from the component-doc convention and is still accepted during the
- * transition. These tests stand up integration templates and external blocks in
- * both families and assert byte-for-byte-equivalent discovery + scaffolding.
+ * New authoring writes `.doc.mjs`, the canonical typed descriptor. Stable
+ * 0.6.0 already accepted `.template.*`, so these tests
+ * keep that family as a compatibility input and assert equivalent discovery +
+ * scaffolding.
  */
 
 import {afterEach, beforeEach, describe, expect, it} from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
-import {
-  template,
-  findShowcase,
-  findRelatedBlocks,
-} from './template.mjs';
+import {template, findShowcase, findRelatedBlocks} from './template.mjs';
 
 let tmpDir;
 let originalCwd;
@@ -82,8 +77,8 @@ afterEach(() => {
   fs.rmSync(tmpDir, {recursive: true, force: true});
 });
 
-describe('integration templates: .template.* discovered like legacy .doc.*', () => {
-  for (const suffix of ['.template.ts', '.template.mjs', '.doc.mjs']) {
+describe('integration templates: canonical .doc.* plus released .template.* compatibility', () => {
+  for (const suffix of ['.doc.mjs', '.doc.ts', '.template.mjs']) {
     it(`discovers + lists a page template authored as ${suffix}`, async () => {
       const pkgDir = installWidgets(tmpDir);
       writeTemplate(pkgDir, 'pricing', {kind: 'page', suffix});
@@ -124,7 +119,7 @@ describe('integration templates: .template.* discovered like legacy .doc.*', ()
     });
   }
 
-  it('treats a .template.ts and a legacy .doc.mjs identically (same shape)', async () => {
+  it('treats canonical .doc.mjs and released .template.ts identically (same shape)', async () => {
     const pkgDir = installWidgets(tmpDir);
     writeTemplate(pkgDir, 'gauge', {kind: 'block', suffix: '.template.ts'});
     writeTemplate(pkgDir, 'chip', {kind: 'block', suffix: '.doc.mjs'});
@@ -143,12 +138,33 @@ describe('integration templates: .template.* discovered like legacy .doc.*', ()
     expect(gauge.type).toBe(chip.type);
     expect(gauge.package).toBe(chip.package);
   });
+  it('lists both same-stem specs and reads the id as ambiguous', async () => {
+    for (const [first, second] of [
+      ['.doc.mjs', '.template.ts'],
+      ['.doc.ts', '.doc.mjs'],
+    ]) {
+      const pkgDir = installWidgets(tmpDir);
+      fs.rmSync(path.join(pkgDir, 'templates'), {recursive: true, force: true});
+      writeTemplate(pkgDir, 'pricing', {kind: 'page', suffix: first});
+      writeTemplate(pkgDir, 'pricing', {kind: 'page', suffix: second});
+
+      const result = await template(undefined, {list: true, cwd: tmpDir});
+      expect(
+        result.data.filter(entry => entry.id === 'pricing'),
+        `${first} + ${second}`,
+      ).toHaveLength(2);
+      await expect(
+        template('pricing', {cwd: tmpDir}),
+        `${first} + ${second}`,
+      ).rejects.toMatchObject({code: 'ERR_AMBIGUOUS_TEMPLATE'});
+    }
+  });
 });
 
-describe('external showcase blocks: .template.* discovered like legacy .doc.*', () => {
+describe('external showcase blocks: canonical .doc.* plus released .template.* compatibility', () => {
   /**
    * Create a consumer whose @test/ext package contributes two showcase blocks,
-   * one authored as `Foo.template.ts` and one as legacy `Bar.doc.mjs`.
+   * one authored with released `Foo.template.ts` and one with canonical `Bar.doc.mjs`.
    */
   function makeShowcaseFixture() {
     // Symlink the real core package (needed by findCoreDir during discovery).
@@ -166,7 +182,7 @@ describe('external showcase blocks: .template.* discovered like legacy .doc.*',
     const extDir = path.join(tmpDir, 'node_modules', '@test', 'ext');
     const blocksDir = path.join(extDir, 'blocks', 'components');
 
-    // Foo showcase — canonical .template.ts (stamped type: 'block' default export).
+    // Foo showcase — released .template.ts compatibility input.
     const fooDir = path.join(blocksDir, 'Foo');
     fs.mkdirSync(fooDir, {recursive: true});
     fs.writeFileSync(
@@ -185,7 +201,7 @@ describe('external showcase blocks: .template.* discovered like legacy .doc.*',
       "'use client';\nexport default function FooShowcase() { return <div>Foo</div>; }",
     );
 
-    // Bar showcase — legacy .doc.mjs (export const doc).
+    // Bar showcase — canonical .doc.mjs (historical named export).
     const barDir = path.join(blocksDir, 'Bar');
     fs.mkdirSync(barDir, {recursive: true});
     fs.writeFileSync(
@@ -209,7 +225,11 @@ describe('external showcase blocks: .template.* discovered like legacy .doc.*',
       path.join(extDir, 'package.json'),
       JSON.stringify({
         name: '@test/ext',
-        astryx: {docs: './src', category: 'Common', blocks: './blocks/components'},
+        astryx: {
+          docs: './src',
+          category: 'Common',
+          blocks: './blocks/components',
+        },
       }),
     );
     fs.mkdirSync(path.join(extDir, 'src'), {recursive: true});
@@ -223,7 +243,7 @@ describe('external showcase blocks: .template.* discovered like legacy .doc.*',
     expect(result.filePath).toContain('FooShowcase.tsx');
   });
 
-  it('findShowcase resolves a legacy .doc.mjs external block by componentsUsed', async () => {
+  it('findShowcase resolves a canonical .doc.mjs external block by componentsUsed', async () => {
     makeShowcaseFixture();
     const result = await findShowcase('Bar', tmpDir);
     expect(result).not.toBeNull();

package/api/template/template.doc.mjs

@@ -11,20 +11,33 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'template',
+  namespace: 'cli/api',
   displayName: 'template()',
   summary: 'List, inspect, or scaffold page and block templates.',
   description:
     'One entry point for the template family: with no name it lists the discovered ' +
     "templates; with a name it returns that template's source, a layout skeleton, or " +
-    'scaffolds it into the project. Templates are discovered across core, external ' +
-    'packages, and integrations, so the same id can appear in more than one place; ' +
-    'narrow an ambiguous name with type and/or package. The cdn option writes the ' +
-    'annotated no-build-step CDN starter page, which ships as an asset rather than as ' +
+    'scaffolds it into the project. A configured integration may replace a Core ' +
+    'template id for unqualified discovery and lookup; package selection still ' +
+    'addresses the Core original. Other duplicate ids remain ambiguous and can be ' +
+    'narrowed by type and/or package. The cdn option writes the annotated ' +
+    'no-build-step CDN starter page, which ships as an asset rather than as ' +
     'a discovered template.',
   importPath: '@astryxdesign/cli/api',
   signature:
     'template(name?: string, options?: TemplateOptions): Promise<TemplateListResponse | TemplateShowResponse | TemplateSkeletonResponse | TemplateCopyResponse | TemplateCdnResponse>',
-  keywords: ['template', 'scaffold', 'page', 'block', 'skeleton', 'starter', 'cdn', 'esm', 'importmap', 'no-build'],
+  keywords: [
+    'template',
+    'scaffold',
+    'page',
+    'block',
+    'skeleton',
+    'starter',
+    'cdn',
+    'esm',
+    'importmap',
+    'no-build',
+  ],
   params: [
     {
       name: 'name',
@@ -69,7 +82,7 @@ export const doc = {
       name: 'options.package',
       type: 'string',
       description:
-        'Narrow lookups to templates from a specific owning package (core templates report @astryxdesign/core).',
+        'Narrow lookups to templates from a specific owning package. Without it, a valid integration replacement is selected for the Core id; use @astryxdesign/core to select the original.',
     },
     {
       name: 'options.targetPath',
@@ -95,7 +108,7 @@ export const doc = {
     {
       type: 'template.list',
       description:
-        'Every discovered template (page + block); each entry carries id, name, description, kind, owning package, optional category and componentsUsed, and readiness flags. Filtered by type/package when provided.',
+        'The effective templates (page + block); a valid integration replacement takes the place of its Core target and carries `replaces`. Pass `package` to list one package, including replaced Core originals.',
     },
     {
       type: 'template.show',
@@ -142,7 +155,15 @@ export const doc = {
   ],
   examples: [
     {label: 'List templates', code: 'const {data} = await template();'},
+    {
+      label: 'List exact Core ids',
+      code: "await template(undefined, {list: true, package: '@astryxdesign/core'});",
+    },
     {label: 'Show source', code: "await template('dashboard');"},
+    {
+      label: 'Select a replaced Core original',
+      code: "await template('shell-side-nav', {package: '@astryxdesign/core'});",
+    },
     {
       label: 'Layout skeleton',
       code: "await template('dashboard', {skeleton: true});",

package/api/template/template.mjs

@@ -15,7 +15,13 @@
  *   ./list, ./show, ./skeleton, ./copy, ./cdn and shared discovery in foundation/discovery.
  */
 
-import {discoverAll, pkgOf} from '../../foundation/discovery/template-adapter.mjs';
+import {
+  discoverAll,
+  discoverAllResolved,
+  discoverAllUnresolved,
+  pkgOf,
+  templateLookupIds,
+} from '../../foundation/discovery/template-adapter.mjs';
 import {AstryxError} from '../error.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 import {templateList} from './list/list.mjs';
@@ -88,18 +94,49 @@ export async function template(name, options = {}) {
     });
   }
 
-  const templates = await discoverAll(cwd);
+  const templates =
+    packageFilter === '@astryxdesign/core'
+      ? await discoverAllUnresolved(cwd)
+      : packageFilter
+        ? await discoverAllResolved(cwd)
+        : await discoverAll(cwd);
 
   if (list || (!name && !skeleton)) {
     return templateList(templates, {type, package: packageFilter});
   }
 
-  // Resolve `name` to a single template. The same id can appear across types
-  // and/or packages (e.g. a core "hero" page and an integration "hero"
-  // block); narrow with --type / --package.
-  let candidates = templates.filter(t => t.dirName === name);
-  if (type) candidates = candidates.filter(t => t.type === type);
-  if (packageFilter) candidates = candidates.filter(t => pkgOf(t) === packageFilter);
+  // Resolve `name` to a single template. Without an explicit package, an active
+  // integration replacement owns the Core id it names. Package-qualified lookup
+  // stays exact, which keeps the original addressable as
+  // `--package @astryxdesign/core`.
+  let pool = templates;
+  if (type) pool = pool.filter(t => t.type === type);
+  if (packageFilter) pool = pool.filter(t => pkgOf(t) === packageFilter);
+  // With no name there is nothing to replace; `--skeleton` alone must still
+  // fail as an unknown template.
+  const replacements =
+    packageFilter || name == null ? [] : pool.filter(t => t.replaces === name);
+  let candidates = packageFilter
+    ? pool.filter(t => t.dirName === (name ?? ''))
+    : replacements.length > 0
+      ? replacements
+      : pool.filter(t => templateLookupIds(t).includes(name ?? ''));
+
+  // A rejected same-id declaration must not displace Core for the bare command,
+  // but a different-kind integration template remains reachable with --type.
+  if (!packageFilter && !type && candidates.length > 1) {
+    const core = candidates.filter(t => pkgOf(t) === '@astryxdesign/core');
+    const rejected = candidates.filter(t => pkgOf(t) !== '@astryxdesign/core');
+    if (
+      core.length === 1 &&
+      rejected.length === candidates.length - 1 &&
+      rejected.every(
+        t => t.replacementRejected && t.replacementTarget === (name ?? ''),
+      )
+    ) {
+      candidates = core;
+    }
+  }
 
   if (name && candidates.length === 0) {
     throw new AstryxError(

package/api/template/template.type.d.mts

@@ -21,6 +21,10 @@ export type TemplateListEntry = {
      * - Owning package; core (built-in) templates report '@astryxdesign/core'.
      */
     package: string;
+    /**
+     * - Core template id this integration template replaces by default.
+     */
+    replaces?: string | undefined;
     /**
      * - Optional grouping/category label.
      */
@@ -116,17 +120,11 @@ export type TemplateOptions = {
      */
     cdn?: string | boolean | undefined;
     /**
-     * Filter templates by kind: 'page' or 'block'. Only applies to list views.
+     * Filter templates by kind: 'page' or 'block'. Narrows both list and direct lookup.
      */
     type?: "page" | "block" | undefined;
     /**
-     * Narrow to templates from a specific package (id-only lookups across packages are ambiguous).
+     * Narrow to templates from a specific package. Without it, a valid integration replacement is selected for the Core id;
      */
     package?: string | undefined;
-    targetPath?: string | undefined;
-    /**
-     * Overwrite an existing target file instead of erroring (ERR_FILE_EXISTS).
-     */
-    overwrite?: boolean | undefined;
-    cwd?: string | undefined;
 };

package/api/template/template.type.mjs

@@ -31,6 +31,7 @@
  * @property {string} description
  * @property {'page' | 'block'} type
  * @property {string} package - Owning package; core (built-in) templates report '@astryxdesign/core'.
+ * @property {string} [replaces] - Core template id this integration template replaces by default.
  * @property {string} [category] - Optional grouping/category label.
  * @property {string[]} [componentsUsed] - Component display names the template composes.
  * @property {number} [aspectRatio] - Block preview width/height ratio.
@@ -93,8 +94,8 @@
  * @property {boolean} [skeleton]
  * @property {boolean} [show]
  * @property {boolean | string} [cdn] Write the no-build-step CDN starter page instead of resolving a template. A string is used as the destination path.
- * @property {'page' | 'block'} [type] Filter templates by kind: 'page' or 'block'. Only applies to list views.
- * @property {string} [package] Narrow to templates from a specific package (id-only lookups across packages are ambiguous).
+ * @property {'page' | 'block'} [type] Filter templates by kind: 'page' or 'block'. Narrows both list and direct lookup.
+ * @property {string} [package] Narrow to templates from a specific package. Without it, a valid integration replacement is selected for the Core id; @astryxdesign/core explicitly selects the original.
  * @property {string} [targetPath]
  * @property {boolean} [overwrite] Overwrite an existing target file instead of erroring (ERR_FILE_EXISTS).
  * @property {string} [cwd]

package/api/theme/_adapter.d.mts

@@ -13,7 +13,7 @@
 export function listThemes(): BundledTheme[];
 /**
  * Bundled themes plus source themes from integrations installed in `cwd`.
- * A project/config load failure degrades to the bundled catalog, preserving the
+ * A project/config load failure degrades to the bundled set, preserving the
  * command's historical usefulness outside a configured project.
  * @param {string} [cwd]
  * @returns {Promise<import('../../foundation/discovery/theme-discovery.mjs').DiscoveredTheme[]>}
@@ -35,6 +35,5 @@ export function findTheme(slug?: string, options?: {
  */
 export type BundledTheme = Pick<import("../../foundation/discovery/theme-discovery.mjs").DiscoveredTheme, "slug" | "displayName" | "description" | "maintained" | "entry" | "exportName" | "files">;
 import { BUNDLED_THEME_PACKAGE } from '../../foundation/discovery/theme-discovery.mjs';
-import { MANIFEST_PATH } from '../../foundation/discovery/theme-discovery.mjs';
 import { THEMES_DIR } from '../../foundation/discovery/theme-discovery.mjs';
-export { BUNDLED_THEME_PACKAGE, MANIFEST_PATH, THEMES_DIR };
+export { BUNDLED_THEME_PACKAGE, THEMES_DIR };

package/api/theme/_adapter.mjs

@@ -5,20 +5,19 @@
  *
  * `listThemes()` intentionally keeps its historical synchronous, bundled-only
  * contract. Project-aware callers use `listAvailableThemes()`, which asks
- * Project for the bundled catalog plus every installed integration catalog.
+ * Project for the bundled themes plus every installed integration theme root.
  */
 
 import {Project} from '../../foundation/config/project.mjs';
 import {
   BUNDLED_THEME_PACKAGE,
-  MANIFEST_PATH,
   THEMES_DIR,
   discoverBundledThemes,
 } from '../../foundation/discovery/theme-discovery.mjs';
 import {AstryxError} from '../error.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 
-export {BUNDLED_THEME_PACKAGE, MANIFEST_PATH, THEMES_DIR};
+export {BUNDLED_THEME_PACKAGE, THEMES_DIR};
 
 /**
  * A bundled theme entry kept for the historical public `listThemes()` helper.
@@ -55,7 +54,7 @@ function availableBundledThemes() {
 /**
  * Load available themes with any package-owned integration issues found while
  * discovering them. The issue set lets a package-scoped lookup distinguish an
- * absent theme from an installed package whose catalog is broken.
+ * absent theme from an installed package whose theme descriptors are broken.
  * @param {string} cwd
  * @returns {Promise<{themes: import('../../foundation/discovery/theme-discovery.mjs').DiscoveredTheme[], issues: Array<import('../../foundation/integrations/issue').AstryxIntegrationIssue & {package: string}>}>}
  */
@@ -71,7 +70,7 @@ async function availableThemeState(cwd) {
 
 /**
  * Bundled themes plus source themes from integrations installed in `cwd`.
- * A project/config load failure degrades to the bundled catalog, preserving the
+ * A project/config load failure degrades to the bundled set, preserving the
  * command's historical usefulness outside a configured project.
  * @param {string} [cwd]
  * @returns {Promise<import('../../foundation/discovery/theme-discovery.mjs').DiscoveredTheme[]>}

package/api/theme/add/add.binary.test.mjs

@@ -37,21 +37,10 @@ beforeEach(() => {
     "export default {themes: './themes'};\n",
   );
   fs.writeFileSync(
-    path.join(packageDir, 'themes', 'manifest.json'),
-    JSON.stringify({
-      version: 1,
-      themes: [
-        {
-          slug: 'ocean',
-          displayName: 'Ocean',
-          description: 'Integration theme that ships a font.',
-          maintained: true,
-          entry: 'oceanTheme.ts',
-          exportName: 'oceanTheme',
-          files: ['oceanTheme.ts', 'fonts/ocean.woff2'],
-        },
-      ],
-    }),
+    path.join(themeDir, 'oceanTheme.doc.mjs'),
+    `/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
+export default {type: 'theme', name: 'ocean', displayName: 'Ocean', description: 'Integration theme that ships a font.', maintained: true};
+`,
   );
   fs.writeFileSync(
     path.join(themeDir, 'oceanTheme.ts'),
@@ -64,14 +53,18 @@ afterEach(() => {
   fs.rmSync(tmpDir, {recursive: true, force: true});
 });
 
-describe('themeAdd copies every listed file', () => {
+describe('themeAdd copies every file of the theme', () => {
   it('copies a binary file byte for byte', async () => {
     const result = await themeAdd('ocean', {
       cwd: tmpDir,
       package: '@acme/themes',
     });
 
-    expect(result.data.files).toEqual(['oceanTheme.ts', 'fonts/ocean.woff2']);
+    expect(result.data.files).toEqual([
+      'oceanTheme.ts',
+      'fonts/ocean.woff2',
+      'oceanTheme.doc.mjs',
+    ]);
     const copied = fs.readFileSync(
       path.join(tmpDir, 'src', 'themes', 'ocean', 'fonts', 'ocean.woff2'),
     );

package/api/theme/add/add.test.mjs

@@ -30,7 +30,20 @@ describe('themeAdd (api/theme/add)', () => {
     expect(result.data.slug).toBe('neutral');
     expect(result.data.package).toBe('@astryxdesign/cli');
     expect(result.data.outputDir).toBe(path.join('src', 'themes', 'neutral'));
-    expect(result.data.files.length).toBeGreaterThan(0);
+    // Exactly what the bundle has always copied, in that order: the CLI's own
+    // descriptor stays behind.
+    expect(result.data.files).toEqual([
+      'neutralTheme.ts',
+      'icons.tsx',
+      'neutralPalettes.ts',
+      'neutralPalettes.generated.ts',
+      'neutralPaletteRefs.generated.ts',
+      'neutralPalettes.generated.receipt.json',
+      'palette.config.json',
+    ]);
+    expect(
+      fs.readdirSync(path.join(tmpDir, 'src', 'themes', 'neutral')).sort(),
+    ).toEqual([...result.data.files].sort());
     for (const f of result.data.files) {
       expect(
         fs.existsSync(path.join(tmpDir, 'src', 'themes', 'neutral', f)),

package/api/theme/generateTonalPalette.doc.mjs

@@ -5,6 +5,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'generateTonalPalette',
+  namespace: 'cli/api',
   displayName: 'generateTonalPalette()',
   summary: 'Generate candidate tonal palette data without filesystem effects.',
   description:

package/api/theme/integration-themes.test.mjs

@@ -7,18 +7,14 @@ import {themeAdd} from './add/add.mjs';
 
 let tmpDir;
 
-function installThemeIntegration(
-  packageName,
-  slug,
-  source = 'export const oceanTheme = {};\n',
-  extraFiles = {},
-) {
+function installThemeIntegration(packageName, slug, source, extraFiles = {}) {
   const packageDir = path.join(
     tmpDir,
     'node_modules',
     ...packageName.split('/'),
   );
   const themeDir = path.join(packageDir, 'themes', slug);
+  const stem = `${slug.replace(/-([a-z0-9])/gu, (_, character) => character.toUpperCase())}Theme`;
   fs.mkdirSync(themeDir, {recursive: true});
   fs.writeFileSync(
     path.join(packageDir, 'package.json'),
@@ -26,26 +22,21 @@ function installThemeIntegration(
   );
   fs.writeFileSync(
     path.join(packageDir, 'astryx.integration.mjs'),
-    `export default {themes: './themes'};\n`,
+    `export default {themes: './themes'};
+`,
   );
   fs.writeFileSync(
-    path.join(packageDir, 'themes', 'manifest.json'),
-    JSON.stringify({
-      version: 1,
-      themes: [
-        {
-          slug,
-          displayName: slug === 'neutral' ? 'Neutral Plus' : 'Ocean',
-          description: 'Integration-owned theme.',
-          maintained: true,
-          entry: 'oceanTheme.ts',
-          exportName: 'oceanTheme',
-          files: ['oceanTheme.ts', ...Object.keys(extraFiles)],
-        },
-      ],
-    }),
+    path.join(themeDir, `${stem}.doc.mjs`),
+    `/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
+export default {type: 'theme', name: '${slug}', displayName: '${slug === 'neutral' ? 'Neutral Plus' : 'Ocean'}', description: 'Integration-owned theme.', maintained: true};
+`,
+  );
+  fs.writeFileSync(
+    path.join(themeDir, `${stem}.ts`),
+    source ??
+      `export const ${stem} = {};
+`,
   );
-  fs.writeFileSync(path.join(themeDir, 'oceanTheme.ts'), source);
   for (const [relativePath, contents] of Object.entries(extraFiles)) {
     const file = path.join(themeDir, relativePath);
     fs.mkdirSync(path.dirname(file), {recursive: true});
@@ -85,23 +76,43 @@ describe('themeAdd with integration themes', () => {
     ).toContain('oceanTheme');
   });
 
-  it('copies nested files listed by an integration theme catalog', async () => {
+  it('copies the complete nested integration theme directory', async () => {
     installThemeIntegration(
       '@acme/themes',
       'ocean',
       "import {oceanBlue} from './tokens/colors';\nexport const oceanTheme = {oceanBlue};\n",
-      {'tokens/colors.ts': "export const oceanBlue = '#0064e0';\n"},
+      {
+        'tokens/colors.ts': "export const oceanBlue = '#0064e0';\n",
+        'receipts/palette.json': '{"version":1}\n',
+      },
     );
 
     const result = await themeAdd('ocean', {cwd: tmpDir});
 
-    expect(result.data.files).toEqual(['oceanTheme.ts', 'tokens/colors.ts']);
+    expect(result.data.files).toEqual([
+      'oceanTheme.ts',
+      'oceanTheme.doc.mjs',
+      'receipts/palette.json',
+      'tokens/colors.ts',
+    ]);
+    expect(
+      fs.readFileSync(
+        path.join(tmpDir, 'src', 'themes', 'ocean', 'oceanTheme.doc.mjs'),
+        'utf-8',
+      ),
+    ).toContain("type: 'theme'");
     expect(
       fs.readFileSync(
         path.join(tmpDir, 'src', 'themes', 'ocean', 'tokens', 'colors.ts'),
         'utf-8',
       ),
     ).toContain('oceanBlue');
+    expect(
+      fs.readFileSync(
+        path.join(tmpDir, 'src', 'themes', 'ocean', 'receipts', 'palette.json'),
+        'utf-8',
+      ),
+    ).toBe('{"version":1}\n');
   });
 
   it('rejects a nested destination symlink that escapes the project', async () => {
@@ -146,7 +157,7 @@ describe('themeAdd with integration themes', () => {
     expect(result.data.package).toBe('@acme/themes');
   });
 
-  it('reports a selected installed package with a corrupted theme catalog', async () => {
+  it('reports a selected installed package with a corrupted theme directory', async () => {
     installThemeIntegration(
       '@acme/themes',
       'ocean',
@@ -170,7 +181,7 @@ describe('themeAdd with integration themes', () => {
       themeAdd('ocean', {cwd: tmpDir, package: '@acme/themes'}),
     ).rejects.toMatchObject({
       code: 'ERR_THEME_INVALID',
-      message: expect.stringContaining('tokens/colors.ts'),
+      message: expect.stringContaining('./tokens/colors'),
     });
   });
 

package/api/theme/list/list.test.mjs

@@ -9,8 +9,13 @@ import {BUNDLED_THEME_PACKAGE} from '../../../foundation/discovery/theme-discove
 let tmpDir;
 
 function installThemeIntegration(packageName = '@acme/themes', slug = 'ocean') {
-  const packageDir = path.join(tmpDir, 'node_modules', ...packageName.split('/'));
+  const packageDir = path.join(
+    tmpDir,
+    'node_modules',
+    ...packageName.split('/'),
+  );
   const themeDir = path.join(packageDir, 'themes', slug);
+  const stem = `${slug.replace(/-([a-z0-9])/gu, (_, character) => character.toUpperCase())}Theme`;
   fs.mkdirSync(themeDir, {recursive: true});
   fs.writeFileSync(
     path.join(packageDir, 'package.json'),
@@ -18,28 +23,19 @@ function installThemeIntegration(packageName = '@acme/themes', slug = 'ocean') {
   );
   fs.writeFileSync(
     path.join(packageDir, 'astryx.integration.mjs'),
-    `export default {themes: './themes'};\n`,
+    `export default {themes: './themes'};
+`,
   );
   fs.writeFileSync(
-    path.join(packageDir, 'themes', 'manifest.json'),
-    JSON.stringify({
-      version: 1,
-      themes: [
-        {
-          slug,
-          displayName: 'Ocean',
-          description: 'Blue and calm.',
-          maintained: true,
-          entry: 'oceanTheme.ts',
-          exportName: 'oceanTheme',
-          files: ['oceanTheme.ts'],
-        },
-      ],
-    }),
+    path.join(themeDir, `${stem}.doc.mjs`),
+    `/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
+export default {type: 'theme', name: '${slug}', displayName: 'Ocean', description: 'Blue and calm.', maintained: true};
+`,
   );
   fs.writeFileSync(
-    path.join(themeDir, 'oceanTheme.ts'),
-    'export const oceanTheme = {};\n',
+    path.join(themeDir, `${stem}.ts`),
+    `export const ${stem} = {};
+`,
   );
 }
 
@@ -47,7 +43,10 @@ beforeEach(() => {
   tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-theme-list-'));
   fs.writeFileSync(
     path.join(tmpDir, 'package.json'),
-    JSON.stringify({name: 'consumer', dependencies: {'@acme/themes': '^1.0.0'}}),
+    JSON.stringify({
+      name: 'consumer',
+      dependencies: {'@acme/themes': '^1.0.0'},
+    }),
   );
 });