@astryxdesign/cli 0.7.12-canary.e0821c1 → 0.7.12-canary.e171d97

package/api/build/blocks/blocks.d.mts

@@ -22,6 +22,47 @@ export function wordsOf(text: string): string[];
  * @returns {string[]}
  */
 export function termsOf(text: string): string[];
+/**
+ * A text's docs side for `matchOf`: its word vector and that vector through
+ * the doc matrix. Search scores its entries' own docs with it.
+ * @param {string} text
+ * @param {BlockPickerWeights} weights
+ * @returns {{vector: Map<number, number>, projected: Float64Array}}
+ */
+export function docSideOf(text: string, weights: BlockPickerWeights): {
+    vector: Map<number, number>;
+    projected: Float64Array;
+};
+/**
+ * A request's side for `matchOf`: its word vector and that vector through the
+ * request matrix.
+ * @param {string} request
+ * @param {BlockPickerWeights} weights
+ * @returns {{vector: Map<number, number>, projected: Float64Array}}
+ */
+export function requestSideOf(request: string, weights: BlockPickerWeights): {
+    vector: Map<number, number>;
+    projected: Float64Array;
+};
+/**
+ * The picker's match of a request to a docs text: their projections' dot
+ * product plus the lexical weight times their plain overlap (the cosine of
+ * their word vectors). Build's ranking also reads the overlap alone.
+ * @param {{vector: Map<number, number>, projected: Float64Array}} request
+ * @param {{vector: Map<number, number>, projected: Float64Array}} doc
+ * @param {BlockPickerWeights} weights
+ * @returns {{match: number, overlap: number}}
+ */
+export function matchOf(request: {
+    vector: Map<number, number>;
+    projected: Float64Array;
+}, doc: {
+    vector: Map<number, number>;
+    projected: Float64Array;
+}, weights: BlockPickerWeights): {
+    match: number;
+    overlap: number;
+};
 /**
  * The blocks build names for a request, ranked by the picker.
  * @param {string} request

package/api/build/blocks/blocks.mjs

@@ -163,34 +163,10 @@ export function termsOf(text) {
   return out;
 }
 
-/**
- * The weights, decoded once per weights object.
- * @type {WeakMap<BlockPickerWeights, {index: Map<string, number>, idf: Float64Array, request: Int8Array, doc: Int8Array}>}
- */
-const decoded = new WeakMap();
-
-/** @param {BlockPickerWeights} weights */
-function decode(weights) {
-  let d = decoded.get(weights);
-  if (!d) {
-    // Each byte is a signed weight stored offset by 128.
-    const bytes = (/** @type {string} */ s) =>
-      Int8Array.from(Buffer.from(s, 'base64'), b => b - 128);
-    d = {
-      index: new Map(weights.vocab.map((w, i) => [w, i])),
-      idf: Float64Array.from(weights.idf, x => x / 1024),
-      request: bytes(weights.request),
-      doc: bytes(weights.doc),
-    };
-    decoded.set(weights, d);
-  }
-  return d;
-}
-
 /**
  * A text's sparse unit vector over the vocabulary: (1 + ln count) x idf.
  * @param {string[]} terms
- * @param {ReturnType<typeof decode>} d
+ * @param {{index: Map<string, number>, idf: Float64Array}} d
  * @returns {Map<number, number>}
  */
 function vectorOf(terms, d) {
@@ -214,20 +190,116 @@ function vectorOf(terms, d) {
 }
 
 /**
- * A sparse vector through a signed byte matrix.
- * @param {Map<number, number>} v
- * @param {Int8Array} m
+ * The vocabulary index and idf, read once per weights object, and each matrix
+ * row decoded when a side first uses it.
+ * @type {WeakMap<BlockPickerWeights, {index: Map<string, number>, idf: Float64Array, rows: Map<string, Int8Array>}>}
+ */
+const vocabularies = new WeakMap();
+
+/** @param {BlockPickerWeights} weights */
+function vocabularyOf(weights) {
+  let v = vocabularies.get(weights);
+  if (!v) {
+    v = {
+      index: new Map(weights.vocab.map((w, i) => [w, i])),
+      idf: Float64Array.from(weights.idf, x => x / 1024),
+      rows: new Map(),
+    };
+    vocabularies.set(weights, v);
+  }
+  return v;
+}
+
+/**
+ * One row of a byte matrix, decoded from the base64 text alone: four
+ * characters hold three bytes, so the row's bytes sit inside the characters
+ * from its first byte's group to its last byte's group.
+ * @param {BlockPickerWeights} weights
+ * @param {'request' | 'doc'} matrix
+ * @param {number} i
+ * @returns {Int8Array}
+ */
+function rowOf(weights, matrix, i) {
+  const {rows} = vocabularyOf(weights);
+  const key = `${matrix}:${i}`;
+  let row = rows.get(key);
+  if (!row) {
+    const {dims} = weights;
+    const first = Math.floor((i * dims) / 3);
+    const last = Math.ceil(((i + 1) * dims) / 3);
+    const bytes = Buffer.from(
+      weights[matrix].slice(first * 4, last * 4),
+      'base64',
+    ).subarray(i * dims - first * 3, i * dims - first * 3 + dims);
+    // Each byte is a signed weight stored offset by 128.
+    row = Int8Array.from(bytes, b => b - 128);
+    rows.set(key, row);
+  }
+  return row;
+}
+
+/**
+ * A text's side for `matchOf` through one matrix: its word vector, and that
+ * vector times the matrix rows its words use, scaled.
+ * @param {string} text
+ * @param {BlockPickerWeights} weights
+ * @param {'request' | 'doc'} matrix
  * @param {number} scale
- * @param {number} dims
+ * @returns {{vector: Map<number, number>, projected: Float64Array}}
  */
-function project(v, m, scale, dims) {
-  const out = new Float64Array(dims);
-  for (const [i, x] of v) {
-    const row = i * dims;
-    for (let k = 0; k < dims; k++) out[k] += x * m[row + k];
+function sideOf(text, weights, matrix, scale) {
+  const vector = vectorOf(termsOf(text), vocabularyOf(weights));
+  const {dims} = weights;
+  const projected = new Float64Array(dims);
+  for (const [i, x] of vector) {
+    const row = rowOf(weights, matrix, i);
+    for (let k = 0; k < dims; k++) projected[k] += x * row[k];
   }
-  for (let k = 0; k < dims; k++) out[k] *= scale;
-  return out;
+  for (let k = 0; k < dims; k++) projected[k] *= scale;
+  return {vector, projected};
+}
+
+/**
+ * A text's docs side for `matchOf`: its word vector and that vector through
+ * the doc matrix. Search scores its entries' own docs with it.
+ * @param {string} text
+ * @param {BlockPickerWeights} weights
+ * @returns {{vector: Map<number, number>, projected: Float64Array}}
+ */
+export function docSideOf(text, weights) {
+  return sideOf(text, weights, 'doc', weights.docScale);
+}
+
+/**
+ * A request's side for `matchOf`: its word vector and that vector through the
+ * request matrix.
+ * @param {string} request
+ * @param {BlockPickerWeights} weights
+ * @returns {{vector: Map<number, number>, projected: Float64Array}}
+ */
+export function requestSideOf(request, weights) {
+  return sideOf(request, weights, 'request', weights.requestScale);
+}
+
+/**
+ * The picker's match of a request to a docs text: their projections' dot
+ * product plus the lexical weight times their plain overlap (the cosine of
+ * their word vectors). Build's ranking also reads the overlap alone.
+ * @param {{vector: Map<number, number>, projected: Float64Array}} request
+ * @param {{vector: Map<number, number>, projected: Float64Array}} doc
+ * @param {BlockPickerWeights} weights
+ * @returns {{match: number, overlap: number}}
+ */
+export function matchOf(request, doc, weights) {
+  let s = 0;
+  for (let k = 0; k < weights.dims; k++)
+    s += request.projected[k] * doc.projected[k];
+  let overlap = 0;
+  for (const [i, x] of request.vector) {
+    const y = doc.vector.get(i);
+    if (y !== undefined) overlap += x * y;
+  }
+  return {match: s + weights.lexical * overlap, overlap};
 }
 
 /**
@@ -261,7 +333,6 @@ function readCatalog(catalog, components, weights) {
   ]);
   const cached = catalogs.get(weights);
   if (cached && cached.key === key) return cached;
-  const d = decode(weights);
   const names = components.map(c => c.name).sort((a, b) => b.length - a.length);
   const keywords = new Map(components.map(c => [c.name, c.keywords ?? []]));
   /** @type {Map<string, {component: string, vector: Map<number, number>, projected: Float64Array}>} */
@@ -276,12 +347,7 @@ function readCatalog(catalog, components, weights) {
       wordsOf(component).join(' '),
       (keywords.get(component) ?? []).join(' '),
     ].join(' ');
-    const vector = vectorOf(termsOf(text), d);
-    blocks.set(b.name, {
-      component,
-      vector,
-      projected: project(vector, d.doc, weights.docScale, weights.dims),
-    });
+    blocks.set(b.name, {component, ...docSideOf(text, weights)});
   }
   // A component is named by its own words, or by a keyword at most three
   // components share (weighted by how few share it).
@@ -378,26 +444,12 @@ export function pickBlocks(request, signals, weights) {
   /** @type {Map<string, SearchResultEntry>} */
   const entries = new Map();
   if (own.length === 0) return {names: [], entries};
-  const d = decode(weights);
   const cat = readCatalog(signals.catalog, signals.components, weights);
-  const q = vectorOf(termsOf(request), d);
-  const eq = project(q, d.request, weights.requestScale, weights.dims);
-  const dot = (/** @type {Map<number, number>} */ v) => {
-    let s = 0;
-    for (const [i, x] of q) {
-      const y = v.get(i);
-      if (y !== undefined) s += x * y;
-    }
-    return s;
-  };
+  const side = requestSideOf(request, weights);
   /** @type {Map<string, {match: number, overlap: number}>} */
   const scored = new Map();
-  for (const [name, b] of cat.blocks) {
-    let s = 0;
-    for (let k = 0; k < weights.dims; k++) s += eq[k] * b.projected[k];
-    const overlap = dot(b.vector);
-    scored.set(name, {match: s + weights.lexical * overlap, overlap});
-  }
+  for (const [name, b] of cat.blocks)
+    scored.set(name, matchOf(side, b, weights));
   const get = (/** @type {string} */ b) =>
     scored.get(b) ?? {match: -Infinity, overlap: 0};
   const ranked = [...scored.keys()].sort((a, b) => get(b).match - get(a).match);
@@ -480,7 +532,7 @@ export function pickBlocks(request, signals, weights) {
       name,
       package: block.package ?? '',
       score: Math.max(1, Math.round(100 * Math.exp(x.score - max))),
-      reason: reasonFor(request, cat.blocks.get(name), d, weights),
+      reason: reasonFor(request, side, cat.blocks.get(name), weights),
       description: block.description ?? '',
       displayName: block.displayName,
       kind: 'block',
@@ -493,11 +545,11 @@ export function pickBlocks(request, signals, weights) {
 /**
  * Why a block fits: the request words that tie it to its docs most.
  * @param {string} request
+ * @param {{vector: Map<number, number>, projected: Float64Array}} side the request's side
  * @param {{vector: Map<number, number>, projected: Float64Array} | undefined} block
- * @param {ReturnType<typeof decode>} d
  * @param {BlockPickerWeights} weights
  */
-function reasonFor(request, block, d, weights) {
+function reasonFor(request, side, block, weights) {
   if (!block) return 'fits by meaning';
   const raw =
     String(request)
@@ -507,16 +559,14 @@ function reasonFor(request, block, d, weights) {
   const wordOf = new Map();
   for (const w of raw)
     if (!STOP.has(w) && !wordOf.has(stemOf(w))) wordOf.set(stemOf(w), w);
-  const q = vectorOf(termsOf(request), d);
   /** @type {[string, number][]} */
   const parts = [];
-  for (const [i, x] of q) {
+  for (const [i, x] of side.vector) {
     const term = weights.vocab[i];
     if (term.includes('_')) continue;
+    const row = rowOf(weights, 'request', i);
     let s = 0;
-    const row = i * weights.dims;
-    for (let k = 0; k < weights.dims; k++)
-      s += d.request[row + k] * block.projected[k];
+    for (let k = 0; k < weights.dims; k++) s += row[k] * block.projected[k];
     s =
       x * s * weights.requestScale +
       weights.lexical * x * (block.vector.get(i) ?? 0);

package/api/component/__fixtures__/resolutions/modules.txt

@@ -271,7 +271,7 @@ useIsomorphicLayoutEffect useIsomorphicLayoutEffect hooks/useAnimatedLayout.doc.
 useLayerDismissal useLayerDismissal Layer/Layer.doc.mjs Layer/useLayerDismissal.ts
 useLightbox useLightbox Lightbox/useLightbox.doc.mjs Lightbox/useLightbox.tsx
 useLinkComponent useLinkComponent Link/useLinkComponent.doc.mjs Link/useLinkComponent.ts
-useLinkify useLinkify Link/Link.doc.mjs Link/useLinkify.tsx
+useLinkify useLinkify Link/useLinkify.doc.mjs Link/useLinkify.tsx
 useListFormatter useListFormatter i18n/InternationalizationProvider.doc.mjs i18n/useListFormatter.ts
 useMenuDrillIn useMenuDrillIn DropdownMenu/DropdownMenu.doc.mjs DropdownMenu/useMenuDrillIn.tsx
 useMenuHover useMenuHover hooks/useAnimatedLayout.doc.mjs hooks/useMenuHover.ts
@@ -282,7 +282,7 @@ useOverlay useOverlay Overlay/useOverlay.doc.mjs Overlay/useOverlay.tsx
 useOwnScrollGesture useOwnScrollGesture DateInput/DateInput.doc.mjs DateInput/useOwnScrollGesture.ts
 usePager usePager hooks/useAnimatedLayout.doc.mjs hooks/usePager.ts
 usePointerDragScroll usePointerDragScroll DateInput/DateInput.doc.mjs DateInput/usePointerDragScroll.ts
-usePowerSearchConfig usePowerSearchConfig PowerSearch/PowerSearch.doc.mjs PowerSearch/usePowerSearchConfig.ts
+usePowerSearchConfig usePowerSearchConfig PowerSearch/usePowerSearchConfig.doc.mjs PowerSearch/usePowerSearchConfig.ts
 usePowerSearchSource usePowerSearchSource PowerSearch/PowerSearch.doc.mjs PowerSearch/usePowerSearchSource.ts
 useRenamedProp useRenamedProp hooks/useAnimatedLayout.doc.mjs hooks/useRenamedProp.ts
 useResolvedRequired useResolvedRequired hooks/useAnimatedLayout.doc.mjs hooks/useResolvedRequired.ts
@@ -298,7 +298,7 @@ useSpeechRecognition useSpeechRecognition Chat/Chat.doc.mjs Chat/useSpeechRecogn
 useSwipeAction useSwipeAction Item/Item.doc.mjs Item/useSwipeAction.ts
 useSwitchTouch useSwitchTouch Switch/Switch.doc.mjs Switch/useSwitchTouch.ts
 useTableCellStyles useTableCellStyles Table/Table.doc.mjs Table/useTableCellStyles.ts
-useTableColumnSettingsState useTableColumnSettingsState Table/Table.doc.mjs Table/plugins/columnSettings/useTableColumnSettingsState.tsx
+useTableColumnSettingsState useTableColumnSettingsState Table/plugins/columnSettings/useTableColumnSettingsState.doc.mjs Table/plugins/columnSettings/useTableColumnSettingsState.tsx
 useTableSortableState useTableSortableState Table/plugins/sortable/useTableSortableState.doc.mjs Table/plugins/sortable/useTableSortableState.tsx
 useToastGesture useToastGesture Toast/Toast.doc.mjs Toast/useToastGesture.ts
 useTouchTrigger useTouchTrigger Layer/Layer.doc.mjs Layer/useTouchTrigger.ts

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 */