@astryxdesign/cli 0.7.12-canary.dfd75a6 → 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/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

@@ -67,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
@@ -110,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';
@@ -167,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
  */
 
@@ -174,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
@@ -193,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;

package/api/search/_fit-order.d.mts

@@ -0,0 +1,47 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * The results with the first kept. Entries #2 to #10 split into runs of one
+ * band and kind. Inside a run, the entries that fit the query under FIT_BAR
+ * times the run's median fit move, in order, after the others, unless their
+ * name spells NAME_WORDS or more of the query's words. A run whose
+ * median fit is zero or less keeps its order. Nothing crosses a run, and
+ * nothing is added or dropped.
+ * @param {any[]} results
+ * @param {any[]} candidates
+ * @param {string} query
+ * @param {Weights | (() => Weights | null | undefined) | null | undefined} weights
+ *   the block picker's weights, or a function that reads them; the function
+ *   runs only when a run can change. Without weights the order stays
+ * @returns {any[]}
+ */
+export function orderByFit(results: any[], candidates: any[], query: string, weights: Weights | (() => Weights | null | undefined) | null | undefined): any[];
+/**
+ * The search response with its results ordered by fit (`orderByFit`). Any
+ * other response passes through.
+ * @template T
+ * @param {T} response
+ * @param {any[]} candidates
+ * @param {string} query
+ * @param {Weights | (() => Weights | null | undefined) | null | undefined} weights
+ * @returns {T}
+ */
+export function withFitOrder<T>(response: T, candidates: any[], query: string, weights: Weights | (() => Weights | null | undefined) | null | undefined): T;
+/**
+ * The search response with at most `limit` results.
+ * @template T
+ * @param {T} response
+ * @param {number} limit
+ * @returns {T}
+ */
+export function withLimit<T>(response: T, limit: number): T;
+/** An entry stays in place when its fit is at least this times the median. */
+export const FIT_BAR: 1.7;
+/** The first result stays; the pass orders the places after it up to here. */
+export const FIT_PLACES: 10;
+export type Weights = import("../build/blocks/blocks.mjs").BlockPickerWeights;
+export type Side = {
+    vector: Map<number, number>;
+    projected: Float64Array;
+};

package/api/search/_fit-order.mjs

