@appinternalleads/ui 0.3.0 → 0.4.1

package/src/agent/core.ts

@@ -1,16 +1,8 @@
 /**
- * **The agent component contract, without React** — `@appinternalleads/ui/agent`. Search, describe,
- * `render/1` validation and `result/1`: what a backend or an MCP server needs, and all of it runs in
- * plain Node. The renderer, `AgentComponent`, is in the main entry. `docs/AGENT-COMPONENT-CONTRACT.md`.
+ * **`@appinternalleads/ui/agent` — the agent contract, with search, without React.** Search,
+ * describe, `render/1` validation and `result/1`: what a backend or an MCP server needs, all of it in
+ * plain Node. `searchComponents` lives only here (and its word-vector table with it); the renderer,
+ * `AgentComponent`, is in the main entry. `docs/AGENT-COMPONENT-CONTRACT.md`.
  */
-export {
-  AGENT_COMPONENTS, agentAvailability, describeComponent, isAgentComponent, listAgentComponents, searchComponents,
-} from './catalog';
-export { validateRenderRequest } from './validate';
-export { RESULT_EVENTS, makeResult } from './result';
-export {
-  CAPABILITY_SCHEMA, RENDER_SCHEMA, RESULT_SCHEMA,
-  type AgentButtonAction, type AgentCapability, type CapabilityAction, type CapabilityCard, type CapabilityEvent, type CapabilityKind,
-  type CopySpec as AgentCopySpec, type DataOrigin, type FieldSpec as AgentFieldSpec, type IssueCode, type IssueLayer, type Owner as AgentOwner,
-  type RenderCheck, type RenderIssue, type RenderPreview, type RenderRequest, type RenderResult, type Section as AgentSection,
-} from './types';
+export * from './base';
+export { searchComponents } from './search';

package/src/agent/index.ts

@@ -1,9 +1,10 @@
 /**
- * **The agent component contract** — `docs/AGENT-COMPONENT-CONTRACT.md`.
+ * **The agent contract, as the main entry carries it** — for the app that renders: `AgentComponent`,
+ * `AGENT_RENDERABLE`, and the small React-free contract they use (describe, validate, results).
  *
- * search → describe → build a `render/1` → `validateRenderRequest` → `<AgentComponent>` → `result/1`.
- * Everything but `AgentComponent` is pure and serialisable, and is also its own entry point —
- * `@appinternalleads/ui/agent` (`./core`) — so a server or an MCP tool can use it without React.
+ * Not `searchComponents`: component search belongs to the agent, and its word-vector table must not
+ * reach an app's bundle. Import it from `@appinternalleads/ui/agent`. `tests/agent/boundary.test.ts`
+ * holds this line on the built package.
  */
-export * from './core';
+export * from './base';
 export { AgentComponent, AGENT_RENDERABLE, type AgentComponentProps } from './AgentComponent';

package/src/agent/manifests.ts

