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

package/foundation/discovery/docs-section-key.mjs

@@ -34,7 +34,10 @@ const SOURCE_TITLE = Symbol('astryx.docs.sourceTitle');
  * @returns {T}
  */
 export function withSourceTitle(section, title) {
-  Object.defineProperty(section, SOURCE_TITLE, {value: title, configurable: true});
+  Object.defineProperty(section, SOURCE_TITLE, {
+    value: title,
+    configurable: true,
+  });
   return section;
 }
 
@@ -77,9 +80,63 @@ export function sectionKey(section) {
 }
 
 /**
- * Problems with the keys of a topic's sections: an authored id that is not a
- * stable key, a title no key derives from, and two sections sharing a key.
- * Keys are never suffixed to make them unique, because readers link to them.
+ * The first section the 0.6.x title-substring lookup would return for a query.
+ * @param {any[]} sections
+ * @param {string} query
+ * @returns {number}
+ */
+function legacyTitleMatchIndex(sections, query) {
+  const lower = query.toLowerCase();
+  return sections.findIndex(section => {
+    const title = sourceTitle(section);
+    return typeof title === 'string' && title.toLowerCase().includes(lower);
+  });
+}
+
+/**
+ * Fatal key problems: only an explicitly authored `id` can make a previously
+ * readable topic invalid. Derived-key collisions and titles with no Latin
+ * letters or digits are handled by {@link withSectionKeys} for 0.6.x
+ * compatibility.
+ * @param {any[]} sections
+ * @returns {string[]}
+ */
+export function sectionKeyErrors(sections) {
+  /** @type {string[]} */
+  const problems = [];
+  /** @type {Map<string, number>} */
+  const seen = new Map();
+  sections.forEach((section, s) => {
+    if (section?.id == null) return;
+    const at = `sections[${s}]`;
+    if (typeof section.id !== 'string' || !SECTION_KEY_RE.test(section.id)) {
+      problems.push(
+        `${at}.id: ${JSON.stringify(section.id)} is not a stable key. Use lowercase letters and digits joined by single hyphens.`,
+      );
+      return;
+    }
+    const first = seen.get(section.id);
+    if (first != null) {
+      problems.push(
+        `${at}: the key "${section.id}" is already used by sections[${first}]. Give one of them a distinct id.`,
+      );
+      return;
+    }
+    const legacyOwner = legacyTitleMatchIndex(sections, section.id);
+    if (legacyOwner !== -1 && legacyOwner !== s) {
+      problems.push(
+        `${at}.id: the key "${section.id}" is already a legacy title query for sections[${legacyOwner}]. Choose an id that resolves to this section.`,
+      );
+      return;
+    }
+    seen.set(section.id, s);
+  });
+  return problems;
+}
+
+/**
+ * Compatibility notices for section keys. These inputs loaded in 0.6.x, so
+ * readers keep accepting them and assign deterministic fallback keys.
  * @param {any[]} sections
  * @returns {string[]}
  */