@@ -0,0 +1,257 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file A last pass over a searcher's answer: inside each run of one score
+ * band and kind, the entries from #2 to #10 that fit the whole query much
+ * worse than the others in their run move, in order, after them.
+ * @input the ordered response, the gathered candidates, and the query
+ * @output the same response with the same results, maybe in a new order
+ * @position api/search; rankWith (_main-searcher.mjs) runs it after
+ * orderMatches, with the weights the adapter loads (loadSearchData) through
+ * build's own loader. The fit is build's block-picker match
+ * (build/blocks/blocks.mjs) with its shipped weights, so an entry the weights
+ * never saw is scored from its own docs the same way. Without readable
+ * weights the order stays.
+ */
+
+import {
+  docSideOf,
+  matchOf,
+  requestSideOf,
+  stemOf,
+  termsOf,
+  wordsOf,
+} from '../build/blocks/blocks.mjs';
+import {bandOf} from './_order.mjs';
+import {searchedComponentsOf} from './_result.mjs';
+
+/** An entry stays in place when its fit is at least this times the median. */
+export const FIT_BAR = 1.7;
+
+/** An entry whose name spells at least this many query words never moves. */
+const NAME_WORDS = 2;
+
+/** The first result stays; the pass orders the places after it up to here. */
+export const FIT_PLACES = 10;
+
+/** @typedef {import('../build/blocks/blocks.mjs').BlockPickerWeights} Weights */
+/** @typedef {{vector: Map<number, number>, projected: Float64Array}} Side */
+
+/**
+ * Each candidate by `domain:name`; a doc also by its topic and by
+ * `topic#section`. The first candidate with a key owns it.
+ * @type {WeakMap<any[], Map<string, any>>}
+ */
+const keyed = new WeakMap();
+
+/**
+ * Each candidate's docs side, computed when a result first needs it.
+ * @type {WeakMap<Weights, WeakMap<any, Side>>}
+ */
+const sides = new WeakMap();
+
+/**
+ * An entry's docs text: its name words, display name or first title,
+ * description, and keywords.
+ * @param {any} c
+ */
+const docText = c =>
+  [
+    wordsOf(c.name).join(' '),
+    c._displayName ?? (Array.isArray(c.titles) ? c.titles[0] : '') ?? '',
+    c.description ?? '',
+    (Array.isArray(c.keywords) ? c.keywords : []).join(' '),
+  ].join(' ');
+
+/**
+ * @param {any[]} candidates
+ * @returns {Map<string, any>}
+ */
+function keysOf(candidates) {
+  let byKey = keyed.get(candidates);
+  if (!byKey) {
+    byKey = new Map();
+    for (const c of candidates) {
+      const keys = [`${c.domain}:${c._resultName ?? c.name}`];
+      if (c.domain === 'doc' && c._topic)
+        keys.push(
+          c._section ? `doc:${c._topic}#${c._section}` : `doc:${c._topic}`,
+        );
+      for (const k of keys) if (!byKey.has(k)) byKey.set(k, c);
+    }
+    keyed.set(candidates, byKey);
+  }
+  return byKey;
+}
+
+/**
+ * @param {any} c
+ * @param {Weights} weights
+ * @returns {Side}
+ */
+function candidateSide(c, weights) {
+  let byCandidate = sides.get(weights);
+  if (!byCandidate) {
+    byCandidate = new WeakMap();
+    sides.set(weights, byCandidate);
+  }
+  let side = byCandidate.get(c);
+  if (!side) {
+    side = docSideOf(docText(c), weights);
+    byCandidate.set(c, side);
+  }
+  return side;
+}
+
+/**
+ * A result's docs side: its candidate's, else one from the result's own name,
+ * display name and description.
+ * @param {any} r
+ * @param {any[]} candidates
+ * @param {Weights} weights
+ * @returns {Side}
+ */
+function resultSideOf(r, candidates, weights) {
+  const byKey = keysOf(candidates);
+  if (r.domain === 'doc' && r.section) {
+    const c = byKey.get(`doc:${r.name}#${r.section}`);
+    if (c) return candidateSide(c, weights);
+  }
+  const c = byKey.get(`${r.domain}:${r.name}`);
+  return c
+    ? candidateSide(c, weights)
+    : docSideOf(
+        `${wordsOf(r.name).join(' ')} ${r.displayName ?? ''} ${r.description ?? ''}`,
+        weights,
+      );
+}
+
+/**
+ * A result's run: its score band and kind (doc or not), as orderMatches reads
+ * them.
+ * @param {any} r
+ */
+const runOf = r => `${bandOf(r.score ?? 0)}:${r.domain === 'doc'}`;
+
+/**
+ * The results with the first kept. Entries #2 to #10 split into runs of one
+ * band and kind. Inside a run, the entries that fit the query under FIT_BAR
+ * times the run's median fit move, in order, after the others, unless their
+ * name spells NAME_WORDS or more of the query's words. A run whose
+ * median fit is zero or less keeps its order. Nothing crosses a run, and
+ * nothing is added or dropped.
+ * @param {any[]} results
+ * @param {any[]} candidates
+ * @param {string} query
+ * @param {Weights | (() => Weights | null | undefined) | null | undefined} weights
+ *   the block picker's weights, or a function that reads them; the function
+ *   runs only when a run can change. Without weights the order stays
+ * @returns {any[]}
+ */
+export function orderByFit(results, candidates, query, weights) {
+  if (!weights || results.length < 3) return results;
+  const end = Math.min(FIT_PLACES, results.length);
+  /** @type {[number, number][]} */
+  const runs = [];
+  for (let i = 1; i < end;) {
+    let j = i;
+    while (j < end && runOf(results[j]) === runOf(results[i])) j++;
+    runs.push([i, j]);
+    i = j;
+  }
+  // Only a run of two or more can change, so the weights stay unread when
+  // there is none.
+  if (!runs.some(([i, j]) => j - i > 1)) return results;
+  const w = typeof weights === 'function' ? weights() : weights;
+  if (!w) return results;
+  const request = requestSideOf(query, w);
+  const queryWords = new Set(termsOf(query).filter(t => !t.includes('_')));
+  /** @param {any} r */
+  const named = r =>
+    new Set(
+      wordsOf(r.name)
+        .map(stemOf)
+        .filter(word => queryWords.has(word)),
+    ).size >= NAME_WORDS;
+  const out = results.slice();
+  let changed = false;
+  for (const [i, j] of runs) {
+    if (j - i < 2) continue;
+    const moved = demoteWeak(
+      results.slice(i, j),
+      request,
+      candidates,
+      w,
+      named,
+    );
+    moved.forEach((r, k) => {
+      if (r !== out[i + k]) changed = true;
+      out[i + k] = r;
+    });
+  }
+  return changed ? out : results;
+}
+
+/**
+ * One run, with the entries under FIT_BAR times its median fit moved, in
+ * order, after the others. An entry whose name spells NAME_WORDS or more of
+ * the query's words stays with the others: its name is strong evidence.
+ * @param {any[]} run
+ * @param {Side} request
+ * @param {any[]} candidates
+ * @param {Weights} weights
+ * @param {(r: any) => boolean} named
+ * @returns {any[]}
+ */
+function demoteWeak(run, request, candidates, weights, named) {
+  const fits = run.map(
+    r => matchOf(request, resultSideOf(r, candidates, weights), weights).match,
+  );
+  const sorted = [...fits].sort((a, b) => a - b);
+  const n = sorted.length;
+  const median =
+    n % 2 ? sorted[(n - 1) / 2] : (sorted[n / 2 - 1] + sorted[n / 2]) / 2;
+  if (!(median > 0)) return run;
+  const bar = FIT_BAR * median;
+  const kept = run.map((r, k) => fits[k] >= bar || named(r));
+  return [...run.filter((_, k) => kept[k]), ...run.filter((_, k) => !kept[k])];
+}
+
+/**
+ * The search response with its results ordered by fit (`orderByFit`). Any
+ * other response passes through.
+ * @template T
+ * @param {T} response
+ * @param {any[]} candidates
+ * @param {string} query
+ * @param {Weights | (() => Weights | null | undefined) | null | undefined} weights
+ * @returns {T}
+ */
+export function withFitOrder(response, candidates, query, weights) {
+  const r = /** @type {any} */ (response);
+  const results = r?.data?.results;
+  if (!Array.isArray(results)) return response;
+  const ordered = orderByFit(results, candidates, query, weights);
+  if (ordered === results) return response;
+  const out = {...r, data: {...r.data, results: ordered}};
+  const searched = searchedComponentsOf.get(r);
+  if (searched) searchedComponentsOf.set(out, searched);
+  return /** @type {T} */ (out);
+}
+
+/**
+ * The search response with at most `limit` results.
+ * @template T
+ * @param {T} response
+ * @param {number} limit
+ * @returns {T}
+ */
+export function withLimit(response, limit) {
+  const r = /** @type {any} */ (response);
+  const results = r?.data?.results;
+  if (!Array.isArray(results) || results.length <= limit) return response;
+  const out = {...r, data: {...r.data, results: results.slice(0, limit)}};
+  const searched = searchedComponentsOf.get(r);
+  if (searched) searchedComponentsOf.set(out, searched);
+  return /** @type {T} */ (out);
+}

