@astryxdesign/cli 0.7.12-canary.f543ec7 → 0.7.12

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/index.d.mts

@@ -47,6 +47,7 @@ export * from "./integration/authoring-checks.type.mjs";
 export * from "./integration/integration-check.type.mjs";
 export type Logger = import("./logger.mjs").Logger;
 export { themeBuild, themeAdd, themeRemove, themeUse, themeEject, themeTemplate, themeList, themeListAvailable, themeListCopySources, themeTargets, themePaletteGenerate, generateTonalPalette, listThemes } from "./theme/theme.mjs";
+export { exportSearchIndex, rankSearchIndex } from "./search/search-index.mjs";
 export { integrationAdd, integrationAddAgentDoc, integrationAddCodemod, integrationAddComponent, integrationAddDoc, integrationAddTemplate } from "./integration/add-contribution.mjs";
 export { validateIntegration, summarizeIssues } from "./integration/validate-integration.mjs";
 export { integrationTemplateConflicts, integrationComponentConflicts, integrationDocConflicts } from "./integration/authoring-checks.mjs";

package/api/index.mjs

@@ -48,6 +48,7 @@ export {
 } from './theme/theme.mjs';
 export {hook} from './hook/hook.mjs';
 export {search} from './search/search.mjs';
+export {exportSearchIndex, rankSearchIndex} from './search/search-index.mjs';
 export {build} from './build/build.mjs';
 export {swizzle} from './swizzle/swizzle.mjs';
 export {gapReport} from './gap-report/gap-report.mjs';

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/_adapter.mjs

@@ -548,6 +548,15 @@ export function reverseToFile({cwd, input, output, overwrite}) {
       ...(missing.length > 0 ? {missing} : {}),
     };
   }
+  // A file a render wrote, whose source block was taken out on the way
+  // (sanitizers and editors strip <script> elements), says so.
+  if (!isAstryxMarkup(html) && /<meta name="generator" content="Astryx[ "]/.test(html)) {
+    throw new AstryxError(
+      `${shown(cwd, input)} was rendered by Astryx, but its embedded source was removed (a sanitizer or an editor strips <script> blocks) and it has no Astryx components to rebuild from; nothing was written. Render the page again from its source and send the new file as is.`,
+      [],
+      ERROR_CODES.ERR_RENDER_SOURCE_DAMAGED,
+    );
+  }
   if (!isAstryxMarkup(html)) {
     throw new AstryxError(
       `${shown(cwd, input)} is not an Astryx page: it has no embedded source and no Astryx components to rebuild from. To start an Astryx page like it, run astryx build "<what the page is>".`,

package/api/render/render.doc.mjs

@@ -96,12 +96,12 @@ 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 with no embedded source and no Astryx markup; the suggestion is `astryx build "<what the page is>"`',
+      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>"`',
     },
-    {code: 'ERR_RENDER_SOURCE_DAMAGED', when: 'reversing a file whose embedded source is damaged, lists a path twice, carries a module, stylesheet or JSON file the page does not reach through its imports, or an image, font or media file whose bytes are not one, or carries a file a render never embeds (a dotfile or dot-folder, `node_modules`, a package manifest, lockfile or tool configuration, or any kind but a page module, stylesheet, JSON or image)'},
+    {code: 'ERR_RENDER_SOURCE_DAMAGED', when: 'reversing a file a render wrote whose embedded source was removed (and that has no Astryx components to rebuild from), a file whose embedded source is damaged, lists a path twice, carries a module, stylesheet or JSON file the page does not reach through its imports, or an image, font or media file whose bytes are not one, or carries a file a render never embeds (a dotfile or dot-folder, `node_modules`, a package manifest, lockfile or tool configuration, or any kind but a page module, stylesheet, JSON or image)'},
     {code: 'ERR_PATH_TRAVERSAL', when: 'a file would be written outside the current folder (symlinks followed), or through a symbolic link: `out`, or with `reverse` the page or an embedded file; or, with `reverse`, a file other than the page would go into a folder that already exists'},
   ],
   examples: [

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/api/search/ORDERING.md

@@ -6,12 +6,15 @@
 
 `spec:AST-083` owns search's result order; this file describes the data that implements it. Inside one score band, a searcher's static weights decide the order. Matches with the same score move together as one block, placed by the learned position of the block's first match: moving each one on its own breaks search's existing rules for tied matches. Inside a block, the lexical ranker's order holds, except below the first result: there a block of one domain puts a part of the first result first (its name words start with the first result's; at most two parts lead across an answer), then the match whose matched words are rarer in the catalog. Matches never cross bands or kinds. There is no model runtime: every number is a plain static value read at load time.
 