@@ -90,7 +147,6 @@ export function sectionKeyProblems(sections) {
   const seen = new Map();
   sections.forEach((section, s) => {
     const at = `sections[${s}]`;
-    // A missing title is reported where titles are checked; no key to judge.
     if (
       section?.id == null &&
       (typeof section?.title !== 'string' || section.title === '')
@@ -109,14 +165,14 @@ export function sectionKeyProblems(sections) {
     const key = sectionKey(section);
     if (key === '') {
       problems.push(
-        `${at}: no key derives from the title ${JSON.stringify(section?.title)}. Give the section an id.`,
+        `${at}: no key derives from the title ${JSON.stringify(section?.title)}. A deterministic section-N compatibility key is used; add an explicit id.`,
       );
       return;
     }
     const first = seen.get(key);
     if (first != null) {
       problems.push(
-        `${at}: the key "${key}" is already used by sections[${first}]. Give one of them a distinct id or title.`,
+        `${at}: the key "${key}" is already used by sections[${first}]. A suffixed compatibility key is used for title-derived collisions; give one of them a distinct id or title.`,
       );
       return;
     }
@@ -133,48 +189,79 @@ export function sectionKeyProblems(sections) {
  * @returns {T}
  */
 export function withSectionKeys(doc) {
+  const reserved = new Set(
+    doc.sections
+      .map(section => section?.id)
+      .filter(id => typeof id === 'string' && SECTION_KEY_RE.test(id)),
+  );
+  const used = new Set();
   return {
     ...doc,
-    sections: doc.sections.map(section =>
-      section.id != null
-        ? section
-        : withSourceTitle(
-            {...section, id: sectionKey(section)},
-            sourceTitle(section),
-          ),
-    ),
+    sections: doc.sections.map((section, index) => {
+      if (section.id != null) {
+        used.add(section.id);
+        return section;
+      }
+      const base =
+        sectionTitleKey(sourceTitle(section)) || `section-${index + 1}`;
+      let key = base;
+      let suffix = 2;
+      while (
+        reserved.has(key) ||
+        used.has(key) ||
+        (legacyTitleMatchIndex(doc.sections, key) !== -1 &&
+          legacyTitleMatchIndex(doc.sections, key) !== index)
+      ) {
+        key = `${base}-${suffix}`;
+        suffix += 1;
+      }
+      used.add(key);
+      return withSourceTitle({...section, id: key}, sourceTitle(section));
+    }),
   };
 }
 
 /**
- * Find the section a reader asked for: by key, then by exact title (or the
- * key the query derives), then by a title that contains the query. More than
- * one match is refused rather than guessed.
+ * Find the section a reader asked for. The 0.6.x first-match title-substring
+ * lookup remains first in the authored-title view. In a localized view, an
+ * exact stable key resolves before translated title substrings because those
+ * translations cannot participate in language-stable key allocation. Generated
+ * keys avoid authored-title conflicts, and authored IDs that would shadow an
+ * authored legacy query are rejected.
  * @param {any[]} sections
  * @param {string} query
- * @returns {{section: any | null, candidates: any[]}} `candidates` lists the
- *   matches when the query is ambiguous, and is empty when nothing matches
+ * @returns {{section: any | null, candidates: any[]}} `candidates` lists every
+ *   legacy title match when the query is ambiguous
  */
 export function findDocSection(sections, query) {
   const wanted = query.trim();
   const byKey = sections.find(section => sectionKey(section) === wanted);
-  if (byKey) return {section: byKey, candidates: []};
+  const hasLocalizedTitles = sections.some(
+    section => sourceTitle(section) !== section.title,
+  );
+  if (byKey && hasLocalizedTitles) {
+    return {section: byKey, candidates: []};
+  }
 
   const lower = wanted.toLowerCase();
-  const derived = sectionTitleKey(wanted);
-  const exact = sections.filter(
-    section =>
-      section.title.toLowerCase() === lower ||
-      (derived !== '' && sectionTitleKey(sourceTitle(section)) === derived),
+  const legacy = sections.filter(section =>
+    section.title.toLowerCase().includes(lower),
   );
-  if (exact.length === 1) return {section: exact[0], candidates: []};
-  if (exact.length > 1) return {section: null, candidates: exact};
+  if (legacy.length > 0) {
+    return {section: legacy[0], candidates: legacy.length > 1 ? legacy : []};
+  }
 
-  const partial = sections.filter(section =>
-    section.title.toLowerCase().includes(lower),
+  const byFallbackKey = sections.find(
+    section => sectionKey(section) === wanted,
+  );
+  if (byFallbackKey) return {section: byFallbackKey, candidates: []};
+
+  const derived = sectionTitleKey(wanted);
+  const byDerivedKey = sections.find(
+    section =>
+      derived !== '' && sectionTitleKey(sourceTitle(section)) === derived,
   );
-  if (partial.length === 1) return {section: partial[0], candidates: []};
-  return {section: null, candidates: partial};
+  return {section: byDerivedKey ?? null, candidates: []};
 }
 
 /**

package/foundation/discovery/docs-section-key.test.mjs

@@ -7,6 +7,7 @@ import {
   buildDocsIndexData,
   findDocSection,
   sectionKey,
+  sectionKeyErrors,
   sectionKeyProblems,
   sectionSummary,
   sectionTitleKey,
@@ -68,12 +69,17 @@ describe('sectionKeyProblems', () => {
       section('Quick-start'),
     ]);
     expect(problems).toHaveLength(1);
-    expect(problems[0]).toContain('"quick-start" is already used by sections[0]');
+    expect(problems[0]).toContain(
+      '"quick-start" is already used by sections[0]',
+    );
   });
 
   it('rejects an authored id that collides with a derived key', () => {
     expect(
-      sectionKeyProblems([section('Install'), section('Setup', {id: 'install'})]),
+      sectionKeyProblems([
+        section('Install'),
+        section('Setup', {id: 'install'}),
+      ]),
     ).toHaveLength(1);
   });
 
@@ -85,13 +91,13 @@ describe('sectionKeyProblems', () => {
     }
   });
 
-  it('rejects a title no key derives from', () => {
+  it('reports a title no key derives from', () => {
     expect(sectionKeyProblems([section('亮/暗模式')])[0]).toContain(
-      'Give the section an id',
-    );
-    expect(sectionKeyProblems([section('亮/暗模式', {id: 'light-dark'})])).toEqual(
-      [],
+      'compatibility key is used',
     );
+    expect(
+      sectionKeyProblems([section('亮/暗模式', {id: 'light-dark'})]),
+    ).toEqual([]);
   });
 
   it('leaves a missing title to the title check', () => {
@@ -107,12 +113,21 @@ describe('withSectionKeys', () => {
     expect(doc.sections.map(s => s.id)).toEqual(['quick-start', 'use']);
   });
 
-  it('keeps the authored title of a translated section', () => {
+  it('keeps authored titles and keys stable for translated sections', () => {
     const doc = withSectionKeys({
-      sections: [withSourceTitle(section('快速开始'), 'Quick Start')],
+      sections: [
+        withSourceTitle(section('高级安装'), 'Install advanced'),
+        withSourceTitle(section('安装'), 'Install'),
+      ],
     });
-    expect(doc.sections[0].id).toBe('quick-start');
-    expect(sourceTitle(doc.sections[0])).toBe('Quick Start');
+    expect(doc.sections.map(s => s.id)).toEqual([
+      'install-advanced',
+      'install-2',
+    ]);
+    for (const target of doc.sections) {
+      expect(findDocSection(doc.sections, target.id).section).toBe(target);
+    }
+    expect(sourceTitle(doc.sections[0])).toBe('Install advanced');
   });
 });
 
@@ -127,7 +142,14 @@ describe('findDocSection', () => {
     ],
   }).sections;
 
-  it('finds a section by key first', () => {
+  it('finds every emitted key without changing a legacy query', () => {
+    const colliding = withSectionKeys({
+      sections: [section('Install advanced'), section('Install')],
+    }).sections;
+    expect(findDocSection(colliding, 'install').section).toBe(colliding[0]);
+    for (const target of colliding) {
+      expect(findDocSection(colliding, target.id).section).toBe(target);
+    }
     expect(findDocSection(sections, 'tokens').section.title).toBe(
       'Theme Tokens',
     );
@@ -149,15 +171,15 @@ describe('findDocSection', () => {
     expect(findDocSection(sections, 'props').section.id).toBe('theme-props');
   });
 
-  it('refuses an ambiguous exact title and lists the candidates', () => {
+  it('keeps the first ambiguous exact-title match and lists the candidates', () => {
     const {section: match, candidates} = findDocSection(sections, 'Overview');
-    expect(match).toBeNull();
+    expect(match?.id).toBe('overview-a');
     expect(candidates.map(s => s.id)).toEqual(['overview-a', 'overview-b']);
   });
 
-  it('refuses an ambiguous partial title', () => {
+  it('keeps the first ambiguous partial-title match', () => {
     const {section: match, candidates} = findDocSection(sections, 'theme');
-    expect(match).toBeNull();
+    expect(match?.id).toBe('theme-props');
     expect(candidates.map(s => s.id)).toEqual(['theme-props', 'tokens']);
   });
 
@@ -185,9 +207,9 @@ describe('sectionSummary', () => {
   });
 
   it('is empty when the section has no text', () => {
-    expect(sectionSummary({content: [{type: 'table', headers: [], rows: []}]})).toBe(
-      '',
-    );
+    expect(
+      sectionSummary({content: [{type: 'table', headers: [], rows: []}]}),
+    ).toBe('');
   });
 
   it('cuts a long summary at a word boundary', () => {

package/foundation/discovery/template-adapter.d.mts

@@ -37,6 +37,13 @@ export function stripTemplateAssetRefs(source: string): string;
  * @returns {string[]}
  */
 export function listTemplates(): string[];
+/**
+ * Resolve the template-spec file for a core page directory: the first existing
+ * metadata file in {@link ALL_TEMPLATE_SUFFIXES} precedence, or null.
+ * @param {string} dirPath
+ * @returns {string | null}
+ */
+export function findPageDocFile(dirPath: string): string | null;
 /**
  * Discover only the templates built into @astryxdesign/core. Integration
  * authoring checks use this narrower surface so a broken project config or a

package/foundation/discovery/template-adapter.mjs

@@ -24,9 +24,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {createRequire} from 'node:module';
-import {createJiti} from 'jiti';
-import {loadModuleWithParser} from '../fs/module-loader.mjs';
-import {parseTemplate} from '../../authoring/doctypes/template/parse.mjs';
+import {readDocView} from '../doc-compiler/read.mjs';
 import {CLI_ROOT, discoverExternalPackages} from '../fs/paths.mjs';
 import {CORE_PROVIDER_ID} from '../identity/providers.mjs';
 import {Project} from '../config/project.mjs';
@@ -84,31 +82,28 @@ export function pkgOf(t) {
  */
 
 /**
- * Canonical basename suffixes for template-spec files, in precedence order.
- * A template spec is a scaffoldable TEMPLATE (a plain object stamped with a
- * `type` of `'page'` or `'block'`), so `.template.*` is the descriptive family
- * name.
+ * Released compatibility suffixes, in precedence order. Stable 0.6.0
+ * documented `.template.*`, so discovery keeps reading those files while all
+ * new authoring uses `.doc.mjs`.
  */
 const TEMPLATE_SUFFIXES = ['.template.ts', '.template.mjs', '.template.js'];
 
 /**
- * Legacy basename suffixes for template-spec files, in precedence order.
- * `.doc.*` was inherited from the component-doc convention before templates
- * had their own name; it is still accepted during the transition window.
+ * Descriptor suffixes for templates, in precedence order. New authoring always
+ * emits `.doc.mjs`; the TypeScript and JavaScript variants remain readable.
  */
 const DOC_SUFFIXES = ['.doc.ts', '.doc.mjs', '.doc.js'];
 
 /**
- * The union of canonical + legacy template-spec suffixes, canonical first so
- * `.template.*` wins over `.doc.*` when both stems exist. All template
- * discovery matches this union so a `Foo.template.ts` file is treated exactly
- * like a legacy `Foo.doc.mjs`.
+ * Every template-spec suffix, in the released precedence a core page directory
+ * uses to pick one file. Integration discovery never picks: every match is a
+ * template, so two specs for one stem list twice and read as ambiguous.
  */
 const ALL_TEMPLATE_SUFFIXES = [...TEMPLATE_SUFFIXES, ...DOC_SUFFIXES];
 
 /**
  * The template-spec suffix present on `file`, or null if none matches.
- * Recognizes both the canonical `.template.*` and legacy `.doc.*` families.
+ * Recognizes both the canonical `.doc.*` and released `.template.*` families.
  * @param {string} file
  * @returns {string | null}
  */
@@ -122,16 +117,6 @@ function matchedTemplateSuffix(file) {
  */
 const TEMPLATE_SUFFIX_RE = /\.(template|doc)\.(ts|mjs|js)$/;
 
-/** @type {ReturnType<typeof createJiti> | undefined} */
-let jitiInstance;
-/** Lazily-created jiti for loading `.ts` template specs (JSX-capable). */
-function getJiti() {
-  if (!jitiInstance) {
-    jitiInstance = createJiti(import.meta.url, {jsx: true});
-  }
-  return jitiInstance;
-}
-
 /**
  * Load an integration template doc module and validate it against the template
  * envelope at the load boundary. Default export only — `.ts` via jiti,
@@ -144,7 +129,13 @@ function getJiti() {
  * @param {string} [label]
  */
 async function loadIntegrationDoc(file, label) {
-  return loadModuleWithParser(file, parseTemplate, {label});
+  return readDocView(file, {
+    root: 'templates',
+    exports: ['default'],
+    label: label ?? file,
+    strict: true,
+    value: 'parsed',
+  });
 }
 
 const TEMPLATES_DIR = path.join(CLI_ROOT, 'assets', 'templates');
@@ -492,12 +483,11 @@ function unsafeFixtureReference(source, at, reason) {
 /**
  * Load a template-spec module and return its metadata object. Supports both
  * families of suffix:
- *   - Legacy `.doc.*` core/external specs export `export const doc = {...}`.
- *   - Canonical `.template.*` specs export the stamped object (`type: 'page' |
- *     'block'`) as the default export.
- * Prefers the default export, falling back to the named `doc` export, so a
- * `Foo.template.ts` (default export) is read identically to a legacy
- * `Foo.doc.mjs` (`doc` export). `.ts` is loaded via jiti; `.mjs`/`.js` via a
+ *   - Canonical `.doc.*` specs may export the stamped object (`type: 'page' |
+ *     'block'`) as the default export or use the historical named `doc` export.
+ *   - Released `.template.*` compatibility specs use the same object shape.
+ * Prefers the default export, falling back to the named `doc` export. `.ts` is
+ * loaded via jiti; `.mjs`/`.js` via a
  * native dynamic import. Returns null if the file does not exist.
  *
  * @param {string} docPath absolute path to the spec file
@@ -505,10 +495,7 @@ function unsafeFixtureReference(source, at, reason) {
  */
 async function loadDocModule(docPath) {
   if (!fs.existsSync(docPath)) return null;
-  const docModule = docPath.endsWith('.ts')
-    ? await getJiti().import(docPath)
-    : await import(`file://${docPath}`);
-  return docModule.default ?? docModule.doc;
+  return readDocView(docPath, {root: 'templates', loader: 'template'});
 }
 
 /**
@@ -553,11 +540,11 @@ function findDocFiles(dir, pattern) {
 
 /**
  * Resolve the template-spec file for a core page directory: the first existing
- * `template.<suffix>` in canonical-then-legacy precedence, or null.
+ * metadata file in {@link ALL_TEMPLATE_SUFFIXES} precedence, or null.
  * @param {string} dirPath
  * @returns {string | null}
  */
-function findPageDocFile(dirPath) {
+export function findPageDocFile(dirPath) {
   for (const suffix of ALL_TEMPLATE_SUFFIXES) {
     const candidate = path.join(dirPath, `template${suffix}`);
     if (fs.existsSync(candidate)) return candidate;
@@ -733,7 +720,7 @@ export async function discoverAllWithErrors(cwd = process.cwd()) {
 /**
  * Recursively collect integration template-spec files under `root`.
  * Returns absolute paths to files ending in one of ALL_TEMPLATE_SUFFIXES
- * (canonical `.template.*` or legacy `.doc.*`).
+ * (canonical `.doc.*` or released `.template.*` compatibility files).
  *
  * @param {string} root
  * @returns {string[]}
@@ -763,7 +750,7 @@ function findIntegrationDocFiles(root) {
  * Discover templates contributed by configured integrations.
  *
  * For each integration with a resolved `templates` root, every
- * `<id>.template.{ts,mjs,js}` (or legacy `<id>.doc.{ts,mjs,js}`) file is a
+ * canonical `<id>.doc.{mjs,ts,js}` (or released `<id>.template.{ts,mjs,js}`) file is a
  * template whose id is its path relative to the templates root with the
  * matched suffix stripped (kebab-case, may be nested). The doc's `type`
  * (page|block) decides scaffolding — there is no `/pages` vs `/blocks`

package/foundation/discovery/template-adapter.test.mjs

@@ -18,6 +18,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import {
   extractComponents,
+  findPageDocFile,
   stripTemplateAssetRefs,
 } from './template-adapter.mjs';
 
@@ -164,3 +165,17 @@ describe('stripTemplateAssetRefs', () => {
     );
   });
 });
+
+describe('findPageDocFile', () => {
+  it('keeps the released precedence when one page has two specs', () => {
+    const page = fs.mkdtempSync(path.join(dir, 'page-'));
+    fs.writeFileSync(path.join(page, 'template.doc.mjs'), 'export {};\n');
+    fs.writeFileSync(path.join(page, 'template.doc.ts'), 'export {};\n');
+    expect(findPageDocFile(page)).toBe(path.join(page, 'template.doc.ts'));
+
+    fs.writeFileSync(path.join(page, 'template.template.mjs'), 'export {};\n');
+    expect(findPageDocFile(page)).toBe(
+      path.join(page, 'template.template.mjs'),
+    );
+  });
+});

package/foundation/discovery/theme-discovery.d.mts

@@ -2,15 +2,65 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * Read and validate one theme catalog.
- * @param {string} themeRoot absolute catalog root
- * @param {string} owner package that owns the catalog
- * @param {{bundled?: boolean}} [options]
+ * How messages about a theme descriptor name it.
+ * @param {string} docPath
+ * @param {string} owner
+ */
+export function themeDescriptorLabel(docPath: string, owner: string): string;
+/**
+ * The static value a theme descriptor default-exports, read from its source
+ * without executing it. Throws when the file is not one static ThemeDoc
+ * object.
+ * @param {string} docPath
+ * @param {string} label
+ * @returns {Record<string, string | boolean>}
+ */
+export function readThemeDescriptorValue(docPath: string, label: string): Record<string, string | boolean>;
+/**
+ * Whether an entry at any depth of a themes root is outside every theme: a dot
+ * entry, or a name npm never publishes (npm-packlist's defaults).
+ * @param {string} name
+ */
+export function isIgnoredThemeEntry(name: string): boolean;
+/**
+ * Whether discovery reads a folder under a theme root as a theme. Dot-folders
+ * and folders with neither a descriptor nor a `<name>Theme` source are not.
+ * @param {string} folder absolute path
+ */
+export function isThemeFolder(folder: string): boolean;
+/**
+ * The files one theme folder ships: every regular file below it except
+ * {@link isIgnoredThemeEntry} entries. What pack-check requires and what
+ * `theme add` copies.
+ * @param {string} folder absolute path
+ * @returns {string[]} sorted POSIX paths relative to the folder
+ */
+export function listThemeFiles(folder: string): string[];
+/**
+ * Discover and validate one theme root.
+ * @param {string} themeRoot absolute root containing one directory per slug
+ * @param {string} owner package that owns the root
+ * @param {{bundled?: boolean}} [options] a bundled root is the CLI's own; its
+ *   sources are checked by the CLI's tests rather than on every read
  * @returns {DiscoveredTheme[]}
  */
-export function discoverThemeCatalog(themeRoot: string, owner: string, { bundled }?: {
+export function discoverThemeDirectory(themeRoot: string, owner: string, { bundled }?: {
     bundled?: boolean;
 }): DiscoveredTheme[];
+/**
+ * Folders under a themes root that look like themes (see looksLikeTheme)
+ * but that discovery does not read as themes, and that no module elsewhere
+ * under the root imports, by a relative path or through the package's own
+ * name. Discovery skips them silently, as the released catalog skipped
+ * unlisted folders; doctor warns.
+ * @param {string} themeRoot
+ * @param {{packageDir?: string, packageName?: string}} [owner]
+ * @returns {string[]} absolute folder paths, sorted
+ */
+export function unreadThemeFolders(themeRoot: string, { packageDir, packageName }?: {
+    packageDir?: string;
+    packageName?: string;
+}): string[];
 /** @returns {DiscoveredTheme[]} */
 export function discoverBundledThemes(): DiscoveredTheme[];
 /**
@@ -20,8 +70,10 @@ export function discoverBundledThemes(): DiscoveredTheme[];
 export function discoverIntegrationThemes(integration: import("../integrations/integrations.mjs").LoadedIntegration): Promise<DiscoveredTheme[]>;
 export const BUNDLED_THEME_PACKAGE: "@astryxdesign/cli";
 export const THEMES_DIR: string;
-export const THEME_MANIFEST_BASENAME: "manifest.json";
-export const MANIFEST_PATH: string;
+export const THEME_DOC_SUFFIX: ".doc.mjs";
+export const THEME_MODULE_EXTENSIONS: string[];
+/** A theme directory's name: lower-kebab, starting with a letter. */
+export const THEME_SLUG_RE: RegExp;
 export type DiscoveredTheme = {
     slug: string;
     displayName: string;
@@ -29,6 +81,10 @@ export type DiscoveredTheme = {
     maintained: boolean;
     entry: string;
     exportName: string;
+    /**
+     * what `theme add` copies, relative to sourceDir,
+     * entry first
+     */
     files: string[];
     package: string;
     /**
@@ -36,4 +92,8 @@ export type DiscoveredTheme = {
      */
     sourceDir: string;
     bundled: boolean;
+    /**
+     * absolute descriptor path
+     */
+    docPath: string;
 };