@astryxdesign/cli 0.7.12 → 0.7.13-canary.1719285

package/assets/templates/pages/table-comparison/template.doc.mjs

@@ -19,6 +19,7 @@ export const doc = {
     Image: 'image',
     Plus: 'add',
     Sparkles: 'sparkles',
+    Type: 'text',
     Video: 'video',
     Zap: 'bolt',
   },

package/authoring/config/config.doc.mjs

@@ -68,7 +68,7 @@ export const doc = {
       description:
         'Tell `{@command discover}` which integrations this project could add: an async function that returns a catalog. An integration can provide one too, as a `discover` named export from its manifest. Discover calls every source, yours first, and one that fails never hides the others. Discover only reads; your package manager installs.',
       example:
-        "async ({signal, package: name, version}) => fetchCatalog({signal, name, version})",
+        'async ({signal, package: name, version}) => fetchCatalog({signal, name, version})',
     },
     {
       name: 'experimental',
@@ -77,11 +77,11 @@ export const doc = {
       fields: [
         {
           name: 'experimental.iconSet',
-          type: 'string',
+          type: 'string | string[]',
           stability: 'experimental',
           description:
-            "Experimental: may change or be removed in a patch release. The project's icon set, by set name or as `<package>/<set>`. It is the opt-in: copied templates use its icons, and `astryx discover` and `astryx doctor` report icon sets, only when it is set. `astryx experimental icon` ranks its icons first; without it, the only installed set is the project's there. `astryx search` never returns icons.",
-          example: "'@acme/outline-icons/outline'",
+            "Experimental: may change or be removed in a patch release. The project's main icon set, by set name or as `<package>/<set>`; or a list of them, the main set first and then backup sets in order. A copied template takes each icon from the first set in the list that has its meaning, and draws a placeholder the copied file declares when none has it. It is the opt-in: copied templates use these icons, and `astryx discover` and `astryx doctor` report icon sets, only when it is set. `astryx experimental icon use <main> --backup <set>` writes it. `astryx experimental icon` ranks the main set's icons first; without it, the only installed set is the project's there. `astryx search` never returns icons.",
+          example: "['@acme/outline-icons/outline', '@acme/brand-icons/brand']",
         },
         {
           name: 'experimental.xle.components',

package/authoring/config/parse.d.mts

@@ -58,7 +58,7 @@ declare const configSchema: z.ZodObject<{
                 default: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strict>>>;
         }, z.core.$strict>>;
-        iconSet: z.ZodOptional<z.ZodString>;
+        iconSet: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export {};

package/authoring/config/parse.mjs

@@ -103,7 +103,9 @@ const configSchema = z
           })
           .strict()
           .optional(),
-        iconSet: z.string().min(1).optional(),
+        iconSet: z
+          .union([z.string().min(1), z.array(z.string().min(1)).min(1)])
+          .optional(),
       })
       .strict()
       .optional(),

package/authoring/config/type.ts

@@ -123,12 +123,14 @@ export interface AstryxConfig {
       components?: Record<string, XleComponent>;
     };
     /**
-     * Experimental icon sets (spec:AST-084): the project's icon set, a set
-     * name (`"outline"`) or `"<package>/<set>"`, and the opt-in. Copied
-     * templates use its icons, and discover and Doctor report icon sets, only
-     * when it is set.
+     * Experimental icon sets (spec:AST-084): the project's main icon set, a
+     * set name (`"outline"`) or `"<package>/<set>"`, and the opt-in. A list
+     * (`["outline", "@acme/icons/brand"]`) names the main set first, then
+     * backup sets in order: a copied template takes each icon from the first
+     * set that has its meaning. Copied templates use these icons, and
+     * discover and Doctor report icon sets, only when it is set.
      * @experimental May change or be removed in a patch release.
      */
-    iconSet?: string;
+    iconSet?: string | string[];
   };
 }

package/authoring/doctypes/template/template.doc.mjs