+After that order, one fit pass reads the first ten results (`_fit-order.mjs`). The first result stays. The others split into runs of one band and kind. Inside a run, each match gets a fit to the whole query from build's block-picker match (`../build/blocks/blocks.mjs` with `blocks.weights.json`) over the match's own docs: its name words, display name or title, description, and keywords. A match whose fit is under 1.7 times the run's median fit moves, in order, after the others in its run, unless its name spells two or more of the query's words. Such a match never moves down; it can still move up when others move after it. A run whose median fit is zero or less keeps its order. A query that is an entry's whole name skips the pass, as it skips the learned order. The pass always reads ten places before the limit cuts the answer. At the default limit, and at any limit of 10 or more, the set of results stays the same. A smaller limit shows the top of the new order, so it can show a different result. Build's loader (`loadBlockPicker` in `../build/_adapter.mjs`) reads and checks the block-picker weights for both commands. When the file is missing, unreadable, or not the picker's shape, the loader returns null and the pass keeps the order. The pass reads the weights only when a run holds two or more matches, and it decodes only the matrix rows that the query's words and those matches' docs use, so a search does not pay for the whole catalog.
+
 ## Files
 
 | File                                                                                           | What it holds                                                                                                                                                                                                                                 |
 | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `tree.weights.json`                                                                            | The root classifier: for each query word or word pair, one number per class (component, hook, doc, template, theme, none). The query's tokens vote, and a topic searcher takes the query only when its class wins by the floor in `tree.mjs`. |
 | `_main-searcher.weights.json`, `_doc-searcher.weights.json`, `_template-searcher.weights.json` | One weight, mean and spread per signal for each searcher (see `SIGNALS` and `PER_DOMAIN` in `_features.mjs`). A match's place inside its band is the weighted sum of its standardized signals.                                                |
+| `../build/blocks/blocks.weights.json`                                                          | The block picker's vocabulary, idf and two projection matrices, shared with build. The fit pass reads them through build's loader; search ships no copy.                                                                                      |
 | `_cards.json`                                                                                  | One card per Core component and hook: what it is, the words people use for it, and its main props, written from the item's own source. Cards feed one signal, word overlap with the card.                                                     |
 
 The signals are counts over the query and each entry's own text: the lexical score and rank, BM25 over the entry's name, docs text and card, how many query words the entry covers, whether the query holds the entry's name, and the classifier's guess of the domain.

package/api/search/_adapter.d.mts

@@ -16,7 +16,7 @@ export function requireSearchCoreDir(cwd: string): string;
  * in the CLI's searches. A caller that runs its own operation shares it.
  *
  * @param {{cwd?: string, type?: string}} options
