@kitn.ai/ui 0.27.0 → 0.29.0

package/src/agent-tooling/mcp/tools/reference.ts

@@ -1,980 +0,0 @@
-import { z } from 'zod';
-import {
-  KAI_TOOL_PREFIX,
-  cardSchemaNames,
-  cardSchemas,
-  cardTools,
-  isCardSchemaName,
-  toolNameForCardType,
-} from '@kitn.ai/ui/schemas';
-import type { CardSchemaName, ToolProvider } from '@kitn.ai/ui/schemas';
-import type { Tool } from './types';
-import {
-  cardHostTags,
-  cardTagForType,
-  cardTypeForTag,
-  entryForTag,
-  getElement,
-  listElements,
-  optInEntryForTag,
-} from '../manifest';
-import type { CemMember } from '../manifest';
-// The RAW literals, not listInvariants() / listSurfaceRecipes(). Those re-run a
-// zod parse over the whole catalog, and this is a per-lookup serving path called
-// once for every element a harness asks about. The parse is not skipped, only
-// moved: invariants.test.ts and surfaces.test.ts run it over these same literals
-// in CI, so a malformed record fails a test rather than a request.
-import { invariants } from '../../catalog/invariants';
-import { surfaceRecipes } from '../../catalog/surfaces';
-import type { TInvariant, TInvariantExample, TSurfaceRecipe } from '../../catalog/catalog-types';
-import { listCodeRecipes, getCodeRecipe } from '../../recipes';
-import type { CodeRecipe } from '../../recipes';
-import { readFileSync, existsSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { resolveManifestPath } from '../manifest';
-
-/**
- * component_reference — look up AI/UI (kai-*) web components, their props,
- * events, attributes, and CSS custom properties from the live Custom Elements
- * Manifest (dist/custom-elements.json).
- *
- * Backed by manifest.ts which resolves the CEM in both the bundled bin
- * (dist/mcp.es.js sibling) and the Vitest source context (walks up to find
- * dist/custom-elements.json in the repo root).
- *
- * For a card-backed element it also serves the card's JSON Schema and a tool
- * definition GENERATED by `cardTools()`. See `renderCardContract` for why not one
- * byte of that is written here as a literal.
- */
-
-/** Types that warrant the JS-property contract note. */
-const JS_ONLY_TYPE_PATTERNS = /\[\]|\{|Record</;
-
-function isJsOnlyType(typeText: string | undefined): boolean {
-  return typeText ? JS_ONLY_TYPE_PATTERNS.test(typeText) : false;
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// The imperative half of the interaction surface
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * A CEM member of `kind: 'method'`.
- *
- * `CemMember` in manifest.ts types what EVERY member carries. `parameters` and
- * `return` exist only on methods, and gen-element-api.mjs writes the AUTHORED
- * parameter list into a single `parameters[0].name` rather than splitting it, so
- * the signature is rebuilt from those two fields rather than read off one.
- */
-interface CemMethodMember extends CemMember {
-  kind: 'method';
-  parameters?: { name: string }[];
-  return?: { type?: { text?: string } };
-}
-
-function isPublicMethod(member: CemMember): member is CemMethodMember {
-  return member.kind === 'method' && member.privacy === 'public';
-}
-
-/** `maximize(index: number): void` — the call as a consumer types it. */
-function methodSignature(method: CemMethodMember): string {
-  return `${method.name}(${method.parameters?.[0]?.name ?? ''}): ${method.return?.type?.text ?? 'void'}`;
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// The card contract
-// ─────────────────────────────────────────────────────────────────────────────
-
-const PROVIDERS = ['openai', 'anthropic', 'jsonschema'] as const;
-
-/**
- * What a caller gets when they do not name a provider.
- *
- * NOT a coin-flip between the two wire formats, and deliberately not "serve all
- * three". The three envelopes are not interchangeable in a way a reader can patch
- * up: OpenAI nests the schema at `function.parameters`, Anthropic puts it flat at
- * `input_schema`. Handing over one of those unasked means a harness on the other
- * provider pastes it in and gets a 400 it will blame on the kit.
- *
- * `jsonschema` is the only one of the three that is not a wire envelope at all —
- * `{ name, description, schema }` cannot be mistaken for either provider's shape, so
- * a caller who reads it as one is corrected by the field names before they ship it.
- * It is also directly usable, not a booby prize: `tool({ inputSchema: jsonSchema(
- * def.schema) })` is exactly what the Vercel AI SDK wants, and of the nine
- * integrations this MCP scaffolds, exactly one (openrouter) posts a raw OpenAI-wire
- * tools array; the rest go through an SDK or an agent framework that takes the bare
- * schema.
- *
- * Serving all three was the other candidate and it loses on cost for no gain in
- * safety: measured on this tree, one card's pretty-printed definition runs
- * 1.7-5.3 KB, so three of them plus the schema turns a single `kai-artifact` lookup
- * into roughly 20 KB of context. The response names all three modes and the exact
- * call that produces each, so a caller who does know their provider is one re-ask
- * away and still never invents an envelope.
- */
-const DEFAULT_PROVIDER: ToolProvider = 'jsonschema';
-
-function isProvider(value: string): value is ToolProvider {
-  return (PROVIDERS as readonly string[]).includes(value);
-}
-
-/** Stable fence info strings, so a reader (and reference.test.ts) can lift the blocks back out exactly. */
-const TOOL_FENCE = 'kai-tool-definition';
-const SCHEMA_FENCE = 'kai-card-schema';
-
-function fence(info: string, value: unknown): string[] {
-  return ['```json ' + info, JSON.stringify(value, null, 2), '```'];
-}
-
-/**
- * Render a card type as it would be written in JS source.
- *
- * The seven built-ins are all bare identifiers, but a card type is whatever string a
- * developer put in `CardEnvelope.type` — `pricing-table` is legal and reaches this
- * code the day an eighth built-in is hyphenated. Emitting `{ pricing-table: … }` as a
- * copy-paste sample would be a syntax error, so the quoting is decided, not assumed.
- */
-const BARE_IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
-
-function asKey(cardType: string): string {
-  return BARE_IDENTIFIER.test(cardType) ? cardType : JSON.stringify(cardType);
-}
-
-function asMember(cardType: string): string {
-  return BARE_IDENTIFIER.test(cardType) ? `.${cardType}` : `[${JSON.stringify(cardType)}]`;
-}
-
-/**
- * The loop, in the four facts a harness cannot infer from a prop table.
- *
- * Shared by the card-backed and the card-host sections because they are the same
- * contract seen from the two ends, and a second copy would be the drift this whole
- * task exists to remove, one level up from the tool definition.
- *
- * `example` is the card the caller actually asked about, so the illustration is about
- * their card rather than a fixed one they then have to translate.
- */
-function loopWiring(example: string): string[] {
-  return [
-    '',
-    '#### Wiring the loop',
-    `- **Tool names are \`${KAI_TOOL_PREFIX}<card type>\`.** \`${toolNameForCardType(example)}\` produces \`{ type: "${example}" }\`. ` +
-      'Use `isCardTool(name)` to split card calls from your own tools; never match the prefix by hand.',
-    '- **`tool_call_id` becomes `CardEnvelope.id`, unchanged.** That is what makes a revision UPSERT: ' +
-      'a model that re-sends the same tool call id replaces the card in place instead of rendering a second copy of it. ' +
-      'Generating your own id breaks that silently.',
-    '- **`cardFromToolCall(name, input, { id: call.id })`** turns the call into a renderable envelope, ' +
-      'or returns `null` when it is one of your own tools so the loop falls through to it. It never throws.',
-    '- **Everything above is one import:** `import { cardTools, cardFromToolCall, isCardTool } from \'@kitn.ai/ui/schemas\'`. ' +
-      `The raw documents also ship as JSON (\`@kitn.ai/ui/schemas/${example}.schema.json\`) for a Python or Go backend.`,
-  ];
-}
-
-/** The card-backed section: schema + a GENERATED tool definition. */
-function renderCardContract(tag: string, cardType: CardSchemaName, provider: ToolProvider): string[] {
-  const schema = cardSchemas[cardType];
-
-  // GENERATED, NEVER RESTATED.
-  //
-  // This calls the same `cardTools` a consumer's route calls, on the same schema, so
-  // the definition served here cannot diverge from the one they ship — not when a
-  // schema gains a field, not when the projection changes what it strips. A literal
-  // typed into this file would read identically today and rot on the first schema
-  // change, which is exactly the hand-copy drift this tool exists to remove.
-  // reference.test.ts asserts byte-equality against BOTH `cardTools({ [type]: schema },
-  // …)` and the matching entry of the whole-registry `cardTools({ provider })`, so a
-  // hand-edit here fails a test rather than shipping.
-  const [def] = cardTools({ [cardType]: schema }, { provider });
-
-  const lines: string[] = [
-    '',
-    '### Card contract',
-    `\`<${tag}>\` renders \`CardEnvelope.type: "${cardType}"\`. A model does not emit an envelope; ` +
-      `it calls the tool \`${toolNameForCardType(cardType)}\`, and the kit turns that call back into one.`,
-  ];
-
-  lines.push(
-    '',
-    `#### Tool definition — provider \`${provider}\``,
-    `Generated by \`cardTools({ ${asKey(cardType)}: cardSchemas${asMember(cardType)} }, { provider: '${provider}' })\`. ` +
-      'Copy it; do not retype it, and do not hand-maintain a second copy — regenerate instead.',
-    `Ask again with \`provider\` set to \`openai\`, \`anthropic\` or \`jsonschema\` for the other envelopes. ` +
-      'They are NOT interchangeable: OpenAI nests the schema at `function.parameters`, Anthropic puts it flat at `input_schema`.',
-    ...fence(TOOL_FENCE, def),
-  );
-
-  lines.push(
-    '',
-    '#### Card data JSON Schema',
-    `\`import { cardSchemas } from '@kitn.ai/ui/schemas'\` → \`cardSchemas${asMember(cardType)}\`. ` +
-      `Raw document: \`@kitn.ai/ui/schemas/${cardType}.schema.json\`.`,
-    'This is the authored contract, and it is what `registry.validate()` checks arriving data against. ' +
-      'The tool definition above carries the same document with `$schema`, `$id` and `x-kai-*` stripped — ' +
-      'that projection is `cardTools`\' job, so do not put a raw schema on the wire yourself.',
-    ...fence(SCHEMA_FENCE, schema),
-  );
-
-  lines.push(...loopWiring(cardType));
-  return lines;
-}
-
-/** The card-host section: no schema of its own, but this is where the props live. */
-function renderCardHost(tag: string): string[] {
-  const rows = cardSchemaNames.map((type) => {
-    const cardTag = cardTagForType(type);
-    return `- \`${type}\` → \`<${cardTag ?? '(no element)'}>\`, tool \`${toolNameForCardType(type)}\``;
-  });
-
-  return [
-    '',
-    '### Card contract',
-    `\`<${tag}>\` renders generative-UI cards inside the thread. It is a HOST: it draws whatever ` +
-      'envelopes arrive, and carries the two props that say what a card may be.',
-    '',
-    '- **`cardTypes`** — `Record<envelope type, custom element tag>`. What DRAWS a card. ' +
-      `Merged over the built-ins, so your entry overrides ours and the other ${cardSchemaNames.length - 1} still render.`,
-    '- **`cardSchemas`** — `Record<envelope type, JSON Schema>`. What a VALID card looks like. ' +
-      `This is the prop that carries YOUR OWN card schemas into the browser validator; the ${cardSchemaNames.length} built-ins are already known. ` +
-      'Both are objects, so both are JS properties (`el.cardSchemas = …`), never HTML attributes.',
-    '',
-    'Write both once with `createCardRegistry({ use, custom })` from `@kitn.ai/ui/schemas` and thread it to both ends: ' +
-      '`el.cardTypes = cards.tags` / `el.cardSchemas = cards.validationSchemas` on the client, `cardTools(cards, { provider })` on the route.',
-    '',
-    'Built-in card types (ask `component_reference` for one of these tags to get its schema and tool definition):',
-    ...rows,
-    ...loopWiring(cardSchemaNames[0]),
-  ];
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// The composition catalog: invariants, and recipe membership
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * An invariant applies to a tag if it is unscoped by tag, or names it.
- *
- * `appliesTo.targets` deliberately does NOT filter here: `upgrade-race` is
- * scoped to script-tag DELIVERY, which is a fact about how the page loads and
- * not about which element is on it — every element can be dropped onto a CDN
- * page. So it is served everywhere and the scope is RENDERED (see `scopeOf`),
- * which is the difference between a conditional rule a reader can apply and an
- * unqualified one they will either over-apply or stop trusting.
- */
-function invariantsFor(tag: string): TInvariant[] {
-  return invariants.filter((i) => !i.appliesTo.tags || i.appliesTo.tags.includes(tag));
-}
-
-/**
- * The recipe's nesting, as markup a reader can paste.
- *
- * `noteSep` is how much of the record to print: the appendix passes ' — ' and
- * gets the WHY, an element lookup passes '' and gets only the shape, on the same
- * split the wiring rows already use. A recipe with no `composition` prints
- * nothing at all rather than "flat" — the field being absent means nobody
- * decided, and a rendered "(none)" would turn a gap into a claim.
- */
-function compositionLines(r: TSurfaceRecipe, noteSep: string): string[] {
-  if (!r.composition) return [];
-  return [
-    '- **Composition** — where the parts go (a slotted child, not a sibling):',
-    ...r.composition.map(
-      (c) =>
-        `  - \`<${c.child} slot="${c.slot}">\` goes INSIDE \`<${c.parent}>\`` +
-        (noteSep && c.note ? `${noteSep}${c.note}` : ''),
-    ),
-  ];
-}
-
-function recipesFor(tag: string): TSurfaceRecipe[] {
-  return surfaceRecipes.filter((r) => r.ingredients.includes(tag));
-}
-
-/**
- * How the coverage of one invariant reads — never a bare status word, and never
- * silence.
- *
- * Three of the catalog's records are enforced by NOTHING and two more by half of
- * what they say. A section that printed every rule as an equal-looking bullet
- * would put back exactly the overstatement those records were rewritten to
- * remove, one layer further out where it is harder to see. The wording also says
- * whose code the guard reads: every path here is inside the KIT's own repo, and
- * none of them checks the consumer's.
- */
-function coverageOf(inv: TInvariant): string {
-  const by = inv.enforcedBy;
-  // `guard` is '' only for kind:'none', and that combination reaches neither the
-  // 'enforced' nor the 'partial' branch below: invariants.test.ts ("open ⟺
-  // enforcedBy.kind none") asserts the equivalence in BOTH directions, so a
-  // kind:'none' record is always status:'open'. Named here because a reader of
-  // this file alone cannot see what makes `enforced by ` with nothing after it
-  // unreachable.
-  const guard =
-    by.kind === 'test'
-      ? `the kit's own tests (${by.paths.join(', ')})`
-      : by.kind === 'lint'
-        ? `the kit's \`${by.script}\` script, in required CI`
-        : by.kind === 'structural'
-          ? `a structural guarantee in ${by.path}`
-          : '';
-
-  switch (inv.status) {
-    case 'enforced':
-      return `enforced by ${guard}`;
-    case 'partial':
-      return `PARTIALLY ENFORCED: one half is covered, by ${guard}; the statement says which half is not`;
-    case 'open':
-      return (
-        'NOT ENFORCED: nothing in the kit checks this' +
-        (by.kind === 'none' && by.until ? `, until ${by.until}` : '') +
-        '. A rule you apply, not a guarantee you will be warned about'
-      );
-  }
-}
-
-/** What narrows an invariant, when something does. `targets` is not `tags`. */
-function scopeOf(inv: TInvariant): string {
-  const { tags, targets, parts } = inv.appliesTo;
-  const bits: string[] = [];
-  if (tags) bits.push(`only ${tags.join(', ')}`);
-  if (targets) bits.push(`${targets.join(' / ')} delivery only`);
-  if (parts) bits.push(`parts ${parts.join(', ')}`);
-  return bits.join('; ');
-}
-
-/**
- * The wrong/right pairs, as one fenced block per invariant.
- *
- * A fence rather than inline code because a `right` form is allowed to span
- * lines (the URL guards do), and because the pairs are meant to be
- * pattern-matched and grepped verbatim — the self-audit checklist greps emitted
- * code for the `wrong` form and expects zero hits, which only works if what is
- * served here is the literal and not a paraphrase of it.
- */
-function exampleLines(examples: TInvariantExample[]): string[] {
-  if (examples.length === 0) return [];
-  const out: string[] = ['', '```js'];
-  examples.forEach((ex, i) => {
-    if (i > 0) out.push('');
-    out.push('// WRONG', ex.wrong, '// RIGHT', ex.right);
-    if (ex.note) out.push(...ex.note.split('\n').map((l) => `// ${l}`));
-  });
-  out.push('```');
-  return out;
-}
-
-/**
- * The one sentence saying how much of this section is actually guarded.
- *
- * BOTH numerators are derived and both are needed. `open` alone was the first
- * form of this line, and it is the more quotable half: "3 of the 7 below are
- * enforced by NOTHING" compresses, in any reader summarising it, into "3
- * unenforced, 4 enforced" — and two of that four are `partial`, covered on one
- * half only. That is this repo's own compression-drops-the-qualifier failure,
- * sitting in the sentence written to prevent it. Naming both counts leaves the
- * compression nothing to invent.
- *
- * Returns '' when every applicable record is fully enforced, so the line can
- * never outlive the gap it describes and become a comfortable falsehood.
- *
- * Exported for reference.test.ts, which drives all four count combinations over
- * synthetic records — the real catalog can only instance one of them at a time.
- */
-export function coverageSummary(applicable: TInvariant[]): string {
-  const open = applicable.filter((i) => i.status === 'open').length;
-  const partial = applicable.filter((i) => i.status === 'partial').length;
-  if (open === 0 && partial === 0) return '';
-
-  const total = applicable.length;
-  const half = (n: number) => `only half of what ${n === 1 ? 'it says' : 'they say'}`;
-  const clauses: string[] = [];
-
-  if (open > 0) {
-    clauses.push(`${open} of the ${total} below ${open === 1 ? 'is' : 'are'} enforced by NOTHING at all`);
-  }
-  if (partial > 0) {
-    clauses.push(
-      open > 0
-        ? `${partial} more by ${half(partial)}`
-        : `${partial} of the ${total} below ${partial === 1 ? 'is' : 'are'} enforced by ${half(partial)}`,
-    );
-  }
-  return ` ${clauses.join(', and ')}.`;
-}
-
-/**
- * `###` to match every other section heading in this file (see '### Props'),
- * `####` for the per-record blocks, matching the card contract's sub-headings.
- *
- * Each invariant gets its heading (id, scope, coverage) and its one-line
- * `statement` — enough to apply the rule and to know how much to trust it —
- * but NOT the diagnosis and wrong/right examples. Those are the bulk: measured
- * on this tree, the full body of the 7 catalog records runs ~13 KB, and every
- * unscoped record (5 of 7) applies to all 80 elements, so printing the full
- * body here paid that in full on every lookup. `renderInvariantAppendix`
- * carries the long form exactly once; this function points to it instead of
- * repeating it.
- */
-function catalogSectionLines(tag: string): string[] {
-  const applicable = invariantsFor(tag);
-  const lines: string[] = [];
-
-  if (applicable.length > 0) {
-    lines.push(
-      '',
-      '### Invariants',
-      'Rules that have already broken real consumers of this kit. Each block says what enforces ' +
-        'it — read that line rather than assuming CI catches a violation, because nothing here ' +
-        'reads YOUR code.' + coverageSummary(applicable) + ' Diagnosis and wrong/right examples for ' +
-        'every invariant are served once, not repeated per element — call component_reference with ' +
-        '{ name: "invariants" }.',
-    );
-
-    for (const inv of applicable) {
-      const scope = scopeOf(inv);
-      lines.push('', `#### ${inv.id}${scope ? ` (${scope})` : ''} — ${coverageOf(inv)}`, inv.statement);
-    }
-  }
-
-  // No recipe, no section. An element that is in none gets its universal
-  // invariants and nothing else — a "part of: (none)" row would be a fabricated
-  // membership claim dressed as an empty one.
-  const recipes = recipesFor(tag);
-  if (recipes.length > 0) {
-    lines.push(
-      '',
-      '### Appears in surface recipes',
-      'Compositions this element is part of, each with the whole ingredient list and the host ' +
-        'wiring — nothing coordinates one element with another except your own code ' +
-        '(host-coordinates). The WHY behind each wiring edge, and the caveats on the nesting ' +
-        'below, are served once rather than repeated per ingredient — call component_reference ' +
-        'with { name: "recipes" }.',
-    );
-    for (const r of recipes) {
-      lines.push(
-        '',
-        `#### ${r.id} — ${r.intent}`,
-        `- **Ingredients:** ${r.ingredients.map((t) => `\`<${t}>\``).join(', ')}`,
-        `- **Delivery:** ${r.targets.join(', ')} · archetype: ${r.archetypes.join(', ')}`,
-        `- **Backend:** your own endpoint, read with \`${r.backend.reader}\` from \`@kitn.ai/ui/wire\``,
-        // WHERE the parts go. Printed per element and not only in the appendix,
-        // because this is the one fact a builder cannot infer from anything else
-        // on the page: the wiring rows say which event drives which property and
-        // are silent about nesting, so an element lookup that omitted this left
-        // the reader to guess between a child and a sibling. Short enough to
-        // repeat; the `note` (the WHY) stays in the appendix with the wiring notes.
-        ...compositionLines(r, ''),
-        // Bare ids, deliberately. This row is a DEPENDENCY list, not a coverage
-        // claim, and it can only ever be read a few lines below the full
-        // `### Invariants` section in the same response, where each of these ids
-        // already carries its own coverage line. Repeating the status here would
-        // print it a second (and, with two recipes, a third) time per element for
-        // no fact a reader does not already have on the page.
-        `- **Invariants it leans on:** ${r.invariants.join(', ')}`,
-        // Compact: the edge (event out of A, property into B) with no `note`.
-        // The note is the WHY — often a full sentence, sometimes several — and
-        // repeating it is the same shape of duplication task 4 removed from
-        // invariants: this recipe's ingredients (kai-chat, kai-conversations,
-        // kai-resizable, kai-artifact) all print this identical wiring list.
-        // `renderRecipeAppendix` carries the notes exactly once.
-        '- **Wiring** — event out of A, property into B, wired by the host:',
-      );
-      for (const w of r.wiring) {
-        lines.push(`  - \`<${w.from}>\` fires \`${w.event}\` → host sets \`${w.to}.${w.property}\``);
-      }
-    }
-  }
-
-  return lines;
-}
-
-/**
- * The long-form recipe reference, served exactly once rather than repeated on
- * every ingredient. `catalogSectionLines` prints the ingredients, delivery,
- * backend and a compact wiring list (edge only, no `note`) per element and
- * points here for the rest — the WHY behind each wiring edge, which is the
- * bulk: `workspace-chat` alone has 4 ingredients, and every one of them
- * printed every wiring note in full before this moved. Reached via
- * `component_reference({ name: "recipes" })`.
- */
-function renderRecipeAppendix(): string[] {
-  const lines: string[] = [
-    `## Surface recipe catalog (${surfaceRecipes.length} total) — wiring notes`,
-    '',
-    'Every element lookup that appears in a recipe lists its ingredients, delivery, backend and ' +
-      'a compact wiring list (event out of A, property into B). This is the long form: the WHY ' +
-      'behind each wiring edge, written once here rather than repeated on every ingredient.',
-  ];
-
-  for (const r of surfaceRecipes) {
-    lines.push(
-      '',
-      `#### ${r.id} — ${r.intent}`,
-      `- **Ingredients:** ${r.ingredients.map((t) => `\`<${t}>\``).join(', ')}`,
-      `- **Delivery:** ${r.targets.join(', ')} · archetype: ${r.archetypes.join(', ')}`,
-      `- **Backend:** your own endpoint, read with \`${r.backend.reader}\` from \`@kitn.ai/ui/wire\``,
-      `- **Invariants it leans on:** ${r.invariants.join(', ')}`,
-      ...compositionLines(r, ' — '),
-      '- **Wiring** — event out of A, property into B, wired by the host:',
-    );
-    for (const w of r.wiring) {
-      lines.push(
-        `  - \`<${w.from}>\` fires \`${w.event}\` → host sets \`${w.to}.${w.property}\`` +
-          (w.note ? ` — ${w.note}` : ''),
-      );
-    }
-  }
-
-  return lines;
-}
-
-/**
- * The long-form invariant reference, served exactly once rather than repeated
- * on every element it applies to. `catalogSectionLines` prints only the id,
- * scope and one-line statement per element and points here for the rest —
- * this is that "rest": every record's full statement again for context, its
- * diagnosis rows, and its wrong/right examples, each written once for the
- * whole catalog regardless of how many of the 80 elements the record applies
- * to. Reached via `component_reference({ name: "invariants" })`.
- */
-function renderInvariantAppendix(): string[] {
-  const lines: string[] = [
-    `## Invariant catalog (${invariants.length} total) — diagnosis and examples`,
-    '',
-    'Every element lookup lists the invariants that apply to it by id and one-line statement. ' +
-      'This is the long form: full statement, diagnosis and wrong/right examples for each record, ' +
-      'written once here rather than repeated on every element it applies to.',
-  ];
-
-  for (const inv of invariants) {
-    const scope = scopeOf(inv);
-    lines.push('', `#### ${inv.id}${scope ? ` (${scope})` : ''} — ${coverageOf(inv)}`, inv.statement);
-    if (inv.diagnosis.length > 0) {
-      lines.push('', 'If you are debugging:');
-      for (const d of inv.diagnosis) lines.push(`- ${d.symptom} → ${d.cause}`);
-    }
-    lines.push(...exampleLines(inv.examples));
-  }
-
-  return lines;
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// The programmatic layer and the code recipes
-// ─────────────────────────────────────────────────────────────────────────────
-
-/** The topic names that all resolve to the programmatic-layer appendix. */
-const PROGRAMMATIC_ALIASES = ['programmatic', 'state', 'wire', 'state-wire'] as const;
-
-/**
- * The `/state` + `/wire` appendix (rung-6 F-46): a marker-fenced section of the
- * package-root `llms-full.txt`, which `build:api` DERIVES from the shipped
- * `dist/state/*.d.ts` + `dist/wire/*.d.ts` (scripts/gen-llms-programmatic.mjs).
- * Read, never restated: this tool restating one signature by hand is exactly
- * the drift the generator exists to remove. The root copy is the CANONICAL and
- * ONLY shipped copy (owner-ruled 2026-08-25): a second copy under `dist/llms/`
- * used to ship too, ~293 KB of duplicate tarball weight — and it once went
- * stale against the root while both claimed to be the artifact. It resolves
- * relative to the manifest (`dist/custom-elements.json`), whose parent's
- * parent is the package root in both contexts — bundled bin and source/vitest.
- */
-/**
- * The fence gen-llms-programmatic.mjs writes around the section inside
- * llms-full.txt. REGISTERED COPY of `PROGRAMMATIC_MARKERS` in that script —
- * this TS module cannot import the generator .mjs. If either side moves, the
- * slice below misses and the reference tests fail on the "Missing build
- * artifact" branch, so the drift is loud.
- */
-const PROGRAMMATIC_START = '<!-- kai:programmatic:start -->';
-const PROGRAMMATIC_END = '<!-- kai:programmatic:end -->';
-
-function renderProgrammaticAppendix(): string {
-  // Sliced out of the SHIPPED llms-full.txt rather than served from a file of
-  // its own: a standalone copy was ~50 KB of duplicate tarball weight
-  // (verify:pack priced it), and slicing keeps one derivation with zero extra
-  // shipped bytes.
-  const path = join(dirname(resolveManifestPath()), '..', 'llms-full.txt');
-  const missing = (what: string) =>
-    `Missing build artifact: ${what}\n\n` +
-    'The programmatic-layer reference is generated from the shipped dist/*.d.ts by the ' +
-    'build (a marker-fenced section of the package-root llms-full.txt). Run `nx build ui` ' +
-    '(or `npm run build:api` in packages/ui) and ask again. It is deliberately not restated ' +
-    'here: a hand-typed copy would drift from the declarations your editor shows.';
-  if (!existsSync(path)) return missing(path);
-  const full = readFileSync(path, 'utf-8');
-  const start = full.indexOf(PROGRAMMATIC_START);
-  const end = full.indexOf(PROGRAMMATIC_END);
-  if (start === -1 || end === -1 || end <= start) {
-    return missing(`the ${PROGRAMMATIC_START} section inside ${path}`);
-  }
-  return full.slice(start + PROGRAMMATIC_START.length, end).trim();
-}
-
-/**
- * One code recipe as files a builder pastes. The catalog half (ingredients,
- * wiring edges, invariants — each executed by surfaces.test.ts) is the surface
- * recipe of the same id; this is the body a data record cannot carry, and
- * `verify:scaffold` compiles every `lang: 'ts'` file of it.
- */
-function renderCodeRecipe(r: CodeRecipe): string {
-  const lines: string[] = [
-    `## Recipe: ${r.title} (\`${r.id}\`)`,
-    '',
-    r.intent,
-    '',
-    `**Elements composed:** ${r.ingredients.map((t) => `\`<${t}>\``).join(', ')}`,
-    '',
-    '**Read these before pasting:**',
-    ...r.notes.map((n) => `- ${n}`),
-  ];
-  for (const f of r.files) {
-    lines.push('', `### \`${f.path}\``, '', '```' + f.lang, f.code.trimEnd(), '```');
-  }
-  lines.push(
-    '',
-    'The wiring topology, invariants and composition claims behind this recipe are the ' +
-      `surface recipe of the same id — call component_reference with { name: "recipes" }.`,
-  );
-  return lines.join('\n');
-}
-
-/**
- * The payload out of `CustomEvent<T>`, or `undefined` when there is no payload.
- *
- * The manifest types every event, but as the wrapper — printing that raw teaches
- * a reader to write `CustomEvent<...>` where a payload belongs. Anything that is
- * not of the form `CustomEvent<…>` has NO payload to print, and this returns
- * `undefined` so the caller omits the `detail` clause entirely.
- *
- * That is read off the generator rather than guessed at. gen-element-api.mjs
- * writes the CEM type as ``CustomEvent<${e.detail}>`` when the element declares a
- * detail and the bare string `CustomEvent` when it does not — exactly two shapes,
- * and the bare one means the detail is `void` (e.g. `'kai-click': void` in
- * button.tsx). Passing an unrecognised type through unchanged looked like a safe
- * fallback for an already-unwrapped payload; what it actually caught was the void
- * events, which then rendered ``Carries no detail. `detail`: `CustomEvent` `` — a
- * line contradicting itself, on 13 events across 10 elements. The whole-manifest
- * probe in reference.test.ts holds both directions of the rule.
- */
-function eventDetail(typeText: string | undefined): string | undefined {
-  const m = /^CustomEvent<([\s\S]*)>$/.exec(typeText?.trim() ?? '');
-  return m ? m[1].trim() || undefined : undefined;
-}
-
-function formatReference(tag: string, provider: ToolProvider): string {
-  const el = getElement(tag);
-
-  if (!el) {
-    const all = listElements();
-    const sample = all.slice(0, 5).join(', ');
-    return (
-      `Unknown element: ${tag}\n\n` +
-      `Valid tags include: ${sample} (and ${Math.max(0, all.length - 5)} more).\n` +
-      `Call component_reference with no name (or name: "list") to list all ${all.length} elements.`
-    );
-  }
-
-  const lines: string[] = [];
-
-  // ── Header ─────────────────────────────────────────────────────────────────
-  lines.push(`## <${tag}>`);
-  if (el.description) {
-    lines.push('', el.description.trim());
-  }
-
-  // ── Getting the element ────────────────────────────────────────────────────
-  // FIRST, above every other section. An element that never upgrades renders
-  // nothing and logs NOTHING: the property assigns and reads back fine, and
-  // whenDefined() never settles, so the listener is never attached. That symptom
-  // is also what props-not-attributes blames on a different cause, so a reader
-  // who has the invariants and not this line is steered to the wrong diagnosis.
-  const entry = entryForTag(tag);
-  const iface = el.name;
-  const neverUpgrades =
-    'If you skip registering it the element never upgrades: nothing renders, ' +
-    '**no error and no warning is logged**, a property you set assigns and reads ' +
-    `back correctly, and \`customElements.whenDefined('${tag}')\` never resolves.`;
-  lines.push('', '### Getting the element');
-  if (entry) {
-    lines.push(
-      `Register it before you use it. ${neverUpgrades}`,
-      '',
-      '```ts',
-      "import '@kitn.ai/ui/elements';",
-      `import '@kitn.ai/ui/elements/${entry}'; // or just this one`,
-      '```',
-    );
-  } else {
-    // entryForTag is undefined exactly when register-impl.ts does not import this
-    // element's source file — i.e. it is NOT in the register-all bundle. The only
-    // current instance is kai-remote, a deliberate exception (opt-in cross-origin
-    // iframe card) documented at src/elements/element-diagnostics.ts:347-363 and
-    // vite.config.elements.ts:44-50. `import '@kitn.ai/ui/elements'` would NOT
-    // register a tag in this state, so asserting it here is exactly the false
-    // claim this section exists to prevent.
-    //
-    // The specifier is still NOT guessed — stripping `kai-` is wrong for ten of
-    // the eighty elements. `optInEntryForTag` reads it off the module the
-    // per-element build actually emitted, matched to this tag by the tag literal
-    // it registers; see the note there. Telling the reader to go look it up was
-    // the last place in this reference where "how to make the element exist" did
-    // not answer itself, and the answer was in the build config all along.
-    const optIn = optInEntryForTag(tag);
-    lines.push(
-      `**\`${tag}\` is opt-in — it is not part of \`import '@kitn.ai/ui/elements'\` ` +
-        '(register-all), and that import alone will NOT register it.** ' +
-        (optIn
-          ? `Import its own entry point instead. ${neverUpgrades}`
-          : // No built module claims this tag, so there is no specifier to name.
-            // Stay honest rather than inventing one.
-            'Find its specific `@kitn.ai/ui/elements/<name>` entry point in the ' +
-            `package's published exports before using it. ${neverUpgrades}`),
-    );
-    if (optIn) {
-      lines.push('', '```ts', `import '@kitn.ai/ui/elements/${optIn}';`, '```');
-    }
-  }
-  if (iface) {
-    lines.push(
-      '',
-      `TypeScript: \`import type { ${iface} } from '@kitn.ai/ui/elements';\` — ` +
-        'the element interface ships with the package; do not hand-roll a structural type.',
-    );
-  }
-
-  // ── Contract note ──────────────────────────────────────────────────────────
-  lines.push(
-    '',
-    '### AI/UI contract',
-    '`kai-*` elements accept **array and object data as JavaScript properties** ' +
-      '(set in JavaScript via `el.property = value`, not as HTML attributes). ' +
-      'Events are native CustomEvents — listen with `el.addEventListener("event-name", handler)` ' +
-      'and read `event.detail` for the payload.',
-  );
-
-  // ── Card contract ─────────────────────────────────────────────────────────
-  // Attached to the two populations manifest.ts derives, and to nothing else. A
-  // reference that hangs card material off all 80 elements is worse than one that
-  // hangs it off none: it teaches a harness that every element takes a tool call.
-  const cardType = cardTypeForTag(tag);
-  if (cardType !== undefined && isCardSchemaName(cardType)) {
-    lines.push(...renderCardContract(tag, cardType, provider));
-  } else if (cardHostTags().includes(tag)) {
-    lines.push(...renderCardHost(tag));
-  }
-
-  // ── Public JS properties ───────────────────────────────────────────────────
-  const publicFields = (el.members ?? []).filter(
-    (m) => m.kind === 'field' && m.privacy === 'public',
-  );
-
-  if (publicFields.length > 0) {
-    lines.push('', '### Props (JavaScript properties)');
-    for (const field of publicFields) {
-      const type = field.type?.text ?? 'unknown';
-      const jsOnly = isJsOnlyType(type);
-      const desc = field.description?.trim() ?? '';
-      const note = jsOnly ? ' ⚑ set as a JS property, not an HTML attribute' : '';
-      lines.push(`- **${field.name}** \`${type}\`${note}`);
-      if (desc) {
-        lines.push(`  ${desc}`);
-      }
-    }
-  }
-
-  // ── HTML attributes ────────────────────────────────────────────────────────
-  const attrs = el.attributes ?? [];
-  if (attrs.length > 0) {
-    lines.push('', '### Attributes (HTML-safe)');
-    for (const attr of attrs) {
-      const type = attr.type?.text ?? 'unknown';
-      const desc = attr.description?.trim() ?? '';
-      lines.push(`- **${attr.name}** \`${type}\``);
-      if (desc) {
-        lines.push(`  ${desc}`);
-      }
-    }
-  }
-
-  // ── Events ────────────────────────────────────────────────────────────────
-  const events = el.events ?? [];
-  if (events.length > 0) {
-    lines.push('', '### Events (CustomEvent, listen via addEventListener)');
-    for (const ev of events) {
-      const desc = ev.description?.trim() ?? '';
-      const detail = eventDetail(ev.type?.text);
-      lines.push(
-        detail
-          ? `- **${ev.name}** — ${desc} \`detail\`: \`${detail}\``
-          : `- **${ev.name}** — ${desc}`,
-      );
-    }
-  }
-
-  // ── Methods ───────────────────────────────────────────────────────────────
-  // The input half of the interaction surface. These were in the manifest and in
-  // the shipped types and rendered in NO reference, so the only way to find one
-  // was to read the kit's source.
-  const methods = (el.members ?? []).filter(isPublicMethod);
-  if (methods.length > 0) {
-    lines.push(
-      '',
-      '### Methods (call these on the element instance)',
-      `Get the element (\`const el = document.querySelector('${tag}')\`), then call it. ` +
-        'Methods drive the element from your code; the events above report back what the ' +
-        'user did. Both are public API.',
-    );
-    for (const method of methods) {
-      const desc = method.description?.trim() ?? '';
-      lines.push(`- **${methodSignature(method)}**${desc ? ` — ${desc}` : ''}`);
-    }
-  }
-
-  // ── CSS custom properties ─────────────────────────────────────────────────
-  const cssProps = el.cssProperties ?? [];
-  if (cssProps.length > 0) {
-    lines.push('', '### CSS custom properties');
-    for (const prop of cssProps) {
-      const desc = prop.description?.trim() ?? '';
-      const def = prop.default ? ` (default: ${prop.default})` : '';
-      lines.push(`- **${prop.name}**${def}${desc ? ` — ${desc}` : ''}`);
-    }
-  }
-
-  // ── Composition slots ──────────────────────────────────────────────────────
-  const slots = el.slots ?? [];
-  if (slots.length > 0) {
-    lines.push(
-      '',
-      '### Composition slots',
-      'Project your own markup into these named regions — add a light-DOM child ' +
-        'with a `slot="…"` attribute (e.g. `<div slot="sidebar">…</div>`).',
-    );
-    for (const slot of slots) {
-      const desc = slot.description?.trim() ?? '';
-      lines.push(`- **${slot.name}**${desc ? ` — ${desc}` : ''}`);
-    }
-  }
-
-  // ── Styleable parts (::part) ───────────────────────────────────────────────
-  const parts = el.cssParts ?? [];
-  if (parts.length > 0) {
-    lines.push(
-      '',
-      '### Styleable parts (`::part`)',
-      'Restyle these from outside the Shadow DOM via `' + tag + '::part(name) { … }`.',
-    );
-    for (const part of parts) {
-      const desc = part.description?.trim() ?? '';
-      lines.push(`- **${part.name}**${desc ? ` — ${desc}` : ''}`);
-      if (part.recipe) {
-        lines.push('  ```css', `  ${part.recipe}`, '  ```');
-      }
-    }
-  }
-
-  // ── The composition catalog ────────────────────────────────────────────────
-  lines.push(...catalogSectionLines(tag));
-
-  return lines.join('\n');
-}
-
-export const reference: Tool = {
-  name: 'component_reference',
-  description:
-    'Look up AI/UI (kai-*) web components: their tags, props, events, imperative methods, and usage examples. ' +
-    'For a card-backed element it also returns the card\'s JSON Schema and a ready-to-send ' +
-    'tool definition generated from it — pass `provider` to get that provider\'s envelope. ' +
-    'Also serves the programmatic layer (name: "programmatic" — the @kitn.ai/ui/state + ' +
-    '@kitn.ai/ui/wire streaming/mock/encode API) and complete code recipes ' +
-    '(e.g. name: "composed-thread" — a hand-composed thread with no <kai-chat>).',
-  inputSchema: z.object({
-    name: z
-      .string()
-      .optional()
-      .describe(
-        'The element tag, e.g. "kai-chat". Omit it (or pass "list") to get the ' +
-          'index of every element with a one-line summary, then ask again for the one you want. ' +
-          'Pass "invariants" for the full diagnosis and wrong/right examples behind every ' +
-          'invariant id an element lookup shows. Pass "recipes" for the full wiring notes ' +
-          'behind every surface recipe an element lookup names. Pass "programmatic" (or ' +
-          '"state" / "wire") for the @kitn.ai/ui/state + @kitn.ai/ui/wire API — streaming ' +
-          'folds, the mock responder, the SSE readers/encoders. Pass a code-recipe id ' +
-          '(e.g. "composed-thread") for a complete pasteable composition.',
-      ),
-    provider: z
-      .enum(PROVIDERS)
-      .optional()
-      .describe(
-        'Which tool-definition envelope to project for a card-backed element. ' +
-          `Defaults to "${DEFAULT_PROVIDER}", the provider-neutral { name, description, schema } form.`,
-      ),
-  }),
-  handler: async (args: Record<string, unknown>) => {
-    const name = typeof args.name === 'string' ? args.name.trim() : undefined;
-
-    // Validated HERE, not left to the zod schema above. server.ts advertises
-    // `inputSchema` over the protocol but hands `request.params.arguments` straight
-    // to this handler without parsing it, so an unrecognised provider would reach
-    // `cardTools`, which treats anything that is not "openai"/"anthropic" as the
-    // jsonschema branch. A caller asking for "gemini" would then get a definition in
-    // a shape they did not ask for, with nothing saying so. Refusing is the only
-    // answer that cannot be mistaken for an answer.
-    const rawProvider = args.provider;
-    if (rawProvider !== undefined && (typeof rawProvider !== 'string' || !isProvider(rawProvider))) {
-      return {
-        content: [
-          {
-            type: 'text' as const,
-            text:
-              `Unknown provider: ${JSON.stringify(rawProvider)}\n\n` +
-              `Valid providers are ${PROVIDERS.map((p) => `"${p}"`).join(', ')}. ` +
-              `Omit it to get "${DEFAULT_PROVIDER}", the provider-neutral { name, description, schema } form ` +
-              'that the Vercel AI SDK and most agent frameworks take directly.\n' +
-              'No tool definition was returned, because guessing which envelope you meant would hand you ' +
-              'a shape your provider rejects with nothing saying why.',
-          },
-        ],
-      };
-    }
-    const provider: ToolProvider = rawProvider ?? DEFAULT_PROVIDER;
-
-    let text: string;
-
-    if (!name || name === 'list') {
-      const tags = listElements();
-      const cardRows = cardSchemaNames
-        .map((t) => cardTagForType(t))
-        .filter((t): t is string => t !== undefined);
-      text =
-        `AI/UI elements (${tags.length} total):\n\n` +
-        tags.map((t) => `  ${t}`).join('\n') +
-        '\n\nCall component_reference with a specific name (e.g. { name: "kai-chat" }) for full API details.' +
-        `\n\nCard-backed elements — ask for one of these to get its JSON Schema and a generated ` +
-        `\`${KAI_TOOL_PREFIX}*\` tool definition:\n  ${cardRows.join(', ')}` +
-        `\nThe elements that HOST them (and carry the \`cardTypes\` / \`cardSchemas\` props): ${cardHostTags().join(', ')}` +
-        `\n\nCall component_reference with { name: "invariants" } for the full diagnosis and ` +
-        'wrong/right examples behind every invariant id shown on an element lookup.' +
-        `\n\nCall component_reference with { name: "recipes" } for the full wiring notes behind ` +
-        'every surface recipe an element lookup names.' +
-        `\n\nCall component_reference with { name: "programmatic" } for the @kitn.ai/ui/state + ` +
-        '@kitn.ai/ui/wire API — createAssistantStream, the part folds, createMockResponder ' +
-        '(and its scripted tool calls), the SSE readers and the provider encoders. That layer ' +
-        'is what a host wires when it composes elements by hand instead of using <kai-chat>.' +
-        `\n\nComplete pasteable compositions (code recipes): ${listCodeRecipes()
-          .map((r) => `{ name: "${r.id}" } — ${r.title}`)
-          .join('; ')}.`;
-    } else if (name === 'invariants') {
-      text = renderInvariantAppendix().join('\n');
-    } else if (name === 'recipes') {
-      text = renderRecipeAppendix().join('\n');
-    } else if ((PROGRAMMATIC_ALIASES as readonly string[]).includes(name)) {
-      text = renderProgrammaticAppendix();
-    } else if (getCodeRecipe(name)) {
-      text = renderCodeRecipe(getCodeRecipe(name)!);
-    } else {
-      text = formatReference(name, provider);
-    }
-
-    return { content: [{ type: 'text' as const, text }] };
-  },
-};