package/api/search/_main-searcher.mjs

@@ -15,6 +15,7 @@
 import {routeKit} from '../../foundation/route/route.mjs';
 import {rank, signals} from './_features.mjs';
 import {entryTable} from './_entries.mjs';
+import {FIT_PLACES, withFitOrder, withLimit} from './_fit-order.mjs';
 import {orderMatches} from './_order.mjs';
 import {routeProbs} from './_query-words.mjs';
 import {namesWhole, rankLexical} from './_lexical.mjs';
@@ -94,13 +95,22 @@ export function rankWith(request, catalog, weights) {
   );
   const route = routeProbs(catalog.data.router, query);
   const rows = signals(table, query, lexical.data.results, route);
-  return orderMatches(
-    table,
-    rank(table, rows, weights),
-    lexical,
+  const limit = options.limit ?? 20;
+  // The fit pass reads the first FIT_PLACES results at every limit, so a
+  // smaller limit shows the top of that order.
+  const ordered = withFitOrder(
+    orderMatches(
+      table,
+      rank(table, rows, weights),
+      lexical,
+      query,
+      Math.max(limit, FIT_PLACES),
+    ),
+    catalog.all,
     query,
-    options.limit ?? 20,
+    () => catalog.data.picker,
   );
+  return withLimit(ordered, limit);
 }
 
 /** @type {import('./tree.mjs').SearchKit} */

package/assets/templates/themes/neutral/neutralTheme.ts

@@ -361,7 +361,13 @@ export const neutralTheme = defineTheme({
         padding: 'var(--spacing-1)',
       },
     },
+    // An unselected label sits on the translucent track, which lifts the
+    // page under it. In dark mode secondary text falls under 4.5:1 on the
+    // track over the surface, so it takes the same next stop.
     'segmented-control-item': {
+      base: {
+        '--color-text-secondary': `light-dark(${neutral.light[30]}, ${neutral.dark[80]})`,
+      },
       'size:sm': {
         height: 'calc(var(--size-element-sm) - 8px)',
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.7.12-canary.dfd75a6",
+  "version": "0.7.12-canary.e171d97",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -125,7 +125,7 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/core": "0.7.12-canary.dfd75a6"
+    "@astryxdesign/core": "0.7.12-canary.e171d97"
   },
   "peerDependenciesMeta": {
     "@astryxdesign/core": {
@@ -133,10 +133,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.7.12-canary.dfd75a6",
-    "@astryxdesign/core": "0.7.12-canary.dfd75a6",
-    "@astryxdesign/lab": "0.7.12-canary.dfd75a6",
-    "@astryxdesign/theme-neutral": "0.7.12-canary.dfd75a6",
+    "@astryxdesign/charts": "0.7.12-canary.e171d97",
+    "@astryxdesign/core": "0.7.12-canary.e171d97",
+    "@astryxdesign/lab": "0.7.12-canary.e171d97",
+    "@astryxdesign/theme-neutral": "0.7.12-canary.e171d97",
     "@heroicons/react": "^2.2.0",
     "@stylexjs/stylex": "^0.19.0",
     "@types/babel__core": "^7.20.5",