- * @returns {Promise<{all: Candidate[], components: Candidate[], searchedComponents: boolean, outside: boolean, coreSkipped: string | null}>}
+ * @returns {Promise<{all: Candidate[], components: Candidate[], searchedComponents: boolean, outside: boolean, coreSkipped: string | null, coreSkippedCode: string | null}>}
  */
 export function gatherCandidates(options: {
     cwd?: string;
@@ -27,7 +27,28 @@ export function gatherCandidates(options: {
     searchedComponents: boolean;
     outside: boolean;
     coreSkipped: string | null;
+    coreSkippedCode: string | null;
 }>;
+/**
+ * The Core a search of `type` reads, and the domains it gathers. `astryx docs`
+ * reads docs without @astryxdesign/core, and `astryx theme list` reads themes
+ * without it, so a docs or themes search never looks for Core. Every other
+ * domain reads Core: the project's, else the answering release's own,
+ * installed into the per-user cache on first need (spec AST-081 FR3). A Core
+ * domain asked for by name throws the lookup's coded error. An open search
+ * without Core gathers the docs and themes alone and records why in
+ * `coreSkipped`; it never fails silently.
+ * @param {string | undefined} type
+ * @param {(cwd: string) => string} lookup finds the Core folder, or throws
+ * @param {string} cwd
+ * @returns {{coreDir: string | null, coreSkipped: string | null, coreSkippedCode: string | null, wants: (domain: string) => boolean}}
+ */
+export function resolveSearchCore(type: string | undefined, lookup: (cwd: string) => string, cwd: string): {
+    coreDir: string | null;
+    coreSkipped: string | null;
+    coreSkippedCode: string | null;
+    wants: (domain: string) => boolean;
+};
 /**
  * gatherCandidates, reused within one process: a later search in the same
  * folder, for the same `type`, ranks the candidates an earlier search
@@ -46,8 +67,10 @@ export function gatherCandidatesReused(options: {
     type?: string;
 }): Promise<Gathered>;
 /**
- * The search tree's static data, read once: the entry cards and each node's
- * weights file.
+ * The search tree's static data, read once: the entry cards, each node's
+ * weights file, and build's block-picker weights for the fit pass. Build's
+ * loader (loadBlockPicker) reads and checks the picker weights, only when the
+ * pass first needs them.
  *
  * These files are static, reviewed data that only order matches inside a score
  * band; ORDERING.md beside them says what each holds and how
@@ -89,6 +112,12 @@ export type SearchData = {
      * The template searcher's weights.
      */
     template: SearcherWeights;
+    /**
+     *  Build's block-picker weights, which the fit pass (_fit-order.mjs) reads;
+     *  null when build's loader finds the file absent, unreadable, or the wrong
+     *  shape.
+     */
+    picker: import("../build/blocks/blocks.mjs").BlockPickerWeights | null;
 };
 export type SearchCatalog = Awaited<ReturnType<typeof gatherCandidates>> & {
     data: SearchData;

package/api/search/_adapter.mjs

@@ -16,6 +16,7 @@ import {
 } from '../../foundation/fs/read-record.mjs';
 import {isOutsideProject} from '../../foundation/env/project-scope.mjs';
 import {coreDirOrThrow} from '../error.mjs';
+import {loadBlockPicker} from '../build/_adapter.mjs';
 import {CORELESS_DOMAINS} from './_query.mjs';
 import {gatherComponents} from './_gather-components.mjs';
 import {gatherHooks} from './_gather-hooks.mjs';
@@ -43,46 +44,62 @@ export function requireSearchCoreDir(cwd) {
  * in the CLI's searches. A caller that runs its own operation shares it.
  *
  * @param {{cwd?: string, type?: string}} options
- * @returns {Promise<{all: Candidate[], components: Candidate[], searchedComponents: boolean, outside: boolean, coreSkipped: string | null}>}
+ * @returns {Promise<{all: Candidate[], components: Candidate[], searchedComponents: boolean, outside: boolean, coreSkipped: string | null, coreSkippedCode: string | null}>}
  */
 export function gatherCandidates(options) {
   return withListingCache(() => gatherDomains(options));
 }
 
 /**
- * @param {{cwd?: string, type?: string}} options
+ * The Core a search of `type` reads, and the domains it gathers. `astryx docs`
+ * reads docs without @astryxdesign/core, and `astryx theme list` reads themes
+ * without it, so a docs or themes search never looks for Core. Every other
+ * domain reads Core: the project's, else the answering release's own,
+ * installed into the per-user cache on first need (spec AST-081 FR3). A Core
+ * domain asked for by name throws the lookup's coded error. An open search
+ * without Core gathers the docs and themes alone and records why in
+ * `coreSkipped`; it never fails silently.
+ * @param {string | undefined} type
+ * @param {(cwd: string) => string} lookup finds the Core folder, or throws
+ * @param {string} cwd
+ * @returns {{coreDir: string | null, coreSkipped: string | null, coreSkippedCode: string | null, wants: (domain: string) => boolean}}
  */
-async function gatherDomains(options) {
-  const {cwd = process.cwd(), type} = options;
-  // `astryx docs` reads docs without @astryxdesign/core, and `astryx theme
-  // list` reads themes without it (bundled themes need no project), so a
-  // search of either must too. Every other domain reads core: asked for by
-  // name, it is an error without core; an open search then covers the docs
-  // and themes alone.
+export function resolveSearchCore(type, lookup, cwd) {
   const needsCore = !type || !CORELESS_DOMAINS.includes(type);
-  // A domain that reads Core gets it as `component` does: the project's, else
-  // the answering release's own, installed into the per-user cache on first
-  // need (spec AST-081 FR3). Asked for by name, a Core that cannot be had is
-  // the error; an open search answers from the rest and says what it skipped
-  // and why, never silently.
   /** @type {string | null} */
   let coreDir = null;
   /** @type {string | null} */
   let coreSkipped = null;
+  /** @type {string | null} */
+  let coreSkippedCode = null;
   if (needsCore && type) {
-    coreDir = coreDirOrThrow(requireSearchCoreDir, cwd);
+    coreDir = coreDirOrThrow(lookup, cwd);
   } else if (needsCore) {
     try {
-      coreDir = requireSearchCoreDir(cwd);
+      coreDir = lookup(cwd);
     } catch (error) {
       coreSkipped = /** @type {Error} */ (error).message;
+      const code = /** @type {any} */ (error)?.code;
+      coreSkippedCode = typeof code === 'string' ? code : null;
     }
   }
+  /** @param {string} domain */
+  const wants = domain =>
+    (!type && (coreDir != null || CORELESS_DOMAINS.includes(domain))) ||
+    type === domain;
+  return {coreDir, coreSkipped, coreSkippedCode, wants};
+}
 
-  // Gather candidates from each requested domain in parallel.
-  /** @param {string} d */
-  const wants = d =>
-    (!type && (coreDir != null || CORELESS_DOMAINS.includes(d))) || type === d;
+/**
+ * @param {{cwd?: string, type?: string}} options
+ */
+async function gatherDomains(options) {
+  const {cwd = process.cwd(), type} = options;
+  const {coreDir, coreSkipped, coreSkippedCode, wants} = resolveSearchCore(
+    type,
+    requireSearchCoreDir,
+    cwd,
+  );
   const [components, hooks, docTopics, templates, themes] = await Promise.all([
     wants('component')
       ? gatherComponents(/** @type {string} */ (coreDir), cwd)
@@ -103,6 +120,7 @@ async function gatherDomains(options) {
     searchedComponents: wants('component'),
     outside,
     coreSkipped,
+    coreSkippedCode,
   };
 }
 
@@ -150,6 +168,10 @@ export function gatherCandidatesReused(options) {
  * @property {SearcherWeights} main The main searcher's weights.
  * @property {SearcherWeights} doc The doc searcher's weights.
  * @property {SearcherWeights} template The template searcher's weights.
+ * @property {import('../build/blocks/blocks.mjs').BlockPickerWeights | null} picker
+ *   Build's block-picker weights, which the fit pass (_fit-order.mjs) reads;
+ *   null when build's loader finds the file absent, unreadable, or the wrong
+ *   shape.
  * @typedef {Awaited<ReturnType<typeof gatherCandidates>> & {data: SearchData}} SearchCatalog
  */
 
@@ -157,8 +179,10 @@ export function gatherCandidatesReused(options) {
 let searchData = null;
 
 /**
- * The search tree's static data, read once: the entry cards and each node's
- * weights file.
+ * The search tree's static data, read once: the entry cards, each node's
+ * weights file, and build's block-picker weights for the fit pass. Build's
+ * loader (loadBlockPicker) reads and checks the picker weights, only when the
+ * pass first needs them.
  *
  * These files are static, reviewed data that only order matches inside a score
  * band; ORDERING.md beside them says what each holds and how
@@ -176,6 +200,10 @@ export function loadSearchData() {
       main: read('./_main-searcher.weights.json'),
       doc: read('./_doc-searcher.weights.json'),
       template: read('./_template-searcher.weights.json'),
+      // Read on first use: most searches never reach the fit pass.
+      get picker() {
+        return loadBlockPicker();
+      },
     };
   }
   return searchData;