@kitn.ai/ui 0.22.1 → 0.23.0

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

@@ -8,6 +8,13 @@ import {
   listArchetypes,
   listIntegrations,
 } from '../../registry';
+// The route-emission facts, read rather than restated — and deliberately living
+// OUTSIDE this file. This module builds its zod input schema at module scope, so
+// a bundler asked for one of these three has to keep all 5,300 lines of it and
+// all of zod with them; `create-kai`'s CLI bundle went 203 kB -> 904 kB when they
+// were exported from here. See the header of `route-emit.ts`. Import FROM there,
+// never re-export through here.
+import { chatRoutePreamble, defaultModelFor } from '../../route-emit';
 // The kit's media-type declaration, read rather than restated. This is the one
 // import in agent-tooling that reaches outside itself, and the module it reaches
 // for is the reason: `wire/media-types.ts` is pure (no I/O, no DOM, no solid-js),
@@ -68,11 +75,11 @@ interface PlacementStyle {
   altNote?: string[];
 }
 
-// The chat element must fill its container. In a `display: flex; flex-direction:
-// column` shell it's a flex child (`flex: 1; min-height: 0`); in a plain block
-// container it fills via `height: 100%`.
+// The chat element must fill its container. Every placement below is a
+// `display: flex; flex-direction: column` shell, so the element is always a flex
+// child and this is the only fill there is. A `height: 100%` variant for a plain
+// block container used to sit here beside it; nothing ever selected it.
 const FLEX_FILL = 'flex: 1; min-height: 0;';
