@kitn.ai/ui 0.26.0 → 0.28.0

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

@@ -450,6 +450,123 @@ const RULES: Rule[] = [
       'A malformed definition (not two candidates, missing/duplicate ids) fires `kai-error` ' +
       'instead. The event is non-bubbling — listen on the element, not on `document`.',
   },
+  {
+    // Rule 13 — kai-composer is the bare editor; attachments + send live on kai-prompt-input
+    // Source: src/elements/composer.tsx (element doc), src/elements/prompt-input.tsx,
+    // apps/docs components/composer.mdx (the taxonomy sentence). Rung-6 F-43.
+    id: 'composer-attachments',
+    test: (t) => {
+      // Attachment / send-button / toolbar questions asked ABOUT the composer.
+      if (!/kai-composer|composer\b/i.test(t)) return false;
+      return /attach|paperclip|file.?upload|upload|send.?button|toolbar|staging|staged/i.test(t);
+    },
+    title: '`<kai-composer>` is the bare editor — attachments and the send button live on `<kai-prompt-input>`',
+    cause:
+      '`<kai-composer>` is deliberately the bare editing surface: rich text, entity pills, ' +
+      'triggers, Enter-to-submit — and nothing else. No send button, no toolbar, no attachment ' +
+      'surface; its `kai-submit` detail is `{ doc, text, entities }` with no `attachments` field. ' +
+      'Nothing is missing — the batteries-included wrapper is a different element.',
+    fix:
+      'Reach for `<kai-prompt-input>`, which is built on the composer and adds the send button, ' +
+      'the toolbar, and attachments: a paperclip that stages files as chips, a ' +
+      '`kai-attachments-change` event, and `attachments` on its `kai-submit` detail.\n\n' +
+      '```html\n' +
+      '<kai-prompt-input placeholder="Send a message..."></kai-prompt-input>\n' +
+      '```\n\n' +
+      '```js\n' +
+      "document.querySelector('kai-prompt-input').addEventListener('kai-submit', (e) => {\n" +
+      '  const { value, attachments } = e.detail; // attachments staged via the paperclip\n' +
+      '});\n' +
+      '```\n\n' +
+      'Keep `<kai-composer>` only when you are composing the input row yourself — then the ' +
+      'picker, staging tray and send control are yours to build, and every staged file’s ' +
+      '`url` must be a `data:` URI, never `URL.createObjectURL` (see the attachment-blob-url rule).',
+  },
+  {
+    // Rule 14 — blob: attachment URLs: the wire refuses them; use a data: URI
+    // Source: src/components/attachment-types.ts (AttachmentData.url doc),
+    // src/elements/default-input.tsx (readAsDataUrl), src/wire/files.ts (the refusal),
+    // apps/docs patterns/attachments-flow.mdx. Rung-6 F-44; the defect PR #186 shipped.
+    id: 'attachment-blob-url',
+    test: (t) => {
+      // The literal defect in a snippet, with attachment/file-staging context.
+      if (/createObjectURL/.test(t) && /attachment|type:\s*'file'|filename|kai|@kitn/i.test(t)) return true;
+      // A wire refusal or preview-works-send-fails symptom naming blob: URLs.
+      if (/blob:/.test(t) && /attachment|toOpenAIMessages|toAnthropicMessages|wire|kai|@kitn/i.test(t)) return true;
+      return false;
+    },
+    title: 'Never `URL.createObjectURL` in `AttachmentData.url` — read the file as a `data:` URI',
+    cause:
+      'An object URL resolves only inside the browser tab that minted it, so `url: ' +
+      'URL.createObjectURL(file)` renders a flawless local preview and is meaningless to any ' +
+      'provider. `toOpenAIMessages` / `toAnthropicMessages` REFUSE a `blob:` URL rather than ' +
+      'send an address the model cannot fetch — before they refused it, an attachment-only ' +
+      'turn reached the model as nothing at all. A mock-only app hides the defect ' +
+      '(`createMockResponder` never encodes the thread back); it surfaces the moment you point ' +
+      'at a real provider.',
+    fix:
+      'Read every staged file as a `data:` URI and put THAT in `url` — it previews identically ' +
+      'and is the one form both provider wires actually take:\n\n' +
+      '```js\n' +
+      'const readAsDataUrl = (file) =>\n' +
+      '  new Promise((resolve, reject) => {\n' +
+      '    const reader = new FileReader();\n' +
+      '    reader.onload = () => resolve(String(reader.result));\n' +
+      '    reader.onerror = () => reject(reader.error);\n' +
+      '    reader.readAsDataURL(file);\n' +
+      '  });\n\n' +
+      "const url = await readAsDataUrl(file); // data: URI — never URL.createObjectURL\n" +
+      "return { id, type: 'file', filename: file.name, mediaType: file.type, url };\n" +
+      '```\n\n' +
+      '`<kai-prompt-input>`’s built-in paperclip already does this for you; the conversion ' +
+      'is only yours when you stage files yourself. With `data:` URIs there is also nothing ' +
+      'to revoke — no object-URL lifecycle to manage.',
+  },
+  {
+    // Rule 15 — mock tool calls: MockTurn.toolCalls scripts them; the HOST resolves them
+    // Source: src/state/mock.ts (MockTurn/MockToolCall), src/wire/chunk.ts (ModelTurn.toolCalls),
+    // src/state/stream.ts (upsertTool). Rung-6 F-46/F-47/F-52.
+    id: 'mock-tool-calls',
+    test: (t) => {
+      const toolContext = /tool.?call|toolCalls|input-available/i.test(t);
+      // The mock responder asked about tool calls…
+      if (/createMockResponder|mock responder|MockTurn/i.test(t) && toolContext) return true;
+      // …or a tool part parked in input-available with kai/mock context.
+      if (toolContext && /\bmock\b/i.test(t) && /kai|@kitn|stream|responder/i.test(t)) return true;
+      return false;
+    },
+    title: 'Scripting mock tool calls — `MockTurn.toolCalls`; the HOST resolves the announced call',
+    cause:
+      'Two separate facts. (1) The default mock replies are text-only, so out of the box ' +
+      '`createMockResponder()` never announces a tool call — scripting one takes a `MockTurn` ' +
+      'reply. (2) A tool call — mock or real provider — is only ever ANNOUNCED by the stream: ' +
+      'the part parks at `state: \'input-available\'` and stays there. The kit parses and ' +
+      'renders the call; EXECUTING it and answering is the host’s job.',
+    fix:
+      'Script the call with a `MockTurn` reply (`{ text?, toolCalls? }`); the mock frames it ' +
+      'announce-then-arguments with `finish_reason: \'tool_calls\'`, exactly as a real ' +
+      'OpenAI-wire turn, so it flows through `readOpenAIStream` unchanged:\n\n' +
+      '```js\n' +
+      "import { createMockResponder } from '@kitn.ai/ui/state';\n\n" +
+      'const mock = createMockResponder({\n' +
+      '  replies: [\n' +
+      "    'Plain text turn.',\n" +
+      "    { text: 'Checking…', toolCalls: [{ name: 'get_weather', arguments: { city: 'Oslo' } }] },\n" +
+      '  ],\n' +
+      '});\n' +
+      '```\n\n' +
+      'Then resolve each announced call yourself after the read settles — walk the returned ' +
+      '`ModelTurn.toolCalls` and patch the part to `output-available`:\n\n' +
+      '```js\n' +
+      'const result = await readOpenAIStream(response, stream);\n' +
+      'for (const call of result.toolCalls) {\n' +
+      '  const output = await runTool(call.name, call.input); // your side of the seam\n' +
+      "  stream.upsertTool(call.id, { state: 'output-available', output });\n" +
+      '}\n' +
+      '```\n\n' +
+      'Skip any call with `providerExecuted: true` — the provider already ran it and its ' +
+      'result arrived in-stream.',
+  },
 ];
 
 function buildText(matched: Rule[]): string {
@@ -458,10 +575,15 @@ function buildText(matched: Rule[]): string {
       'No known failure pattern matched. Suggested next steps:\n\n' +
       '1. Use the `component_reference` tool to look up the real API for the element ' +
       '(prop names, event names, attribute vs. property distinction).\n' +
-      '2. Check the **Streaming recipe** in `llms-full.txt` ' +
-      '(`node_modules/@kitn.ai/ui/llms-full.txt` or https://ui.kitn.ai/llms-full.txt) ' +
-      'for correct streaming wiring.\n' +
-      '3. Paste `https://ui.kitn.ai/llms.txt` into your prompt for a compact orientation.'
+      '2. If the problem is in host code rather than an element — streaming, ' +
+      '`createAssistantStream`, `createMockResponder`, the SSE readers, the encoders — ' +
+      'call `component_reference` with `{ name: "programmatic" }` for the full ' +
+      '`@kitn.ai/ui/state` + `@kitn.ai/ui/wire` API, and `{ name: "composed-thread" }` ' +
+      'for a complete hand-composed surface to compare wiring against.\n' +
+      '3. Check the **Streaming recipe** and the **Programmatic layer** sections in ' +
+      '`llms-full.txt` (`node_modules/@kitn.ai/ui/llms-full.txt` or ' +
+      'https://ui.kitn.ai/llms-full.txt) for correct streaming wiring.\n' +
+      '4. Paste `https://ui.kitn.ai/llms.txt` into your prompt for a compact orientation.'
     );
   }
 

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

@@ -27,6 +27,11 @@ import type { CemMember } from '../manifest';
 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,
@@ -553,6 +558,85 @@ function renderInvariantAppendix(): string[] {
   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.
  *
@@ -799,7 +883,10 @@ export const reference: Tool = {
   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.',
+    '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()
@@ -809,7 +896,10 @@ export const reference: Tool = {
           '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.',
+          '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)
@@ -865,11 +955,22 @@ export const reference: Tool = {
         `\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.';
+        '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);
     }