@astryxdesign/cli 0.4.7 → 0.5.0-canary.32a62fd

package/clients/cli/commands/theme-targets.doc.mjs

@@ -0,0 +1,38 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CommandDoc for `astryx theme targets`. The terminal binding of the
+ * `themeTargets()` function (referenced via `fn`); its args map to that
+ * function's params so a converter can build Commander config + --help from one
+ * source of truth.
+ * @position packages/cli/clients/cli/commands — command documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').CommandDoc} */
+export const doc = {
+  type: 'command',
+  name: 'theme targets',
+  displayName: 'astryx theme targets',
+  namespace: 'cli',
+  summary: 'List the component theming targets a theme can override',
+  description:
+    'Prints every `defineTheme` components key across the system: the stable class it paints, ' +
+    'the component that declares it, and the props and states that are legal override keys ' +
+    'under it. This is the whole themeable surface in one command — what auditing a theme, or ' +
+    'answering "which key paints this pixel?", used to need one `astryx component <Name>` per ' +
+    'component to assemble. Pass a component name to scope it; pass any substring to search ' +
+    'keys. `--json` for a list a repo can lint its own theme against.',
+  fn: 'themeTargets',
+  args: [{name: 'filter', param: 'filter', required: false}],
+  examples: [
+    {label: 'The whole themeable surface', cli: 'astryx theme targets'},
+    {label: "One component's targets", cli: 'astryx theme targets Switch'},
+    {label: 'Search keys', cli: 'astryx theme targets thumb'},
+    {label: 'For a lint or an audit script', cli: 'astryx --json theme targets'},
+  ],
+  exitCodes: [
+    {code: 0, when: 'success'},
+    {code: 1, when: 'a filter matches no target, or core cannot be resolved'},
+  ],
+  related: ['component', 'theme build', 'theme template'],
+};

package/clients/cli/commands/theme-template.doc.mjs