@@ -69,7 +69,7 @@ export const doc = {
       type: 'Record<string, string>',
       stability: 'experimental',
       description:
-        "The icon definition each icon the source imports draws, such as `{TrashIcon: 'delete'}`: a named import is keyed by the name it imports (`{Trash as TrashIcon}` is `Trash`), a default import by its local name (`import DeleteIcon from …` is `DeleteIcon`). When the project sets `experimental.iconSet`, `astryx template` (shown or copied) replaces each declared icon with the set's icon for that definition (`astryx docs cli/experimental/icon-definitions`) and reports every key as mapped or kept; an undeclared import is left alone. A name imported from two modules (`TrashIcon` from an outline and a solid module) needs one key, and each import keeps its variant when its module belongs to an installed set.",
+        "The icon definition each icon the source imports draws, such as `{TrashIcon: 'delete'}`: a named import is keyed by the name it imports (`{Trash as TrashIcon}` is `Trash`), a default import by its local name (`import DeleteIcon from …` is `DeleteIcon`). When the project sets `experimental.iconSet`, `astryx template` (shown or copied) replaces each declared icon with the icon for that definition (`astryx docs cli/experimental/icon-definitions`) from the first set in the project's list that maps it, or with a placeholder the copied file declares when no set does, and reports every key as mapped, a placeholder, or kept; an undeclared import is left alone, and `astryx integration check` notes it (`template_icon_undeclared`, failing `--strict --next`) in a package whose templates declare `icons`. A name imported from two modules (`TrashIcon` from an outline and a solid module) needs one key, and each import keeps its variant when its module belongs to an installed set.",
     },
     {
       name: 'isReady',

package/authoring/doctypes/template/type.ts

@@ -55,9 +55,11 @@ export interface BaseTemplateDoc extends AuthoredDocGraphFields {
    *  (`{TrashIcon: 'delete'}`), keyed by the name a named import reads
    *  (`{Trash as TrashIcon}` is `Trash`) or a default import's local name
    *  (`import DeleteIcon from …` is `DeleteIcon`). When the project has an
-   *  icon set, each declared icon is replaced by the set's icon for that
-   *  definition (`astryx docs cli/experimental/icon-definitions`), and every
-   *  key is reported as mapped or kept. A name imported from two modules
+   *  icon set, each declared icon is replaced by the icon for that
+   *  definition (`astryx docs cli/experimental/icon-definitions`) from the
+   *  first set in the project's list that maps it, or by a placeholder the
+   *  copied file declares when no set does, and every key is reported as mapped, a
+   *  placeholder, or kept. A name imported from two modules
    *  (`TrashIcon` from an outline and a solid module) needs one key.
    *  @experimental May change or be removed in a patch release. */
   icons?: Record<string, string>;

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

@@ -256,10 +256,17 @@ export function registerExperimentalIcon(group, program) {
         return answered;
       }
 
-      const {status, projectSet, reason, sets, withdrawn} = result.data;
+      const {status, projectSet, reason, sets, withdrawn, order, next} =
+        result.data;
       emit(
         section('Icon sets'),
-        record({status, projectSet, reason}),
+        record({
+          status,
+          projectSet,
+          ...(order.length > 1 ? {order: order.join(' > ')} : {}),
+          reason,
+        }),
+        ...(next ? [text(`[warn] ${next}`)] : []),
         ...(sets.length > 0
           ? [
               records(
@@ -283,6 +290,7 @@ export function registerExperimentalIcon(group, program) {
                     'definitions',
                     'own',
                     'missing',
+                    'role',
                     'project',
                     'description',
                   ],
@@ -346,21 +354,42 @@ export function registerExperimentalIcon(group, program) {
 
   defineCommand(iconCli, iconUseCommand, {
     fn: iconUseFn,
-    action: (/** @type {string} */ set) =>
+    action: (
+      /** @type {string} */ set,
+      /** @type {{backup?: string[]}} */ options,
+    ) =>
       run(
-        () => iconUse(set, {cwd: process.cwd()}),
-        ({data}) =>
+        () => iconUse(set, {cwd: process.cwd(), backups: options.backup ?? []}),
+        ({data}) => {
+          /** @type {Array<{iconSet: string, set: string}>} */
+          const backups = data.backups;
+          const shown = (/** @type {string | string[]} */ value) =>
+            Array.isArray(value) ? JSON.stringify(value) : `"${value}"`;
+          const main = `"${data.iconSet}" (${data.set})`;
+          const order =
+            backups.length > 0
+              ? `main set ${main}, then ${backups.map(each => `"${each.iconSet}" (${each.set})`).join(', then ')}`
+              : main;
           emit(
             text(
               data.changed
-                ? `[ok] experimental.iconSet is now "${data.iconSet}" (${data.set}) in ${data.config}${data.created ? ', created' : ''}.`
-                : `[ok] experimental.iconSet already names "${data.iconSet}" in ${data.config}.`,
+                ? `[ok] experimental.iconSet is now ${order} in ${data.config}${data.created ? ', created' : ''}.`
+                : `[ok] experimental.iconSet already names ${order} in ${data.config}.`,
             ),
+            ...(backups.length > 0
+              ? [
+                  text(
+                    'A copied template takes each icon from the first set in this order that has its meaning.',
+                  ),
+                ]
+              : []),
             ...(data.previous && data.changed
-              ? [text(`It was "${data.previous}".`)]
+              ? [text(`It was ${shown(data.previous)}.`)]
               : []),
+            ...(data.next ? [text(`[warn] ${data.next}`)] : []),
             ...(data.warning ? [text(`[warn] ${data.warning}`)] : []),
-          ),
+          );
+        },
       ),
   });
 

package/clients/cli/commands/experimental-icon-use.doc.mjs

@@ -9,13 +9,18 @@ export const doc = {
   displayName: 'astryx experimental icon use',
   namespace: 'cli/commands',
   stability: 'experimental',
-  summary: "Choose the project's icon set",
+  summary: "Choose the project's main icon set and backups",
   description:
-    "Writes `experimental.iconSet` in astryx.config, so copied templates and blocks use that set's icons. The set must be installed. Experimental: it may change or be removed in a patch release.",
+    "Writes `experimental.iconSet` in astryx.config, so copied templates and blocks use that set's icons. With `--backup`, it writes a list: the main set first, then each backup in the order given. A copied template takes each icon from the first set in the list that has its meaning. Every set must be installed. Experimental: it may change or be removed in a patch release.",
   fn: 'iconUse',
   args: [{name: 'set', param: 'set', required: true}],
+  options: [{flag: '--backup <set...>', param: 'options.backups'}],
   examples: [
     {label: 'Use a set', cli: 'astryx experimental icon use outline'},
+    {
+      label: 'Use a main set with a backup',
+      cli: 'astryx experimental icon use outline --backup @acme/brand-icons/brand',
+    },
     {
       label: 'Name its package',
       cli: 'astryx experimental icon use @acme/icons/outline',
@@ -25,11 +30,11 @@ export const doc = {
   exitCodes: [
     {
       code: 0,
-      when: 'experimental.iconSet is written, or already names the set',
+      when: 'experimental.iconSet is written, or already names the sets',
     },
     {
       code: 1,
-      when: 'the set is not installed, two packages ship it, the config cannot be updated (not a static object literal, or it spreads another object, which you then edit by hand), or the config is protected (a symbolic link, or marked generated, vendored, or ignored: `ERR_CODEMOD_PROTECTED`, naming the declaration)',
+      when: 'a set is not installed, two packages ship it, a set is named twice, the config cannot be updated (not a static object literal, or it spreads another object, which you then edit by hand), or the config is protected (a symbolic link, or marked generated, vendored, or ignored: `ERR_CODEMOD_PROTECTED`, naming the declaration)',
     },
   ],
   related: ['experimental icon', 'template'],

package/clients/cli/commands/template.mjs

@@ -57,9 +57,10 @@ function demoContentNote(count, file) {
 }
 
 /**
- * The icon report as text lines (AST-084 FR10): one line per mapped or kept
- * icon, or one line saying why nothing was mapped. Nothing when the project
- * has no icon set at all (no report: icon sets are experimental).
+ * The icon report as text lines (AST-084 FR10): one line per mapped,
+ * placeholder, or kept icon, or one line saying why nothing was mapped.
+ * Nothing when the project has no icon set at all (no report: icon sets are
+ * experimental). A placeholder line names its meaning and both fixes.
  * @param {import('../../../api/template/template.type.mjs').TemplateIconsReport | undefined} icons
  * @returns {string[]}
  */
@@ -74,10 +75,18 @@ function iconLines(icons) {
     ...icons.mapped.map(
       each =>
         `icons: mapped ${each.source.export} (${each.source.module}) -> ${each.target.export} (${each.target.module}) by ${each.by}` +
+        (icons.order ? ` from ${each.target.package}/${each.target.set}` : '') +
+        (each.variant
+          ? `; ${each.variant.asked} look not in the set, drew ${each.variant.used ?? 'its default look'}`
+          : '') +
         (each.dropped && each.dropped.length > 0
           ? `; dropped ${each.dropped.join(', ')} (size comes from CSS)`
           : ''),
     ),
+    ...(icons.placeholder ?? []).map(
+      each =>
+        `icons: placeholder ${each.source.export} (${each.source.module}) -> ${each.target.local}: no set in your list has "${each.definitions.join('", "')}", so the file draws a placeholder it declares. Fix: add a backup set that has it, \`${each.fixes[1]}\`; or, if you author your main set, map it there, \`${each.fixes[0]}\`.`,
+    ),
     ...icons.kept.map(
       each =>
         `icons: kept ${each.export}${each.module == null ? '' : ` (${each.module})`}: ${each.reason}` +

package/foundation/config/config-writer.d.mts

@@ -14,6 +14,20 @@ export function setConfigString(projectDir: string, key: string, value: string):
     previous: string | null;
     changed: boolean;
 };
+/**
+ * Set `key` to `value`, a string or a list of strings, in the project's
+ * astryx.config.
+ * @param {string} projectDir
+ * @param {string} key a top-level key, or a dotted path (`experimental.iconSet`)
+ * @param {string | readonly string[]} value
+ * @returns {{file: string, created: boolean, previous: string | string[] | null, changed: boolean}}
+ */
+export function setConfigValue(projectDir: string, key: string, value: string | readonly string[]): {
+    file: string;
+    created: boolean;
+    previous: string | string[] | null;
+    changed: boolean;
+};
 /** A protected astryx.config the writer refused to touch. */
 export class ConfigProtectedError extends Error {
     /**

package/foundation/config/config-writer.mjs

@@ -1,7 +1,8 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Write one string field of a project's astryx.config.
+ * @file Write one string field, or one list of strings, in a project's
+ * astryx.config.
  *
  * The field is a top-level key or a dotted path into nested object literals
  * (`experimental.iconSet`); a missing object on the path is created.
@@ -18,7 +19,8 @@
  * `ERR_CODEMOD_PROTECTED` naming the protecting declaration, and an unreadable
  * protection source fails with `ERR_CODEMOD_PROTECTION_SOURCE`.
  *
- * @input A project directory, a field name, and its string value
+ * @input A project directory, a field name, and its value: a string or a
+ *   list of strings
  * @output The config file written and the value it replaced
  * @position packages/cli/foundation/config — read by `astryx experimental icon use`
  */
@@ -87,6 +89,47 @@ function propertyNamed(property, name) {
   );
 }
 
+/** @param {string} text */
+const quote = text => `'${text.replace(/\\/gu, '\\\\').replace(/'/gu, "\\'")}'`;
+
+/** @param {string | readonly string[]} value */
+const written = value =>
+  typeof value === 'string'
+    ? quote(value)
+    : `[${value.map(each => quote(each)).join(', ')}]`;
+
+/**
+ * The string, or list of strings, a config property holds; null for any
+ * other value.
+ * @param {any} node
+ * @returns {string | string[] | null}
+ */
+function literalValue(node) {
+  if (node?.type === 'StringLiteral' || node?.type === 'Literal') {
+    return typeof node.value === 'string' ? node.value : null;
+  }
+  if (node?.type === 'ArrayExpression') {
+    const items = node.elements.map((/** @type {any} */ each) =>
+      each?.type === 'StringLiteral' ||
+      (each?.type === 'Literal' && typeof each.value === 'string')
+        ? String(each.value)
+        : null,
+    );
+    return items.every((/** @type {string | null} */ each) => each != null)
+      ? /** @type {string[]} */ (items)
+      : null;
+  }
+  return null;
+}
+
+/**
+ * @param {string | string[] | null} a
+ * @param {string | readonly string[]} b
+ */
+function sameValue(a, b) {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
 /**
  * Set `key` to `value` in the project's astryx.config.
  * @param {string} projectDir
@@ -95,6 +138,22 @@ function propertyNamed(property, name) {
  * @returns {{file: string, created: boolean, previous: string | null, changed: boolean}}
  */
 export function setConfigString(projectDir, key, value) {
+  const result = setConfigValue(projectDir, key, value);
+  return {
+    ...result,
+    previous: typeof result.previous === 'string' ? result.previous : null,
+  };
+}
+
+/**
+ * Set `key` to `value`, a string or a list of strings, in the project's
+ * astryx.config.
+ * @param {string} projectDir
+ * @param {string} key a top-level key, or a dotted path (`experimental.iconSet`)
+ * @param {string | readonly string[]} value
+ * @returns {{file: string, created: boolean, previous: string | string[] | null, changed: boolean}}
+ */
+export function setConfigValue(projectDir, key, value) {
   const keys = key.split('.');
   const leaf = /** @type {string} */ (keys[keys.length - 1]);
   const existing = CONFIG_BASENAMES.map(name =>
@@ -103,7 +162,6 @@ export function setConfigString(projectDir, key, value) {
   if (!existing) {
     const file = path.join(projectDir, 'astryx.config.mjs');
     assertWritable(projectDir, file);
-    const quoted = `'${value.replace(/\\/gu, '\\\\').replace(/'/gu, "\\'")}'`;
     // Each key on the path opens one nested object: `experimental: {`.
     const open = keys
       .slice(0, -1)
@@ -116,7 +174,7 @@ export function setConfigString(projectDir, key, value) {
       .join('');
     writeAtomically(
       file,
-      `export default {\n${open}${'  '.repeat(keys.length)}${leaf}: ${quoted},\n${close}};\n`,
+      `export default {\n${open}${'  '.repeat(keys.length)}${leaf}: ${written(value)},\n${close}};\n`,
     );
     return {file, created: true, previous: null, changed: true};
   }
@@ -127,7 +185,7 @@ export function setConfigString(projectDir, key, value) {
   let object = findManifestObject(j, ast);
   const refuse = () =>
     new Error(
-      `Could not update ${path.basename(existing)} safely: its default export is not a static object literal. Set "${key}: '${value}'" in it yourself.`,
+      `Could not update ${path.basename(existing)} safely: its default export is not a static object literal. Set "${key}: ${written(value)}" in it yourself.`,
     );
   if (!object) throw refuse();
   // A spread on the path can hold the same keys: a key added beside it would
@@ -137,7 +195,7 @@ export function setConfigString(projectDir, key, value) {
   const assertNoSpread = (holder, where) => {
     if (holder.properties.some((/** @type {any} */ each) => isSpread(each))) {
       throw new Error(
-        `Could not update ${path.basename(existing)} safely: ${where} spreads another object (\`...\`), whose keys a written "${key}" could replace. Set "${key}: '${value}'" in it yourself.`,
+        `Could not update ${path.basename(existing)} safely: ${where} spreads another object (\`...\`), whose keys a written "${key}" could replace. Set "${key}: ${written(value)}" in it yourself.`,
       );
     }
   };
@@ -160,22 +218,20 @@ export function setConfigString(projectDir, key, value) {
   const property = object.properties.find((/** @type {any} */ each) =>
     propertyNamed(each, leaf),
   );
-  /** @type {string | null} */
+  const node =
+    typeof value === 'string'
+      ? j.stringLiteral(value)
+      : j.arrayExpression(value.map(each => j.stringLiteral(each)));
+  /** @type {string | string[] | null} */
   let previous = null;
   if (property) {
-    const current = property.value;
-    previous =
-      current?.type === 'StringLiteral' || current?.type === 'Literal'
-        ? String(current.value)
-        : null;
-    if (previous === value) {
+    previous = literalValue(property.value);
+    if (sameValue(previous, value)) {
       return {file: existing, created: false, previous, changed: false};
     }
-    property.value = j.stringLiteral(value);
+    property.value = node;
   } else {
-    object.properties.push(
-      j.objectProperty(j.identifier(leaf), j.stringLiteral(value)),
-    );
+    object.properties.push(j.objectProperty(j.identifier(leaf), node));
   }
   let next = ast.toSource({quote: 'single', reuseWhitespace: true});
   if (source.endsWith('\n') && !next.endsWith('\n')) next += '\n';

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

@@ -43,6 +43,14 @@ export function hasLicenseNotice(dir: string): boolean;
  *   file is invalid; `unresolved`: its module does not resolve from the project
  * @property {string} reason
  */
+/**
+ * One backup set the project's list names, and what it resolves to.
+ * @typedef {object} IconSetBackup
+ * @property {string} selector the name as the list writes it
+ * @property {'selected' | 'ambiguous' | 'missing' | 'withdrawn'} status
+ * @property {DiscoveredIconSet} [set] the set, when selected
+ * @property {string} reason one sentence saying why
+ */
 /**
  * The project's icon set (FR8).
  * @typedef {object} IconSetChoice
@@ -53,7 +61,13 @@ export function hasLicenseNotice(dir: string): boolean;
  *   `withdrawn`: it names a set that is installed but withdrawn (invalid, or
  *   its module does not resolve), and `reason` says why
  * @property {DiscoveredIconSet} [set] the project's set, when selected
- * @property {string} [configured] the `experimental.iconSet` config value, when set
+ * @property {string} [configured] the main set `experimental.iconSet` names
+ *   (its first entry, when it is a list), when set
+ * @property {IconSetBackup[]} [backups] the backup sets the list names after
+ *   the main set, in order, when it names any
+ * @property {DiscoveredIconSet[]} [order] the sets a template icon is looked
+ *   up in, in order: the main set, then each backup that resolves. Present
+ *   only when the main set is selected
  * @property {string} reason one sentence saying why
  */
 /**
@@ -120,16 +134,39 @@ export function discoverIntegrationIconSets(integration: import("../integrations
  */
 export function withdrawnNamed(withdrawn: WithdrawnIconSet[], selector: string): WithdrawnIconSet[];
 /**
- * Pick the project's icon set (FR8, FR17): the set `experimental.iconSet`
- * names, as `"<set>"` or `"<package>/<set>"`; otherwise the only installed
+ * The entries of an `experimental.iconSet` value, main set first: a string is
+ * a one-entry list.
+ * @param {string | readonly string[] | undefined} configured
+ * @returns {string[]}
+ */
+export function iconSetList(configured: string | readonly string[] | undefined): string[];
+/**
+ * Installed sets the project's list leaves out: the problem, and the fix that
+ * adds them as backups after the list's own. Doctor and `experimental icon
+ * use` print the same words.
+ * @param {number} installed how many sets are installed
+ * @param {string} main the main set as the list writes it
+ * @param {string[]} backups the list's backups, in order
+ * @param {string[]} unlisted the installed sets the list leaves out
+ * @returns {{problem: string, command: string, fix: string}}
+ */
+export function unlistedIconSets(installed: number, main: string, backups: string[], unlisted: string[]): {
+    problem: string;
+    command: string;
+    fix: string;
+};
+/**
+ * Pick the project's icon set (FR8, FR17): the main set `experimental.iconSet`
+ * names, as `"<set>"` or `"<package>/<set>"`, or as the first entry of a list
+ * whose other entries are backup sets in order; otherwise the only installed
  * set; otherwise none. A configured name that matches no valid set but an
  * installed set that was withdrawn says so, with why.
  * @param {DiscoveredIconSet[]} sets installed sets, in integration load order
- * @param {string | undefined} configured the `experimental.iconSet` config value
+ * @param {string | readonly string[] | undefined} configured the `experimental.iconSet` config value
  * @param {WithdrawnIconSet[]} [withdrawn] installed sets that were withdrawn
  * @returns {IconSetChoice}
  */
-export function chooseProjectIconSet(sets: DiscoveredIconSet[], configured: string | undefined, withdrawn?: WithdrawnIconSet[]): IconSetChoice;
+export function chooseProjectIconSet(sets: DiscoveredIconSet[], configured: string | readonly string[] | undefined, withdrawn?: WithdrawnIconSet[]): IconSetChoice;
 /**
  * A set's full name, `<package>/<set>`.
  * @param {{package: string, name: string}} set
@@ -139,7 +176,8 @@ export function iconSetKey(set: {
     name: string;
 }): string;
 /**
- * Sets in tie order (FR6, FR8): the project's set first, then load order.
+ * Sets in tie order (FR6, FR8): the project's set and its backups first, in
+ * list order, then load order.
  * @param {DiscoveredIconSet[]} sets
  * @param {IconSetChoice} choice
  * @returns {DiscoveredIconSet[]}
@@ -147,6 +185,8 @@ export function iconSetKey(set: {
 export function orderIconSets(sets: DiscoveredIconSet[], choice: IconSetChoice): DiscoveredIconSet[];
 /** A license or notice file a set ships beside its data (FR15). */
 export const NOTICE_FILE_RE: RegExp;
+/** The command that chooses a main set and backups, as the CLI prints it. */
+export const ICON_USE_ORDER_COMMAND: "astryx experimental icon use <main> --backup <set>";
 /**
  * One installed icon set: its descriptor, its data, and where it came from.
  */
@@ -213,6 +253,24 @@ export type WithdrawnIconSet = {
     kind: "invalid" | "unresolved";
     reason: string;
 };
+/**
+ * One backup set the project's list names, and what it resolves to.
+ */
+export type IconSetBackup = {
+    /**
+     * the name as the list writes it
+     */
+    selector: string;
+    status: "selected" | "ambiguous" | "missing" | "withdrawn";
+    /**
+     * the set, when selected
+     */
+    set?: DiscoveredIconSet | undefined;
+    /**
+     * one sentence saying why
+     */
+    reason: string;
+};
 /**
  * The project's icon set (FR8).
  */
@@ -230,9 +288,21 @@ export type IconSetChoice = {
      */
     set?: DiscoveredIconSet | undefined;
     /**
-     * the `experimental.iconSet` config value, when set
+     * the main set `experimental.iconSet` names
+     * (its first entry, when it is a list), when set
      */
     configured?: string | undefined;
+    /**
+     * the backup sets the list names after
+     * the main set, in order, when it names any
+     */
+    backups?: IconSetBackup[] | undefined;
+    /**
+     * the sets a template icon is looked
+     * up in, in order: the main set, then each backup that resolves. Present
+     * only when the main set is selected
+     */
+    order?: DiscoveredIconSet[] | undefined;
     /**
      * one sentence saying why
      */