@astryxdesign/cli 0.6.3 → 0.6.4-canary.10dd683

package/assets/codemods/transforms/v0.6.4/__tests__/migrate-theme-catalog-to-descriptors.test.mjs

@@ -0,0 +1,220 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import manifest from '../index.mjs';
+import migrate from '../migrate-theme-catalog-to-descriptors.mjs';
+import {runCodemods} from '../../../runner.mjs';
+import {discoverThemeDirectory} from '../../../../../foundation/discovery/theme-discovery.mjs';
+
+let root;
+
+beforeEach(() => {
+  root = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-theme-catalog-'));
+});
+
+afterEach(() => {
+  fs.rmSync(root, {recursive: true, force: true});
+});
+
+/** A catalog entry exactly as `astryx integration add theme <slug>` wrote it in 0.6. */
+function entry(slug, overrides = {}) {
+  const identifier = slug.replace(/-([a-z0-9])/gu, (_, c) => c.toUpperCase());
+  const displayName = slug
+    .split('-')
+    .map(part => part[0].toUpperCase() + part.slice(1))
+    .join(' ');
+  return {
+    slug,
+    displayName,
+    description: `${displayName} theme.`,
+    maintained: true,
+    entry: `${identifier}Theme.ts`,
+    exportName: `${identifier}Theme`,
+    files: [`${identifier}Theme.ts`],
+    ...overrides,
+  };
+}
+
+/** @param {ReturnType<typeof entry>[]} themes */
+function writeKit(themes, {sources = true} = {}) {
+  fs.writeFileSync(
+    path.join(root, 'package.json'),
+    '{"name":"@acme/kit","version":"1.0.0"}\n',
+  );
+  fs.writeFileSync(
+    path.join(root, 'astryx.integration.mjs'),
+    "export default {themes: './themes'};\n",
+  );
+  for (const theme of themes) {
+    const source = path.join(root, 'themes', theme.slug, theme.entry);
+    fs.mkdirSync(path.dirname(source), {recursive: true});
+    if (sources) {
+      fs.writeFileSync(
+        source,
+        `import {defineTheme} from '@astryxdesign/core/theme';\n\nexport const ${theme.exportName} = defineTheme({\n  name: '${theme.slug}',\n});\n`,
+      );
+    }
+  }
+  fs.mkdirSync(path.join(root, 'themes'), {recursive: true});
+  fs.writeFileSync(
+    path.join(root, 'themes', 'manifest.json'),
+    `${JSON.stringify({version: 1, themes}, null, 2)}\n`,
+  );
+}
+
+const catalog = () => path.join(root, 'themes', 'manifest.json');
+
+/** @param {boolean} apply @param {string} [srcPath] */
+const run = (apply, srcPath = root) =>
+  runCodemods([{version: 'next', transforms: manifest}], {
+    apply,
+    path: srcPath,
+    codemod: undefined,
+    silent: true,
+    root,
+  });
+
+describe('migrate-theme-catalog-to-descriptors', () => {
+  it('is staged for the next release as a project codemod', () => {
+    expect(manifest.map(t => [t.name, t.meta.codemodType])).toEqual([
+      ['migrate-theme-catalog-to-descriptors', 'project'],
+      ['migrate-native-picker-to-presentation', undefined],
+    ]);
+  });
+
+  it('writes one typed descriptor per catalog theme and removes the catalog', async () => {
+    writeKit([
+      entry('ocean'),
+      entry('deep-sea', {
+        displayName: "Deep 'Sea'",
+        description: 'Line one\nline two \\ done.',
+        maintained: false,
+      }),
+    ]);
+
+    const result = await run(true);
+
+    expect(result).toMatchObject({errors: [], totalFilesChanged: 3});
+    expect(fs.existsSync(catalog())).toBe(false);
+    expect(
+      fs.readFileSync(
+        path.join(root, 'themes/ocean/oceanTheme.doc.mjs'),
+        'utf-8',
+      ),
+    ).toBe(
+      "/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */\nexport default {\n  type: 'theme',\n  name: 'ocean',\n  displayName: 'Ocean',\n  description: 'Ocean theme.',\n  maintained: true,\n};\n",
+    );
+    const themes = discoverThemeDirectory(
+      path.join(root, 'themes'),
+      '@acme/kit',
+    );
+    expect(
+      themes.map(({slug, displayName, description, maintained}) => ({
+        slug,
+        displayName,
+        description,
+        maintained,
+      })),
+    ).toEqual([
+      {
+        slug: 'deep-sea',
+        displayName: "Deep 'Sea'",
+        description: 'Line one\nline two \\ done.',
+        maintained: false,
+      },
+      {
+        slug: 'ocean',
+        displayName: 'Ocean',
+        description: 'Ocean theme.',
+        maintained: true,
+      },
+    ]);
+  });
+
+  it('previews without writing, even with no source folder', async () => {
+    writeKit([entry('ocean')]);
+    // A staged code codemod (migrate-native-picker-to-presentation) requires
+    // the source folder to exist; an empty one exercises the same preview.
+    fs.mkdirSync(path.join(root, 'src'), {recursive: true});
+
+    const result = await run(false, path.join(root, 'src'));
+
+    expect(result).toMatchObject({
+      errors: [],
+      totalFilesChanged: 2,
+      writtenFiles: [],
+    });
+    expect(fs.existsSync(catalog())).toBe(true);
+    expect(
+      fs.existsSync(path.join(root, 'themes/ocean/oceanTheme.doc.mjs')),
+    ).toBe(false);
+  });
+
+  it('keeps a descriptor that already exists and still removes the catalog', async () => {
+    writeKit([entry('ocean'), entry('reef')]);
+    const kept = path.join(root, 'themes/ocean/oceanTheme.doc.mjs');
+    fs.writeFileSync(
+      kept,
+      "export default {type: 'theme', name: 'ocean', displayName: 'Mine', description: '', maintained: true};\n",
+    );
+
+    const result = await run(true);
+
+    expect(result.errors).toEqual([]);
+    expect(fs.readFileSync(kept, 'utf-8')).toContain("displayName: 'Mine'");
+    expect(
+      fs.existsSync(path.join(root, 'themes/reef/reefTheme.doc.mjs')),
+    ).toBe(true);
+    expect(fs.existsSync(catalog())).toBe(false);
+  });
+
+  it('changes nothing and names each entry that cannot convert', async () => {
+    writeKit([
+      entry('ocean'),
+      entry('sea', {exportName: 'oceanBlue'}),
+      entry('nested', {
+        entry: 'src/nestedTheme.ts',
+        files: ['src/nestedTheme.ts'],
+      }),
+    ]);
+    fs.rmSync(path.join(root, 'themes/ocean/oceanTheme.ts'));
+    const before = fs.readFileSync(catalog(), 'utf-8');
+
+    const result = await run(true);
+
+    expect(result.errors.map(e => [e.file, e.error])).toEqual([
+      ['themes/ocean', 'holds no oceanTheme.ts for theme "ocean".'],
+      [
+        'themes/manifest.json',
+        'theme "sea" exports "oceanBlue" from seaTheme.ts; a descriptor takes the export name from the file name, so rename the export or the file to match.',
+      ],
+      [
+        'themes/manifest.json',
+        'theme "nested" has entry "src/nestedTheme.ts"; a descriptor sits beside a .ts, .tsx, .mjs, or .js source directly in themes/nested/.',
+      ],
+    ]);
+    expect(fs.readFileSync(catalog(), 'utf-8')).toBe(before);
+    expect(fs.existsSync(path.join(root, 'themes/sea/seaTheme.doc.mjs'))).toBe(
+      false,
+    );
+  });
+
+  it('leaves a package with no catalog to convert alone', async () => {
+    const empty = {writes: [], deletes: [], problems: []};
+    await expect(migrate(root)).resolves.toEqual(empty);
+    fs.writeFileSync(
+      path.join(root, 'astryx.integration.mjs'),
+      'export default {};\n',
+    );
+    await expect(migrate(root)).resolves.toEqual(empty);
+    fs.writeFileSync(
+      path.join(root, 'astryx.integration.mjs'),
+      "export default {themes: './themes'};\n",
+    );
+    fs.mkdirSync(path.join(root, 'themes'));
+    await expect(migrate(root)).resolves.toEqual(empty);
+  });
+});

