@astryxdesign/cli 0.7.12-canary.da3dbdc → 0.7.12-canary.dfd75a6

package/api/icon/_authoring.mjs

@@ -691,6 +691,7 @@ async function redeclareIconSet(
     );
     result.data.icons = set.data.icons.length;
     result.data.updated = true;
+    if (where.moduleUpdate) result.data.moduleUpdate = where.moduleUpdate;
     // A look the icons' own library draws comes from that library, so its
     // command runs as printed; any other look comes from a module the
     // author names.
@@ -1388,6 +1389,7 @@ async function refreshIconSet(
     );
     result.data.icons = icons.length;
     result.data.refreshed = true;
+    if (where.moduleUpdate) result.data.moduleUpdate = where.moduleUpdate;
     // Every entry an exact name gives, kept or new, so a refresh lists
     // them for review again.
     const byName = Object.fromEntries(
@@ -1542,7 +1544,7 @@ export async function addIconDefinition(name, options) {
         throw error;
       }
     }
-    return receipt(
+    const result = receipt(
       'icon-definition',
       doc.name,
       {
@@ -1559,5 +1561,10 @@ export async function addIconDefinition(name, options) {
       files,
       dryRun,
     );
+    // Only a new definition with an icon writes the data file.
+    if (icon != null && where.moduleUpdate) {
+      result.data.moduleUpdate = where.moduleUpdate;
+    }
+    return result;
   });
 }

package/api/icon/add/add.mjs

@@ -147,6 +147,15 @@ export async function iconAdd(exportName, options) {
       );
     }
   }
+  // An export name cannot start with a digit, and an id the author gives has
+  // no library prefix to keep.
+  if (givenId != null && /^[0-9]/u.test(givenId)) {
+    throw new AstryxError(
+      `The icon id "${givenId}" starts with a digit, and an export name cannot. Pass --id with an id that starts with a letter.`,
+      undefined,
+      ERROR_CODES.ERR_INVALID_ARGUMENT,
+    );
+  }
   if (all) {
     return authoring(() => addVariantForAll({cwd, from, selector, variant}));
   }
@@ -386,6 +395,8 @@ export async function iconAdd(exportName, options) {
       map,
       icons,
     };
+    const dataChanged =
+      JSON.stringify(next) !== JSON.stringify(set.data) || where.moduleRenamed;
     /** @type {string[]} */
     const files = [];
     // Every write happens inside this try, so any failure undoes the ones
@@ -413,7 +424,7 @@ export async function iconAdd(exportName, options) {
             .join('/'),
         );
       }
-      if (JSON.stringify(next) !== JSON.stringify(set.data)) {
+      if (dataChanged) {
         writeIconSetData(set, next, {
           extraDefinitions: created ? [created.name] : [],
         });
@@ -433,10 +444,12 @@ export async function iconAdd(exportName, options) {
       }
       throw error;
     }
-    const changed =
+    // A renamed package's new name alone is not an added icon.
+    const added =
       JSON.stringify(next) !== JSON.stringify(set.data) ||
       created != null ||
       generatedChanged;
+    const changed = dataChanged || added;
     // A ./ file publishes only when package.json `files` lists it; the
     // author adds it (architecture:cli-surface INV16).
     const note =
@@ -457,6 +470,8 @@ export async function iconAdd(exportName, options) {
         ...(created ? {newDefinition: created.name} : {}),
         files,
         changed,
+        added,
+        ...(where.moduleUpdate ? {moduleUpdate: where.moduleUpdate} : {}),
         ...(note ? {note} : {}),
       },
     };
@@ -638,8 +653,27 @@ async function addVariantForAll({cwd, from, selector, variant}) {
   );
   // Only icons from the same package as the variant module can have a
   // variant there: an icon from your own `./` file, or from another library,
-  // is left as it is and never listed as missing.
+  // is left as it is and never listed as missing. Some libraries ship each
+  // look as its own package (Font Awesome's solid and regular packages): an
+  // icon from another package meets its variant only under the same export
+  // name and of the same kind, a component or data for the adapter. Once
+  // one icon of a package meets its twin, that package is a look package of
+  // the variant module, so its other icons are listed as missing.
   const variantPackage = iconModulePackage(source.module);
+  /** @param {{module: string, source: string, adapt: boolean}} origin */
+  const otherPackageTwin = origin => {
+    if (origin.module.startsWith('.')) return false;
+    const twin = byLibraryExport.get(origin.source);
+    return twin != null && twin.adapt === origin.adapt;
+  };
+  const lookPackages = new Set(
+    set.data.icons.flatMap(icon => {
+      const origin = origins.get(icon.export);
+      return origin && otherPackageTwin(origin)
+        ? [iconModulePackage(origin.module)]
+        : [];
+    }),
+  );
   const generated = generatedModulePath(set, packageDir);
   /** @type {import('../../../foundation/discovery/icon-set-writer.mjs').GeneratedIcon[]} */
   const toWrite = [];
