@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

package/api/search/search.mjs

@@ -57,9 +57,10 @@
  * Between domains, ranking adds one rule ahead of the score: domain priority
  * (see {@link domainPriority}). A component, hook, template, or theme whose
  * name or keyword a query word hits ranks ahead of every doc the reader did not
- * ask for by name or title, so `font size` finds `Text` before a typography
- * topic that declares the phrase. A doc the query names, or whose title the
- * query holds, keeps its place.
+ * ask for by name, title, or a declared phrase, so `font size` finds `Text`
+ * before a token page whose heading holds the phrase. A doc the query names,
+ * whose title the query holds, or that declares the whole query as a keyword
+ * keeps its place.
  *
  * Description and guidance are separate tiers on purpose. A component's own
  * one-line description saying "notification" is a claim about what it IS; the
@@ -81,11 +82,19 @@
 
 import {withListingCache} from '../../foundation/fs/listing-cache.mjs';
 import {readDocView} from '../../foundation/doc-compiler/read.mjs';
-import {findCoreDir} from '../../foundation/fs/paths.mjs';
+import {discoverExternalPackages} from '../../foundation/fs/paths.mjs';
+import {requireSearchCoreDir} from './_adapter.mjs';
+import {isOutsideProject} from '../../foundation/env/project-scope.mjs';
 import {
   discoverComponents,
   discoverValidIntegrationComponents,
+  docStem,
+  familyMember,
   findComponentReadme,
+  forEachIntegrationDoc,
+  integrationMemberEntry,
+  integrationRecordHold,
+  isIntegrationMember,
   resolveImportPath,
   resolveIntegrationImportPath,
   CORE_PACKAGE,
@@ -97,6 +106,7 @@ import {
 import {
   loadComponentReplacements,
   loadIntegrationsSafely,
+  resolveLegacyExternalDoc,
 } from '../component/_adapter.mjs';
 import {levenshteinDistance} from '../../foundation/text/string-utils.mjs';
 import {discoverTemplates, extractComponents} from '../template/template.mjs';
@@ -115,9 +125,10 @@ import {
   sectionKey,
   sectionSummary,
 } from '../../foundation/discovery/docs-section-key.mjs';
-import {AstryxError} from '../error.mjs';
+import {AstryxError, coreDirOrThrow} from '../error.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 import {setResultCoverage} from './coverage.mjs';
+import {linkSearchResponse} from '../component/_adapter.mjs';
 
 /**
  * A search candidate gathered from one content domain. Extra underscore-
@@ -128,6 +139,9 @@ import {setResultCoverage} from './coverage.mjs';
  * @property {string[]} [aliases] - Other names the candidate answers to, scored
  *   with the same name signals: a theme's display name.
  * @property {string[]} [keywords]
+ * @property {string[]} [_declared] - A doc's own declared keywords: what its
+ *   author lists in `keywords`, without the code terms and table cells its
+ *   other keywords add.
  * @property {string[]} [weakKeywords]
  * @property {string} [description]
  * @property {string[]} [prose]
@@ -149,6 +163,9 @@ import {setResultCoverage} from './coverage.mjs';
  * @property {'page'|'block'} [_kind]
  * @property {string} [_resultName]
  * @property {string} [_commandName]
+ * @property {'file'|'doc'} [_hold] - How an integration component holds its
+ *   name, for the owner rule.
+ * @property {string} [_docPath] - An integration component's doc.
  */
 
 /**
@@ -242,9 +259,34 @@ function wordForms(w) {
   if (w.length > 3 && w.endsWith('s')) forms.add(w.slice(0, -1));
   if (w.length > 4 && w.endsWith('es')) forms.add(w.slice(0, -2));
   if (w.length > 4 && w.endsWith('ies')) forms.add(w.slice(0, -3) + 'y');
+  // A gerund keeps its verb: "spacing" lost a final e ("space"), and
+  // "dragging" doubled a consonant ("drag"). A past participle does not: it
+  // usually describes a state ("archived notes"), not the action a catalog
+  // word names.
+  if (w.length >= 6 && w.endsWith('ing')) {
+    const base = w.slice(0, -3);
+    forms.add(base);
+    forms.add(`${base}e`);
+    if (/([b-df-hj-np-tv-z])\1$/.test(base)) forms.add(base.slice(0, -1));
+  }
   return forms;
 }
 
+/**
+ * The singulars a lowercase word may have when it ends in a plural suffix:
+ * "tokens" is "token", "boxes" is "box", "entries" is "entry".
+ * @param {string} w
+ * @returns {string[]}
+ */
+function singulars(w) {
+  /** @type {string[]} */
+  const out = [];
+  if (w.length > 3 && w.endsWith('s')) out.push(w.slice(0, -1));
+  if (w.length > 4 && w.endsWith('es')) out.push(w.slice(0, -2));
+  if (w.length > 4 && w.endsWith('ies')) out.push(w.slice(0, -3) + 'y');
+  return out;
+}
+
 /**
  * Whether two lowercase words are the same word, up to plural and stem form.
  * @param {string} a
@@ -285,9 +327,201 @@ function wordsOf(text) {
 function startsAWordOf(term, text) {
   if (term.length < 4) return false;
   if (term.length / String(text).length < 0.5) return false;
-  return wordsOf(text).some(w => w.startsWith(term) || sameWord(term, w));
+  // The term or its singular may start the word: "tokens" starts
+  // "tokenizer" through "token". A singular needs five letters, so "stats"
+  // does not start "status".
+  const starts = [term, ...singulars(term).filter(f => f.length >= 5)];
+  return wordsOf(text).some(
+    w => starts.some(f => w.startsWith(f)) || sameWord(term, w),
+  );
+}
+
+/**
+ * A query with its camelCase and PascalCase identifiers spelled as words, so
+ * `SidebarToggle` reads "sidebar toggle" and `useTablePaginationState` "use
+ * table pagination state". Plain words, and identifiers joined with `_` or `-`, are
+ * unchanged: a joined token that matches nothing stays unmatched.
+ * @param {string} query - The query as typed, before lowercasing.
+ * @returns {string} Lowercased.
+ */
+export function spellIdentifiers(query) {
+  return String(query)
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z])([A-Z][a-z])/g, '$1 $2')
+    .toLowerCase();
+}
+
+/**
+ * A name or keyword with its separators removed, lowercased: `Side Nav`,
+ * `side-nav`, and `SideNav` all join to `sidenav`.
+ * @param {string} text
+ * @returns {string}
+ */
+function joined(text) {
+  return String(text)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '');
+}
+
+/**
+ * The strongest hit a run of two or more adjacent query words has when it is
+ * read as one joined word, and the query words it covers. Readers type a
+ * compound name as separate words (`table header cell` is TableHeaderCell,
+ * `number field` the keyword `numberfield`), and no single word of the run
+ * matches on its own.
+ *
+ * - 100: the run joins to a component, hook, or template name, or its plural
+ *   (`table header cells` is TableHeaderCell), or a hook name without its
+ *   `use` prefix (`table sticky columns` is useTableStickyColumns).
+ * - 90: the run joins to a one-word keyword (`number field` is
+ *   `numberfield`).
+ * - 95: the run joins to most of a name, cut short (`dropdown menu radio` is
+ *   DropdownMenuRadioItem); 92: it is a name's leading words, covering at least half
+ *   of it (`top nav mega` is TopNavMegaMenu); 70: it is two or more adjacent
+ *   words of a name that cover at least half of it (`header cell` in
+ *   TableHeaderCell), the same coverage a word prefix needs. These three
+ *   are for components and hooks only.
+ *
+ * A doc's name is a route or key, so docs are left out.
+ * @param {string[]} words - The query's words, stopwords included.
+ * @param {Candidate} candidate
+ * @returns {{score: number, reason: string, covered: Set<string>, alias?: 'partial' | 'keyword', aliasWords?: number} | null}
+ *   `covered` holds the run's words and every stretch of them joined. `alias`
+ *   marks a hit on part of a name or on a keyword, not on the whole name.
+ */
+export function compoundHit(words, candidate) {
+  if (candidate.domain === 'doc' || words.length < 2) return null;
+  const names = [candidate.name, ...(candidate.aliases ?? [])]
+    .filter(Boolean)
+    .map(name => ({name, nameJoined: joined(name), nameWords: wordsOf(name)}));
+  // Part of a name counts only for a component or hook. A template's name
+  // starts with the component it shows (`ProgressBarShowcase`), so part of it
+  // names the component, not the template.
+  const partial =
+    candidate.domain === 'component' || candidate.domain === 'hook';
+  // One-word lowercase keywords: a keyword an author declares for a reader
+  // to type, joined (`numberfield`). A capitalized one names another entry (a
+  // block's `componentsUsed`), which matches by its own name, and a keyword of
+  // several words is a phrase, matched as one.
+  const keywords = (candidate.keywords ?? []).filter(k =>
+    /^[a-z0-9]+$/.test(String(k)),
+  );
+  /** @type {{score: number, reason: string, covered: Set<string>, alias?: 'partial' | 'keyword', aliasWords?: number} | null} */
+  let best = null;
+  for (const {run, word} of queryRuns(words)) {
+    let score = 0;
+    let reason = '';
+    /** @type {'partial' | 'keyword' | null} */
+    let kind = null;
+    for (const {name, nameJoined, nameWords} of names) {
+      if (
+        nameJoined === word ||
+        pluralOf(word, nameJoined) ||
+        (candidate.domain === 'hook' && nameJoined === `use${word}`)
+      ) {
+        if (score < 100)
+          [score, reason, kind] = [100, `name ${name} spelled`, null];
+      } else if (!partial) {
+        continue;
+      } else if (
+        nameJoined.startsWith(word) &&
+        word.length / nameJoined.length >= 0.75
+      ) {
+        // Most of the name, cut short: `dropdown menu radio` is
+        // DropdownMenuRadioItem.
+        if (score < 95)
+          [score, reason, kind] = [95, `name ${name} spelled`, 'partial'];
+      } else if (
+        word.length / nameJoined.length >= 0.5 &&
+        run.every(
+          (w, j) => nameWords[j + (nameWords[0] === 'use' ? 1 : 0)] === w,
+        )
+      ) {
+        // The name's leading words: `top nav mega` is TopNavMegaMenu.
+        if (score < 92)
+          [score, reason, kind] = [
+            92,
+            `name ${name} starts "${run.join(' ')}"`,
+            'partial',
+          ];
+      } else if (
+        word.length / nameJoined.length >= 0.5 &&
+        nameWords.some((_, k) => run.every((w, j) => nameWords[k + j] === w))
+      ) {
+        if (score < 70)
+          [score, reason, kind] = [
+            70,
+            `name ${name} holds "${run.join(' ')}"`,
+            'partial',
+          ];
+      }
+    }
+    if (score < 90 && keywords.includes(word)) {
+      [score, reason, kind] = [
+        90,
+        `keyword "${run.join(' ')}" spelled`,
+        'keyword',
+      ];
+    }
+    if (score > (best?.score ?? 0)) {
+      // Each word of the run, and each identifier typed as several of its
+      // words joined (`dropdownMenu` in `dropdownMenu checkbox`).
+      const covered = new Set();
+      for (let a = 0; a < run.length; a++) {
+        for (let b = a + 1; b <= run.length; b++) {
+          covered.add(run.slice(a, b).join(''));
+        }
+      }
+      best = {
+        score,
+        reason,
+        covered,
+        ...(kind ? {alias: kind, aliasWords: run.length} : {}),
+      };
+    }
+  }
+  return best;
+}
+
+/**
+ * The longest run of adjacent query words read as one name. Core's longest
+ * names run to six words; a longer run is a sentence, not a name, and reading
+ * every run of a long build idea costs time on every candidate.
+ */
+const MAX_RUN_WORDS = 6;
+
+/**
+ * Each run of two to {@link MAX_RUN_WORDS} adjacent query words, longest
+ * first, with the run joined into one word. Computed once per query.
+ * @type {WeakMap<string[], {run: string[], word: string}[]>}
+ */
+const runsOf = new WeakMap();
+
+/**
+ * @param {string[]} words
+ * @returns {{run: string[], word: string}[]}
+ */
+function queryRuns(words) {
+  let runs = runsOf.get(words);
+  if (runs) return runs;
+  runs = [];
+  for (let len = Math.min(words.length, MAX_RUN_WORDS); len >= 2; len--) {
+    for (let i = 0; i + len <= words.length; i++) {
+      const run = words.slice(i, i + len);
+      runs.push({run, word: run.join('')});
+    }
+  }
+  runsOf.set(words, runs);
+  return runs;
 }
 