package/assets/codemods/transforms/v0.6.4/index.mjs

@@ -0,0 +1,31 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file next transform manifest
+ *
+ * Staged codemods for the next release. The Version Packages PR promotes
+ * this file into the resolved version folder.
+ */
+
+import migrateThemeCatalogToDescriptors, {
+  meta as migrateThemeCatalogToDescriptorsMeta,
+} from './migrate-theme-catalog-to-descriptors.mjs';
+import migrateNativePickerToPresentation, {
+  meta as migrateNativePickerToPresentationMeta,
+} from './migrate-native-picker-to-presentation.mjs';
+
+export default [
+  {
+    name: 'migrate-theme-catalog-to-descriptors',
+    transform:
+      /** @type {import('../../../../authoring/codemod/type').CodemodTransform} */ (
+        /** @type {unknown} */ (migrateThemeCatalogToDescriptors)
+      ),
+    meta: migrateThemeCatalogToDescriptorsMeta,
+  },
+  {
+    name: 'migrate-native-picker-to-presentation',
+    transform: migrateNativePickerToPresentation,
+    meta: migrateNativePickerToPresentationMeta,
+  },
+];

package/assets/codemods/transforms/v0.6.4/migrate-native-picker-to-presentation.mjs

@@ -0,0 +1,148 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: migrate nativePicker to presentation on date/time inputs
+ *
+ * `spec:AST-043` FR3 mapping, applied only to static literals written
+ * directly on imported `DateInput`, `DateTimeInput`, and `TimeInput`
+ * elements: the prop is renamed to `presentation` and its value mapped.
+ * When the element already sets `presentation`, the deprecated prop is
+ * removed (presentation wins, FR4). Dynamic values are left unchanged —
+ * the deprecated prop keeps working, so an unmigrated callsite is still
+ * correct, and guessing at an expression's values would not be.
+ */
+
+import {transformProp} from '../../transform-prop.mjs';
+
+export const meta = {
+  title: 'Migrate nativePicker to presentation',
+  description:
+    'Renames `nativePicker` to `presentation` on DateInput, DateTimeInput, ' +
+    'and TimeInput, mapping touch→adaptive-native, always→native, and ' +
+    'never→adaptive-bottom-sheet (text-input for TimeInput). Dynamic ' +
+    'values are left for manual migration; the deprecated prop still works.',
+};
+
+const CORE_IMPORT_RE = /^@(astryxdesign|xds)\/core(?:\/|$)/;
+
+const COMPONENT_PROPS = new Map([
+  ['DateInput', new Set(['nativePicker'])],
+  ['DateTimeInput', new Set(['nativePicker'])],
+  ['TimeInput', new Set(['nativePicker'])],
+]);
+
+/** @param {string} component @param {string} value */
+function mapValue(component, value) {
+  switch (value) {
+    case 'touch':
+      return 'adaptive-native';
+    case 'always':
+      return 'native';
+    case 'never':
+      return component === 'TimeInput' ? 'text-input' : 'adaptive-bottom-sheet';
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Collect the string-literal leaves of a value expression without mutating
+ * anything. Returns false for any dynamic or non-string node.
+ * @param {any} node
+ * @param {any[]} leaves
+ * @returns {boolean}
+ */
+function collectStaticLeaves(node, leaves) {
+  if (!node) return false;
+  if (
+    node.type === 'TSAsExpression' ||
+    node.type === 'TSSatisfiesExpression' ||
+    node.type === 'TypeCastExpression' ||
+    node.type === 'ParenthesizedExpression'
+  ) {
+    return collectStaticLeaves(node.expression, leaves);
+  }
+  if (node.type === 'ConditionalExpression') {
+    return (
+      collectStaticLeaves(node.consequent, leaves) &&
+      collectStaticLeaves(node.alternate, leaves)
+    );
+  }
+  if (
+    (node.type !== 'StringLiteral' && node.type !== 'Literal') ||
+    typeof node.value !== 'string'
+  ) {
+    return false;
+  }
+  leaves.push(node);
+  return true;
+}
+
+/**
+ * Map every leaf, or none of them: a mixed static/dynamic conditional must
+ * stay byte-identical, never half-migrated.
+ * @param {any} node
+ * @param {string} component
+ */
+function mapStaticValue(node, component) {
+  /** @type {any[]} */
+  const leaves = [];
+  if (!collectStaticLeaves(node, leaves)) return false;
+  if (leaves.some(leaf => mapValue(component, leaf.value) === undefined)) {
+    return false;
+  }
+  for (const leaf of leaves) {
+    leaf.value = mapValue(component, leaf.value);
+    if (leaf.raw) leaf.raw = undefined;
+  }
+  return true;
+}
+
+/**
+ * @param {import('../../../../authoring/codemod/type').AstryxCodemodFile} file
+ * @param {import('../../../../authoring/codemod/type').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
+export default function transformer(file, api) {
+  if (!file.source.includes('nativePicker')) return undefined;
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  let hasChanges = false;
+
+  transformProp(
+    root,
+    j,
+    {
+      matchesImport: source => CORE_IMPORT_RE.test(source),
+      components: COMPONENT_PROPS,
+    },
+    (propPath, {component}) => {
+      const opening = propPath.parent?.node;
+      const attributes = opening?.attributes ?? [];
+      const hasPresentation = attributes.some(
+        (/** @type {any} */ attribute) =>
+          attribute.type === 'JSXAttribute' &&
+          attribute.name?.name === 'presentation',
+      );
+      const prop = propPath.node;
+      if (hasPresentation) {
+        // FR4: presentation wins; drop the deprecated prop.
+        opening.attributes = attributes.filter(
+          (/** @type {any} */ attribute) => attribute !== prop,
+        );
+        hasChanges = true;
+        return;
+      }
+      const value =
+        prop.value?.type === 'JSXExpressionContainer'
+          ? prop.value.expression
+          : prop.value;
+      if (!mapStaticValue(value, component)) return;
+      prop.name.name = 'presentation';
+      hasChanges = true;
+    },
+  );
+
+  if (!hasChanges) return undefined;
+  return root.toSource({quote: 'single'});
+}