@@ -653,7 +687,11 @@ async function addVariantForAll({cwd, from, selector, variant}) {
   const own = [];
   const icons = set.data.icons.map(icon => {
     const origin = origins.get(icon.export);
-    if (origin && iconModulePackage(origin.module) !== variantPackage) {
+    if (
+      origin &&
+      iconModulePackage(origin.module) !== variantPackage &&
+      !lookPackages.has(iconModulePackage(origin.module))
+    ) {
       return icon;
     }
     const librarySource =
@@ -742,7 +780,8 @@ async function addVariantForAll({cwd, from, selector, variant}) {
   const files = [];
   const written = writeGeneratedIcons(packageDir, generated, next, toWrite);
   files.push(...written.files);
-  const dataChanged = JSON.stringify(next) !== JSON.stringify(set.data);
+  const dataChanged =
+    JSON.stringify(next) !== JSON.stringify(set.data) || where.moduleRenamed;
   if (dataChanged) {
     try {
       writeIconSetData(set, next);
@@ -766,6 +805,7 @@ async function addVariantForAll({cwd, from, selector, variant}) {
       missing,
       files,
       changed: dataChanged || written.changed,
+      ...(where.moduleUpdate ? {moduleUpdate: where.moduleUpdate} : {}),
     },
   };
 }

package/api/icon/icon.type.d.mts

@@ -223,6 +223,10 @@ export type IconMapManyResponse = {
             changed: boolean;
         }>;
         changed: boolean;
+        moduleUpdate?: {
+            previous: string;
+            module: string;
+        } | undefined;
         files?: string[] | undefined;
     };
 };
@@ -239,6 +243,10 @@ export type IconMapResponse = {
         icon: string | null;
         previous: string | null;
         changed: boolean;
+        moduleUpdate?: {
+            previous: string;
+            module: string;
+        } | undefined;
         files?: string[] | undefined;
     };
 };
@@ -303,6 +311,10 @@ export type IconAddVariantsResponse = {
         missing: string[];
         files: string[];
         changed: boolean;
+        moduleUpdate?: {
+            previous: string;
+            module: string;
+        } | undefined;
     };
 };
 /**
@@ -323,6 +335,11 @@ export type IconAddResponse = {
         newDefinition?: string | undefined;
         files: string[];
         changed: boolean;
+        added: boolean;
+        moduleUpdate?: {
+            previous: string;
+            module: string;
+        } | undefined;
         note?: string | undefined;
     };
 };
@@ -557,6 +574,13 @@ export type IconNewData = {
      * - What the author does next, including each change the package needs that the CLI never makes itself (its entry, peers, scripts), as text to copy.
      */
     notes?: string[] | undefined;
+    /**
+     * - On a refresh, an update, or a new definition with `icon`: the data file's `module` before and after this command, when the package was renamed and the command writes its new name.
+     */
+    moduleUpdate?: {
+        previous: string;
+        module: string;
+    } | undefined;
 };
 /**
  * `astryx --json experimental icon new-set <name>`.

package/api/icon/icon.type.mjs

@@ -156,6 +156,7 @@
  * @property {string} data.file - The data file, relative to the package.
  * @property {Array<{definition: string, icon: string, previous: string | null, changed: boolean}>} data.entries - Each pair, in order, and what it replaced.
  * @property {boolean} data.changed - Whether the file was written.
+ * @property {{previous: string, module: string}} [data.moduleUpdate] - The data file's `module` before and after this command, when the package was renamed and the command wrote its new name.
  * @property {string[]} [data.files] - The generated module and its types, when its theme map was rewritten.
  */
 
@@ -172,6 +173,7 @@
  * @property {string | null} data.icon - The id of the icon now mapped (the icon may be named by any name `map` accepts); null after `remove`.
  * @property {string | null} data.previous - The icon id it replaced.
  * @property {boolean} data.changed - Whether the file was written.
+ * @property {{previous: string, module: string}} [data.moduleUpdate] - The data file's `module` before and after this command, when the package was renamed and the command wrote its new name.
  * @property {string[]} [data.files] - The generated module and its types, when its theme map was rewritten.
  */
 
@@ -207,6 +209,7 @@
  * @property {string[]} data.missing - Ids of icons `from` has no export for; they keep no such variant.
  * @property {string[]} data.files - Files written, relative to the package.
  * @property {boolean} data.changed
+ * @property {{previous: string, module: string}} [data.moduleUpdate] - The data file's `module` before and after this command, when the package was renamed and the command wrote its new name.
  */
 
 /**
@@ -223,6 +226,8 @@
  * @property {string} [data.newDefinition] - The set's own definition the command wrote.
  * @property {string[]} data.files - Files written, relative to the package.
  * @property {boolean} data.changed - Whether anything was written.
+ * @property {boolean} data.added - Whether the icon, its variant, its `map` entry, or a new definition was added. False when the set already had them, even when `changed` is true because the command wrote a renamed package's new name.
+ * @property {{previous: string, module: string}} [data.moduleUpdate] - The data file's `module` before and after this command, when the package was renamed and the command wrote its new name.
  * @property {string} [data.note] - What the package still needs, as text to copy: the entry line that exports the icon from the set's module, and the package.json `files` that publishes a `./` source.
  */
 
