@kitn.ai/ui 0.25.2 → 0.26.0

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

@@ -9,8 +9,24 @@ import {
 } from '@kitn.ai/ui/schemas';
 import type { CardSchemaName, ToolProvider } from '@kitn.ai/ui/schemas';
 import type { Tool } from './types';
-import { cardHostTags, cardTagForType, cardTypeForTag, getElement, listElements } from '../manifest';
+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';
 
 /**
  * component_reference — look up AI/UI (kai-*) web components, their props,
@@ -225,6 +241,341 @@ function renderCardHost(tag: string): string[] {
   ];
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// 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 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);
 
@@ -246,6 +597,66 @@ function formatReference(tag: string, provider: ToolProvider): string {
     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(
     '',
@@ -306,7 +717,12 @@ function formatReference(tag: string, provider: ToolProvider): string {
     lines.push('', '### Events (CustomEvent, listen via addEventListener)');
     for (const ev of events) {
       const desc = ev.description?.trim() ?? '';
-      lines.push(`- **${ev.name}** — ${desc}`);
+      const detail = eventDetail(ev.type?.text);
+      lines.push(
+        detail
+          ? `- **${ev.name}** — ${desc} \`detail\`: \`${detail}\``
+          : `- **${ev.name}** — ${desc}`,
+      );
     }
   }
 
@@ -372,6 +788,9 @@ function formatReference(tag: string, provider: ToolProvider): string {
     }
   }
 
+  // ── The composition catalog ────────────────────────────────────────────────
+  lines.push(...catalogSectionLines(tag));
+
   return lines.join('\n');
 }
 
@@ -382,7 +801,16 @@ export const reference: Tool = {
     '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.',
   inputSchema: z.object({
-    name: z.string().optional(),
+    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.',
+      ),
     provider: z
       .enum(PROVIDERS)
       .optional()
@@ -433,7 +861,15 @@ export const reference: Tool = {
         '\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(', ')}`;
+        `\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.';
+    } else if (name === 'invariants') {
+      text = renderInvariantAppendix().join('\n');
+    } else if (name === 'recipes') {
+      text = renderRecipeAppendix().join('\n');
     } else {
       text = formatReference(name, provider);
     }