@@ -16,9 +16,9 @@ export const doc = {
   namespace: 'cli',
   summary: 'Write the annotated theme template into your project',
   description:
-    'Writes theme.template.ts: the annotated reference for the whole theme surface — every ' +
+    'Writes theme.template.ts: the annotated reference for the whole theme surface, covering every ' +
     'defineTheme field, the token families, the component override syntax, and how a theme is ' +
-    'consumed — naming the CLI command that prints the authoritative reference for each. Read ' +
+    'consumed, naming the CLI command that prints the authoritative reference for each. Read ' +
     'it, copy what you need into your own theme file, delete it. Use `theme add <slug>` instead ' +
     'to start from a theme we ship. Leaves an existing file untouched unless --overwrite.',
   fn: 'themeTemplate',

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

@@ -17,11 +17,13 @@ export const doc = {
   description:
     'The theme command group. Running astryx theme with no subcommand prints the ' +
     'subcommand list; the work happens in the subcommands: compile a theme (build), ' +
-    'scaffold one into your project (add), start a custom one from the annotated template (template), or list the bundled themes (list).',
-  subcommands: ['build', 'add', 'list', 'template'],
+    'scaffold one into your project (add), start a custom one from the annotated template (template), ' +
+    'list the bundled themes (list), or list the component theming targets a theme can override (targets).',
+  subcommands: ['build', 'add', 'list', 'template', 'targets'],
   examples: [
     {label: 'List bundled themes', cli: 'astryx theme list'},
     {label: 'Scaffold a theme', cli: 'astryx theme add matcha'},
+    {label: 'See what a theme can override', cli: 'astryx theme targets'},
   ],
   exitCodes: [
     {code: 0, when: 'success (help shown, or a subcommand succeeded)'},

package/clients/cli/index.mjs

@@ -70,6 +70,7 @@ export const JSON_SUPPORTED = new Set([
   'theme list',
   'theme add',
   'theme template',
+  'theme targets',
   'upgrade',
   'manifest',
   'doctor',

package/clients/cli/lib/component-format.mjs

@@ -13,8 +13,8 @@ import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
  *
  * Override keys are the component's stable class name with the `astryx-`
  * namespace prefix stripped — `generateThemeRules` re-adds the prefix when it
- * builds the `.astryx-*` selector. So `astryx-base-table` → key `base-table`
- * (→ `.astryx-base-table`), and `astryx-button` → key `button`.
+ * builds the `.astryx-*` selector. So `astryx-table-cell` → key `table-cell`
+ * (→ `.astryx-table-cell`), and `astryx-button` → key `button`.
  *
  * Keep the `astryx-` literal in sync with packages/core/src/naming.ts
  * (NAMESPACE / classPrefix), the same way build-theme.mjs mirrors it.

package/clients/cli/lib/manifest.mjs

@@ -77,6 +77,7 @@ export const RESPONSE_TYPES = {
   'theme list': ['theme.list'],
   'theme add': ['theme.list', 'theme.add'],
   'theme template': ['theme.template'],
+  'theme targets': ['theme.targets'],
   upgrade: ['upgrade.list', 'upgrade.status', 'upgrade.run'],
   manifest: ['manifest'],
   doctor: ['doctor'],
@@ -116,6 +117,7 @@ const EXAMPLES = {
     'astryx theme add matcha ./src/themes/matcha',
   ],
   'theme template': ['astryx theme template', 'astryx theme template --json'],
+  'theme targets': ['astryx theme targets Switch', 'astryx --json theme targets'],
   upgrade: ['astryx upgrade --json'],
   manifest: ['astryx manifest --json', 'astryx --json'],
   doctor: ['astryx doctor', 'astryx doctor --json'],

package/foundation/discovery/theming-targets.d.mts

@@ -0,0 +1,86 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Every theming target declared under a core `src` directory, sorted by key
+ * then component. A key can appear more than once: a shared sub-element (the
+ * radio indicator, say) is documented by every component that renders it.
+ *
+ * Unreadable docs are skipped rather than fatal — a single malformed doc must
+ * not take out theme validation or the listing.
+ *
+ * @param {string} coreSrc - absolute path to `<core>/src`
+ * @returns {Promise<ThemingTarget[]>}
+ */
+export function collectThemingTargets(coreSrc: string): Promise<ThemingTarget[]>;
+/**
+ * One public custom property a theme may set on a component's target.
+ * @typedef {object} ThemingVar
+ * @property {string} name - the custom property, e.g. `--tree-list-indent`
+ * @property {string} component - the component whose doc declares it
+ * @property {string} dir - absolute path to the directory the doc lives in
+ * @property {string} default - the documented default value
+ */
+/**
+ * Every PUBLIC theming var declared under a core `src` directory, sorted by
+ * name. Private `--_*` vars are a component's own plumbing, not a theme's to
+ * set, so they are not enumerated here.
+ *
+ * @param {string} coreSrc - absolute path to `<core>/src`
+ * @returns {Promise<ThemingVar[]>}
+ */
+export function collectThemingVars(coreSrc: string): Promise<ThemingVar[]>;
+/**
+ * Collapse the enumeration into the `{key: [props and states]}` map theme
+ * validation checks override keys against — both are legal override keys, so
+ * they share one list.
+ * @param {ThemingTarget[]} targets
+ * @returns {Record<string, string[]>}
+ */
+export function targetsByKey(targets: ThemingTarget[]): Record<string, string[]>;
+/**
+ * One theming target, as a theme author has to write it.
+ */
+export type ThemingTarget = {
+    /**
+     * - the `defineTheme` `components` key (class minus the `astryx-` prefix)
+     */
+    key: string;
+    /**
+     * - the stable class the component renders
+     */
+    className: string;
+    /**
+     * - the component whose doc declares it
+     */
+    component: string;
+    /**
+     * - visual props the target reflects (`variant:value` keys)
+     */
+    props: string[];
+    /**
+     * - runtime states the target reflects (bare-name keys)
+     */
+    states: string[];
+};
+/**
+ * One public custom property a theme may set on a component's target.
+ */
+export type ThemingVar = {
+    /**
+     * - the custom property, e.g. `--tree-list-indent`
+     */
+    name: string;
+    /**
+     * - the component whose doc declares it
+     */
+    component: string;
+    /**
+     * - absolute path to the directory the doc lives in
+     */
+    dir: string;
+    /**
+     * - the documented default value
+     */
+    default: string;
+};

package/foundation/discovery/theming-targets.mjs

@@ -0,0 +1,202 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The one enumeration of component theming targets.
+ *
+ * @input  a core `src` directory
+ * @output every `theming.targets` entry authored in a component `.doc.mjs`,
+ *         flattened into the `defineTheme` component key a theme author writes
+ * @position packages/cli/foundation/discovery — shared by `theme targets` (the
+ *           listing) and `theme build` (override validation). Both read the
+ *           component docs, which are the source of truth `astryx component
+ *           <Name>` prints; nothing here is a second registry, so the list a
+ *           theme author can enumerate and the set the compiler accepts cannot
+ *           drift from the components or from each other.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {loadComponentDoc} from './component-loader.mjs';
+
+const SKIP_DIRS = new Set(['node_modules', '__tests__']);
+
+/**
+ * One theming target, as a theme author has to write it.
+ * @typedef {object} ThemingTarget
+ * @property {string} key - the `defineTheme` `components` key (class minus the `astryx-` prefix)
+ * @property {string} className - the stable class the component renders
+ * @property {string} component - the component whose doc declares it
+ * @property {string[]} props - visual props the target reflects (`variant:value` keys)
+ * @property {string[]} states - runtime states the target reflects (bare-name keys)
+ */
+
+/**
+ * Strip the namespace prefix to get the `defineTheme` key for a class name.
+ *
+ * Keep the `astryx-` literal in sync with packages/core/src/naming.ts
+ * (NAMESPACE / classPrefix), the same way component-format.mjs does.
+ * <!-- SYNC: packages/core/src/naming.ts (namespace prefix source of truth) -->
+ * @param {string} className
+ * @returns {string}
+ */
+function targetKey(className) {
+  return className.replace(/^astryx-/, '');
+}
+
+/**
+ * Every theming target declared under a core `src` directory, sorted by key
+ * then component. A key can appear more than once: a shared sub-element (the
+ * radio indicator, say) is documented by every component that renders it.
+ *
+ * Unreadable docs are skipped rather than fatal — a single malformed doc must
+ * not take out theme validation or the listing.
+ *
+ * @param {string} coreSrc - absolute path to `<core>/src`
+ * @returns {Promise<ThemingTarget[]>}
+ */
+export async function collectThemingTargets(coreSrc) {
+  if (!coreSrc || !fs.existsSync(coreSrc)) return [];
+
+  /** @type {ThemingTarget[]} */
+  const targets = [];
+
+  /** @param {string} dir */
+  async function scan(dir) {
+    for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        await scan(full);
+        continue;
+      }
+      if (!entry.name.endsWith('.doc.mjs')) continue;
+
+      /** @type {any} */
+      let doc;
+      try {
+        doc = await loadComponentDoc(full);
+      } catch {
+        continue;
+      }
+
+      const component =
+        typeof doc?.name === 'string' && doc.name
+          ? doc.name
+          : path.basename(path.dirname(full));
+
+      for (const target of doc?.theming?.targets || []) {
+        const className = target?.className;
+        if (typeof className !== 'string') continue;
+        const key = targetKey(className);
+        if (!key) continue;
+        targets.push({
+          key,
+          className,
+          component,
+          props: stringList(target.visualProps),
+          states: stringList(target.states),
+        });
+      }
+    }
+  }
+
+  await scan(coreSrc);
+
+  targets.sort(
+    (a, b) => a.key.localeCompare(b.key) || a.component.localeCompare(b.component),
+  );
+  return targets;
+}
+
+/**
+ * One public custom property a theme may set on a component's target.
+ * @typedef {object} ThemingVar
+ * @property {string} name - the custom property, e.g. `--tree-list-indent`
+ * @property {string} component - the component whose doc declares it
+ * @property {string} dir - absolute path to the directory the doc lives in
+ * @property {string} default - the documented default value
+ */
+
+/**
+ * Every PUBLIC theming var declared under a core `src` directory, sorted by
+ * name. Private `--_*` vars are a component's own plumbing, not a theme's to
+ * set, so they are not enumerated here.
+ *
+ * @param {string} coreSrc - absolute path to `<core>/src`
+ * @returns {Promise<ThemingVar[]>}
+ */
+export async function collectThemingVars(coreSrc) {
+  if (!coreSrc || !fs.existsSync(coreSrc)) return [];
+
+  /** @type {Map<string, ThemingVar>} */
+  const vars = new Map();
+
+  /** @param {string} dir */
+  async function scan(dir) {
+    for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        await scan(full);
+        continue;
+      }
+      if (!entry.name.endsWith('.doc.mjs')) continue;
+
+      /** @type {any} */
+      let doc;
+      try {
+        doc = await loadComponentDoc(full);
+      } catch {
+        continue;
+      }
+
+      const component =
+        typeof doc?.name === 'string' && doc.name
+          ? doc.name
+          : path.basename(path.dirname(full));
+
+      for (const entryVar of doc?.theming?.vars || []) {
+        const name = entryVar?.name;
+        if (typeof name !== 'string') continue;
+        if (entryVar.private === true || name.startsWith('--_')) continue;
+        if (vars.has(name)) continue;
+        vars.set(name, {
+          name,
+          component,
+          dir: path.dirname(full),
+          default: typeof entryVar.default === 'string' ? entryVar.default : '',
+        });
+      }
+    }
+  }
+
+  await scan(coreSrc);
+
+  return [...vars.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Collapse the enumeration into the `{key: [props and states]}` map theme
+ * validation checks override keys against — both are legal override keys, so
+ * they share one list.
+ * @param {ThemingTarget[]} targets
+ * @returns {Record<string, string[]>}
+ */
+export function targetsByKey(targets) {
+  /** @type {Record<string, string[]>} */
+  const byKey = {};
+  for (const t of targets) {
+    byKey[t.key] = [...new Set([...(byKey[t.key] || []), ...t.props, ...t.states])];
+  }
+  return byKey;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string[]}
+ */
+function stringList(value) {
+  return Array.isArray(value)
+    ? value.filter((/** @type {unknown} */ v) => typeof v === 'string')
+    : [];
+}

package/foundation/discovery/theming-targets.test.mjs

@@ -0,0 +1,245 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The enumerability guard for component theming targets.
+ *
+ * A theming target is only useful if a theme author can find it. These tests
+ * run against the REAL core docs and fail if any component's targets stop
+ * being enumerable — a doc that moves out of the scanned tree, a target shape
+ * that stops being read, or a component whose Theming table says one thing
+ * while `theme targets` says another. That divergence is the failure the
+ * listing exists to prevent: a target list that can drift from the components
+ * is worse than no list.
+ *
+ * The public vars a target carries get the same treatment, one step further:
+ * being enumerable is not the same as being settable. A documented var no
+ * component reads compiles to a declaration that never applies (#5012), and a
+ * var the component writes inline outranks every cascade layer, so no theme can
+ * reach it (#4530). Both shipped. Neither is visible in the generated theme CSS
+ * — the artifact the jsdom suites assert on — so the wiring is checked here
+ * against source. Whether the cascade then lands the value on the element is a
+ * browser fact and no jsdom test can stand in for it.
+ */
+
+import {describe, it, expect} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {findCoreDir} from '../fs/paths.mjs';
+import {
+  discoverComponents,
+  findComponentReadme,
+} from './component-discovery.mjs';
+import {loadComponentDoc} from './component-loader.mjs';
+import {
+  collectThemingTargets,
+  collectThemingVars,
+  targetsByKey,
+} from './theming-targets.mjs';
+
+const coreDir = /** @type {string} */ (findCoreDir(process.cwd()));
+const coreSrc = path.join(coreDir, 'src');
+
+/** @type {Promise<import('./theming-targets.mjs').ThemingTarget[]>} */
+const enumerated = collectThemingTargets(coreSrc);
+
+describe('collectThemingTargets', () => {
+  it('enumerates the whole surface, not a handful', async () => {
+    const targets = await enumerated;
+    expect(targets.length).toBeGreaterThan(100);
+    expect(new Set(targets.map(t => t.component)).size).toBeGreaterThan(50);
+  });
+
+  it('drops the namespace prefix so each key is what defineTheme takes', async () => {
+    for (const t of await enumerated) {
+      expect(t.className).toBe(`astryx-${t.key}`);
+      expect(t.component).toBeTruthy();
+    }
+  });
+
+  it('carries the props and states a target reflects', async () => {
+    const targets = await enumerated;
+    expect(targets.find(t => t.key === 'switch-thumb')).toEqual({
+      key: 'switch-thumb',
+      className: 'astryx-switch-thumb',
+      component: 'Switch',
+      props: ['size'],
+      states: ['checked'],
+    });
+  });
+
+  it('is sorted by key, so a diff of two runs is readable', async () => {
+    const keys = (await enumerated).map(t => t.key);
+    expect(keys).toEqual([...keys].sort((a, b) => a.localeCompare(b)));
+  });
+
+  // The listing and `theme build`'s override validation read this one
+  // enumeration. `targetsByKey` is the shape validation wants: props and
+  // states merged, because both are legal override keys.
+  it('collapses to the override keys, merging the components that share one', async () => {
+    const byKey = targetsByKey(await enumerated);
+    expect(byKey['switch']).toEqual(['size', 'checked', 'disabled']);
+    // `radio` is documented by both Indicator and RadioList.
+    const radio = (await enumerated).filter(t => t.key === 'radio');
+    expect(radio.length).toBeGreaterThan(1);
+    for (const t of radio) {
+      for (const name of [...t.props, ...t.states]) {
+        expect(byKey['radio']).toContain(name);
+      }
+    }
+  });
+
+  it('every component doc that declares targets has them enumerated', async () => {
+    const targets = await enumerated;
+    /** @type {Map<string, Set<string>>} key -> props+states */
+    const byKey = new Map(
+      Object.entries(targetsByKey(targets)).map(([k, v]) => [k, new Set(v)]),
+    );
+
+    const names = Object.values(discoverComponents(coreDir)).flat();
+    /** @type {string[]} */
+    const missing = [];
+    /** @type {Set<string>} */
+    const seenDocs = new Set();
+    let checked = 0;
+
+    for (const name of names) {
+      const docPath = findComponentReadme(coreDir, name);
+      if (!docPath || seenDocs.has(docPath)) continue;
+      seenDocs.add(docPath);
+
+      /** @type {any} */
+      let doc;
+      try {
+        doc = await loadComponentDoc(docPath);
+      } catch {
+        continue;
+      }
+
+      for (const target of doc?.theming?.targets || []) {
+        if (typeof target?.className !== 'string') continue;
+        checked++;
+        const key = target.className.replace(/^astryx-/, '');
+        const known = byKey.get(key);
+        if (!known) {
+          missing.push(`${name}: ${target.className} is not enumerable`);
+          continue;
+        }
+        for (const prop of [
+          ...(target.visualProps || []),
+          ...(target.states || []),
+        ]) {
+          if (!known.has(prop)) {
+            missing.push(`${name}: ${target.className} lost "${prop}"`);
+          }
+        }
+      }
+    }
+
+    expect(checked).toBeGreaterThan(100);
+    expect(missing).toEqual([]);
+  }, 60_000);
+});
+
+// ---------------------------------------------------------------------------
+// Public vars — enumerable is not the same as settable
+// ---------------------------------------------------------------------------
+
+/** @type {Promise<import('./theming-targets.mjs').ThemingVar[]>} */
+const enumeratedVars = collectThemingVars(coreSrc);
+
+/** Every non-test source file under a component directory. */
+function sourcesIn(dir) {
+  /** @type {string[]} */
+  const out = [];
+  for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules' || entry.name === '__tests__') continue;
+      out.push(...sourcesIn(path.join(dir, entry.name)));
+      continue;
+    }
+    if (!/\.tsx?$/.test(entry.name)) continue;
+    if (/\.(test|stories)\.tsx?$/.test(entry.name)) continue;
+    out.push(path.join(dir, entry.name));
+  }
+  return out;
+}
+
+/**
+ * The text of every inline style a file writes — `style={{…}}` objects and
+ * `setProperty` calls. A custom property written from either outranks every
+ * cascade layer, so a theme cannot reach it.
+ */
+function inlineStyleText(src) {
+  const chunks = [];
+  for (const m of src.matchAll(/style=\{\{/g)) {
+    const end = src.indexOf('}}', m.index);
+    chunks.push(src.slice(m.index, end === -1 ? src.length : end));
+  }
+  for (const m of src.matchAll(/setProperty\(\s*'[^']+'/g)) chunks.push(m[0]);
+  return chunks.join('\n');
+}
+
+describe('collectThemingVars', () => {
+  it('enumerates the public vars and drops the private plumbing', async () => {
+    const names = (await enumeratedVars).map(v => v.name);
+    expect(names.length).toBeGreaterThan(0);
+    expect(names.every(n => !n.startsWith('--_'))).toBe(true);
+    expect(names).toEqual([...names].sort((a, b) => a.localeCompare(b)));
+    expect(names).toEqual([...new Set(names)]);
+  });
+
+  it('carries the component and the documented default', async () => {
+    const indent = (await enumeratedVars).find(
+      v => v.name === '--tree-list-indent',
+    );
+    expect(indent).toMatchObject({
+      name: '--tree-list-indent',
+      component: 'TreeList',
+      default: 'var(--spacing-4)',
+    });
+  });
+
+  // #5012: the theme docs advertised `--button-press-scale`, which no component
+  // ever read. A theme setting it compiled to a declaration nothing consumed,
+  // and nothing failed — the var was in the docs, so every existence check
+  // passed. Reading it is the minimum that makes a documented var mean anything.
+  it('every documented var is read by the component that documents it', async () => {
+    /** @type {string[]} */
+    const unread = [];
+    for (const v of await enumeratedVars) {
+      const read = sourcesIn(v.dir).some(f =>
+        fs.readFileSync(f, 'utf-8').includes(`var(${v.name}`),
+      );
+      if (!read) unread.push(`${v.component}: nothing reads var(${v.name})`);
+    }
+    expect(
+      unread,
+      `A documented public var no component reads compiles to a declaration ` +
+        `that never applies (#5012). Either wire it up or drop it from the doc.`,
+    ).toEqual([]);
+  });
+
+  // #4530: TreeList's indent was an inline `margin-inline-start` on the element
+  // carrying the theme target. An inline declaration outranks every cascade
+  // layer, so `@layer astryx-theme` could not reach it — the var was real, read,
+  // and documented, and still unsettable. The fix moved it into a StyleX rule.
+  it('no documented var is written inline, where no theme can outrank it', async () => {
+    /** @type {string[]} */
+    const clobbered = [];
+    for (const v of await enumeratedVars) {
+      for (const f of sourcesIn(v.dir)) {
+        if (inlineStyleText(fs.readFileSync(f, 'utf-8')).includes(v.name)) {
+          clobbered.push(
+            `${v.component}: ${path.basename(f)} sets ${v.name} inline`,
+          );
+        }
+      }
+    }
+    expect(
+      clobbered,
+      `An inline custom property beats every cascade layer, so a theme setting ` +
+        `it through @layer astryx-theme is silently ignored (#4530). Declare it ` +
+        `in a StyleX rule instead.`,
+    ).toEqual([]);
+  });
+});

package/foundation/response/response-types.doc.mjs

@@ -153,7 +153,7 @@ export const doc = {
     {
       value: 'template.cdn',
       description:
-        'A write receipt for the no-build-step CDN starter page: the path (relative to cwd), the Astryx version every CDN URL was pinned to, whether it was written, and the reason it was not — `exists` when a file was already there, which is a success.',
+        'A write receipt for the no-build-step CDN starter page: the path (relative to cwd), the Astryx version every CDN URL was pinned to, whether it was written, and the reason it was not. `exists` when a file was already there, which is a success.',
     },
 
     // hook
@@ -197,7 +197,12 @@ export const doc = {
     {
       value: 'theme.template',
       description:
-        'A write receipt for the annotated theme template: the path (relative to cwd), whether it was written, and the reason it was not — `exists` when a file was already there, which is a success.',
+        'A write receipt for the annotated theme template: the path (relative to cwd), whether it was written, and the reason it was not. `exists` when a file was already there, which is a success.',
+    },
+    {
+      value: 'theme.targets',
+      description:
+        'The whole themeable surface: the echoed filter, the component count, and one entry per theming target — {key, className, component, props, states}, where props and states are its legal override keys.',
     },
 
     // upgrade