@@ -332,6 +337,7 @@
  * @property {Array<{definition: string, icon: string}>} [mapped] - With `from`: the `map` entries an icon with the definition's exact name gives (on a refresh, every such entry, kept or new); check each.
  * @property {Array<{definition: string, icon: string, word: string}>} [suggestions] - With `from`: for each unmapped Astryx definition, up to three icons it might map to, best first: the definition's name in another spelling or as another name of an icon, ids that start with it, an id or another name that is one of its words, then two-word ids that are a one-word word sized, shaped, or numbered (`grid-2x2`); never a negated form, the opposite direction, or an icon already mapped. `word` is the name or word that matched. Never written.
  * @property {string[]} [notes] - What the author does next, including each change the package needs that the CLI never makes itself (its entry, peers, scripts), as text to copy.
+ * @property {{previous: string, module: string}} [moduleUpdate] - On a refresh, an update, or a new definition with `icon`: the data file's `module` before and after this command, when the package was renamed and the command writes its new name.
  */
 
 /**

package/api/icon/iconAdd.doc.mjs

@@ -119,7 +119,7 @@ export const doc = {
     },
     {
       code: 'ERR_INVALID_ARGUMENT',
-      when: "the export is data rather than a component, a new definition is named like an Astryx one, or the variant is not one the set declares, is the look each icon's own export already draws, or is no look word of a library whose export names encode looks",
+      when: "the export is data rather than a component, a new definition is named like an Astryx one, or the variant is not one the set declares, is the look each icon's own export already draws, or is no look word of a library whose export names encode looks, or `id` starts with a digit",
     },
     {code: 'ERR_FILE_EXISTS', when: 'another icon already has the id'},
     {

package/api/icon/map/map.mjs

@@ -77,7 +77,8 @@ export async function iconMap(definition, icon, options = {}) {
         ERROR_CODES.ERR_MISSING_ARGUMENT,
       );
     }
-    const {packageDir, set} = await findLocalIconSet(cwd, selector);
+    const {packageDir, set, moduleRenamed, moduleUpdate} =
+      await findLocalIconSet(cwd, selector);
     // The docs' kebab id (`eye-slash`) names the same definition, and a
     // library's other name for an icon (`trash-2`) names the same icon.
     definition = definitionNameOf(definition, mappableDefinitions(set));
@@ -112,7 +113,8 @@ export async function iconMap(definition, icon, options = {}) {
       }
       map[definition] = /** @type {string} */ (icon);
     }
-    const changed = remove ? previous != null : previous !== icon;
+    const changed =
+      (remove ? previous != null : previous !== icon) || moduleRenamed;
     /** @type {string[]} */
     const files = [];
     if (changed) {
@@ -139,6 +141,7 @@ export async function iconMap(definition, icon, options = {}) {
         icon: remove ? null : /** @type {string} */ (icon),
         previous,
         changed,
+        ...(moduleUpdate ? {moduleUpdate} : {}),
         ...(files.length > 0 ? {files} : {}),
       },
     };
@@ -161,7 +164,10 @@ async function mapMany({cwd, selector, pairs}) {
       ERROR_CODES.ERR_MISSING_ARGUMENT,
     );
   }
-  const {packageDir, set} = await findLocalIconSet(cwd, selector);
+  const {packageDir, set, moduleRenamed, moduleUpdate} = await findLocalIconSet(
+    cwd,
+    selector,
+  );
   const known = mappableDefinitions(set);
   const ids = set.data.icons.map(each => each.id);
   const map = {...(set.data.map ?? {})};
@@ -204,7 +210,7 @@ async function mapMany({cwd, selector, pairs}) {
       changed: previous !== id,
     });
   }
-  const changed = entries.some(each => each.changed);
+  const changed = entries.some(each => each.changed) || moduleRenamed;
   /** @type {string[]} */
   const files = [];
   if (changed) {
@@ -228,6 +234,7 @@ async function mapMany({cwd, selector, pairs}) {
       file: path.relative(packageDir, set.dataPath).split(path.sep).join('/'),
       entries,
       changed,
+      ...(moduleUpdate ? {moduleUpdate} : {}),
       ...(files.length > 0 ? {files} : {}),
     },
   };

package/api/integration/add-helpers.d.mts