@@ -5,6 +5,8 @@ import { FIELD_KEY, RECEIPT_MAX_AMOUNT, RECEIPT_MAX_FIELDS, RECEIPT_MAX_ITEMS, R
 import { HEATMAP_REVEALS } from '../components/onboarding/activity-heatmap/contract';
 import { FEED_BLOCK_KINDS } from '../components/onboarding/expandable-feed/contract';
 import { MAX_SLIDES } from '../components/onboarding/carousel/contract';
+import { SEND_COMPLETION_ICONS, SEND_COMPLETION_LIMITS } from '../components/onboarding/send-completion/contract';
+import { COLOR_FORMATS, COLOR_HINT, COLOR_PATTERN } from '../components/onboarding/shared/configColor';
 import { bool, json, list, map, num, obj, text } from './spec';
 import type { AgentCapability, CapabilityAction, CapabilityCard, CapabilityEvent, CopySpec, FieldSpec } from './types';
 
@@ -531,4 +533,84 @@ const completion: NewManifest = {
   system: ['partialStats', 'successStats', 'partialItems', 'successItems', 'demoSkipped', 'ship'],
 };
 
-export const NEW_MANIFESTS: readonly NewManifest[] = [receiptPrinter, budgetTracker, activityHeatmap, criteriaSpider, expandableFeed, fallback, seatAllocation, carousel, completion];
+const colour = (c: OnboardingComponent, key: string, what: string) =>
+  text(`${what} A colour: ${COLOR_FORMATS}.`, {
+    format: 'color', pattern: COLOR_PATTERN.source, patternHint: COLOR_HINT, default: base(c)[key], owners: ['agent', 'builder', 'developer'],
+  });
+const sendCompletion: NewManifest = {
+  family: 'new',
+  component: 'send-completion',
+  name: 'Send Completion',
+  kind: 'interactive',
+  purpose: 'A single send button that shows the send happening: pressed, its icon launches, the button becomes a check, and a pill confirms ("Sent!") — once the host\'s send has really succeeded.',
+  signals: ['send button', 'sent', 'submit', 'submitted', 'send button', 'confirm', 'upload', 'save', 'message sent', 'done button', 'send animation', 'success animation'],
+  useWhen: [
+    'One action the person triggers — send, submit, upload, confirm, save — whose success should be shown as it happens.',
+    'The host can run the action (the send operation) and say whether it succeeded.',
+  ],
+  avoidWhen: [
+    'A form with fields to fill — this is the one button, not the form.',
+    'Making a receipt, invoice or document to send someone — that is the document\'s own component; this is only the button that sends.',
+    'Several steps or a summary of what was set up — use completion.',
+    'Progress over time (percent, many items) — the circle only waits, it does not count.',
+  ],
+  related: [
+    { component: 'completion', distinction: 'Completion summarises a finished flow; Send Completion is the one press that finishes it.' },
+  ],
+  states: [
+    { state: 'idle', description: 'The button, ready; the tap cue shows first when behavior.showTapCue.' },
+    { state: 'sending', description: 'Pressed: the host\'s send runs while the icon flies; the circle waits (breathing) for it.' },
+    { state: 'sent', description: 'The send succeeded: the check and the completed label. This is the task\'s result, not just the animation\'s end.' },
+    { state: 'failed', description: 'The send failed: the button returns and an alert says why; pressing again retries.' },
+    ...LOAD_STATES,
+  ],
+  actions: [
+    { id: 'send', description: 'The person presses the button (or Enter / Space on it). Runs the host\'s send operation.', hostOperation: true },
+    { id: 'reset', description: 'Brings the button back, after sent or failed.' },
+  ],
+  events: [
+    { event: 'sendStarted', description: 'The person pressed the button; the send is running.', data: '{}' },
+    { event: 'sent', description: 'The send succeeded and "Sent!" is showing.', data: '{}' },
+    { event: 'reset', description: 'The person pressed Reset.', data: '{}' },
+    { event: 'statusChanged', description: 'Playback moved on.', data: '{ status: "idle" | "pressed" | "launching" | "transforming" | "sent" }' },
+  ],
+  requiresInput: false,
+  rules: [
+    'data.label is what the button does (Send, Submit, Upload…); data.completedLabel what it says when done (Sent!, Submitted!…). Each at most 3 words and 16 characters: longer text shrinks inside the fixed button.',
+    'The motion, its timing and the layout are fixed: there are no keys for them.',
+    '"sent" is reported only after the host\'s send operation succeeds; a failure never shows the check.',
+    'behavior.loop is decorative: it replays forever and never calls the host\'s send.',
+  ],
+  askFor: {
+    label: 'What does the button do — Send, Submit, Upload, Save?',
+  },
+  data: {
+    label: text('What the button says: the action (Send, Submit, Upload, Confirm, Save…).', { required: true, maxLength: SEND_COMPLETION_LIMITS.label.chars, origin: 'invent' }),
+    completedLabel: text('What the pill says once it is done (Sent!, Submitted!, Uploaded…).', { required: true, maxLength: SEND_COMPLETION_LIMITS.completedLabel.chars, origin: 'invent' }),
+  },
+  behavior: {
+    showTapCue: bool('Show "TAP/CLICK" and a fingertip before the press.', { default: base('send-completion').showTapCue, owners: ['agent', 'builder', 'developer'] }),
+    autoplay: bool('Press on its own as soon as it shows (and run the send).', { default: false, owners: ['agent', 'builder', 'developer'] }),
+    loop: bool('Replay forever as a decoration; the host\'s send is never called.', { default: false, owners: ['agent', 'builder', 'developer'] }),
+  },
+  presentation: {
+    ...presentation('send-completion'),
+    backgroundColor: colour('send-completion', 'backgroundColor', 'Behind everything.'),
+    buttonColor: colour('send-completion', 'buttonColor', 'The button, the circle and the pill.'),
+    textColor: colour('send-completion', 'textColor', 'The button\'s label.'),
+    iconColor: colour('send-completion', 'iconColor', 'The icon while it sits in the button.'),
+    completionColor: colour('send-completion', 'completionColor', 'The check and the completed label.'),
+    trailColor: colour('send-completion', 'trailColor', 'The icon in flight, its trail and the tap cue.'),
+    sendIcon: text('The icon the button carries and launches.', { enum: SEND_COMPLETION_ICONS, default: base('send-completion').sendIcon, owners: ['agent', 'builder', 'developer'] }),
+    iconScale: num('The icon\'s size (1 is the design\'s).', { min: SEND_COMPLETION_LIMITS.iconScale[0], max: SEND_COMPLETION_LIMITS.iconScale[1], default: 1, owners: ['agent', 'builder', 'developer'] }),
+    cornerRadius: num('The button\'s corner radius, in points.', { min: SEND_COMPLETION_LIMITS.cornerRadius[0], max: SEND_COMPLETION_LIMITS.cornerRadius[1], default: base('send-completion').cornerRadius, owners: ['agent', 'builder', 'developer'] }),
+    width: num('The animation\'s widest, in points; it keeps 4:3 and shrinks with its container.', { min: SEND_COMPLETION_LIMITS.width[0], max: SEND_COMPLETION_LIMITS.width[1], default: base('send-completion').width, owners: ['agent', 'builder', 'developer'] }),
+  },
+  system: ['ship'],
+  copyExtra: {
+    ...HEADER,
+    tapHint: { maxLength: SEND_COMPLETION_LIMITS.tapHint.chars },
+  },
+};
+
+export const NEW_MANIFESTS: readonly NewManifest[] = [receiptPrinter, budgetTracker, activityHeatmap, criteriaSpider, expandableFeed, fallback, seatAllocation, carousel, completion, sendCompletion];

package/src/agent/result.ts

@@ -40,6 +40,12 @@ export const RESULT_EVENTS: Record<string, Record<string, [string, Mapper]>> = {
     onContinue: ['continued', (() => ({})) as Mapper],
     onFinishLater: ['finishLater', (() => ({})) as Mapper],
   },
+  'send-completion': {
+    onSend: ['sendStarted', (() => ({})) as Mapper],
+    onSent: ['sent', (() => ({})) as Mapper],
+    onReset: ['reset', (() => ({})) as Mapper],
+    onStatusChange: ['statusChanged', ((status: string) => ({ status })) as Mapper],
+  },
   directory: { onSelect: ['selected', ((id: string) => ({ id })) as Mapper] },
   checklist: { onChange: ['changed', ((checklist: unknown, change: unknown) => ({ checklist, change })) as Mapper] },
   'threshold-flow': {

package/src/agent/search/document.ts

@@ -0,0 +1,46 @@
+import type { AgentCapability, FieldSpec } from '../types';
+import type { FieldType, SearchDocument } from './types';
+
+/**
+ * **A component's search document, derived from its capability.** It says what problem the
+ * component solves — purpose, when to use it, its selection signals, its case studies' scenarios,
+ * what a person can do with it, what it shows and what it reports — and, separately, what it is not
+ * for (`avoidWhen`). Nothing is written for search alone, so a new approved component is searchable
+ * the moment it has a capability. No source, no implementation, no runtime values.
+ */
+
+/** "…statement over time — use budget-tracker or a list." → "…statement over time": the pointer to another component is advice, not meaning. */
+function ownMeaning(text: string, ids: readonly string[]): string {
+  let t = text.replace(/\s[—–-]+\s*use\s.*$/i, '').replace(/:\s*use\s.*$/i, '');
+  for (const id of ids) t = t.split(id).join(' ');
+  return t.replace(/\s+/g, ' ').trim();
+}
+
+const describeData = (key: string, spec: FieldSpec): string => {
+  const words = key.replace(/([a-z])([A-Z])/g, '$1 $2').toLowerCase();
+  return `${words}: ${spec.description}`;
+};
+
+export function searchDocumentOf(c: AgentCapability, order: number, allIds: readonly string[]): SearchDocument {
+  const positive: { type: FieldType; text: string }[] = [];
+  const add = (type: FieldType, text: string | undefined) => { const t = text && ownMeaning(text, allIds); if (t) positive.push({ type, text: t }); };
+  add('name', c.name);
+  add('purpose', c.purpose);
+  c.signals.forEach(s => add('signal', s));
+  c.useWhen.forEach(s => add('useWhen', s));
+  c.presets.forEach(p => add('scenario', `${p.title}. ${p.scenario}`));
+  c.actions.forEach(a => add('action', a.description));
+  c.states.forEach(s => add('state', s.description));
+  c.events.forEach(e => add('event', e.description));
+  for (const [k, spec] of Object.entries(c.data)) add('data', describeData(k, spec));
+  const negative = c.avoidWhen.map(t => ownMeaning(t, allIds)).filter(Boolean).map(text => ({ text }));
+  return { component: c.component, order, positive, negative };
+}
+
+/** FNV-1a over the documents: the catalogue's search version. Any change to what search reads changes it. */
+export function versionOf(value: unknown): string {
+  const s = JSON.stringify(value);
+  let h = 0x811c9dc5;
+  for (let i = 0; i < s.length; i++) { h ^= s.charCodeAt(i); h = Math.imul(h, 0x01000193); }
+  return (h >>> 0).toString(16).padStart(8, '0');
+}

package/src/agent/search/embedding.ts

@@ -0,0 +1,95 @@
+import type { EmbeddingProvider } from './types';
+
+/**
+ * **Embedding providers.** The search asks a provider for vectors and nothing else, so the one
+ * below — pretrained word vectors shipped in the package, no network — can be replaced by a hosted
+ * model without touching retrieval or ranking.
+ */
+
+/** `bits`: 8 — int8 per value; 4 — two values per byte, each stored as value + 8 (−7…7). */
+export type WordVectorTable = { dims: number; count: number; words: string; data: string; bits?: 4 | 8 };
+
+const bytesOf = (b64: string): Uint8Array => {
+  if (typeof Buffer !== 'undefined') { const b = Buffer.from(b64, 'base64'); return new Uint8Array(b.buffer, b.byteOffset, b.length); }
+  const bin = atob(b64); const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+};
+/* One signed value per entry, whatever the storage. Only directions matter (vectors are averaged and normalised), so no rescaling. */
+function decode(t: WordVectorTable): Int8Array {
+  const bytes = bytesOf(t.data);
+  if (t.bits !== 4) return new Int8Array(bytes.buffer, bytes.byteOffset, bytes.length);
+  const out = new Int8Array(t.count * t.dims);
+  for (let i = 0; i < out.length; i++) out[i] = ((bytes[i >> 1]! >> ((i & 1) * 4)) & 15) - 8;
+  return out;
+}
+
+const unit = (v: Float32Array): Float32Array => {
+  let n = 0; for (const x of v) n += x * x;
+  n = Math.sqrt(n);
+  if (n > 0) for (let i = 0; i < v.length; i++) v[i]! /= n;
+  return v;
+};
+
+/**
+ * **Word vectors, averaged — offline and deterministic.** A text's vector is the average of its
+ * words' vectors, each weighted by how rare the word is (Arora et al.'s smooth inverse frequency,
+ * with the table's frequency order standing in for counts), so "the" counts for almost nothing and
+ * "receipt" for a lot. A word the table lacks is tried without a plural or tense ending; failing
+ * that it is skipped (lexical matching still sees it).
+ */
+export function createWordVectorProvider(table: WordVectorTable, opts: { smoothing?: number } = {}): EmbeddingProvider {
+  let index: Map<string, number> | null = null;
+  let data: Int8Array | null = null;
+  const a = opts.smoothing ?? 1e-3;
+  /* Zipf: a word's share of text ∝ 1 / rank. H is the normaliser for the table's size. */
+  const H = Math.log(table.count) + 0.5772;
+  const load = () => {
+    if (index) return;
+    index = new Map(table.words.split(' ').map((w, i) => [w, i]));
+    data = decode(table);
+  };
+  const lookup = (w: string): number | undefined => {
+    const m = index!;
+    return m.get(w) ?? m.get(w.replace(/'s$/, '')) ?? m.get(w.replace(/ies$/, 'y')) ?? m.get(w.replace(/s$/, ''))
+      ?? m.get(w.replace(/ing$/, '')) ?? m.get(w.replace(/ing$/, 'e')) ?? m.get(w.replace(/ed$/, '')) ?? m.get(w.replace(/d$/, ''));
+  };
+  return {
+    id: `word-vectors:${table.dims}x${table.count}x${table.bits ?? 8}bit:sif-${a}`,
+    embed(texts) {
+      load();
+      return texts.map(text => {
+        const v = new Float32Array(table.dims);
+        for (const raw of text.toLowerCase().split(/[^\p{L}']+/u)) {
+          if (!raw) continue;
+          const r = lookup(raw);
+          if (r === undefined) continue;
+          const p = 1 / ((r + 1) * H);
+          const w = a / (a + p);
+          const off = r * table.dims;
+          for (let d = 0; d < table.dims; d++) v[d]! += w * data![off + d]!;
+        }
+        return unit(v);
+      });
+    },
+  };
+}
+
+/**
+ * **For tests: deterministic vectors, no model.** Each word hashes to a few dimensions, so equal words
+ * give equal vectors and different words mostly do not. It proves the machinery — indexing, ranking,
+ * filtering, fallback — not semantic quality.
+ */
+export function createFakeEmbeddingProvider(dims = 64): EmbeddingProvider {
+  const hash = (s: string, seed: number) => { let h = 0x811c9dc5 ^ seed; for (let i = 0; i < s.length; i++) { h ^= s.charCodeAt(i); h = Math.imul(h, 0x01000193); } return h >>> 0; };
+  return {
+    id: `fake:${dims}`,
+    embed(texts) {
+      return texts.map(t => {
+        const v = new Float32Array(dims);
+        for (const w of t.toLowerCase().split(/[^\p{L}\p{N}]+/u)) if (w) for (let s = 0; s < 3; s++) v[hash(w, s) % dims]! += (hash(w, s + 7) & 1) ? 1 : -1;
+        return unit(v);
+      });
+    },
+  };
+}

package/src/agent/search/index.ts

@@ -0,0 +1,20 @@
+import { createWordVectorProvider, type WordVectorTable } from './embedding';
+import { createComponentSearch, type SearchCard } from './search';
+import type { SearchOptions } from './types';
+import { DEFAULT_WEIGHTS } from './weights';
+import table from './wordvectors.json';
+
+/**
+ * **`searchComponents` — the package's one search.** The MCP tool and the site's API call this; the
+ * hybrid engine behind it (`search.ts`) uses the offline word-vector provider shipped with the
+ * package, so it needs no network and gives the same answer every time.
+ */
+const engine = createComponentSearch({ provider: createWordVectorProvider(table as WordVectorTable), weights: DEFAULT_WEIGHTS });
+
+/** Intent → candidate cards, best first. `options.available` is the host's policy: only those components may be offered. */
+export function searchComponents(query: string, limit = 5, options?: SearchOptions): SearchCard[] {
+  return engine.search(query, limit, options);
+}
+
+/** Development only: why each component scored what it did. Not part of the agent's result. */
+export const explainSearch = (query: string, options?: SearchOptions) => engine.explain(query, options);

package/src/agent/search/lexical.ts

@@ -0,0 +1,25 @@
+import type { AgentCapability } from '../types';
+
+/**
+ * **Lexical scoring — the search as it shipped in 0.3.0, unchanged.** Whole selection-signal phrases
+ * in the request count most, then shared words with the signals, the name and purpose, then when to
+ * use it. It is one input to the hybrid ranking, and on its own it is the fallback whenever semantic
+ * retrieval is unavailable.
+ */
+const STOP = new Set('a an the of for to and or in on at by with my me i we our you your it is are be this that these those can could would should please make create show give get want need some any what how which who when from as into about'.split(' '));
+const stem = (w: string) => w.replace(/(ies)$/, 'y').replace(/(ing|ed|es|s)$/, '');
+const words = (s: string) => s.toLowerCase().replace(/[^\p{L}\p{N}\s'-]/gu, ' ').split(/[\s'-]+/).filter(w => w.length > 1 && !STOP.has(w)).map(stem);
+
+export function lexicalScore(c: AgentCapability, query: string): number {
+  const q = ` ${query.toLowerCase().replace(/[^\p{L}\p{N}\s]/gu, ' ').replace(/\s+/g, ' ')} `;
+  const qw = new Set(words(query));
+  let score = 0;
+  for (const s of c.signals) {
+    const phrase = ` ${s.toLowerCase().replace(/[^\p{L}\p{N}\s]/gu, ' ').replace(/\s+/g, ' ')} `;
+    if (q.includes(phrase)) score += 6 + 2 * (phrase.trim().split(' ').length - 1);
+    else score += words(s).filter(w => qw.has(w)).length * 2;
+  }
+  score += words(`${c.name} ${c.purpose}`).filter(w => qw.has(w)).length;
+  score += new Set(words(c.useWhen.join(' ')).filter(w => qw.has(w))).size * 0.5;
+  return score;
+}

package/src/agent/search/normalize.ts

@@ -0,0 +1,17 @@
+/**
+ * **Query normalisation** — whitespace, case, obvious punctuation and repeated words. Nothing that
+ * changes meaning: no synonyms, no spelling rewrites. The original stays available for lexical
+ * phrase matching and for debugging.
+ */
+export type NormalizedQuery = { original: string; text: string; tokens: string[]; empty: boolean };
+
+export function normalizeQuery(query: unknown): NormalizedQuery {
+  const original = typeof query === 'string' ? query : '';
+  const text = original.toLowerCase().normalize('NFKC').replace(/[^\p{L}\p{N}\s'-]/gu, ' ').replace(/\s+/g, ' ').trim();
+  const tokens: string[] = [];
+  for (const t of text.split(/[\s-]+/)) {
+    const w = t.replace(/^'+|'+$/g, '');
+    if (w && tokens[tokens.length - 1] !== w) tokens.push(w);
+  }
+  return { original, text: tokens.join(' '), tokens, empty: tokens.length === 0 };
+}

package/src/agent/search/search.ts

@@ -0,0 +1,148 @@
+import { AGENT_COMPONENTS, describeComponent, isAgentComponent } from '../catalog';
+import type { AgentCapability, CapabilityCard } from '../types';
+import { searchDocumentOf } from './document';
+import { SearchIndex, cosine, indexVersion, type Centring, type IndexedDocument } from './searchIndex';
+import { lexicalScore } from './lexical';
+import { normalizeQuery, type NormalizedQuery } from './normalize';
+import type { EmbeddingProvider, ScoreBreakdown, SearchDocument, SearchOptions, SearchWeights } from './types';
+
+/**
+ * **Component search: intent → candidates.**
+ *
+ *   normalizeQuery → retrieveCandidates (semantic + lexical) → applyEligibility → rankCandidates → cards
+ *
+ * Semantic similarity comes from an `EmbeddingProvider` over each component's search document
+ * (`document.ts`, derived from its capability); lexical similarity is 0.3.0's scorer. If semantic
+ * retrieval is unavailable — no provider, an index that fails to build, a query with no known
+ * words — the ranking is exactly the lexical one. Eligibility (approved, and allowed by the host)
+ * is applied after retrieval and is authoritative: relevance never makes a component usable.
+ * Ties break on catalogue order, so the same query and catalogue give the same list.
+ */
+
+export type SearchCard = CapabilityCard & { score: number };
+
+export type ComponentSearch = {
+  search(query: string, limit?: number, options?: SearchOptions): SearchCard[];
+  /** Development: every component's scores, best first — never part of the agent's result. */
+  explain(query: string, options?: SearchOptions): ScoreBreakdown[] & { mode: 'hybrid' | 'lexical'; version: string };
+  /** The index in use (null when searching lexically). */
+  index(): SearchIndex | null;
+};
+
+const round = (x: number) => Math.round(x * 1000) / 1000;
+const cardOf = (c: AgentCapability): CapabilityCard => ({ component: c.component, name: c.name, kind: c.kind, purpose: c.purpose, signals: c.signals });
+
+/** The approved catalogue, in order, and its search documents — derived once per module. */
+let catalogCache: { caps: AgentCapability[]; docs: SearchDocument[] } | null = null;
+export function searchCatalog(): { caps: AgentCapability[]; docs: SearchDocument[] } {
+  if (!catalogCache) {
+    const caps = AGENT_COMPONENTS.map(id => describeComponent(id)!);
+    catalogCache = { caps, docs: caps.map((c, i) => searchDocumentOf(c, i, AGENT_COMPONENTS)) };
+  }
+  return catalogCache;
+}
+
+export function createComponentSearch(opts: {
+  provider?: EmbeddingProvider | null;
+  weights: SearchWeights;
+  /** Where the documents come from — the approved catalogue by default. */
+  catalog?: () => { caps: AgentCapability[]; docs: SearchDocument[] };
+}): ComponentSearch {
+  const catalog = opts.catalog ?? searchCatalog;
+  const w = opts.weights;
+  let built: SearchIndex | null = null;
+  let failed: string | null = null;
+
+  /* The index for the catalogue as it is now — rebuilt whenever its version (documents + provider) changes. */
+  const indexFor = (docs: readonly SearchDocument[]): SearchIndex | null => {
+    const provider = opts.provider;
+    if (!provider) return null;
+    const version = indexVersion(docs, provider);
+    if (built?.version === version) return built;
+    if (failed === version) return null;
+    try {
+      built = new SearchIndex(provider, version).build(docs);
+      return built;
+    } catch {
+      failed = version;
+      built = null;
+      return null;
+    }
+  };
+
+  const queryVector = (q: NormalizedQuery, index: SearchIndex): Float32Array | null => {
+    try {
+      const v = index.provider.embed([q.text])[0];
+      if (!v || v.length !== index.mean?.length || !v.some(x => x !== 0) || v.some(x => !Number.isFinite(x))) return null;
+      return v;
+    } catch { return null; }
+  };
+
+  function retrieveCandidates(q: NormalizedQuery) {
+    const { caps, docs } = catalog();
+    const index = q.empty ? null : indexFor(docs);
+    const qv = index ? queryVector(q, index) : null;
+    const centring = { mean: w.centre !== 'none' ? index?.mean ?? null : null, principal: w.centre === 'pc' ? index?.principal ?? null : null };
+    return {
+      mode: (qv ? 'hybrid' : 'lexical') as 'hybrid' | 'lexical',
+      version: index?.version ?? '',
+      candidates: caps.map((c, order) => {
+        const lexical = q.empty ? 0 : lexicalScore(c, q.original);
+        if (!qv || !index) return { cap: c, order, lexical, semantic: null as number | null, negative: null as number | null };
+        const e = index.entries.get(c.component);
+        if (!e) return { cap: c, order, lexical, semantic: null, negative: null };
+        const { pos, posMax } = fieldScore(qv, e, centring);
+        const neg = e.negative.length ? Math.max(...e.negative.map(n => cosine(qv, n, centring))) : 0;
+        return { cap: c, order, lexical, semantic: pos - w.negative * Math.max(0, neg - posMax), negative: neg };
+      }),
+    };
+  }
+
+  /* How close a query vector is to a component: the mean of its `topK` closest fields (weighted by kind), and the closest one. */
+  function fieldScore(qv: Float32Array, e: IndexedDocument, centring: Centring) {
+    const sims = e.positive.filter(p => w.fields[p.type] > 0).map(p => { const raw = cosine(qv, p.vector, centring); return { raw, weighted: w.fields[p.type] * raw }; });
+    const top = sims.map(x => x.weighted).sort((a, b) => b - a).slice(0, w.topK);
+    return { pos: top.length ? top.reduce((a, b) => a + b, 0) / top.length : 0, posMax: sims.length ? Math.max(...sims.map(x => x.raw)) : 0 };
+  }
+
+  const applyEligibility = <T extends { cap: AgentCapability }>(list: T[], options: SearchOptions = {}) => list.map(x => ({
+    ...x,
+    availability: isAgentComponent(x.cap.component) && (!options.available || options.available.includes(x.cap.component)) ? 1 : 0,
+    metadata: !options.kinds || options.kinds.includes(x.cap.kind) ? 1 : 0,
+  }));
+
+  function rankCandidates(query: string, options?: SearchOptions) {
+    const q = normalizeQuery(query);
+    const r = retrieveCandidates(q);
+    const scored = applyEligibility(r.candidates, options).map(x => ({
+      ...x,
+      final: r.mode === 'lexical' || x.semantic === null
+        ? x.lexical
+        : w.semantic * x.semantic + w.lexical * (x.lexical / (x.lexical + w.lexicalHalf)),
+    }));
+    scored.sort((a, b) => b.final - a.final || a.order - b.order);
+    return { ...r, scored };
+  }
+
+  return {
+    search(query, limit = 5, options) {
+      const r = rankCandidates(query, options);
+      const eligible = r.scored.filter(x => x.availability && x.metadata);
+      const kept = r.mode === 'lexical'
+        ? eligible.filter(x => x.final > 0)
+        : (() => { const best = eligible[0]?.final ?? 0; return eligible.filter(x => x.final >= w.minScore && (best <= 0 || x.final >= best * w.relative)); })();
+      return kept.slice(0, Math.max(0, limit)).map(x => ({ ...cardOf(x.cap), score: round(x.final) }));
+    },
+    explain(query, options) {
+      const r = rankCandidates(query, options);
+      const out = r.scored.map(x => ({
+        component: x.cap.component, semantic: x.semantic === null ? null : round(x.semantic), negative: x.negative === null ? null : round(x.negative),
+        lexical: round(x.lexical), metadata: x.metadata, availability: x.availability, final: round(x.final),
+      })) as ScoreBreakdown[] & { mode: 'hybrid' | 'lexical'; version: string };
+      out.mode = r.mode;
+      out.version = r.version;
+      return out;
+    },
+    index: () => indexFor(catalog().docs),
+  };
+}

package/src/agent/search/searchIndex.ts

@@ -0,0 +1,107 @@
+import { versionOf } from './document';
+import type { EmbeddingProvider, FieldType, SearchDocument } from './types';
+
+/**
+ * **The search index — derived, rebuildable, never the source of truth.** Each component's document
+ * fields as vectors, plus the catalogue mean (for centring). Its `version` is the documents' hash
+ * plus the provider's id: if the catalogue or the model changes, the version does, and a cached
+ * index for the old one is never served (`indexFor`).
+ */
+export type IndexedDocument = {
+  component: string;
+  order: number;
+  positive: { type: FieldType; vector: Float32Array }[];
+  negative: Float32Array[];
+};
+
+export class SearchIndex {
+  readonly entries = new Map<string, IndexedDocument>();
+  mean: Float32Array | null = null;
+  /** The first principal component of the (centred) document vectors — the direction every text shares most (SIF's common-component removal). */
+  principal: Float32Array | null = null;
+  constructor(readonly provider: EmbeddingProvider, public version: string) {}
+
+  /** Throw away everything and index these documents. */
+  build(docs: readonly SearchDocument[]): this {
+    this.entries.clear();
+    for (const d of docs) this.put(d);
+    this.version = indexVersion(docs, this.provider);
+    return this.recentre();
+  }
+
+
+  /** Add or replace one component. */
+  upsert(doc: SearchDocument, allDocs?: readonly SearchDocument[]): this {
+    this.put(doc);
+    if (allDocs) this.version = indexVersion(allDocs, this.provider);
+    return this.recentre();
+  }
+
+  remove(component: string, allDocs?: readonly SearchDocument[]): this {
+    this.entries.delete(component);
+    if (allDocs) this.version = indexVersion(allDocs, this.provider);
+    return this.recentre();
+  }
+
+  private put(d: SearchDocument) {
+    const vectors = this.provider.embed([...d.positive.map(p => p.text), ...d.negative.map(n => n.text)]);
+    if (vectors.length !== d.positive.length + d.negative.length) throw new Error(`${this.provider.id} returned ${vectors.length} vectors for ${d.component}`);
+    this.entries.set(d.component, {
+      component: d.component,
+      order: d.order,
+      positive: d.positive.map((p, i) => ({ type: p.type, vector: vectors[i]! })),
+      negative: vectors.slice(d.positive.length),
+    });
+  }
+
+  /** The mean of every positive field vector: what all documents share, subtracted before comparing when centring. */
+  private recentre(): this {
+    let sum: Float32Array | null = null; let n = 0;
+    for (const e of this.entries.values()) for (const p of e.positive) {
+      sum ??= new Float32Array(p.vector.length);
+      for (let i = 0; i < sum.length; i++) sum[i]! += p.vector[i]!;
+      n++;
+    }
+    if (sum && n) for (let i = 0; i < sum.length; i++) sum[i]! /= n;
+    this.mean = sum;
+    this.principal = sum ? firstComponent([...this.entries.values()].flatMap(e => e.positive.map(p => p.vector)), sum) : null;
+    return this;
+  }
+}
+
+export const indexVersion = (docs: readonly SearchDocument[], provider: EmbeddingProvider) => `${versionOf(docs)}:${provider.id}`;
+
+/** Power iteration — deterministic start, fixed iterations. */
+function firstComponent(vectors: Float32Array[], mean: Float32Array): Float32Array {
+  const d = mean.length;
+  let u = new Float32Array(d).fill(1 / Math.sqrt(d));
+  for (let it = 0; it < 30; it++) {
+    const next = new Float32Array(d);
+    for (const v of vectors) {
+      let dot = 0; for (let i = 0; i < d; i++) dot += (v[i]! - mean[i]!) * u[i]!;
+      for (let i = 0; i < d; i++) next[i]! += dot * (v[i]! - mean[i]!);
+    }
+    let n = 0; for (const x of next) n += x * x; n = Math.sqrt(n) || 1;
+    for (let i = 0; i < d; i++) next[i]! /= n;
+    u = next;
+  }
+  return u;
+}
+
+/** What is compared: the vector less the shared mean and, if given, less its projection on the shared direction. */
+export type Centring = { mean: Float32Array | null; principal: Float32Array | null };
+function centred(v: Float32Array, c: Centring): Float32Array {
+  if (!c.mean && !c.principal) return v;
+  const out = new Float32Array(v.length);
+  for (let i = 0; i < v.length; i++) out[i] = v[i]! - (c.mean ? c.mean[i]! : 0);
+  if (c.principal) { let dot = 0; for (let i = 0; i < v.length; i++) dot += out[i]! * c.principal[i]!; for (let i = 0; i < v.length; i++) out[i]! -= dot * c.principal[i]!; }
+  return out;
+}
+
+/** Cosine similarity after centring. */
+export function cosine(a: Float32Array, b: Float32Array, c: Centring = { mean: null, principal: null }): number {
+  const x = centred(a, c), y = centred(b, c);
+  let dot = 0, na = 0, nb = 0;
+  for (let i = 0; i < x.length; i++) { dot += x[i]! * y[i]!; na += x[i]! * x[i]!; nb += y[i]! * y[i]!; }
+  return na && nb ? dot / Math.sqrt(na * nb) : 0;
+}