+/**
+ * Each candidate's compound hit from its last scoreQuery, so domainPriority
+ * reads it without walking the query's runs again.
+ * @type {WeakMap<object, ReturnType<typeof compoundHit>>}
+ */
+const compoundOf = new WeakMap();
+
 /**
  * The fewest letters both words need before an edit distance counts as a
  * typo, by distance. Below them, one edit usually makes a different word.
@@ -500,19 +734,20 @@ const STRONG_TOKEN_SCORE = 70;
  *   typography/font-setup, `side panel` is "Side panels");
  * - 1: a word of the query is the topic's name (`illustration` in a longer
  *   question is the illustrations guide);
+ * - 1: a query of two or more words is one of the topic's own declared
+ *   keywords, whatever the plural (`code review` on a guide that declares it);
  * - 1: the query holds one of the doc's titles whole (`resizable side panels`
  *   names "Side panels"; `light dark mode button` names "Light/Dark Mode");
  * - 1: the doc matches every word of the query and one of them is a word of
  *   its title (`switch to a dark theme` and "Use a theme").
  * A section answers to its topic's name.
  *
- * A doc that matched only by keyword, by a heading holding the query, or by
+ * A doc that matched only by a heading holding the query, by one word, or by
  * words spread through its text has no priority. Docs are split into many
- * small topics, and each declares its own keywords and headings, so a common
- * phrase such as `font size` hits a guide's keyword or heading exactly
- * (170-190) while the component the reader is after matches one word by
- * keyword (`Text`, 98). Ranked on text alone, every split adds another doc
- * above the component. Broad reference pages match every word of many queries
+ * small topics, each with its own headings, so a common phrase such as
+ * `font size` hits a heading exactly (170) while the component the reader is
+ * after matches one word by keyword (`Text`, 98). Ranked on text alone, every
+ * split adds another doc above the component. Broad reference pages match every word of many queries
  * in their text the same way. The score stays the text-match strength the
  * result reports, so callers that gate on it (`build`) see the same numbers.
  *
@@ -523,7 +758,13 @@ const STRONG_TOKEN_SCORE = 70;
  *   candidate's scoreQuery result.
  * @returns {0 | 1 | 2}
  */