@@ -92,7 +92,7 @@ export function loadCurrentManifest(manifestFile: string, manifestExists: boolea
  * @param {string} manifestPath
  * @param {string[]} files
  * @param {boolean} dryRun
- * @returns {{type: 'integration.add', data: Omit<import('./integration-authoring.type.mjs').IntegrationAddData, 'kind'> & {kind: K, icons?: number, refreshed?: boolean, updated?: boolean, renamed?: Array<{from: string, to: string}>, moved?: Array<{id: string, from: string, to: string}>, licenseNoticeMissing?: {library: string, path: string}, mapped?: Array<{definition: string, icon: string}>, suggestions?: Array<{definition: string, icon: string, word: string}>, notes?: string[]}}}
+ * @returns {{type: 'integration.add', data: Omit<import('./integration-authoring.type.mjs').IntegrationAddData, 'kind'> & {kind: K, icons?: number, refreshed?: boolean, updated?: boolean, renamed?: Array<{from: string, to: string}>, moved?: Array<{id: string, from: string, to: string}>, licenseNoticeMissing?: {library: string, path: string}, mapped?: Array<{definition: string, icon: string}>, suggestions?: Array<{definition: string, icon: string, word: string}>, notes?: string[], moduleUpdate?: {previous: string, module: string}}}}
  */
 export function receipt<K extends import("./integration-authoring.type.mjs").IntegrationAddData["kind"] | import("../icon/icon.type.mjs").IconNewData["kind"]>(kind: K, name: string, root: {
     path: string;
@@ -127,6 +127,10 @@ export function receipt<K extends import("./integration-authoring.type.mjs").Int
             word: string;
         }>;
         notes?: string[];
+        moduleUpdate?: {
+            previous: string;
+            module: string;
+        };
     };
 };
 /** @param {string} slug */

package/api/integration/add-helpers.mjs