package/assets/codemods/transforms/v0.6.4/migrate-theme-catalog-to-descriptors.mjs

@@ -0,0 +1,141 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Give each integration theme a typed descriptor instead of the
+ *   `manifest.json` theme catalog.
+ *
+ * Astryx 0.6 scaffolded integration themes into one catalog,
+ * `<themes root>/manifest.json`. Each theme now carries a strongly typed
+ * same-stem `.doc.mjs` descriptor, and a themes root that still holds the
+ * catalog is refused. This project codemod reads the package's integration
+ * manifest, plans one descriptor per catalog entry beside that theme's source,
+ * and removes the catalog. When any entry cannot convert, it plans nothing and
+ * names the entry, so the package is never left half converted.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {loadManifestObject} from '../../../../foundation/integrations/integrations.mjs';
+import {findLocalIntegrationManifestOrNull} from '../../../../foundation/integrations/manifest-writer.mjs';
+import {themeDescriptorSource} from '../../../../foundation/integrations/theme-descriptor.mjs';
+
+export const meta = {
+  title:
+    'Give each integration theme a typed descriptor instead of the manifest.json catalog',
+  description:
+    'Writes <name>Theme.doc.mjs beside each theme the catalog lists, then removes the catalog.',
+  codemodType: 'project',
+};
+
+const SLUG = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u;
+const SOURCE = /\.(?:ts|tsx|mjs|js)$/u;
+
+/**
+ * @param {string} root the package directory
+ * @returns {Promise<import('../../runner.mjs').ProjectCodemodPlan>}
+ */
+export default async function migrateThemeCatalogToDescriptors(root) {
+  /** @type {import('../../runner.mjs').ProjectCodemodPlan} */
+  const plan = {writes: [], deletes: [], problems: []};
+  /** @param {string} file @returns {string} */
+  const rel = file => path.relative(root, file).split(path.sep).join('/');
+  /** @param {string} file @param {string} message */
+  const problem = (file, message) => plan.problems.push({file, message});
+
+  const manifestFile = findLocalIntegrationManifestOrNull(root);
+  if (!manifestFile) return plan;
+  const manifest = await loadManifestObject(
+    manifestFile,
+    `Integration manifest ${path.basename(manifestFile)}`,
+    {fresh: true},
+  );
+  if (typeof manifest.themes !== 'string') return plan;
+  const themesRoot = path.resolve(root, manifest.themes);
+  const fromRoot = path.relative(root, themesRoot);
+  if (fromRoot.startsWith('..') || path.isAbsolute(fromRoot)) return plan;
+  const catalogFile = path.join(themesRoot, 'manifest.json');
+  if (!fs.existsSync(catalogFile)) return plan;
+  const catalogPath = rel(catalogFile);
+
+  let catalog;
+  try {
+    catalog = JSON.parse(fs.readFileSync(catalogFile, 'utf-8'));
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    problem(catalogPath, `is not valid JSON (${reason}).`);
+    return plan;
+  }
+  if (
+    !catalog ||
+    typeof catalog !== 'object' ||
+    catalog.version !== 1 ||
+    !Array.isArray(catalog.themes)
+  ) {
+    problem(catalogPath, 'is not a version 1 theme catalog.');
+    return plan;
+  }
+
+  for (const [index, entry] of catalog.themes.entries()) {
+    const slug = entry?.slug;
+    if (typeof slug !== 'string' || !SLUG.test(slug)) {
+      problem(
+        catalogPath,
+        `themes[${index}] has no lowercase kebab-case slug; fix the entry or add that theme's descriptor by hand.`,
+      );
+      continue;
+    }
+    const themeDir = path.join(themesRoot, slug);
+    const source = entry.entry;
+    if (
+      typeof source !== 'string' ||
+      !SOURCE.test(source) ||
+      source !== path.basename(source)
+    ) {
+      problem(
+        catalogPath,
+        `theme "${slug}" has entry ${JSON.stringify(source)}; a descriptor sits beside a .ts, .tsx, .mjs, or .js source directly in ${rel(themeDir)}/.`,
+      );
+      continue;
+    }
+    const stem = source.replace(SOURCE, '');
+    if (entry.exportName !== stem) {
+      problem(
+        catalogPath,
+        `theme "${slug}" exports ${JSON.stringify(entry.exportName)} from ${source}; a descriptor takes the export name from the file name, so rename the export or the file to match.`,
+      );
+      continue;
+    }
+    if (typeof entry.displayName !== 'string' || !entry.displayName.trim()) {
+      problem(catalogPath, `theme "${slug}" has no displayName.`);
+      continue;
+    }
+    if (typeof entry.description !== 'string') {
+      problem(catalogPath, `theme "${slug}" has no description string.`);
+      continue;
+    }
+    if (typeof entry.maintained !== 'boolean') {
+      problem(catalogPath, `theme "${slug}" has no maintained flag.`);
+      continue;
+    }
+    if (!fs.existsSync(path.join(themeDir, source))) {
+      problem(rel(themeDir), `holds no ${source} for theme "${slug}".`);
+      continue;
+    }
+    const descriptor = path.join(themeDir, `${stem}.doc.mjs`);
+    if (fs.existsSync(descriptor)) continue;
+    plan.writes.push({
+      path: descriptor,
+      contents: themeDescriptorSource({
+        type: 'theme',
+        name: slug,
+        displayName: entry.displayName,
+        description: entry.description,
+        maintained: entry.maintained,
+      }),
+    });
+  }
+  if (plan.problems.length > 0)
+    return {writes: [], deletes: [], problems: plan.problems};
+  plan.deletes.push(catalogFile);
+  return plan;
+}

