@kitn.ai/ui 0.26.0 → 0.27.0

package/src/agent-tooling/construct/schema.ts

@@ -0,0 +1,371 @@
+/**
+ * The construct format, v1 — Zod is the SINGLE SOURCE OF TRUTH.
+ *
+ * The published JSON Schema (apps/docs/public/schemas/construct/v1.json) and the
+ * checked-in construct.v1.schema.json are DERIVED from this object by
+ * scripts/gen-construct-schema.mjs (build:api, drift-guarded). Never edit those
+ * by hand; never restate an enum from here anywhere else — read it off
+ * `ConstructSchema.shape` or the generated artifact.
+ *
+ * Format rules (spec, binding): vocabulary never logic — no handlers, no
+ * expressions; `.strict()` everywhere so an unknown key is a loud rejection,
+ * not a silently ignored one. No secrets, no client: `provider` can name a URL
+ * and a wire format, nothing else.
+ */
+import { z } from 'zod';
+// REPO-INTERNAL ONLY: isSafeUrl is not reachable from the published package
+// (see agent-tooling/catalog/invariants.ts's own note on this), so the
+// emitted App.tsx cannot import it — the sink codegen writes to
+// (launcherIcon -> <img src>) has no guard it can reach at runtime. Enforcing
+// the SAME policy here, at authoring time, is the reachable equivalent: a
+// hostile launcherIcon is rejected before a construct ever validates, so
+// codegen never has an unsafe value to emit. Reuses the kit's one existing
+// URL-sink policy (markdown.tsx's image renderer, artifact.tsx) rather than
+// authoring a second one. Imported from url-scheme-policy.ts, NOT
+// card-routing.ts: this file compiles under tsconfig.mcp.json's Node-only, no-
+// DOM-lib pass (transitively, via mcp/tools/construct.ts), and card-routing.ts
+// pulls in HTMLElement/window/CustomEvent that pass can't see.
+import { isSafeUrl } from '../../primitives/url-scheme-policy';
+
+export const CONSTRUCT_SCHEMA_URL = 'https://ui.kitn.ai/schemas/construct/v1.json';
+
+/** A valid custom-element tag: lowercase, starts with a letter, contains a hyphen. */
+const TAG_RE = /^[a-z][a-z0-9]*-[a-z0-9-]+$/;
+
+const ProviderSchema = z.discriminatedUnion('mode', [
+  z.object({ mode: z.literal('mock') }).strict(),
+  z
+    .object({
+      mode: z.literal('endpoint'),
+      /** The CONSUMER's chat route. Kit parses, consumer fetches. */
+      url: z.string().min(1),
+      wire: z.enum(['openai', 'anthropic']),
+    })
+    .strict(),
+]);
+
+export const ConstructSchema = z
+  .object({
+    $schema: z.string().optional(),
+    /** The emitted tag: <acme-support>. Must satisfy customElements.define. */
+    name: z
+      .string()
+      .regex(TAG_RE, 'must be a valid custom-element tag: lowercase, with a hyphen (e.g. "acme-support")'),
+    // Widened progressively: fullscreen/aside/split landed in Task 12, custom in Task 13.
+    layout: z.enum(['widget', 'fullscreen', 'aside', 'split', 'custom']),
+    provider: ProviderSchema,
+    /** Plain (unsigned) identity passthrough — no signing/auth infra (owner
+     *  ruling, 2026-08-26: signed JWT/HMAC identity is later additive
+     *  vocabulary, not this field). TOP-LEVEL, not nested under `provider`:
+     *  local history scoping (`capabilities.history.persistence: 'local'`)
+     *  needs userId independent of provider mode — nesting it inside the
+     *  provider union would make it silently inert for `mode: 'mock'` +
+     *  local history, a real and common combination. Threaded as the
+     *  `x-kai-user-id` header on every emitted fetch to the CONSUMER's own
+     *  backend (the endpoint provider's chat POST, history's endpoint
+     *  GET/PUT), and folded into the localStorage key for `local` history so
+     *  different users on the same browser profile don't share one thread.
+     *  Constrained to printable-ASCII (no CR/LF, no non-ISO-8859-1 code
+     *  points) beyond the usual construct-authored-text escaping: this value
+     *  reaches an HTTP HEADER VALUE, not just a JS string literal, and
+     *  `fetch()` throws at RUNTIME on a header value containing CR/LF or
+     *  outside ISO-8859-1 — a bad userId would surface as an opaque crash in
+     *  the CONSUMER's generated app, not a construct-validation error. Reject
+     *  loudly here instead, where the author gets a path + message. */
+    userId: z
+      .string()
+      .min(1)
+      .regex(
+        /^[\x20-\x7E]+$/,
+        'must be printable ASCII with no line breaks (it becomes an HTTP header value)',
+      )
+      .optional(),
+    theme: z
+      .object({
+        /** Any CSS color; becomes --kai-color-primary on the host. */
+        accent: z.string().optional(),
+        mode: z.enum(['light', 'dark', 'system']).default('system'),
+      })
+      .strict()
+      .optional(),
+    /** Construct-wide header chrome, valid on every layout (not layout-scoped
+     *  like `widget`, and not a capability toggle — a header is a construct-
+     *  wide fact, like `theme`). Rendered inside ChatThread's own built-in
+     *  header bar; a logo/icon projects through the kit's EXISTING
+     *  `header-start` named slot (`slots` vocabulary above), not a second
+     *  image-prop convention here. */
+    header: z
+      .object({
+        /** Rendered in ChatThread's built-in header bar (left side). Construct-
+         *  authored/untrusted text, like theme.accent/provider.url — JSON.stringify'd
+         *  at its one emit site, never a raw JSX attribute string. */
+        title: z.string().min(1).optional(),
+      })
+      .strict()
+      .optional(),
+    /** Greeting shown while the thread is empty (no messages yet) — the
+     *  proven "welcome screen" pattern (Intercom-class): title + optional
+     *  description + optional icon above, with `capabilities.starters`'
+     *  chips and the composer still rendering below (ChatThread's `empty`
+     *  REPLACE slot only stands in for the empty MESSAGE LIST — see
+     *  chat-thread.tsx's own doc comment on `empty` — so the chips are
+     *  never lost). Construct-wide like `header`, not a capability: it's a
+     *  fact about the empty state, not a toggleable affordance.
+     *  `title`/`description` are construct-authored/untrusted text, like
+     *  `header.title`/`theme.accent`/`provider.url` — JSON.stringify'd at
+     *  their one emit site, never a raw JSX attribute string. `icon` is a
+     *  URL reaching an `<img src>` sink in emitted code, exactly like
+     *  `widget.launcherIcon` — same `isSafeUrl` policy, same superRefine
+     *  shape, below. */
+    empty: z
+      .object({
+        title: z.string().min(1),
+        description: z.string().min(1).optional(),
+        icon: z.string().min(1).optional(),
+      })
+      .strict()
+      .optional(),
+    // Capability vocabulary, widened one field at a time by later tasks.
+    capabilities: z
+      .object({
+        /** Starter prompts shown on the empty thread; clicking one sends it.
+         *  1-6 non-empty strings — construct-authored text, escaped like
+         *  `theme.accent`/`provider.url` at every emit interpolation site. */
+        starters: z.array(z.string().min(1)).min(1).max(6).optional(),
+        /** Enables the paperclip attach affordance; accept is a non-empty
+         *  list of media types/globs, e.g. ["image/*", "application/pdf"] —
+         *  WHETHER stays with the construct author (this field), HOW stays
+         *  with the kit (ChatThread's own attach/accept props, threaded
+         *  through by codegen). */
+        attachments: z
+          .object({
+            /** Accept-list of media types/globs, e.g. ["image/*", "application/pdf"]. */
+            accept: z.array(z.string().min(1)).min(1),
+          })
+          .strict()
+          .optional(),
+        /** Conversation persistence. `none` (default, nothing emitted): the
+         *  thread lives only in memory for the tab's lifetime. `local`:
+         *  persisted to this browser's localStorage, keyed by the construct's
+         *  tag — a mechanism decision (WHERE); what to retain and for how
+         *  long stays an app decision (component-scope-boundary), so no
+         *  retention count/quota lands here. `endpoint`: the CONSUMER's own
+         *  thread route (GET returns ChatMessage[], PUT stores them) —
+         *  requires `url`; `url` is rejected for any other persistence
+         *  (superRefine below, both directions loud). */
+        history: z
+          .object({
+            persistence: z.enum(['none', 'local', 'endpoint']),
+            /** endpoint persistence only: the CONSUMER's thread routes (GET returns
+             *  ChatMessage[], PUT stores them). Refined below. */
+            url: z.string().min(1).optional(),
+          })
+          .strict()
+          .optional(),
+        /** How the model's thinking (reasoning parts) renders. `'full'`
+         *  (the default when omitted — see codegen.ts's emitReasoningProp)
+         *  is the collapsible "Thinking" disclosure, shimmering while it
+         *  streams. `'compact'` shows only a shimmer/typing loader while
+         *  reasoning streams, with no expandable detail. `'off'` hides
+         *  reasoning entirely. This is HOW an existing medium fact (the
+         *  model's thinking) displays — the kit's call — so it maps straight
+         *  onto ChatThread's own `reasoning` prop; there is no app-layer
+         *  quota or retention decision hiding in it. Left `.optional()`
+         *  rather than `.default('full')`, matching every sibling field in
+         *  this object: a zod `.default()` here would make `reasoning`
+         *  REQUIRED on the inferred input type (z.infer is the output type),
+         *  breaking every `capabilities: {...}` object literal in this file
+         *  and its tests that doesn't mention it. */
+        reasoning: z.enum(['full', 'compact', 'off']).optional(),
+        /** Seeds the reasoning disclosure open AND keeps it tracking the
+         *  stream (open while streaming, closes when it settles) — the
+         *  pre-Task-19f `full` behavior. Default false/absent: the panel
+         *  starts closed (just the "Thinking" shimmer chip) and only opens
+         *  on click — the current default (owner ruling, 2026-08-26).
+         *  Meaningless when `reasoning` is `'compact'` (no expandable
+         *  content exists) or `'off'` (nothing renders); rejected on both,
+         *  loudly, below. */
+        reasoningOpen: z.boolean().optional(),
+      })
+      .strict()
+      .optional(),
+    /** Named generative-UI card definitions the model can emit as tool calls,
+     *  rendered in the thread. Top-level (not a capability): a card is
+     *  something the construct's model can DO at any point once a card is
+     *  declared, not a thread-affordance toggle like starters/attachments/
+     *  reasoning. Reuses the kit's own card-tool projection end to end
+     *  (`cardTools`/`toOpenAITools`/`toAnthropicTools`, `@kitn.ai/ui/schemas`)
+     *  — never a second one authored here. `schema` is validated structurally
+     *  only; deep card validation (incl. `x-kai-format` mask hints) is the
+     *  kit's own card contract at render time. */
+    cards: z
+      .array(
+        z
+          .object({
+            /** Tool-facing card name, e.g. "refund_approval". */
+            name: z.string().regex(/^[a-z][a-z0-9_]*$/),
+            /** The kit's card schema JSON (incl. x-kai-format mask hints).
+             *  Validated structurally here; deep card validation is the kit's
+             *  own card contract at render time. */
+            schema: z.record(z.string(), z.unknown()),
+          })
+          .strict(),
+      )
+      .min(1)
+      .optional(),
+    /** Named `<slot>` projection points the emitted web component exposes —
+     *  the format's ONLY escape hatch (named slots, no code-in-JSON). Each
+     *  name must be a valid HTML slot-attribute value AND a legible
+     *  identifier: kebab-case, starting with a letter (the same shape as a
+     *  CSS custom-ident) — `slot name="Header!"` is rejected, not sanitized,
+     *  matching the format's loud-rejection discipline everywhere else.
+     *  1-8 entries, no duplicates (superRefine below — a regex alone can't
+     *  see across array entries). `layout: 'custom'` requires at least one
+     *  declared slot (superRefine below): `custom` IS the slots grain — a
+     *  `custom` layout with nothing to project into is not meaningfully
+     *  different from `fullscreen`. */
+    slots: z
+      .array(z.string().regex(/^[a-z][a-z0-9-]*$/, 'slot names must be kebab-case, starting with a letter'))
+      .min(1)
+      .max(8)
+      .optional(),
+    /** Layout-scoped FAB chrome, `layout: 'widget'` only (superRefine below).
+     *  Purely additive sibling to `layout` (widen-never-restructure) — mirrors
+     *  Dock's own props verbatim, threaded through by codegen's emitLayoutOpen. */
+    widget: z
+      .object({
+        /** Which corner. Mirrors Dock's own DockPosition enum verbatim — not a
+         *  new left/right binary. Omitted keeps Dock's own default (bottom-end). */
+        position: z.enum(['bottom-end', 'bottom-start', 'top-end', 'top-start']).optional(),
+        /** An image URL for the closed-state launcher glyph, replacing Dock's
+         *  built-in chat-bubble icon. Construct-authored/untrusted text, like
+         *  theme.accent and provider.url — escaped the same way at its one emit site. */
+        launcherIcon: z.string().min(1).optional(),
+        /** Seed Dock's open state at mount. Uncontrolled — never steals focus (Dock's
+         *  own focus contract, dock.tsx). Omitted keeps Dock's own default (closed). */
+        defaultOpen: z.boolean().optional(),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict()
+  .superRefine((construct, ctx) => {
+    if (construct.slots) {
+      const seen = new Set<string>();
+      construct.slots.forEach((name, i) => {
+        if (seen.has(name)) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['slots', i],
+            message: `duplicate slot name "${name}"`,
+          });
+        }
+        seen.add(name);
+      });
+    }
+    if (construct.layout === 'custom' && (!construct.slots || construct.slots.length === 0)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['slots'],
+        message: '"custom" layout requires at least one declared slot — custom IS the slots grain',
+      });
+    }
+    if (construct.layout === 'split' && construct.slots) {
+      const i = construct.slots.indexOf('pane');
+      if (i !== -1) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ['slots', i],
+          message:
+            '"pane" collides with the "split" layout\'s own fixed <slot name="pane"> — choose a different slot name',
+        });
+      }
+    }
+    if (construct.widget && construct.layout !== 'widget') {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['widget'],
+        message: '"widget" is only valid on layout: "widget"',
+      });
+    }
+    if (construct.widget?.launcherIcon && !isSafeUrl(construct.widget.launcherIcon)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['widget', 'launcherIcon'],
+        message: 'launcherIcon must be an http(s)/mailto or relative URL — no javascript:/data: schemes',
+      });
+    }
+    if (construct.empty?.icon && !isSafeUrl(construct.empty.icon)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['empty', 'icon'],
+        message: 'icon must be an http(s)/mailto or relative URL — no javascript:/data: schemes',
+      });
+    }
+    const reasoning = construct.capabilities?.reasoning;
+    const reasoningOpen = construct.capabilities?.reasoningOpen;
+    if (reasoningOpen !== undefined && (reasoning === 'compact' || reasoning === 'off')) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['capabilities', 'reasoningOpen'],
+        message: '"reasoningOpen" only applies when reasoning is "full" or omitted — "compact"/"off" have no disclosure to open',
+      });
+    }
+    const history = construct.capabilities?.history;
+    if (!history) return;
+    if (history.persistence === 'endpoint' && !history.url) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['capabilities', 'history', 'url'],
+        message: '"endpoint" persistence requires a url',
+      });
+    }
+    if (history.persistence !== 'endpoint' && history.url !== undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['capabilities', 'history', 'url'],
+        message: 'url is only valid with "endpoint" persistence',
+      });
+    }
+  });
+
+export type Construct = z.infer<typeof ConstructSchema>;
+
+export interface ConstructProblem {
+  /** Dotted path into the construct, '' for the root. */
+  path: string;
+  message: string;
+}
+
+export type ValidationOutcome =
+  | { ok: true; construct: Construct }
+  | { ok: false; problems: ConstructProblem[] };
+
+/**
+ * Validate one construct. The ONLY doorway to codegen: a failure never reaches
+ * generation — the problems go back to the author/agent with paths and reasons.
+ */
+export function validateConstruct(input: unknown): ValidationOutcome {
+  const parsed = ConstructSchema.safeParse(input);
+  if (parsed.success) return { ok: true, construct: parsed.data };
+  return {
+    ok: false,
+    problems: parsed.error.issues.flatMap((issue) => {
+      // zod's unrecognized-key issue names the keys in its message but paths the
+      // OBJECT; surface each unknown key as its own problem so the agent sees
+      // exactly which word is not vocabulary.
+      if (issue.code === 'unrecognized_keys') {
+        return issue.keys.map((key) => ({
+          path: [...issue.path.map(String), key].join('.'),
+          message: `"${key}" is not construct vocabulary`,
+        }));
+      }
+      return [
+        {
+          path: issue.path.map(String).join('.'),
+          message: issue.message,
+        },
+      ];
+    }),
+  };
+}