-const BLOCK_FILL = 'height: 100%; width: 100%;';
 
 /**
  * full-page, and it has to be true in a STOCK starter — not just in an empty page.
@@ -808,65 +815,6 @@ function realBodyPayload(opts: { defaultModel?: string; tools: boolean }): (thre
   };
 }
 
-// ── SCAF-8: per-integration default model ids ─────────────────────────────────
-
-/**
- * Default model id per integration whose route forwards one.
- *
- * THE ID IS HOST-SPECIFIC, and there is no such thing as a safe generic one.
- * This used to fall through to `'openai/gpt-4o-mini'` for anything unlisted, on
- * the reasoning that "a route that forwards the client's model is by definition
- * pointed at an OpenAI-compatible endpoint". That was false twice over the
- * moment a first-party provider landed: `openai/gpt-4o-mini` is an OPENROUTER
- * slug — api.openai.com 404s the prefixed form, and api.anthropic.com rejects it
- * outright — so a scaffold generated for the provider it names could not run
- * against it.
- *
- * tsc cannot see any of this; every one of those strings compiles. The guard is
- * `scaffold.test.ts` → "the emitted model id is valid for the host its route
- * POSTs to", which reads the id out of the EMITTED scaffold and the host out of
- * the route source, so a new integration cannot reintroduce a wrong one.
- */
-const CLIENT_MODEL_IDS: Record<string, string> = {
-  // Vendor-prefixed `vendor/model`: OpenRouter's own id space, and the ONLY one
-  // of the three where the prefix belongs.
-  openrouter: 'openai/gpt-4o-mini',
-  // No vendor prefix. This is what the route already pinned, so moving the knob
-  // to the client changes the wire not at all.
-  openai: 'gpt-4o-mini',
-  // Anthropic's id space. Matches what the route pinned; 'claude-sonnet-5' and
-  // 'claude-haiku-4-5' are the cheaper swaps (see this integration's runNote).
-  anthropic: 'claude-opus-5',
-};
-
-/**
- * The default model id for an integration whose ROUTE reads the client's `model`
- * field, and undefined for every other one.
- *
- * This used to be a substring test (`routeSrc.includes('model')`), which is true
- * of any template that so much as writes `model: 'llama3.2'`. That emitted an
- * editable `const model` into ollama, langgraph, vercel-ai-sdk and cloudflare
- * scaffolds whose routes pin their own model and never read the field, so
- * changing it did nothing, and cloudflare's default was not even a valid Workers
- * AI id. `forwardsFromClient` states the fact instead of guessing at it.
- */
-function defaultModelFor(integration: Integration): string | undefined {
-  if (!integration.forwardsFromClient.includes('model')) return undefined;
-  const id = CLIENT_MODEL_IDS[integration.id];
-  // No fallback, deliberately — the old `?? 'openai/gpt-4o-mini'` is what let a
-  // first-party provider inherit an OpenRouter slug and emit a scaffold that
-  // 404s on its own host. A model id is a per-host fact; an integration that
-  // forwards one has to say which.
-  if (id === undefined) {
-    throw new Error(
-      `Integration '${integration.id}' forwards the client's 'model' but has no CLIENT_MODEL_IDS entry, so the ` +
-        `scaffold would emit a model id that is not valid for the host its route POSTs to. Add one in ` +
-        `mcp/tools/scaffold.ts.`,
-    );
-  }
-  return id;
-}
-
 /**
  * True when the scaffold should declare tool schemas and put them in the body.
  *
@@ -3499,7 +3447,17 @@ function renderSolid(components: readonly string[], ctx: RenderCtx): string {
       `            // shortened the array.`,
       `            <Show when={messages()[i()]}>`,
       `              {(m) => (`,
-      `                <Message class={\`mx-auto flex w-full max-w-3xl flex-col gap-2 px-6 \${m().role === 'user' ? 'items-end' : 'items-start'}\`}>`,
+      `                <Message`,
+      `                  // \`role\` is the SPEAKER, not an ARIA role — <Message> turns it`,
+      `                  // into role="article" plus an aria-label naming the speaker, and`,
+      `                  // a data-role hook for styling. Omit it and the row is an`,
+      `                  // unlabelled <div> that tells a screen reader nothing about who`,
+      `                  // is talking. The alignment class below reads the SAME value: if`,
+      `                  // you are deriving CSS from a semantic field, the semantics have`,
+      `                  // to reach the DOM too.`,
+      `                  role={m().role}`,
+      `                  class={\`mx-auto flex w-full max-w-3xl flex-col gap-2 px-6 \${m().role === 'user' ? 'items-end' : 'items-start'}\`}`,
+      `                >`,
       `                  {/* <Index>, not <For>, INSIDE a message. The state folds only`,
       `                      ever append a part or patch one in place — they never`,
       `                      reorder — so a part's POSITION is a stable identity, and`,
@@ -4478,122 +4436,6 @@ const WEB_ROUTE_ADAPTERS: Record<string, WebRouteAdapter> = {
   },
 };
 
-/**
- * The request body, declared once per route file.
- *
- * `await request.json()` is `unknown` — it is whatever the client sent — so
- * destructuring it directly is TS2339 on EVERY field. That is not pedantry: it
- * is a hard `npm run build` failure the moment a Node-typed project compiles the
- * route, where `Request` comes from undici (`json(): Promise<unknown>`) rather
- * than from the DOM lib (`json(): Promise<any>`). A stock Vite app does exactly
- * that — `tsc -b` walks vite.config.ts → vite-chat-api.ts → src/server/chat.ts
- * with `lib` and no DOM — so the route ran fine and the build did not.
- *
- * `messages` is typed as the kit's OWN encoder output rather than restated
- * structurally, which keeps the two halves of the scaffold pinned to one type:
- * the front end sends `toOpenAIMessages(thread)`, and this is what that returns.
- * The import is type-only and erases at build time, so the route ships no
- * runtime dependency on the kit.
- */
-const CHAT_REQUEST_BODY_IMPORT = `import type { OpenAIWireMessage } from '@kitn.ai/ui/wire';`;
-const CHAT_REQUEST_BODY_DECL = [
-  `/**`,
-  ` * What the front end POSTs. \`request.json()\` is \`unknown\` (it is whatever the`,
-  ` * client sent), so the body is narrowed once here instead of at every use —`,
-  ` * without it this route does not compile under a server tsconfig. Widen it as`,
-  ` * you add fields of your own.`,
-  ` */`,
-  `type ChatRequestBody = {`,
-  `  messages: OpenAIWireMessage[];`,
-  `  model?: string;`,
-  `  tools?: unknown[];`,
-  `};`,
-  ``,
-  `/** Narrow the JSON body once, at the edge. */`,
-  `async function readChatRequest(request: Request): Promise<ChatRequestBody> {`,
-  `  return (await request.json()) as ChatRequestBody;`,
-  `}`,
-];
-
-/**
- * Attachments, on the way IN.
- *
- * A user turn's `content` is a plain string until it carries a file, at which
- * point `toOpenAIMessages` emits the ARRAY form. Every route that re-maps
- * messages into some other SDK's shape has to handle both, and the three that do
- * (anthropic, mastra, vercel-ai-sdk) were each written when only the string form
- * existed — so each one would have quietly dropped the attachment while still
- * compiling, which is the same defect the encoder was just fixed for.
- *
- * These two helpers are the shared half of that: flattening the wire shape is
- * identical everywhere, while the target shape is not, so each route maps
- * `WirePart[]` into its own SDK itself rather than inheriting a lowest common
- * denominator.
- *
- * Only injected into routes that actually call them — the eight pass-through
- * integrations forward `messages` untouched and need none of this, and an unused
- * declaration is a hard error under the gate's `--noUnusedLocals`.
- */
-const CONTENT_PARTS_DECL = [
-  `/** Where an attachment's bytes are: inline base64, or an address the PROVIDER`,
-  ` *  fetches. Never both. */`,
-  `type WireFileSource = { type: 'data'; data: string } | { type: 'url'; url: string };`,
-  ``,
-  `/** One piece of a turn, with the string and array content forms flattened into`,
-  ` *  a single shape. */`,
-  `type WirePart =`,
-  `  | { kind: 'text'; text: string }`,
-  `  | { kind: 'file'; mediaType: string; filename?: string; source: WireFileSource };`,
-  ``,
-  `const DATA_URI = /^data:([^;,]+);base64,([\\s\\S]*)$/;`,
-  ``,
-  `/**`,
-  ` * Flatten a wire message's content into parts.`,
-  ` *`,
-  ` * An image sent by URL has no media type here — \`image_url\` carries only the`,
-  ` * address — so it reports the top-level segment \`'image'\`, which is all a URL`,
-  ` * source needs. Only images can reach that branch: the kit refuses to encode a`,
-  ` * remote PDF rather than guess at one.`,
-  ` */`,
-  `function wireParts(content: OpenAIWireMessage['content']): WirePart[] {`,
-  `  if (content == null) return [];`,
-  `  if (typeof content === 'string') return content === '' ? [] : [{ kind: 'text', text: content }];`,
-  `  return content.map((part): WirePart => {`,
-  `    if (part.type === 'text') return { kind: 'text', text: part.text };`,
-  `    if (part.type === 'image_url') {`,
-  `      const asData = DATA_URI.exec(part.image_url.url);`,
-  `      return asData`,
-  `        ? { kind: 'file', mediaType: asData[1], source: { type: 'data', data: asData[2] } }`,
-  `        : { kind: 'file', mediaType: 'image', source: { type: 'url', url: part.image_url.url } };`,
-  `    }`,
-  `    const asData = DATA_URI.exec(part.file.file_data);`,
-  `    if (!asData) {`,
-  `      // LOUD on purpose. \`file_data\` is a data URI on this wire; anything else`,
-  `      // cannot be turned into bytes without fetching it, and forwarding a turn`,
-  `      // with the attachment quietly missing is the bug this whole path exists`,
-  `      // to prevent.`,
-  `      throw new Error(`,
-  `        'Unsupported file content part: file_data must be a data: URI of the form data:<media type>;base64,<data>.',`,
-  `      );`,
-  `    }`,
-  `    return {`,
-  `      kind: 'file',`,
-  `      mediaType: asData[1],`,
-  `      filename: part.file.filename,`,
-  `      source: { type: 'data', data: asData[2] },`,
-  `    };`,
-  `  });`,
-  `}`,
-  ``,
-  `/** Just the text of a turn. System, assistant and tool messages are text-only`,
-  ` *  on this wire, so this collapses the array form for them. */`,
-  `function wireText(content: OpenAIWireMessage['content']): string {`,
-  `  return wireParts(content)`,
-  `    .map((p) => (p.kind === 'text' ? p.text : ''))`,
-  `    .join('');`,
-  `}`,
-];
-
 /**
  * Slot the body type in just above `chatHandler`.
  *
@@ -4603,12 +4445,7 @@ const CONTENT_PARTS_DECL = [
  * block that documents it — puts the declaration where a person would have
  * written it.
  */