package/assets/docs/README.md

@@ -48,3 +48,12 @@ The material is usually good; the finding is placement, not quality. It goes in
 **Fits no row?** It is still not caller-facing. Default it to [Contributing](https://github.com/facebook/astryx/wiki/Contributing), or `CONTRIBUTING.md` when it is a step someone follows with the repo cloned. Never default it back to this directory.
 
 Worked example: a responsive-and-interaction readiness rubric is grading criteria → **Component-Audit-Rubric**, or **Component-Lifecycle** if it is a promotion gate.
+
+## Sections are read one at a time
+
+`astryx docs <topic> --index` lists a topic's sections, and readers then open
+one section by its key. A section's key is its `id`, or a key derived from its
+title when it has none. Give a section an `id` when its title may change, since
+readers and extensions link to the key. Two sections in one topic cannot share
+a key. Keep each section small enough to read on its own: `astryx doctor` fails
+any section over 32 KB.

package/assets/docs/authoring.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs authoring`: every authoring schema, one section each.
+ *
+ * Built from the self-docs colocated under packages/cli/authoring, so it cannot
+ * drift from the schemas it describes. `astryx doctor` names a self-doc this
+ * topic cannot reach.
+ */
+
+import {buildAuthoringTopic} from '../../foundation/discovery/authoring-self-docs.mjs';
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = await buildAuthoringTopic();

package/assets/docs/getting-started.doc.mjs

@@ -98,11 +98,11 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'These stylesheets are cascade-layered: the reset loads in @layer reset and component styles in @layer astryx-base. If your project has existing global CSS, a legacy reset, or Tailwind, declare the layer order explicitly and assign every stylesheet to a layer deliberately: unlayered styles and later layers both override astryx-base regardless of specificity. See the Cascade Layer Safety section in `astryx docs migration` before building screens.',
+          text: 'These stylesheets are cascade-layered: the reset loads in @layer reset and component styles in @layer astryx-base. If your project has existing global CSS, a legacy reset, or Tailwind, declare the layer order explicitly and assign every stylesheet to a layer deliberately: unlayered styles and later layers both override astryx-base regardless of specificity. See the Cascade Layer Safety section in {@link generic:migration} before building screens.',
         },
         {
           type: 'prose',
-          text: 'Run `astryx docs theme` for the full theming guide.',
+          text: 'Run {@link generic:theme} for the full theming guide.',
         },
       ],
     },

package/assets/docs/internationalization.doc.mjs

@@ -41,15 +41,17 @@ function App() {
           lang: 'tsx',
           label: 'Load an astryx locale catalog',
           code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';
-import fr from '@astryxdesign/core/locales/fr.json';
+import frFR from '@astryxdesign/core/locales/fr-FR.generated.js';
 
-<InternationalizationProvider locale="fr" messages={{fr}}>
+<InternationalizationProvider
+  locale="fr-FR"
+  messages={{'fr-FR': frFR}}>
   <App />
 </InternationalizationProvider>;`,
         },
         {
           type: 'prose',
-          text: 'Astryx ships English today, with first-party translations for other locales on the roadmap. Until a locale is available from `@astryxdesign/core/locales/*`, apps can pass a local catalog with the same shape. See `@astryxdesign/core/locales/en.json` for the current key inventory. Missing keys fall back through the locale chain to English (for example, `pt-BR` walks to `pt`, then to shipped `en`).',
+          text: 'Astryx ships English and first-party translations for supported locales. Compact runtime modules from `@astryxdesign/core/locales/*.generated.js` contain only the messages apps need; the existing `@astryxdesign/core/locales/*.json` files retain translator context. Until a locale is available, apps can pass a local catalog in either shape. Missing keys fall back through the locale chain to English (for example, `pt-BR` walks to `pt`, then to shipped `en`).',
         },
         {
           type: 'prose',
@@ -290,7 +292,7 @@ export default function App() {
         },
         {
           type: 'prose',
-          text: '`Catalog` types a single locale file; `MessagesByLocale` types the map passed to `messages`. A catalog entry uses the same `{defaultMessage, description?}` shape as `@astryxdesign/core/locales/en.json`.',
+          text: '`Catalog` types the rich `{defaultMessage, description?}` authoring shape. `RuntimeCatalog` types the generated key-to-message string map. `ProviderMessagesByLocale` accepts either shape for the provider, while `MessagesByLocale` keeps the original rich-only context shape.',
         },
       ],
     },