-export function domainPriority(term, tokens, candidate, hit) {
+export function domainPriority(
+  term,
+  tokens,
+  candidate,
+  hit,
+  queryWords = phraseWords(term),
+) {
   const words = [term, ...tokens];
   if (candidate.domain === 'doc') {
     const topic = String(candidate._topic ?? candidate.name).toLowerCase();
@@ -538,6 +779,20 @@ export function domainPriority(term, tokens, candidate, hit) {
     if (named.some(n => samePhrase(term, n))) {
       return 2;
     }
+    // A query of two or more words that is one of the doc's own declared
+    // keywords, read as words whatever the plural, is the author naming the
+    // doc for that phrase: `code review` on a guide that declares it. Only
+    // what the author declared counts: the code terms and table cells a
+    // doc's other keywords add (`missing_field`) name what it mentions, not
+    // what it is for. One word is left out too, and a section declares
+    // nothing.
+    if (
+      phraseWords(term).length >= 2 &&
+      candidate._section == null &&
+      (candidate._declared ?? []).some(k => samePhrase(term, String(k)))
+    ) {
+      return 1;
+    }
     if (
       words.some(
         w =>
@@ -568,6 +823,12 @@ export function domainPriority(term, tokens, candidate, hit) {
     return 0;
   }
   if (hit.score >= FULL_COVERAGE_SCORE) return 1;
+  const compound = compoundOf.has(candidate)
+    ? compoundOf.get(candidate)
+    : compoundHit(queryWords, candidate);
+  if ((compound?.score ?? 0) >= STRONG_TOKEN_SCORE) {
+    return 1;
+  }
   const fuzzy = tokens.length <= 1;
   return words.some(
     w =>
@@ -683,14 +944,24 @@ export function titleInQuery(term, titles) {
  * @param {string} term - Lowercased full query.
  * @param {string[]} tokens - Content tokens from tokenizeQuery(term).
  * @param {Candidate} candidate
- * @returns {{score: number, reason: string, matched: number, total: number} | null}
+ * @param {string[]} [words] - The query's words for compound names (see
+ *   compoundHit); empty when the query names an entry outright.
+ * @param {{plain?: boolean}} [opts] - `plain`: score without matches on part
+ *   of a name or a joined keyword.
+ * @returns {{score: number, reason: string, matched: number, total: number, alias?: 'partial' | 'keyword', aliasWords?: number} | null}
  *   `matched`/`total` are the query concepts this candidate answered, out of
  *   the concepts the query had. Callers that must distinguish "matched one word
  *   of three" from "matched all three" — `build`, which gates its pages group
  *   on coverage — cannot recover that from the score, because a single strong
  *   hit and a broad weak one land on the same number.
  */
-export function scoreQuery(term, tokens, candidate) {
+export function scoreQuery(
+  term,
+  tokens,
+  candidate,
+  words = phraseWords(term),
+  {plain = false} = {},
+) {
   const total = Math.max(tokens.length, 1);
   // A whole-phrase hit answered the whole query by definition.
   const asFull = (/** @type {{score: number, reason: string}} */ hit) => ({
@@ -699,14 +970,24 @@ export function scoreQuery(term, tokens, candidate) {
     total,
   });
   // Typo tolerance is for one-word lookups. In a multi-word query a near miss
-  // is usually a different word, not a typo.
-  const fuzzy = tokens.length <= 1;
-  const full = scoreCandidate(term, candidate, {fuzzy});
+  // is usually a different word, not a typo. One typed identifier is one
+  // word, whatever words it spells.
+  const fuzzy = tokens.length <= 1 || !/\s/.test(term);
+  const full = scoreCandidate(term, candidate, {
+    fuzzy,
+    joins: !plain && words.length > 0,
+  });
   // A query of several words keeps its phrase tiers below even when stopwords
   // leave one content word: "make an integration" is still the phrase an
   // author declares as a keyword, and "build an integration" still names a
   // title outright, though each tokenizes to `integration` alone.
-  const phrase = phraseWords(term).length >= 2;
+  const phrase = phraseWords(term).length >= 2 || words.length >= 2;
+  let compound = compoundHit(words, candidate);
+  if (plain) {
+    if (compound?.alias) compound = null;
+  } else {
+    compoundOf.set(candidate, compound);
+  }
 
   /** 0–1 content tokens: whole-phrase fuzzy matching (typo tolerance for
    *  single words), but if stopwords left exactly one DIFFERENT token (e.g.
@@ -731,7 +1012,11 @@ export function scoreQuery(term, tokens, candidate) {
   // of Table-related templates each match "table" and "contents" separately
   // and accumulate a higher raw score (#5239).
   if (full && full.score >= 90) {
-    return asFull({score: full.score + 100, reason: full.reason});
+    return asFull({
+      score: full.score + 100,
+      reason: full.reason,
+      ...(full.alias ? {alias: full.alias, aliasWords: words.length} : {}),
+    });
   }
 
   // The whole query standing as a phrase in a doc's title or one of its
@@ -757,8 +1042,25 @@ export function scoreQuery(term, tokens, candidate) {
   let tokenSum = 0;
   /** @type {string[]} */
   const hitTerms = [];
+  // Adjacent words that join into a name or keyword answer each word they
+  // join, as strongly as the joined word matches (see compoundHit).
+  // Whether a counted word matched only through part of a name or a keyword
+  // read joined, not through the entry's own name or a word of it.
+  /** @type {'partial' | 'keyword' | false} */
+  let alias = false;
+  let aliasWords = 0;
   for (const tok of tokens) {
-    const h = bestForToken(tok, candidate, {fuzzy});
+    let h = bestForToken(tok, candidate, {fuzzy});
+    if (
+      compound?.covered.has(joined(tok)) &&
+      compound.score > (h?.score ?? 0)
+    ) {
+      h = compound;
+      if (compound.alias && compound.score >= MIN_TOKEN_SCORE) {
+        alias = alias === 'partial' ? alias : compound.alias;
+        aliasWords = compound.aliasWords ?? 0;
+      }
+    }
     if (h && h.score >= MIN_TOKEN_SCORE) {
       if (h.score > strongest) strongest = h.score;
       matched++;
@@ -808,6 +1110,7 @@ export function scoreQuery(term, tokens, candidate) {
       reason,
       matched,
       total,
+      ...(alias ? {alias, aliasWords} : {}),
     };
   }
 
@@ -833,7 +1136,13 @@ export function scoreQuery(term, tokens, candidate) {
     strongest + Math.min(matched - 1, 3) * 12 + coverage * 15,
   );
   if (full && full.score >= tokenScore) return asFull(full);
-  return {score: tokenScore, reason, matched, total};
+  return {
+    score: tokenScore,
+    reason,
+    matched,
+    total,
+    ...(alias ? {alias, aliasWords} : {}),
+  };
 }
 
 /**
@@ -852,8 +1161,9 @@ export function scoreQuery(term, tokens, candidate) {
  * @param {string} [candidate.description]
  * @param {string[]} [candidate.prose] - Extra free-text blobs (doc section text, best practices).
  * @param {string[]} [candidate.guidance] - Usage guidance (features, best practices) — scored a tier below description.
- * @param {{fuzzy?: boolean}} [opts] - `fuzzy`: allow edit-distance (typo) matches. Default true; multi-word queries pass false.
- * @returns {{score: number, reason: string} | null}
+ * @param {{fuzzy?: boolean, joins?: boolean}} [opts] - `fuzzy`: allow edit-distance (typo) matches. Default true; multi-word queries pass false. `joins`: read a spaced query joined into a name or keyword (default true); off when the query names an entry outright.
+ * @returns {{score: number, reason: string, alias?: 'partial' | 'keyword'} | null}
+ *   `alias` marks a hit that read the query's words joined.
  */
 export function scoreCandidate(
   term,
@@ -867,18 +1177,23 @@ export function scoreCandidate(
     prose = [],
     guidance = [],
   },
-  {fuzzy = true} = {},
+  {fuzzy = true, joins = true} = {},
 ) {
   let best = 0;
   let reason = '';
+  /** @type {'partial' | 'keyword' | false} */
+  let alias = false;
   /**
    * @param {number} score
    * @param {string} why
+   * @param {'partial' | 'keyword' | false} [byAlias] - the hit reads the
+   *   query's words joined, into part of a name or into a keyword
    */
-  const consider = (score, why) => {
+  const consider = (score, why, byAlias = false) => {
     if (score > best) {
       best = score;
       reason = why;
+      alias = byAlias;
     }
   };
 
@@ -902,6 +1217,16 @@ export function scoreCandidate(
       nameLower === term.replace(/\s+/g, '');
     if (nameLower === term || leafLower === term || spelled) {
       consider(100, 'exact name');
+    } else if (
+      joins &&
+      (domain === 'component' || domain === 'hook') &&
+      /\s/.test(term) &&
+      nameLower.startsWith(term.replace(/\s+/g, '')) &&
+      term.replace(/\s+/g, '').length / nameLower.length >= 0.75
+    ) {
+      // Most of the name typed as words, cut short: `complex select` is
+      // ComplexSelector, ahead of a one-word keyword elsewhere.
+      consider(95, `name "${candidateName}" spelled`, 'partial');
     } else if (pluralOf(nameLower, term) || pluralOf(term, nameLower)) {
       // One point under the exact spelling, so the doc named `tokens` still
       // outranks the Token component for `tokens`.
@@ -925,12 +1250,27 @@ export function scoreCandidate(
   }
 
   // ── Keyword signals ─────────────────────────────────────────────
+  const termJoined = joined(term);
   for (const kw of keywords) {
     const kwLower = String(kw).toLowerCase();
+    // A one-word keyword typed as separate words is the keyword: `number
+    // field` is `numberfield`. Only a
+    // lowercase keyword, one an author declares for a reader to type: a
+    // capitalized one names another entry (a block's `componentsUsed`). A
+    // doc's keywords include code terms, matched as written.
     if (kwLower === term) {
       consider(90, `keyword "${kw}"`);
       continue;
     }
+    if (
+      joins &&
+      domain !== 'doc' &&
+      /\s/.test(term) &&
+      String(kw) === termJoined
+    ) {
+      consider(90, `keyword "${kw}"`, 'keyword');
+      continue;
+    }
     if (sameWord(term, kwLower)) {
       consider(88, `keyword "${kw}"`);
       continue;
@@ -962,9 +1302,12 @@ export function scoreCandidate(
   // Match the term's stem as a whole word, tolerating plural/gerund suffixes
   // so "chart" matches "charts" and "filter" matches "filtering".
   if (term.length >= 3) {
-    const root = stem(term);
-    const escaped = root.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    const re = new RegExp(`\\b${escaped}(s|es|ing|ed|ies)?\\b`);
+    // Any form of the term, with any common suffix: `spacing` finds
+    // "space" and "spaces", `tables` finds "table".
+    const roots = [...new Set([stem(term), ...wordForms(term)])]
+      .filter(f => f.length >= 3)
+      .map(f => f.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+    const re = new RegExp(`\\b(?:${roots.join('|')})(s|es|ing|ed|ies)?\\b`);
     if (description && re.test(description.toLowerCase())) {
       consider(50, `description mentions "${term}"`);
     } else {
@@ -990,7 +1333,7 @@ export function scoreCandidate(
     }
   }
 
-  return best > 0 ? {score: best, reason} : null;
+  return best > 0 ? {score: best, reason, ...(alias ? {alias} : {})} : null;
 }
 
 /**
@@ -1079,7 +1422,11 @@ async function gatherCoreComponents(coreDir) {
     /** @type {string[]} */
     let guidance = [];
     if (readme && readme.endsWith('.doc.mjs')) {
-      const doc = await loadModuleDoc(readme);
+      const loaded = await loadModuleDoc(readme);
+      // A member documented in its family's doc (VStack in Stack's doc) is
+      // indexed from its own entry: the family's keywords and guidance
+      // describe the family, not the member.
+      const doc = familyMember(loaded, comp) ?? loaded;
       if (doc) {
         keywords = Array.isArray(doc.keywords) ? doc.keywords : [];
         description = doc.usage?.description || doc.description || '';
@@ -1105,20 +1452,57 @@ async function gatherCoreComponents(coreDir) {
  * usage/description from each component's .doc.mjs, same as core. Without
  * this, an integration component is invisible to `search`/`build` even
  * though `component --list`/`component <Name>` already resolve it — the two
- * discovery paths silently disagreed.
+ * discovery paths silently disagreed. Also returns, per name, the docs that
+ * hold it by their file name and the loadable docs that only record it.
  * @param {import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]} loadedIntegrations
- * @returns {Promise<Candidate[]>}
+ * @returns {Promise<{candidates: Candidate[], fileNamed: Map<string, Set<string>>, documented: Map<string, Set<string>>}>}
  */
 async function gatherIntegrationComponents(loadedIntegrations) {
   /** @type {Candidate[]} */
   const candidates = [];
+  // What the owner rule reads: the docs that hold a name by their file name,
+  // loadable or not and hidden ones too, and the loadable docs that only
+  // record it.
+  /** @type {Map<string, Set<string>>} */
+  const fileNamed = new Map();
+  /** @type {Map<string, Set<string>>} */
+  const documented = new Map();
+  /** @param {Map<string, Set<string>>} map @param {string} name @param {string} docPath */
+  const hold = (map, name, docPath) =>
+    map.set(name, (map.get(name) ?? new Set()).add(docPath));
   for (const integration of loadedIntegrations) {
-    const {components} = await discoverValidIntegrationComponents(integration);
+    const {components, discovered} =
+      await discoverValidIntegrationComponents(integration);
+    const renamed = new Set(
+      discovered
+        .filter(rec => integrationRecordHold(rec) === 'doc')
+        .filter(rec => !isIntegrationMember(rec))
+        .map(rec => rec.docPath),
+    );
+    forEachIntegrationDoc(integration.components, (docPath, stem) => {
+      if (!renamed.has(docPath)) hold(fileNamed, stem, docPath);
+    });
     for (const rec of components) {
-      const doc = await loadModuleDoc(rec.docPath);
+      const loaded = await loadModuleDoc(rec.docPath);
+      // A family member is indexed from its own entry: the family's keywords
+      // and guidance describe the family.
+      const member = isIntegrationMember(rec);
+      const doc = member ? integrationMemberEntry(loaded, rec) : loaded;
+      // A doc that names another export of its file still answers to the
+      // file's name, as `component <file name>` does.
+      const fileName = docStem(rec.docPath);
+      if (integrationRecordHold(rec) === 'doc') {
+        hold(documented, rec.name, rec.docPath);
+      }
+      if (renamed.has(rec.docPath) && !member) {
+        hold(documented, fileName, rec.docPath);
+      }
       candidates.push({
         domain: 'component',
         name: rec.name,
+        aliases: !member && fileName !== rec.name ? [fileName] : [],
+        _hold: integrationRecordHold(rec),
+        _docPath: rec.docPath,
         keywords: doc && Array.isArray(doc.keywords) ? doc.keywords : [],
         description: doc ? doc.usage?.description || doc.description || '' : '',
         guidance: guidanceFrom(doc),
@@ -1138,12 +1522,12 @@ async function gatherIntegrationComponents(loadedIntegrations) {
             packageName: rec.package,
           },
           rec.name,
-          doc?.import,
+          loaded?.import,
         ),
       });
     }
   }
-  return candidates;
+  return {candidates, fileNamed, documented};
 }
 
 /**
@@ -1155,11 +1539,12 @@ async function gatherIntegrationComponents(loadedIntegrations) {
  */
 async function gatherComponents(coreDir, cwd) {
   const loadedIntegrations = await loadIntegrationsSafely(cwd);
-  const [core, integrations, replacements] = await Promise.all([
+  const [core, gathered, replacements] = await Promise.all([
     gatherCoreComponents(coreDir),
     gatherIntegrationComponents(loadedIntegrations),
     loadComponentReplacements(coreDir, loadedIntegrations),
   ]);
+  const {candidates: integrations, fileNamed, documented} = gathered;
   // An active replacement answers to the Core name it replaces, so a search
   // for that name finds the replacement and not the Core original
   // (spec:AST-035 FR11).
@@ -1170,9 +1555,43 @@ async function gatherComponents(coreDir, cwd) {
       active.target,
     ]),
   );
+  // The owner rule, as component detail applies it: a candidate `component
+  // <name>` does not open names its package and follows the owner, and a
+  // file-name alias that opens another owner is dropped.
+  const coreNames = new Set(core.map(candidate => candidate.name));
+  /** @param {string} name @param {Candidate} candidate */
+  const opens = (name, candidate) =>
+    !coreNames.has(name) &&
+    findComponentReadme(coreDir, name) == null &&
+    [...(fileNamed.get(name) ?? [])].every(doc => doc === candidate._docPath) &&
+    [...(documented.get(name) ?? [])].every(doc => doc === candidate._docPath);
+  // A legacy docs package keeps an exact name over an export name a doc records.
+  /** @type {ReturnType<typeof discoverExternalPackages> | undefined} */
+  let externals;
+  /** @param {string} name */
+  const legacyDocuments = name =>
+    (externals ??= discoverExternalPackages(cwd)).some(
+      ext => resolveLegacyExternalDoc(ext, name) != null,
+    );
+  const ruled = integrations.map(candidate => {
+    const aliases = (candidate.aliases ?? []).filter(alias =>
+      opens(alias, candidate),
+    );
+    return candidate._hold === 'doc' &&
+      (!opens(candidate.name, candidate) || legacyDocuments(candidate.name))
+      ? {
+          ...candidate,
+          aliases,
+          _command: `astryx component ${candidate.name} --package ${candidate._package}`,
+        }
+      : {...candidate, aliases};
+  });
   return [
     ...core.filter(candidate => !replacements.forTarget(candidate.name)),
-    ...integrations.map(candidate => {
+    ...[
+      ...ruled.filter(candidate => !candidate._command),
+      ...ruled.filter(candidate => candidate._command),
+    ].map(candidate => {
       const target = targetOf.get(`${candidate._package}\0${candidate.name}`);
       if (target != null) {
         return {...candidate, aliases: [...(candidate.aliases ?? []), target]};
@@ -1225,11 +1644,11 @@ export async function componentKeywords(coreDir, cwd) {
     .flat()
     .map(async name => {
       const readme = findComponentReadme(coreDir, name);
-      const doc =
+      const loaded =
         readme && readme.endsWith('.doc.mjs')
           ? await loadModuleDoc(readme)
           : null;
-      return {name, keywords: keywordsOf(doc)};
+      return {name, keywords: keywordsOf(familyMember(loaded, name) ?? loaded)};
     });
   const loadedIntegrations = await loadIntegrationsSafely(cwd);
   const replacements = await loadComponentReplacements(
@@ -1239,10 +1658,13 @@ export async function componentKeywords(coreDir, cwd) {
   const integrations = loadedIntegrations.map(async integration => {
     const {components} = await discoverValidIntegrationComponents(integration);
     return Promise.all(
-      components.map(async rec => ({
-        name: rec.name,
-        keywords: keywordsOf(await loadModuleDoc(rec.docPath)),
-      })),
+      components.map(async rec => {
+        const loaded = await loadModuleDoc(rec.docPath);
+        return {
+          name: rec.name,
+          keywords: keywordsOf(integrationMemberEntry(loaded, rec) ?? loaded),
+        };
+      }),
     );
   });
   return [
@@ -1416,6 +1838,10 @@ async function gatherDocs(cwd) {
         ...defined,
         ...codeTerms({content}),
       ],
+      _declared: [
+        ...(Array.isArray(selfDoc?.keywords) ? selfDoc.keywords : []),
+        ...(Array.isArray(node.keywords) ? node.keywords : []),
+      ],
       description: node.summary || '',
       prose: sectionProse({title: node.title, content}),
       titles: [node.title],
@@ -1552,6 +1978,7 @@ function topicCandidates(
         ...(doc?.title || title ? [doc?.title || title] : []),
         ...(Array.isArray(doc?.keywords) ? doc.keywords : []),
       ],
+      _declared: Array.isArray(doc?.keywords) ? doc.keywords : [],
       description: doc?.description || summary,
       prose: split
         ? sections.map(section => section.title).filter(Boolean)
@@ -1700,8 +2127,11 @@ async function gatherThemes(cwd) {
  * @param {string} reason
  * @param {number} matchedTerms - Query concepts this result answered.
  * @param {number} queryTerms - Query concepts there were to answer.
+ * @param {boolean} [outside] - The search runs outside a project, where a
+ *   theme cannot be added to an app, so its command forks the source instead
+ *   (spec AST-081 FR3).
  */
-function toResult(c, score, reason, matchedTerms, queryTerms) {
+function toResult(c, score, reason, matchedTerms, queryTerms, outside = false) {
   const base = {
     domain: c.domain,
     name: c._resultName ?? c.name,
@@ -1750,7 +2180,9 @@ function toResult(c, score, reason, matchedTerms, queryTerms) {
       result = {
         ...base,
         displayName: c._displayName,
-        command: `astryx theme add ${c.name}`,
+        command: outside
+          ? `astryx theme eject ${c.name}`
+          : `astryx theme add ${c.name}`,
       };
       break;
     default:
@@ -1811,21 +2243,29 @@ async function searchOnce(query, options) {
   }
 
   const term = String(query).trim().toLowerCase();
-  const tokens = tokenizeQuery(term);
-
   // `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.
   const needsCore = !type || !CORELESS_DOMAINS.includes(type);
-  const coreDir = needsCore ? findCoreDir(cwd) : null;
-  if (type && needsCore && !coreDir) {
-    throw new AstryxError(
-      'Could not find @astryxdesign/core package',
-      undefined,
-      ERROR_CODES.ERR_CORE_NOT_FOUND,
-    );
+  // 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;
+  if (needsCore && type) {
+    coreDir = coreDirOrThrow(requireSearchCoreDir, cwd);
+  } else if (needsCore) {
+    try {
+      coreDir = requireSearchCoreDir(cwd);
+    } catch (error) {
+      coreSkipped = /** @type {Error} */ (error).message;
+    }
   }
 
   // Gather candidates from each requested domain in parallel.
@@ -1844,14 +2284,101 @@ async function searchOnce(query, options) {
 
   const all = [...components, ...hooks, ...docTopics, ...templates, ...themes];
 
+  // A query that is one identifier counts as the words it spells
+  // (`SidebarToggle`), and still matches whole as typed. In a query of several
+  // words, each identifier stays one term (`ChatComposer ChatLayout` names two
+  // components), and its words still join into names (see compoundHit). Both
+  // only help a query that names no entry outright: when the query is an
+  // entry's name, typed whole or as its words, that entry answers it, and
+  // neither reading may add near siblings beside it.
+  const spelled = spellIdentifiers(String(query).trim());
+  const exact = all.some(candidate =>
+    [candidate.name, ...(candidate.aliases ?? [])].some(name => {
+      const lower = String(name).toLowerCase();
+      return (
+        lower === term ||
+        (candidate.domain !== 'doc' &&
+          !/[\s_-]/.test(lower) &&
+          lower === term.replace(/\s+/g, ''))
+      );
+    }),
+  );
+  // One identifier is read as its words only when, read whole, it matches
+  // nothing: a prop or hook name a doc already mentions keeps the
+  // entries that mention it.
+  const split =
+    !exact &&
+    !/\s/.test(term) &&
+    spelled !== term &&
+    !all.some(candidate => scoreCandidate(term, candidate));
+  const tokens = tokenizeQuery(split ? spelled : term);
+  /** @type {string[]} */
+  const words = exact
+    ? []
+    : phraseWords(split || /\s/.test(term) ? spelled : term);
+  // The entries the query names: a component, hook, or template whose whole
+  // name is adjacent query words joined (`icon button in a card header` names
+  // IconButton), or one identifier typed as such. A name inside a longer named
+  // run does not count (`icon` there is part of IconButton).
+  const queryWords = phraseWords(spelled);
+  const typedIdentifiers = new Set(
+    (String(query).match(/[A-Za-z0-9]+/g) ?? [])
+      .filter(w => /[A-Z]/.test(w))
+      .map(w => w.toLowerCase()),
+  );
+  /** @type {Map<string, [number, number]>} each run joined, longest first */
+  const spans = new Map();
+  for (let len = Math.min(queryWords.length, MAX_RUN_WORDS); len >= 1; len--) {
+    for (let a = 0; a + len <= queryWords.length; a++) {
+      // One plain word names too much (`list`, `field`); a named entry is a
+      // run of joined words, or an identifier typed as one.
+      if (len === 1 && !typedIdentifiers.has(queryWords[a])) continue;
+      const run = queryWords.slice(a, a + len).join('');
+      if (!spans.has(run)) spans.set(run, [a, a + len]);
+    }
+  }
+  /**
+   * Where a query word is the candidate's whole name, or null: such an entry
+   * keeps the rank its name earns, whatever else it matched.
+   * @param {Candidate} candidate
+   * @returns {[number, number] | null}
+   */
+  const wordNamed = candidate => {
+    if (candidate.domain === 'doc') return null;
+    for (const name of [candidate.name, ...(candidate.aliases ?? [])]) {
+      const n = joined(name);
+      const at = queryWords.findIndex(w => w === n || w === `${n}s`);
+      if (at >= 0) return [at, at + 1];
+    }
+    return null;
+  };
+  /** @param {Candidate} candidate @returns {[number, number] | null} */
+  const namedSpan = candidate => {
+    if (candidate.domain === 'doc') return null;
+    /** @type {[number, number] | null} */
+    let best = null;
+    for (const name of [candidate.name, ...(candidate.aliases ?? [])]) {
+      const n = joined(name);
+      const span =
+        spans.get(n) ??
+        spans.get(`${n}s`) ??
+        (/(?:s|x|z|ch|sh)$/.test(n) ? spans.get(`${n}es`) : undefined);
+      if (span && (!best || span[1] - span[0] > best[1] - best[0])) {
+        best = span;
+      }
+    }
+    return best;
+  };
+
   // Score every candidate on its own merits. The consumer groups results by
   // role (page / block / component) and takes the top of each, so there's no
   // cross-role competition to engineer — a target page only needs to be the
   // strongest PAGE, not outrank every component.
-  /** @type {{result: any, priority: 0 | 1 | 2}[]} */
+  /** @type {{result: any, priority: 0 | 1 | 2, key: number, alias: 'partial' | 'keyword' | false, aliasWords: number, candidate: Candidate, span: [number, number] | null, word: [number, number] | null}[]} */
   const ranked = [];
+  const outside = themes.length > 0 && isOutsideProject(cwd);
   for (const candidate of all) {
-    const hit = scoreQuery(term, tokens, candidate);
+    const hit = scoreQuery(term, tokens, candidate, words);
     if (hit)
       ranked.push({
         result: toResult(
@@ -1860,10 +2387,56 @@ async function searchOnce(query, options) {
           hit.reason,
           hit.matched,
           hit.total,
+          outside,
         ),
-        priority: domainPriority(term, tokens, candidate, hit),
+        priority: domainPriority(term, tokens, candidate, hit, words),
+        key: hit.score,
+        alias: hit.alias ?? false,
+        aliasWords: hit.aliasWords ?? 0,
+        candidate,
+        span: namedSpan(candidate),
+        word: wordNamed(candidate),
       });
   }
+  // A match on a keyword read joined never outranks an entry the query names,
+  // and neither does a match on part of another name unless it spans more
+  // query words than any named run: `table header with sticky columns` keeps
+  // TableHeader above useTableStickyColumns, which only holds the words
+  // `sticky columns`. Only the order changes; each result keeps the score its
+  // text earned.
+  /** @param {[number, number]} inner @param {[number, number]} outer */
+  const inside = (inner, outer) =>
+    outer[0] <= inner[0] &&
+    outer[1] >= inner[1] &&
+    outer[1] - outer[0] > inner[1] - inner[0];
+  const named = ranked.filter(r => {
+    const span = r.span;
+    return (
+      span != null &&
+      !ranked.some(o => o !== r && o.span != null && inside(span, o.span))
+    );
+  });
+  /** @param {{key: number}[]} rows */
+  const floorOf = rows =>
+    rows.length ? Math.min(...rows.map(r => r.key)) : Infinity;
+  const namedFloor = floorOf(named);
+  const longestNamed = Math.max(
+    0,
+    ...named.map(r => (r.span ? r.span[1] - r.span[0] : 0)),
+  );
+  for (const r of ranked) {
+    if (named.includes(r)) continue;
+    if (!r.alias || r.word) continue;
+    // A match on part of a longer name that spans more words than any named
+    // run reads more of the query than the named entry does (`dropdown menu
+    // radio` and DropdownMenuRadioItem, against DropdownMenu), so it is not
+    // held back. A joined keyword always is.
+    if (r.alias === 'partial' && r.aliasWords > longestNamed) continue;
+    // It keeps what it earns without those matches.
+    const own =
+      scoreQuery(term, tokens, r.candidate, words, {plain: true})?.score ?? 0;
+    r.key = Math.max(own, Math.min(r.key, namedFloor - 0.5));
+  }
 
   // Docs and everything else are each sorted by score desc, then domain
   // (stable order), then name. The two are merged: at each step the stronger
@@ -1872,11 +2445,11 @@ async function searchOnce(query, options) {
   /** @type {Record<string, number>} */
   const domainOrder = {component: 0, hook: 1, doc: 2, template: 3, theme: 4};
   /**
-   * @param {{result: any}} x
-   * @param {{result: any}} y
+   * @param {{result: any, key: number}} x
+   * @param {{result: any, key: number}} y
    */
-  const byScore = ({result: a}, {result: b}) =>
-    b.score - a.score ||
+  const byScore = ({result: a, key: ka}, {result: b, key: kb}) =>
+    kb - ka ||
     (domainOrder[a.domain] ?? 9) - (domainOrder[b.domain] ?? 9) ||
     a.name.localeCompare(b.name);
   const others = ranked.filter(r => r.result.domain !== 'doc').sort(byScore);
@@ -1923,11 +2496,19 @@ async function searchOnce(query, options) {
       ),
     },
   };
+  if (coreSkipped) {
+    response.meta = {
+      partial: {
+        skipped: ['component', 'hook', 'template'],
+        reason: coreSkipped,
+      },
+    };
+  }
   if (wants('component')) {
     searchedComponentsOf.set(
       response,
       components.map(c => ({name: c.name, keywords: c.keywords ?? []})),
     );
   }
-  return response;
+  return linkSearchResponse(response, cwd);
 }