@@ -486,7 +486,7 @@ export async function loadCurrentManifest(manifestFile, manifestExists) {
  * @param {string} manifestPath
  * @param {string[]} files
  * @param {boolean} dryRun
- * @returns {{type: 'integration.add', data: Omit<import('./integration-authoring.type.mjs').IntegrationAddData, 'kind'> & {kind: K, icons?: number, refreshed?: boolean, updated?: boolean, renamed?: Array<{from: string, to: string}>, moved?: Array<{id: string, from: string, to: string}>, licenseNoticeMissing?: {library: string, path: string}, mapped?: Array<{definition: string, icon: string}>, suggestions?: Array<{definition: string, icon: string, word: string}>, notes?: string[]}}}
+ * @returns {{type: 'integration.add', data: Omit<import('./integration-authoring.type.mjs').IntegrationAddData, 'kind'> & {kind: K, icons?: number, refreshed?: boolean, updated?: boolean, renamed?: Array<{from: string, to: string}>, moved?: Array<{id: string, from: string, to: string}>, licenseNoticeMissing?: {library: string, path: string}, mapped?: Array<{definition: string, icon: string}>, suggestions?: Array<{definition: string, icon: string, word: string}>, notes?: string[], moduleUpdate?: {previous: string, module: string}}}}
  */
 export function receipt(kind, name, root, manifestPath, files, dryRun) {
   return {

package/api/render/render.doc.mjs

@@ -96,7 +96,7 @@ export const doc = {
     {code: 'ERR_RENDER_BROWSER_API', when: 'the page reads a browser-only API, such as window or document, while rendering'},
     {code: 'ERR_RENDER_ASSET_TOO_LARGE', when: 'a local file the page uses is over 8 MB'},
     {code: 'ERR_RENDER_TIMEOUT', when: 'the page does not finish rendering within 60 seconds'},
-    {code: 'ERR_RENDER_FAILED', when: 'the page throws while rendering for any other reason'},
+    {code: 'ERR_RENDER_FAILED', when: 'the page throws while rendering for any other reason, or Node itself crashes (a crash signal, or a crash status on Windows) or is stopped by a signal while it renders the page (the message names the Node version and path)'},
     {
       code: 'ERR_RENDER_NOT_ASTRYX',
       when: 'reversing a file a render did not write, with no embedded source and no Astryx markup; the suggestion is `astryx build "<what the page is>"`',

package/api/render/render.type.d.mts

@@ -31,7 +31,7 @@ export type RenderWarning = {
     /**
      * - What kind of problem.
      */
-    code: "dropped-children" | "remote-asset" | "missing-asset" | "page-output" | "page-script" | "no-astryx-styles" | "chart-size" | "not-embedded";
+    code: "dropped-children" | "remote-asset" | "missing-asset" | "page-output" | "page-script" | "no-astryx-styles" | "chart-size" | "not-embedded" | "node-crash";
     /**
      * - What happened and what to do, in one sentence.
      */

package/api/render/render.type.mjs

@@ -22,7 +22,7 @@
  * author meant.
  * @experimental May change or be removed in a patch release.
  * @typedef {object} RenderWarning
- * @property {'dropped-children' | 'remote-asset' | 'missing-asset' | 'page-output' | 'page-script' | 'no-astryx-styles' | 'chart-size' | 'not-embedded'} code - What kind of problem.
+ * @property {'dropped-children' | 'remote-asset' | 'missing-asset' | 'page-output' | 'page-script' | 'no-astryx-styles' | 'chart-size' | 'not-embedded' | 'node-crash'} code - What kind of problem.
  * @property {string} message - What happened and what to do, in one sentence.
  */
 

package/assets/docs/tree/icon-sets.doc.mjs

@@ -61,7 +61,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: "`outline.doc.mjs` is the descriptor: name, display name and description (`--display-name`, `--description`), and `license`, the SPDX license of the artwork (it starts as your package's own). `outline.icons.json` starts with no icons and an empty `map`; its `module` is your package name. `outline.generated.js` is the set's generated module, with its declaration file `outline.generated.d.ts`: the CLI writes both, and every icon and the theme map are exports of it. Every field is in {@link schema:icon-set-doc} and {@link schema:icon-set-data}.",
+          text: "`outline.doc.mjs` is the descriptor: name, display name and description (`--display-name`, `--description`), and `license`, the SPDX license of the artwork (it starts as your package's own). `outline.icons.json` starts with no icons and an empty `map`; its `module` is your package name. After you rename the package, the next command that writes the data file (`new-set` on the existing set, with or without `--from`, `add`, `map`, or `new-definition --icon`) writes the new name and keeps any subpath (`@acme/old-icons/outline` becomes `@acme/new-icons/outline`), and its receipt says so. `outline.generated.js` is the set's generated module, with its declaration file `outline.generated.d.ts`: the CLI writes both, and every icon and the theme map are exports of it. Every field is in {@link schema:icon-set-doc} and {@link schema:icon-set-data}.",
         },
         {
           type: 'prose',
@@ -121,7 +121,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: "Every component the library exports becomes an icon (an alias of one component is recorded once), named `<Name>Icon`, with an id from its name (`Squares2X2Icon` is `squares-2x2`: a dimension stays one word). `map` is filled only where a definition's name is an icon's id (`delete` → icon `delete`), and the receipt lists those entries under Mapped by name: a library can draw another meaning under the same name (one library's `delete` is a backspace key), so check each. An icon whose id is only one of a definition's words (`trash` for `delete`) may mean something else in this library, so the receipt lists it under Suggestions, with the `experimental icon map <definition> <icon>` command for each, and writes nothing for it: check the meaning, then run the ones that fit. Run it again after a library release to refresh the icons that library supplies; `map` entries whose icon still exists are kept, and the receipt names any icon the library dropped, any icon `--exclude` left out, and the `map` entries each took with it. Icons you added from your own files or another library are left as they are. Icons you added one file at a time from the same package (`--from <package>/dist/XIcon`) move to the root import when you refresh from the package root and the root exports the same icon; each keeps its id, export, `map` entries, variants, and words on that refresh and every later one, and the receipt lists it under `moved`. A library icon whose id or name a moved icon already has is left out. When another icon of the set already reads the same root export, the icon stays on its own file, and the receipt says why. An icon you already have is known by the library export it re-exports, so it keeps its export name exactly, its `map` entries, variants, and words, even when a newer CLI spells its id differently or your `--exclude` lets a library prefix come off new ids; the receipt lists each changed id under `renamed`. An id you chose that is not a spelling of the library name (`dismiss` for `XIcon`) is kept. A refresh with `--dry-run` writes nothing and prints the Mapped by name and Suggestions lists again; `--display-name` and `--description` on a refresh rewrite the descriptor. Variants added with `add --variant … --all` are kept too; run that `add` again to pick up icons the release added. `experimental icon --list` shows how many definitions the set maps.",
+          text: "Every component the library exports becomes an icon (an alias of one component is recorded once), named `<Name>Icon`, with an id from its name (`Squares2X2Icon` is `squares-2x2`: a dimension stays one word). An export name cannot start with a digit, so an icon whose id would start with one once the library prefix comes off keeps the prefix (`fa0` is id `fa-0`, exported as `Fa0Icon`), and an id you give with `--id` must start with a letter. `map` is filled only where a definition's name is an icon's id (`delete` → icon `delete`), and the receipt lists those entries under Mapped by name: a library can draw another meaning under the same name (one library's `delete` is a backspace key), so check each. An icon whose id is only one of a definition's words (`trash` for `delete`) may mean something else in this library, so the receipt lists it under Suggestions, with the `experimental icon map <definition> <icon>` command for each, and writes nothing for it: check the meaning, then run the ones that fit. Run it again after a library release to refresh the icons that library supplies; `map` entries whose icon still exists are kept, and the receipt names any icon the library dropped, any icon `--exclude` left out, and the `map` entries each took with it. Icons you added from your own files or another library are left as they are. Icons you added one file at a time from the same package (`--from <package>/dist/XIcon`) move to the root import when you refresh from the package root and the root exports the same icon; each keeps its id, export, `map` entries, variants, and words on that refresh and every later one, and the receipt lists it under `moved`. A library icon whose id or name a moved icon already has is left out. When another icon of the set already reads the same root export, the icon stays on its own file, and the receipt says why. An icon you already have is known by the library export it re-exports, so it keeps its export name exactly, its `map` entries, variants, and words, even when a newer CLI spells its id differently or your `--exclude` lets a library prefix come off new ids; the receipt lists each changed id under `renamed`. An id you chose that is not a spelling of the library name (`dismiss` for `XIcon`) is kept. A refresh with `--dry-run` writes nothing and prints the Mapped by name and Suggestions lists again; `--display-name` and `--description` on a refresh rewrite the descriptor. Variants added with `add --variant … --all` are kept too; run that `add` again to pick up icons the release added. `experimental icon --list` shows how many definitions the set maps.",
         },
         {
           type: 'prose',
@@ -139,11 +139,11 @@ astryx experimental icon add --variant solid --from @heroicons/react/24/solid --
         },
         {
           type: 'prose',
-          text: "A library that redraws its artwork for small sizes (Heroicons' 20px mini and 16px micro) ships each of those as its own set in its own package (their export names match the 24px ones), not as variants: a variant's size comes from CSS. `--variants` lists the variants; `--default-variant` names the one each icon's own export draws (when omitted, the look a library that names its looks draws; otherwise the set's current default, else, on a set without icons, the first variant; a set with icons changes it only with `--from`, and only in a library that names its looks). `--all` adds the variant for every icon whose id an export of `--from` has (`TrashIcon` in the solid module becomes `TrashSolidIcon`, the solid variant of `trash`), and the receipt lists the icons the module has no export for. Running it again changes nothing.",
+          text: "A library that redraws its artwork for small sizes (Heroicons' 20px mini and 16px micro) ships each of those as its own set in its own package (their export names match the 24px ones), not as variants: a variant's size comes from CSS. `--variants` lists the variants; `--default-variant` names the one each icon's own export draws (when omitted, the look a library that names its looks draws; otherwise the set's current default, else, on a set without icons, the first variant; a set with icons changes it only with `--from`, and only in a library that names its looks). `--all` adds the variant for every icon whose id an export of `--from` has (`TrashIcon` in the solid module becomes `TrashSolidIcon`, the solid variant of `trash`), and the receipt lists the icons the module has no export for. A library may ship each look as its own package (Font Awesome's solid and regular packages): `--from` may then name the other package, and an icon gains the variant from the export of the same name there; the receipt lists the icons that package has no export for. Running it again changes nothing.",
         },
         {
           type: 'prose',
-          text: 'A library whose icons are data (objects or SVG strings) has no components to find: create the set, declare an `adapter` in its data file (see library shapes), and run the command again; every data export then becomes an icon through the adapter. When every icon export shares a leading word, such as `feather` in `featherEye` and `featherSun`, ids and export names leave it out: `featherEye` becomes id `eye`, exported as `EyeIcon`. The prefix is read over icon-like exports only: SCREAMING_CASE constants (`README`, `VERSION`), number and boolean exports, and, next to components or icon objects, plain strings are never icons. Components named `…Provider` or `…Context` are never icons either. Leave out any other export that is not an icon with `--exclude meta,version`: the data file keeps the list in `exclude`, so a refresh leaves them out too. When a library exports one icon under several names (`Trash2` and `Trash`), the icon is recorded once and its other names become words, so `experimental icon trash-2` finds it and `experimental icon map delete trash-2` maps it. `experimental icon add` reads the prefix the same way, and reuses the icon an export already has, so its commands need no `--id`.',
+          text: 'A library whose icons are data (objects or SVG strings) has no components to find: create the set, declare an `adapter` in its data file (see library shapes), and run the command again; every data export then becomes an icon through the adapter. When every icon export shares a leading word, such as `feather` in `featherEye` and `featherSun`, ids and export names leave it out: `featherEye` becomes id `eye`, exported as `EyeIcon`. The prefix is read over icon-like exports only: SCREAMING_CASE constants (`README`, `VERSION`), number and boolean exports, and, next to components or icon objects, plain strings are never icons. Components named `…Provider` or `…Context` are never icons either, and neither is a pack: an object whose keys are all other exports of the module, such as `fas` next to `faXmark`. Leave out any other export that is not an icon with `--exclude meta,version`: the data file keeps the list in `exclude`, so a refresh leaves them out too. When a library exports one icon under several names (`Trash2` and `Trash`), the icon is recorded once and its other names become words, so `experimental icon trash-2` finds it and `experimental icon map delete trash-2` maps it. `experimental icon add` reads the prefix the same way, and reuses the icon an export already has, so its commands need no `--id`.',
         },
       ],
     },

package/assets/docs/tree/render-pages.doc.mjs

@@ -67,7 +67,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Each warning names something that may look different from what you meant, and what to change. The most common is a component that ignores its children: `<ListItem>Save</ListItem>` renders an empty row because ListItem takes `label="Save"`. Others flag remote images (a sandboxed viewer cannot load them; save the image next to the page and import it), a `<script>`, `<link>` or `<iframe>` the page itself renders (the file promises to run and load nothing, so remove them), missing images, and output the page printed while rendering.',
+          text: 'Each warning names something that may look different from what you meant, and what to change. The most common is a component that ignores its children: `<ListItem>Save</ListItem>` renders an empty row because ListItem takes `label="Save"`. Others flag remote images (a sandboxed viewer cannot load them; save the image next to the page and import it), a `<script>`, `<link>` or `<iframe>` the page itself renders (the file promises to run and load nothing, so remove them), missing images, and output the page printed while rendering. A `node-crash` warning names a Node build that crashes in `Intl.Segmenter` (its version and path). The page rendered without it, so the output may differ slightly: initials and character counts (such as Avatar initials) can split a joined emoji, a flag, or a letter written with a separate accent mark. Names in ordinary composed letters (`José`, `Zoë`, `李小龙`) come out the same. Render with an official Node.js build to remove the difference.',
         },
       ],
     },