@@ -307,7 +309,7 @@ export default function App() {
           lang: 'tsx',
           label: 'Turn on pseudo-localization',
           code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';
-import pseudo from '@astryxdesign/core/locales/pseudo.json';
+import pseudo from '@astryxdesign/core/locales/pseudo.generated.js';
 
 <InternationalizationProvider locale="pseudo" messages={{pseudo}}>
   <App />

package/assets/docs/layout.doc.dense.mjs

@@ -25,7 +25,7 @@ export const docsDense = {
         },
         {
           type: 'prose',
-          text: 'decides layout, not component APIs. npx astryx build "<idea>" = closest template for your app type. npx astryx component <Name> = props.',
+          text: 'decides layout, not component APIs. npx astryx build "<idea>" = the template to start from for your app type. npx astryx component <Name> = props.',
         },
       ],
     },
@@ -71,7 +71,7 @@ export const docsDense = {
         null,
         {
           type: 'prose',
-          text: 'verify: you can state the reason in one sentence, and it still holds if the nav doubles. npx astryx build "<idea>" names the closest template, --skeleton shows the pairing wired up.',
+          text: 'verify: you can state the reason in one sentence, and it still holds if the nav doubles. npx astryx build "<idea>" names the template to start from; scaffold it and the pairing is wired up.',
         },
         // Best practices
         null,

package/assets/docs/layout.doc.mjs

@@ -106,7 +106,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'Verify: you can state the reason in one sentence, and the choice still holds if the nav doubles in size. `npx astryx build "<idea>"` names the closest template, and its `--skeleton` shows the pairing already wired up.',
+          text: 'Verify: you can state the reason in one sentence, and the choice still holds if the nav doubles in size. `npx astryx build "<idea>"` names the template to start from; scaffold it and the pairing is already wired up.',
         },
 
         {type: 'heading', level: 3, text: 'Best practices'},