package/src/agent-tooling/mcp/server.ts

@@ -9,10 +9,11 @@ import { reference } from './tools/reference';
 import { scaffold } from './tools/scaffold';
 import { theme } from './tools/theme';
 import { debug } from './tools/debug';
+import { constructTool } from './tools/construct';
 import type { Tool } from './tools/types';
 import { validateToolArgs } from './validate-args';
 
-const tools: Tool[] = [reference, scaffold, theme, debug];
+const tools: Tool[] = [reference, scaffold, theme, debug, constructTool];
 
 const PACKAGE_NAME = '@kitn.ai/ui';
 

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

@@ -0,0 +1,130 @@
+import { z } from 'zod';
+import type { Tool } from './types';
+import { validateConstruct, CONSTRUCT_SCHEMA_URL } from '../../construct/schema';
+
+/**
+ * construct — turn-by-turn authoring of a kitn construct (one JSON file → one
+ * web component). Stateless by design: the HARNESS owns the construct file;
+ * every call carries the full construct for THIS turn — that is what makes
+ * turn 40 safe, there is no server-side draft to corrupt.
+ *
+ * Two entry shapes: `intent` alone returns a STARTER construct plus the
+ * real-choice questions the intent leaves open (menu-honesty: never ask a
+ * question the intent already answers). `construct` (optionally with
+ * `intent`) validates — rejection is a NORMAL, non-error result, not a thrown
+ * error, because an invalid turn does not change the file: the previous good
+ * construct still stands.
+ *
+ * NOTE on the advertised schema: `Tool.inputSchema` is a plain `z.ZodObject`,
+ * and both `server.ts` (`z.toJSONSchema`) and `validate-args.ts`
+ * (`schema.shape`) need that exact shape — a `.superRefine` wrapper is a
+ * `ZodEffects`-like type with no `.shape`, so it can't be `tool.inputSchema`.
+ * The advertised schema therefore stays a plain `.strict()` object; the
+ * "at least one of intent/construct" rule is enforced here in the handler
+ * with the same message the skeleton's superRefine would have produced.
+ */
+
+const inputSchema = z
+  .object({
+    intent: z
+      .string()
+      .min(1)
+      .optional()
+      .describe('What the author wants, in their words. Alone: returns a starter construct.'),
+    construct: z
+      .record(z.string(), z.unknown())
+      .optional()
+      .describe('The FULL construct JSON for this turn. The harness owns the file; send all of it every turn.'),
+  })
+  .strict();
+
+function starterFor(intent: string) {
+  // Derive what the intent already implies; ask only what it leaves open.
+  const impliesWidget = /widget|embed|bubble|corner|launcher/i.test(intent);
+  const name = 'my-chat'; // real-choice: always ask for the tag name (it is theirs)
+  return {
+    construct: {
+      $schema: CONSTRUCT_SCHEMA_URL,
+      name,
+      layout: 'widget',
+      provider: { mode: 'mock' },
+    },
+    stated: impliesWidget ? ['layout: widget (implied by your request)'] : [],
+    questions: [
+      `What should the element tag be? (kebab-case, e.g. "acme-support"; using "${name}" until you say)`,
+      ...(impliesWidget ? [] : ['Layout: widget, fullscreen, aside, split, or custom?']),
+    ],
+  };
+}
+
+export const constructTool: Tool = {
+  name: 'construct',
+  description:
+    'Author a kitn construct (one JSON file → one web component) turn by turn. ' +
+    'Send the full construct each turn; invalid turns come back REJECTED with per-path reasons and the previous good construct stands. ' +
+    `Schema: ${CONSTRUCT_SCHEMA_URL}. Preview with "kai dev <file>".`,
+  inputSchema,
+  handler: async (args) => {
+    const { intent, construct } = args as { intent?: string; construct?: Record<string, unknown> };
+
+    if (!intent && !construct) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: 'construct: pass intent, construct, or both' }],
+      };
+    }
+
+    if (!construct) {
+      const s = starterFor(intent ?? '');
+      return {
+        content: [
+          {
+            type: 'text',
+            text: [
+              'STARTER construct (mock provider — keyless, previews immediately):',
+              '```json',
+              JSON.stringify(s.construct, null, 2),
+              '```',
+              ...s.stated,
+              ...s.questions,
+            ].join('\n'),
+          },
+        ],
+      };
+    }
+
+    const out = validateConstruct(construct);
+    if (!out.ok) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: [
+              'REJECTED — this turn does not change the file; the previous good construct stands.',
+              ...out.problems.map((p) => `  ${p.path || '(root)'}: ${p.message}`),
+            ].join('\n'),
+          },
+        ],
+      };
+    }
+
+    const c = out.construct;
+    return {
+      content: [
+        {
+          type: 'text',
+          text: [
+            `VALID: <${c.name}> (${c.layout}, ${c.provider.mode}).`,
+            '```json',
+            JSON.stringify(c, null, 2),
+            '```',
+            `Preview: kai dev <file>. Compile: kai compile <file>.`,
+            ...(c.provider.mode === 'endpoint'
+              ? ['Backend route: use the scaffold tool — it emits a compiling route for your framework and wire.']
+              : []),
+          ].join('\n'),
+        },
+      ],
+    };
+  },
+};

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.'
     );
   }