-function withChatRequestBody(fragment: string): string {
-  // The content helpers ride along only where the route calls them; see
-  // CONTENT_PARTS_DECL for why an unconditional injection would not compile.
-  const decl = /\bwire(?:Parts|Text)\s*\(/.test(fragment)
-    ? [...CHAT_REQUEST_BODY_DECL, ``, ...CONTENT_PARTS_DECL]
-    : CHAT_REQUEST_BODY_DECL;
+function withChatRequestBody(fragment: string, decl: readonly string[]): string {
   const lines = fragment.split('\n');
   let at = lines.findIndex((l) => /^(?:export\s+)?async function chatHandler\b/.test(l));
   if (at < 0) return [...decl, ``, ...lines].join('\n');
@@ -4625,17 +4462,22 @@ function webRouteFor(integration: Integration, framework: string): RouteChoice |
   // pull in an import to do it (SvelteKit's $env accessor). Both land at the top
   // of the file, beside the adapter's own `before` lines.
   const adapted = adapter.adaptFragment?.(fragment) ?? { fragment, imports: [] };
+  // One preamble for the whole file: its `imports` go at the top beside the
+  // adapter's own, its `decl` immediately above the handler. Both halves come
+  // from `chatRoutePreamble` rather than from a constant here, so this emitter
+  // and `create-kai`'s cannot answer "what does this route need" differently.
+  const preamble = chatRoutePreamble(adapted.fragment);
   return {
     framework,
     runtime: adapter.runtime,
     exact: true,
     template: [
       `// ${adapter.file}`,
-      CHAT_REQUEST_BODY_IMPORT,
+      ...preamble.imports,
       ...(adapter.before ?? []),
       ...adapted.imports,
       ``,
-      withChatRequestBody(adapted.fragment),
+      withChatRequestBody(adapted.fragment, preamble.decl),
       ...adapter.after,
     ].join('\n'),
   };

package/src/agent-tooling/route-emit.ts

@@ -0,0 +1,281 @@
+/**
+ * What a second emitter needs in order to write a chat route to a real file.
+ *
+ * Three facts live here, and they are the three a consumer that writes handlers
+ * to disk cannot do without: `chatRoutePreamble` (what goes above a bare
+ * `Integration.webRoute` so it compiles), and `CLIENT_MODEL_IDS` +
+ * `defaultModelFor` (whether the front end sends a model, and which id is valid
+ * for the host its route POSTs to). The `kai` MCP's own emitter in
+ * `mcp/tools/scaffold.ts` imports them from here, so there is one code path and
+ * the two emitters cannot disagree.
+ *
+ * WHY THIS IS ITS OWN MODULE, AND WHY IT MUST STAY A LEAF. These three were
+ * exported from `mcp/tools/scaffold.ts`, which is ~5,300 lines and builds a zod
+ * schema at MODULE SCOPE (`scaffold.inputSchema = z.object({…})`). A side effect
+ * at module scope is not tree-shakeable, so a bundler asked for
+ * `chatRoutePreamble` alone had to keep the whole file and all of zod with it.
+ * Measured on `create-kai`, whose CLI is one bundled zero-dependency file:
+ * **203 kB -> 904 kB**, of which 505 kB was zod the CLI never executes, on every
+ * `npx create-kai`. It also pulled 5,300 lines of kit source into `create-kai`'s
+ * `tsc` program under `--noUnusedLocals`, a flag the kit's own typecheck does not
+ * run, which forced an unrelated deletion in the kit to keep the CLI green.
+ *
+ * So the rule for this file is a rule about its IMPORTS, not its size: nothing
+ * here may import a module that reaches zod, the registry, or the integration
+ * catalog. `import type` is fine — it erases. Today that means exactly one
+ * import, and it is type-only. `create-kai`'s build guard
+ * (`bundleGraphProblem` in its `src/build-guards.ts`) fails the CLI build if zod
+ * ever reappears in the bundle, which is the check that turns this paragraph
+ * into something that can go red.
+ *
+ * NOT RE-EXPORTED from `mcp/tools/scaffold.ts`, deliberately. A second import
+ * path for the same symbol is how the fat one gets picked again.
+ */
+import type { Integration } from './types';
+
+// ── SCAF-8: per-integration default model ids ─────────────────────────────────
+
+/**
+ * Default model id per integration whose route forwards one.
+ *
+ * THE ID IS HOST-SPECIFIC, and there is no such thing as a safe generic one.
+ * This used to fall through to `'openai/gpt-4o-mini'` for anything unlisted, on
+ * the reasoning that "a route that forwards the client's model is by definition
+ * pointed at an OpenAI-compatible endpoint". That was false twice over the
+ * moment a first-party provider landed: `openai/gpt-4o-mini` is an OPENROUTER
+ * slug — api.openai.com 404s the prefixed form, and api.anthropic.com rejects it
+ * outright — so a scaffold generated for the provider it names could not run
+ * against it.
+ *
+ * tsc cannot see any of this; every one of those strings compiles. The guard is
+ * `scaffold.test.ts` → "the emitted model id is valid for the host its route
+ * POSTs to", which reads the id out of the EMITTED scaffold and the host out of
+ * the route source, so a new integration cannot reintroduce a wrong one.
+ *
+ * EXPORTED because a route is only half of the fact. `openrouter`'s handler puts
+ * the client's `model` straight into its upstream payload, so a front end that
+ * posts `{ messages }` alone sends no model, OpenRouter answers 400, and nothing
+ * in a build or a typecheck can see it. Any second emitter of these routes needs
+ * the same table; `defaultModelFor` below is the accessor, and the raw table is
+ * exported alongside it so a consumer can also check it for drift at ITS build
+ * time rather than discovering a missing row when a user types.
+ */
+export const CLIENT_MODEL_IDS: Record<string, string> = {
+  // Vendor-prefixed `vendor/model`: OpenRouter's own id space, and the ONLY one
+  // of the three where the prefix belongs.
+  openrouter: 'openai/gpt-4o-mini',
+  // No vendor prefix. This is what the route already pinned, so moving the knob
+  // to the client changes the wire not at all.
+  openai: 'gpt-4o-mini',
+  // Anthropic's id space. Matches what the route pinned; 'claude-sonnet-5' and
+  // 'claude-haiku-4-5' are the cheaper swaps (see this integration's runNote).
+  anthropic: 'claude-opus-5',
+};
+
+/**
+ * The default model id for an integration whose ROUTE reads the client's `model`
+ * field, and undefined for every other one.
+ *
+ * This used to be a substring test (`routeSrc.includes('model')`), which is true
+ * of any template that so much as writes `model: 'llama3.2'`. That emitted an
+ * editable `const model` into ollama, langgraph, vercel-ai-sdk and cloudflare
+ * scaffolds whose routes pin their own model and never read the field, so
+ * changing it did nothing, and cloudflare's default was not even a valid Workers
+ * AI id. `forwardsFromClient` states the fact instead of guessing at it.
+ *
+ * Exported for the same reason as `CLIENT_MODEL_IDS`: a second emitter of these
+ * routes has to answer "does this front end send a model, and which" the same
+ * way, and both halves of that answer live here.
+ */
+export function defaultModelFor(integration: Integration): string | undefined {
+  if (!integration.forwardsFromClient.includes('model')) return undefined;
+  const id = CLIENT_MODEL_IDS[integration.id];
+  // No fallback, deliberately — the old `?? 'openai/gpt-4o-mini'` is what let a
+  // first-party provider inherit an OpenRouter slug and emit a scaffold that
+  // 404s on its own host. A model id is a per-host fact; an integration that
+  // forwards one has to say which.
+  if (id === undefined) {
+    throw new Error(
+      `Integration '${integration.id}' forwards the client's 'model' but has no CLIENT_MODEL_IDS entry, so the ` +
+        `scaffold would emit a model id that is not valid for the host its route POSTs to. Add one in ` +
+        `agent-tooling/route-emit.ts.`,
+    );
+  }
+  return id;
+}
+
+/**
+ * The request body, declared once per route file.
+ *
+ * `await request.json()` is `unknown` — it is whatever the client sent — so
+ * destructuring it directly is TS2339 on EVERY field. That is not pedantry: it
+ * is a hard `npm run build` failure the moment a Node-typed project compiles the
+ * route, where `Request` comes from undici (`json(): Promise<unknown>`) rather
+ * than from the DOM lib (`json(): Promise<any>`). A stock Vite app does exactly
+ * that — `tsc -b` walks vite.config.ts → vite-chat-api.ts → src/server/chat.ts
+ * with `lib` and no DOM — so the route ran fine and the build did not.
+ *
+ * `messages` is typed as the kit's OWN encoder output rather than restated
+ * structurally, which keeps the two halves of the scaffold pinned to one type:
+ * the front end sends `toOpenAIMessages(thread)`, and this is what that returns.
+ * The import is type-only and erases at build time, so the route ships no
+ * runtime dependency on the kit.
+ */
+const CHAT_REQUEST_BODY_IMPORT = `import type { OpenAIWireMessage } from '@kitn.ai/ui/wire';`;
+const CHAT_REQUEST_BODY_DECL = [
+  `/**`,
+  ` * What the front end POSTs. \`request.json()\` is \`unknown\` (it is whatever the`,
+  ` * client sent), so the body is narrowed once here instead of at every use —`,
+  ` * without it this route does not compile under a server tsconfig. Widen it as`,
+  ` * you add fields of your own.`,
+  ` */`,
+  `type ChatRequestBody = {`,
+  `  messages: OpenAIWireMessage[];`,
+  `  model?: string;`,
+  `  tools?: unknown[];`,
+  `};`,
+  ``,
+  `/** Narrow the JSON body once, at the edge. */`,
+  `async function readChatRequest(request: Request): Promise<ChatRequestBody> {`,
+  `  return (await request.json()) as ChatRequestBody;`,
+  `}`,
+];
+
+/**
+ * Attachments, on the way IN.
+ *
+ * A user turn's `content` is a plain string until it carries a file, at which
+ * point `toOpenAIMessages` emits the ARRAY form. Every route that re-maps
+ * messages into some other SDK's shape has to handle both, and the three that do
+ * (anthropic, mastra, vercel-ai-sdk) were each written when only the string form
+ * existed — so each one would have quietly dropped the attachment while still
+ * compiling, which is the same defect the encoder was just fixed for.
+ *
+ * These two helpers are the shared half of that: flattening the wire shape is
+ * identical everywhere, while the target shape is not, so each route maps
+ * `WirePart[]` into its own SDK itself rather than inheriting a lowest common
+ * denominator.
+ *
+ * Only injected into routes that actually call them — the eight pass-through
+ * integrations forward `messages` untouched and need none of this, and an unused
+ * declaration is a hard error under the gate's `--noUnusedLocals`.
+ */
+const CONTENT_PARTS_DECL = [
+  `/** Where an attachment's bytes are: inline base64, or an address the PROVIDER`,
+  ` *  fetches. Never both. */`,
+  `type WireFileSource = { type: 'data'; data: string } | { type: 'url'; url: string };`,
+  ``,
+  `/** One piece of a turn, with the string and array content forms flattened into`,
+  ` *  a single shape. */`,
+  `type WirePart =`,
+  `  | { kind: 'text'; text: string }`,
+  `  | { kind: 'file'; mediaType: string; filename?: string; source: WireFileSource };`,
+  ``,
+  `const DATA_URI = /^data:([^;,]+);base64,([\\s\\S]*)$/;`,
+  ``,
+  `/**`,
+  ` * Flatten a wire message's content into parts.`,
+  ` *`,
+  ` * An image sent by URL has no media type here — \`image_url\` carries only the`,
+  ` * address — so it reports the top-level segment \`'image'\`, which is all a URL`,
+  ` * source needs. Only images can reach that branch: the kit refuses to encode a`,
+  ` * remote PDF rather than guess at one.`,
+  ` */`,
+  `function wireParts(content: OpenAIWireMessage['content']): WirePart[] {`,
+  `  if (content == null) return [];`,
+  `  if (typeof content === 'string') return content === '' ? [] : [{ kind: 'text', text: content }];`,
+  `  return content.map((part): WirePart => {`,
+  `    if (part.type === 'text') return { kind: 'text', text: part.text };`,
+  `    if (part.type === 'image_url') {`,
+  `      const asData = DATA_URI.exec(part.image_url.url);`,
+  `      return asData`,
+  `        ? { kind: 'file', mediaType: asData[1], source: { type: 'data', data: asData[2] } }`,
+  `        : { kind: 'file', mediaType: 'image', source: { type: 'url', url: part.image_url.url } };`,
+  `    }`,
+  `    const asData = DATA_URI.exec(part.file.file_data);`,
+  `    if (!asData) {`,
+  `      // LOUD on purpose. \`file_data\` is a data URI on this wire; anything else`,
+  `      // cannot be turned into bytes without fetching it, and forwarding a turn`,
+  `      // with the attachment quietly missing is the bug this whole path exists`,
+  `      // to prevent.`,
+  `      throw new Error(`,
+  `        'Unsupported file content part: file_data must be a data: URI of the form data:<media type>;base64,<data>.',`,
+  `      );`,
+  `    }`,
+  `    return {`,
+  `      kind: 'file',`,
+  `      mediaType: asData[1],`,
+  `      filename: part.file.filename,`,
+  `      source: { type: 'data', data: asData[2] },`,
+  `    };`,
+  `  });`,
+  `}`,
+  ``,
+  `/** Just the text of a turn. System, assistant and tool messages are text-only`,
+  ` *  on this wire, so this collapses the array form for them. */`,
+  `function wireText(content: OpenAIWireMessage['content']): string {`,
+  `  return wireParts(content)`,
+  `    .map((p) => (p.kind === 'text' ? p.text : ''))`,
+  `    .join('');`,
+  `}`,
+];
+
+/**
+ * What a bare `Integration.webRoute` needs above it before it will compile.
+ *
+ * WHY THIS IS A FUNCTION AND NOT TWO EXPORTED CONSTANTS. `webRoute` reads like a
+ * self-contained handler and is not one: every fragment in the catalog calls
+ * `readChatRequest`, and three of them (anthropic, mastra, vercel-ai-sdk) also
+ * call `wireParts` / `wireText` and annotate with `WirePart`. Measured over the
+ * catalog, a bare fragment under `tsc --strict` is TS2304 on five distinct names.
+ * A consumer handed `CHAT_REQUEST_BODY_DECL` alone would therefore emit five
+ * routes that compile and three that do not, and would find out only for the
+ * ones it happened to wire first. Asking the question the caller actually has —
+ * "what goes above THIS fragment" — is the shape that cannot be answered
+ * half-right, so that is what is exported.
+ *
+ * `symbols` is DERIVED from `decl` rather than listed beside it, so a rename
+ * inside either declaration block moves it and a consumer's drift guard grades
+ * the real text.
+ */
+export interface ChatRoutePreamble {
+  /** import lines the declarations need, emitted at the top of the route file */
+  readonly imports: readonly string[];
+  /** the declaration lines, emitted immediately above the handler */
+  readonly decl: readonly string[];
+  /** every symbol `decl` declares, read back out of `decl` */
+  readonly symbols: readonly string[];
+}
+
+/** A top-level declaration in a preamble block. Indented lines are bodies. */
+const PREAMBLE_DECLARATION = /^(?:export\s+)?(?:async\s+)?(?:function|type|interface|const|class)\s+([A-Za-z_$][\w$]*)/;
+
+/**
+ * The preamble a given handler fragment needs.
+ *
+ * Used by the MCP below to build its own route blocks, and exported for
+ * `create-kai`, which writes the same handler to a real file that has to
+ * compile. One code path, so the two cannot disagree about what a route needs.
+ */
+export function chatRoutePreamble(fragment: string): ChatRoutePreamble {
+  // The content helpers ride along only where the route calls them; see
+  // CONTENT_PARTS_DECL for why an unconditional injection would not compile.
+  //
+  // KNOWN GAP, live but not yet reachable: this tests for a CALL, so a fragment
+  // that only annotates with `WirePart` / `WireFileSource` and never calls
+  // either helper would be told it needs nothing and would not compile. No
+  // catalog route is shaped that way today — vercel-ai-sdk is the only one that
+  // names the type, and it calls `wireParts` two lines later — so widening the
+  // test would change no emitted byte, and that is exactly why it is left alone
+  // here rather than fixed blind. `scaffold.test.ts` → "webRoute has no symbol
+  // its own preamble fails to declare" is the check that turns this from a
+  // comment into a failing build the day an integration lands in that shape.
+  const decl = /\bwire(?:Parts|Text)\s*\(/.test(fragment)
+    ? [...CHAT_REQUEST_BODY_DECL, ``, ...CONTENT_PARTS_DECL]
+    : [...CHAT_REQUEST_BODY_DECL];
+  return {
+    imports: [CHAT_REQUEST_BODY_IMPORT],
+    decl,
+    symbols: decl.flatMap((line) => PREAMBLE_DECLARATION.exec(line)?.[1] ?? []),
+  };
+}

package/src/components/file-tree.tsx

@@ -5,7 +5,6 @@ import {
   splitProps,
   createSignal,
   createMemo,
-  mergeProps,
 } from 'solid-js';
 import { cn } from '../utils/cn';
 import {
@@ -208,8 +207,13 @@ export interface FileTreeProps extends Omit<JSX.HTMLAttributes<HTMLDivElement>,
  * calls `onSelect(path, file)`.
  */
 export function FileTree(props: FileTreeProps): JSX.Element {
-  const merged = mergeProps({ files: [] as FileTreeFile[] }, props);
-  const [local, rest] = splitProps(merged, [
+  // `files` is REQUIRED, so it is read straight off `props` — no `mergeProps`
+  // default. Defaulting it to `[]` here would turn a caller who forgot it into a
+  // silently empty tree, which fails far from the mistake. The `<kai-file-tree>`
+  // facade declares its own `files: []` default (elements/file-tree.tsx), so the
+  // web-component path is covered where the property genuinely arrives late.
+  // Same shape as `Segmented`, which reads `merged.options` directly.
+  const [local, rest] = splitProps(props, [
     'files',
     'activeFile',
     'onSelect',