package/assets/templates/themes/gothic/gothicTheme.ts

@@ -395,6 +395,22 @@ export const gothicTheme = defineTheme({
     },
   },
 
+  // Gothic's accent text and icons are one light color. On a media surface
+  // they follow that surface's accent, so a dark surface inside a light one
+  // gets its light accent back.
+  onDark: {
+    tokens: {
+      '--color-text-accent': 'var(--color-accent)',
+      '--color-icon-accent': 'var(--color-accent)',
+    },
+  },
+  onLight: {
+    tokens: {
+      '--color-text-accent': 'var(--color-accent)',
+      '--color-icon-accent': 'var(--color-accent)',
+    },
+  },
+
   icons: gothicIconRegistry,
 });
 

package/clients/cli/commands/experimental/icon.mjs

@@ -59,6 +59,20 @@ const defaultVariantText = value =>
 /** @param {unknown} value */
 const variantsText = value => (Array.isArray(value) ? value.join('/') : '');
 
+/**
+ * The receipt line for a data file whose `module` the command rewrote after
+ * a package rename.
+ * @param {{moduleUpdate?: {previous: string, module: string}, dryRun?: boolean}} data
+ */
+const moduleUpdateLines = data =>
+  data.moduleUpdate
+    ? [
+        text(
+          `${data.dryRun ? '[plan] Would update' : '[ok] Updated'} module to "${data.moduleUpdate.module}" (was "${data.moduleUpdate.previous}"), from the package name in package.json.`,
+        ),
+      ]
+    : [];
+
 /**
  * Register `icon` and its subcommands under the `experimental` group.
  * @param {import('commander').Command} group the `experimental` command
@@ -376,20 +390,24 @@ export function registerExperimentalIcon(group, program) {
                     (
                       /** @type {{definition: string, icon: string, previous: string | null}} */ each,
                     ) =>
-                      `${each.definition} = "${each.icon}"${each.previous && each.previous !== each.icon ? ` (was "${each.previous}")` : ''}`,
+                      `${each.definition} = "${each.icon}"${each.previous === each.icon ? ' (unchanged)' : each.previous ? ` (was "${each.previous}")` : ' (was not mapped)'}`,
                   ),
                 ),
+                ...moduleUpdateLines(data),
               )
             : emit(
+                // The entry line reads `previous` and `icon`: a write can
+                // come from a package rename alone.
                 text(
                   data.icon == null
-                    ? data.changed
+                    ? data.previous != null
                       ? `[ok] Removed map.${data.definition} (was "${data.previous}") from ${data.file}.`
                       : `[ok] ${data.file} has no map.${data.definition}.`
-                    : data.changed
+                    : data.previous !== data.icon
                       ? `[ok] map.${data.definition} = "${data.icon}" in ${data.file}${data.previous ? ` (was "${data.previous}")` : ''}.`
                       : `[ok] map.${data.definition} is already "${data.icon}".`,
                 ),
+                ...moduleUpdateLines(data),
               ),
       ),
   });
@@ -430,6 +448,7 @@ export function registerExperimentalIcon(group, program) {
               text(
                 `[ok] ${data.variant}: ${data.added} icons gained it${data.already > 0 ? `, ${data.already} already had it` : ''}, read from ${data.from}.`,
               ),
+              ...moduleUpdateLines(data),
               ...(data.files.length > 0 ? [list(data.files)] : []),
               ...(data.missing.length > 0
                 ? [
@@ -488,10 +507,11 @@ export function registerExperimentalIcon(group, program) {
           const {data} = result;
           emit(
             text(
-              data.changed
+              data.added
                 ? `[ok] Added ${data.icon.export} as "${data.icon.id}"${data.variant ? ` (variant ${data.variant})` : ''}${data.definition ? `, map.${data.definition} = "${data.icon.id}"` : ''}.`
                 : `[ok] ${data.icon.export} is already "${data.icon.id}"${data.definition ? ` and map.${data.definition} names it` : ''}.`,
             ),
+            ...moduleUpdateLines(data),
             ...(data.files.length > 0 ? [list(data.files)] : []),
             ...(data.note ? [text(`[next] ${data.note}`)] : []),
           );
@@ -543,6 +563,7 @@ export function registerExperimentalIcon(group, program) {
               : `The experimental.iconSets root ${root.path} in ${manifest} is unchanged.`
             : `${dryRun ? 'Would update' : 'Updated'} ${manifest}.`,
         ),
+        ...moduleUpdateLines(data),
         ...(files.length > 0 ? [list(files)] : []),
         // What to do next comes before the long lists, so it never scrolls
         // away.

package/clients/cli/commands/experimental-render.doc.mjs

@@ -53,7 +53,7 @@ export const doc = {
     {code: 0, when: 'the file was written (warnings included)'},
     {
       code: 1,
-      when: 'no file, a wrong extension, a missing file, a page that does not compile, has no default export, imports a package that is not installed, reads a browser API while rendering, throws, or takes over 60 seconds; a file to write outside the current folder; with --reverse, an existing output without --overwrite, a damaged embedded source, or HTML that is not an Astryx page',
+      when: 'no file, a wrong extension, a missing file, a page that does not compile, has no default export, imports a package that is not installed, reads a browser API while rendering, throws, crashes Node, or takes over 60 seconds; a file to write outside the current folder; with --reverse, an existing output without --overwrite, a damaged embedded source, or HTML that is not an Astryx page',
     },
   ],
   related: ['template', 'build'],

package/foundation/discovery/icon-set-writer.d.mts

@@ -11,7 +11,10 @@
 export function iconIdOf(name: string): string;
 /**
  * The name an icon set exports an icon as: PascalCase ending in `Icon`
- * (`Trash2` → `Trash2Icon`; `TrashIcon` stays).
+ * (`Trash2` → `Trash2Icon`; `TrashIcon` stays). A JavaScript name cannot
+ * start with a digit, so a name that starts with one is refused.
+ * {@link iconNaming} keeps a library prefix to prevent this (`fa0` →
+ * `Fa0Icon`).
  * @param {string} name
  */
 export function iconExportName(name: string): string;
@@ -27,7 +30,11 @@ export function variantExportName(iconName: string, variant: string): string;
  * `selector` names, else the only set.
  * @param {string} cwd
  * @param {string} [selector] a set name
- * @returns {Promise<{packageDir: string, pkg: Record<string, any>, root: string, set: DiscoveredIconSet, sets: DiscoveredIconSet[]}>}
+ * The set's `module` names the package as package.json names it now;
+ * `moduleRenamed` says the data file still names an old name, so a command
+ * writes the data file even when nothing else changes; `moduleUpdate` gives
+ * the old and the new name for the receipt, else null.
+ * @returns {Promise<{packageDir: string, pkg: Record<string, any>, root: string, set: DiscoveredIconSet, sets: DiscoveredIconSet[], moduleRenamed: boolean, moduleUpdate: {previous: string, module: string} | null}>}
  */
 export function findLocalIconSet(cwd: string, selector?: string): Promise<{
     packageDir: string;
@@ -35,6 +42,11 @@ export function findLocalIconSet(cwd: string, selector?: string): Promise<{
     root: string;
     set: DiscoveredIconSet;
     sets: DiscoveredIconSet[];
+    moduleRenamed: boolean;
+    moduleUpdate: {
+        previous: string;
+        module: string;
+    } | null;
 }>;
 /**
  * A data file's text, in one fixed shape: fields in schema order, `map` keys
@@ -147,7 +159,9 @@ export function nonIconExports(file: string, options?: {
 export function libraryPrefix(names: string[]): string[];
 /**
  * An export's id and the name the set exports it as, with the library prefix
- * left out: `featherEye` with prefix `feather` is id `eye`, `EyeIcon`.
+ * left out: `featherEye` with prefix `feather` is id `eye`, `EyeIcon`. A
+ * name that would start with a digit keeps the prefix (`fa500px` is
+ * `fa-500px`, `Fa500pxIcon`).
  * @param {string} name
  * @param {string[]} prefix
  * @returns {{id: string, name: string}}
@@ -371,7 +385,7 @@ export function writeDefinitionFile(set: DiscoveredIconSet, doc: {
 /**
  * Whether a generated declaration file declares what its generated module
  * gives, statement by statement however a formatter left either file
- * ({@link generatedStatements}); the header comment is ignored.
+ * ({@link statementTrees}); the header comment is ignored.
  * @param {string} actual the declaration file as it is
  * @param {string} expected {@link generatedTypesText} for the module
  * @param {string} label the declaration file's path, for a parse error
@@ -442,11 +456,13 @@ export function generatedNamesOf(packageDir: string, generated: string, from: st
  * differently; and a refresh changes only the icons its module supplies.
  * @param {string} packageDir
  * @param {string} generated
- * @returns {Map<string, {module: string, source: string}>}
+ * @returns {Map<string, {module: string, source: string, adapt: boolean}>}
+ *   `adapt`: the set's adapter turns the export into a component
  */
 export function generatedOrigins(packageDir: string, generated: string): Map<string, {
     module: string;
     source: string;
+    adapt: boolean;
 }>;
 /**
  * Whether two module specifiers name the same module: the same package