@kitn.ai/ui 0.22.2 → 0.23.0

package/dist/mcp.es.js

@@ -1559,13 +1559,50 @@ const vercelAiSdk = {
   // No per-framework templates: the handler below is web-standard, so the
   // scaffolder wraps it in the target framework's own route declaration.
   routeTemplates: {},
-  webRoute: `import { streamText } from 'ai';
-import type { ModelMessage, AssistantContent, UserContent, FilePart, ToolResultPart } from 'ai';
+  webRoute: `import { dynamicTool, jsonSchema, streamText } from 'ai';
+import type {
+  AssistantContent,
+  FilePart,
+  JSONSchema7,
+  ModelMessage,
+  SystemModelMessage,
+  ToolResultPart,
+  ToolSet,
+  UserContent,
+} from 'ai';
 
 // Next.js only: add \`export const maxDuration = 30\` to the route file to allow
 // long streaming responses. It is a Next route-segment config, not part of the
 // handler, so it lives in the file rather than in here.
 
+/**
+ * The model, PINNED — and deliberately NOT read off the request body.
+ *
+ * Change THIS LINE to change the model; it is the only place one is named. The
+ * AI Gateway takes a \`creator/model-name\` string, so any id it routes works
+ * here without touching another import.
+ *
+ * Why it is not forwarded from the client, unlike the openai / openrouter /
+ * anthropic routes:
+ *
+ *   · Those three POST to ONE host with ONE id space, so the scaffold can seed a
+ *     valid default. The Gateway is a router across every vendor's id space at
+ *     once, so there is no default that is right for it — only one vendor's guess
+ *     baked into a provider-agnostic template.
+ *   · A forwarded model id on a \`needs-proxy\` route is a spend lever handed to
+ *     anything that can POST here, and the Gateway bills per token per model.
+ *
+ * WHY THIS ID. It is the one this route has actually been driven against live —
+ * text, a single tool call and a multi-round tool loop, through the Gateway —
+ * and, unlike a frontier default, it ANSWERS ON A FREE GATEWAY ACCOUNT. A paid
+ * id fails a first \`npm run dev\` with
+ * \`Free tier users do not have access to this model\`, which reads as a broken
+ * scaffold rather than as a billing setting. It also supports tools and
+ * reasoning, so the two things this route re-frames are reachable by default,
+ * and it is cheaper than gpt-4o by roughly two orders of magnitude.
+ */
+const MODEL = 'openai/gpt-oss-120b';
+
 /**
  * One attachment to an AI SDK FilePart.
  *
@@ -1637,21 +1674,211 @@ function toModelMessages(messages: ChatRequestBody['messages']): ModelMessage[]
   });
 }
 
+/** The OpenAI function-calling envelope the front end sends, narrowed from
+ *  \`unknown[]\`. Declared as this integration's \`clientToolFormat\`. */
+type OpenAIFunctionTool = {
+  function?: { name?: string; description?: string; parameters?: unknown };
+};
+
+/**
+ * OpenAI function schemas -> the AI SDK's own ToolSet.
+ *
+ * \`dynamicTool\` is the helper for a schema known only at RUNTIME. The ordinary
+ * \`tool()\` infers its input type from a Zod schema written in the route, which
+ * a list arriving in the request body cannot have.
+ *
+ * NO \`execute\`, deliberately. A tool the SDK can run makes the ROUTE the loop
+ * owner: streamText would call it, feed the result back and answer in a single
+ * response, so the tool call would never reach the browser and \`<kai-tool>\`
+ * would have nothing to render. Without \`execute\` the SDK emits the call and
+ * stops, which is the contract the kit's front end already implements — run the
+ * tool, \`applyToolOutput\`, POST the thread again.
+ */
+function toToolSet(tools: ChatRequestBody['tools']): ToolSet | undefined {
+  if (!tools?.length) return undefined;
+  const out: ToolSet = {};
+  for (const raw of tools) {
+    const fn = (raw as OpenAIFunctionTool).function;
+    if (!fn?.name) continue;
+    out[fn.name] = dynamicTool({
+      description: fn.description ?? '',
+      inputSchema: jsonSchema((fn.parameters as JSONSchema7 | undefined) ?? { type: 'object' }),
+    });
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/** AI SDK finish reasons -> OpenAI's spelling. They agree on 'stop', 'length'
+ *  and 'error' and disagree on the other two, and readOpenAIStream's table reads
+ *  OpenAI's — so an unmapped 'tool-calls' normalises to 'other' and the turn
+ *  stops saying why it stopped. */
+const FINISH_REASONS: Record<string, string> = {
+  'tool-calls': 'tool_calls',
+  'content-filter': 'content_filter',
+};
+
 async function chatHandler(request: Request): Promise<Response> {
-  const { messages } = await readChatRequest(request);
+  const { messages, tools } = await readChatRequest(request);
+  const toolSet = toToolSet(tools);
+  const prompt = toModelMessages(messages);
 
+  // THE SYSTEM TURN DOES NOT GO IN \`messages\`, and this is the one that costs a
+  // live run to find. \`SystemModelMessage\` is still part of the \`ModelMessage\`
+  // union, so a system entry in this array TYPECHECKS — and then \`ai\` v7's
+  // \`standardizePrompt\` throws \`InvalidPromptError: System messages are not
+  // allowed in the prompt or messages fields. Use the instructions option
+  // instead.\` The kit's own encoder puts the system prompt at \`messages[0]\`, so
+  // that is every single turn of a scaffolded app, not an edge case.
+  //
+  // Hoisted rather than joined into a string: \`instructions\` takes the message
+  // array, so several system turns keep their order and their count.
+  //
+  // On \`ai\` v5/v6 there is no \`instructions\` option and a system message in
+  // \`messages\` is correct — drop this split and pass \`prompt\` straight through
+  // if you pin an older SDK.
+  const instructions = prompt.filter((m): m is SystemModelMessage => m.role === 'system');
+  const conversation = prompt.filter((m) => m.role !== 'system');
+
+  // \`streamText\` is not awaited: it returns synchronously and does its work as
+  // the stream is iterated. Prompt validation is part of that work, so an
+  // invalid prompt surfaces from \`for await (… of result.fullStream)\` below
+  // rather than from this line — which is why the catch that reports it lives
+  // in the stream and not around this call. Confirmed by observation: a rejected
+  // prompt reached the browser as an in-band error frame, not as a 500.
   const result = streamText({
-    model: 'openai/gpt-4o', // AI Gateway id; needs AI_GATEWAY_API_KEY
-    messages: toModelMessages(messages),
+    model: MODEL, // AI Gateway id; needs AI_GATEWAY_API_KEY
+    ...(instructions.length > 0 ? { instructions } : {}),
+    messages: conversation,
+    ...(toolSet ? { tools: toolSet } : {}),
   });
 
   const encoder = new TextEncoder();
+
+  // OpenAI correlates tool-call fragments by their POSITION in the tool_calls
+  // array; the SDK identifies each call by id and never sends a position. So one
+  // is derived from the other, in first-seen order, and every fragment of a call
+  // carries the same number. Getting this wrong does not throw — the fragments
+  // land on the wrong call and the arguments come out as spliced JSON.
+  const toolIndex = new Map<string, number>();
+  const indexOf = (id: string): number => {
+    const known = toolIndex.get(id);
+    if (known !== undefined) return known;
+    const next = toolIndex.size;
+    toolIndex.set(id, next);
+    return next;
+  };
+  // How many argument characters a call streamed. \`tool-call\` re-sends the whole
+  // input at the end, so emitting it unconditionally would DOUBLE the arguments
+  // of every call that streamed — and skipping it unconditionally would empty
+  // the arguments of any provider that does not stream them. Neither is safe to
+  // assume, so the decision is made per call from what actually arrived.
+  const streamedArgs = new Map<string, number>();
+
   const sse = new ReadableStream({
     async start(controller) {
+      const send = (chunk: unknown): void => {
+        controller.enqueue(encoder.encode(\`data: \${JSON.stringify(chunk)}\\n\\n\`));
+      };
       try {
-        for await (const delta of result.textStream) {
-          const chunk = { choices: [{ delta: { content: delta } }] };
-          controller.enqueue(encoder.encode(\`data: \${JSON.stringify(chunk)}\\n\\n\`));
+        // fullStream, NOT textStream. textStream is text deltas only: a tool call
+        // or a reasoning block goes past it silently, so a route built on it
+        // emits a plain answer and nothing else however the model replied.
+        for await (const part of result.fullStream) {
+          switch (part.type) {
+            case 'text-delta':
+              send({ choices: [{ delta: { content: part.text } }] });
+              break;
+
+            case 'reasoning-delta':
+              send({ choices: [{ delta: { reasoning: part.text } }] });
+              break;
+
+            // The call is ANNOUNCED here, before its arguments exist, which is
+            // what lets <kai-tool> open a panel with the tool's name in it while
+            // the arguments are still being written.
+            case 'tool-input-start':
+              streamedArgs.set(part.id, 0);
+              send({
+                choices: [{
+                  delta: {
+                    tool_calls: [{
+                      index: indexOf(part.id),
+                      id: part.id,
+                      type: 'function',
+                      function: { name: part.toolName, arguments: '' },
+                    }],
+                  },
+                }],
+              });
+              break;
+
+            case 'tool-input-delta':
+              streamedArgs.set(part.id, (streamedArgs.get(part.id) ?? 0) + part.delta.length);
+              send({
+                choices: [{
+                  delta: { tool_calls: [{ index: indexOf(part.id), function: { arguments: part.delta } }] },
+                }],
+              });
+              break;
+
+            case 'tool-call':
+              // Only when nothing streamed: see \`streamedArgs\`.
+              if ((streamedArgs.get(part.toolCallId) ?? 0) === 0) {
+                send({
+                  choices: [{
+                    delta: {
+                      tool_calls: [{
+                        index: indexOf(part.toolCallId),
+                        id: part.toolCallId,
+                        type: 'function',
+                        function: {
+                          name: part.toolName,
+                          arguments: JSON.stringify(part.input ?? {}),
+                        },
+                      }],
+                    },
+                  }],
+                });
+              }
+              break;
+
+            // One frame carries both, the way chat-completions sends them.
+            // \`reasoning_tokens\` is the number that proves thinking happened even
+            // when the provider streamed no reasoning text.
+            case 'finish':
+              send({
+                choices: [{
+                  delta: {},
+                  finish_reason: FINISH_REASONS[part.finishReason] ?? part.finishReason,
+                }],
+                usage: {
+                  prompt_tokens: part.totalUsage.inputTokens,
+                  completion_tokens: part.totalUsage.outputTokens,
+                  total_tokens: part.totalUsage.totalTokens,
+                  completion_tokens_details: {
+                    reasoning_tokens: part.totalUsage.outputTokenDetails.reasoningTokens,
+                  },
+                },
+              });
+              break;
+
+            // An error the SDK caught mid-stream. The status is long spent, so it
+            // goes IN BAND like the catch below.
+            case 'error':
+              send({
+                error: {
+                  message: part.error instanceof Error ? part.error.message : String(part.error),
+                },
+              });
+              break;
+
+            // Everything else — text-start/end, tool-input-end, sources, files,
+            // step boundaries, raw provider frames — has no OpenAI-wire spelling
+            // and is dropped. \`source\` is the one worth knowing about: map it to
+            // \`delta.annotations[].url_citation\` if your model cites its sources.
+            default:
+              break;
+          }
         }
       } catch (err) {
         // The status is spent by the time the SDK fails — the headers went out
@@ -1659,7 +1886,7 @@ async function chatHandler(request: Request): Promise<Response> {
         // this on turn.error and keeps whatever streamed before it. Without it a
         // failed key is an empty bubble and nothing in the console.
         const message = err instanceof Error ? err.message : 'Model stream failed';
-        controller.enqueue(encoder.encode(\`data: \${JSON.stringify({ error: { message } })}\\n\\n\`));
+        send({ error: { message } });
       }
       controller.enqueue(encoder.encode('data: [DONE]\\n\\n'));
       controller.close();
@@ -1676,12 +1903,24 @@ async function chatHandler(request: Request): Promise<Response> {
     },
   });
 }`,
-  streamMapping: "The Vercel AI SDK's toUIMessageStreamResponse() and toTextStreamResponse() don't emit OpenAI-format SSE. Wrap result.textStream manually: iterate text deltas and emit data: {choices:[{delta:{content}}]} frames, closing with data: [DONE]. readOpenAIStream from @kitn.ai/ui/wire parses tool calls and reasoning too, but textStream carries neither: it is text deltas only. Switch to result.fullStream, which yields typed parts, and re-frame its tool-call and reasoning parts onto delta.tool_calls and delta.reasoning to get them.",
-  runNote: "Set AI_GATEWAY_API_KEY for the AI Gateway (string model id form: creator/model-name). For direct provider access, import its provider package (e.g. @ai-sdk/openai) and set the corresponding key (e.g. OPENAI_API_KEY).",
+  streamMapping: "The Vercel AI SDK's toUIMessageStreamResponse() and toTextStreamResponse() don't emit OpenAI-format SSE, so the route re-frames the stream itself and readOpenAIStream from @kitn.ai/ui/wire parses it exactly as it does every other integration. Iterate result.fullStream, NOT result.textStream: textStream carries text deltas only, so a route built on it emits a plain answer however the model replied and drops every tool call and every reasoning block silently. fullStream yields typed parts: text-delta.text -> delta.content, reasoning-delta.text -> delta.reasoning, tool-input-start plus its tool-input-delta fragments -> delta.tool_calls, finish -> finish_reason plus a usage frame, error -> an in-band {error:{message}}. Two traps. (1) OpenAI correlates tool-call fragments by their POSITION in the tool_calls array and the SDK only ever gives an id, so the route keeps an id -> index map; passing anything else through as the index splices one call's arguments into another. (2) fullStream sends the complete input AGAIN on the tool-call part after streaming it in fragments, so emitting both doubles the arguments — the route tracks how much each call streamed and emits the tool-call part only for a provider that streamed none. Parts with no OpenAI spelling (text-start/end, tool-input-end, step boundaries, raw) are dropped; source parts have one — delta.annotations[].url_citation — and are left unmapped because the SDK's Source union carries document sources a url_citation cannot express. On the REQUEST side the trap that only a live run finds: ai v7 REFUSES a system message inside `messages` (InvalidPromptError, 'Use the instructions option instead') even though SystemModelMessage is still in the ModelMessage union and therefore typechecks — and the kit's encoder puts the system prompt at messages[0], so that is every turn. Hoist system turns into `instructions` and pass the rest as `messages`. That failure arrives from ITERATING fullStream, not from the streamText() call — streamText returns synchronously and validates as the stream is read — so the in-band catch around the loop is what reports it, and it reaches the browser as an error frame rather than as a 500.",
+  runNote: "Set AI_GATEWAY_API_KEY for the AI Gateway (string model id form: creator/model-name). The route pins `const MODEL = 'openai/gpt-oss-120b'` — one line, at the top, and any id the Gateway routes works in it. That id is pinned because it answers on a FREE Gateway account: most ids (deepseek/*, meta/*, anthropic/*) return `Free tier users do not have access to this model` or a free-tier rate limit until the account has paid credits, which looks like a broken scaffold rather than a billing setting. For direct provider access, import its provider package (e.g. @ai-sdk/openai) and set the corresponding key (e.g. OPENAI_API_KEY). The tools the front end posts become `dynamicTool`s with NO `execute`, which is what keeps the tool loop in the app: the SDK emits the call and stops, the app runs it, renders it in <kai-tool> and posts the thread back. Give a tool an `execute` and the SDK runs the whole loop server-side, so nothing reaches the browser but the final sentence.",
   docsSlug: "integrations/vercel-ai-sdk",
-  // Nothing. The route pins model: 'openai/gpt-4o' in the streamText() call and
-  // defines any tools there too, so neither belongs in the front end.
-  forwardsFromClient: [],
+  // `tools` only. `model` is deliberately NOT forwarded — the route pins it in
+  // one named const, and see that const's comment for why the Gateway is the one
+  // host where a client-supplied id has no correct default. The catalog check
+  // agrees from the other direction: `every integration that forwards a model
+  // emits one valid for the host it POSTs to` reads the host off the route's own
+  // fetch(), and this route makes no fetch call at all — the SDK owns the
+  // transport — so a forwarded model here could not be validated against
+  // anything.
+  forwardsFromClient: ["tools"],
+  // 'openai': the ROUTE's request contract, not the SDK's own. `toToolSet` reads
+  // `raw.function.name` / `.function.parameters` off each entry — the OpenAI
+  // function-calling envelope — and rebuilds it as a `dynamicTool` with a
+  // `jsonSchema()` input. Sending the SDK's own tool shape from the client would
+  // leave `.function` undefined and every tool would arrive nameless.
+  clientToolFormat: "openai",
   // `ai` only. A direct provider (e.g. @ai-sdk/openai) is the alternative path
   // described in runNote, not what this route imports, so it is not listed: the
   // rule is what the emitted code actually imports.
@@ -2594,6 +2833,114 @@ function listIntegrations() {
 function listArchetypes() {
   return archetypes;
 }
+const CLIENT_MODEL_IDS = {
+  // 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"
+};
+function defaultModelFor(integration) {
+  if (!integration.forwardsFromClient.includes("model")) return void 0;
+  const id = CLIENT_MODEL_IDS[integration.id];
+  if (id === void 0) {
+    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;
+}
+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;`,
+  `}`
+];
+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('');`,
+  `}`
+];
+const PREAMBLE_DECLARATION = /^(?:export\s+)?(?:async\s+)?(?:function|type|interface|const|class)\s+([A-Za-z_$][\w$]*)/;
+function chatRoutePreamble(fragment) {
+  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] ?? [])
+  };
+}
 const ENCODABLE = [
   { pattern: "image/jpeg", kind: "image" },
   { pattern: "image/png", kind: "image" },
@@ -2976,27 +3323,6 @@ function realBodyPayload(opts) {
     return `{ ${fields.join(", ")} }`;
   };
 }
-const CLIENT_MODEL_IDS = {
-  // 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"
-};
-function defaultModelFor(integration) {
-  if (!integration.forwardsFromClient.includes("model")) return void 0;
-  const id = CLIENT_MODEL_IDS[integration.id];
-  if (id === void 0) {
-    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;
-}
 function emitsToolSchemas(components, integration) {
   const needsToolsArray = hasToolPanel(components) || bearsCards(components);
   return needsToolsArray && integration.forwardsFromClient.includes("tools");
@@ -5419,86 +5745,7 @@ const WEB_ROUTE_ADAPTERS = {
     ]
   }
 };
-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;`,
-  `}`
-];
-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('');`,
-  `}`
-];
-function withChatRequestBody(fragment) {
-  const decl = /\bwire(?:Parts|Text)\s*\(/.test(fragment) ? [...CHAT_REQUEST_BODY_DECL, ``, ...CONTENT_PARTS_DECL] : CHAT_REQUEST_BODY_DECL;
+function withChatRequestBody(fragment, decl) {
   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");
@@ -5510,17 +5757,18 @@ function webRouteFor(integration, framework) {
   const adapter = WEB_ROUTE_ADAPTERS[framework];
   if (!fragment || !adapter) return void 0;
   const adapted = adapter.adaptFragment?.(fragment) ?? { fragment, imports: [] };
+  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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitn.ai/ui",
-  "version": "0.22.2",
+  "version": "0.23.0",
   "nx": {
     "name": "ui",
     "targets": {
@@ -155,7 +155,7 @@
   "scripts": {
     "prepublishOnly": "npm run build",
     "prebuild": "npm run build:css && npm run build:card-validation",
-    "build": "vite build --config vite.config.ts && vite build --config vite.config.provider.ts && vite build --config vite.config.react.ts && vite build --config vite.config.barrel.ts && vite build --config vite.config.barrel.server.ts && vite build --config vite.config.solid.ts && vite build --config vite.config.solid.server.ts && vite build --config vite.config.state.ts && vite build --config vite.config.wire.ts && vite build --config vite.config.schemas.ts && vite build --config vite.config.mcp.ts && npm run build:elements && node scripts/verify-elements-bundle.mjs && node scripts/verify-react-wrappers.mjs && node scripts/verify-shader-lazy.mjs",
+    "build": "vite build --config vite.config.ts && vite build --config vite.config.provider.ts && vite build --config vite.config.react.ts && vite build --config vite.config.barrel.ts && vite build --config vite.config.barrel.server.ts && vite build --config vite.config.solid.ts && vite build --config vite.config.solid.server.ts && vite build --config vite.config.state.ts && vite build --config vite.config.wire.ts && vite build --config vite.config.schemas.ts && vite build --config vite.config.mcp.ts && npm run build:elements && npm run verify:elements-bundle && npm run verify:react-wrappers && npm run verify:shader-lazy",
     "build:elements": "node scripts/gen-elements-manifest.mjs && vite build --config vite.config.elements.ts && node scripts/gen-element-dts.mjs",
     "postbuild": "npm run build:theme && npm run build:api && npm run build:schemas && npm run build:subpath-dts && npm run verify:dts",
     "build:theme": "node scripts/build-theme-tokens.mjs",
@@ -166,11 +166,14 @@
     "verify:card-validation": "node scripts/gen-card-validation-schemas.mjs --check",
     "verify:consumer": "node scripts/verify-consumer-sideeffects.mjs",
     "verify:dts": "node scripts/verify-dts-boundaries.mjs",
+    "verify:elements-bundle": "node scripts/verify-elements-bundle.mjs --self-test && node scripts/verify-elements-bundle.mjs",
     "verify:dts:consumer": "node scripts/verify-dts-consumer.mjs",
     "verify:generated": "node scripts/verify-generated-sync.mjs",
     "verify:quarantine": "node scripts/verify-quarantine.mjs",
+    "verify:react-wrappers": "node scripts/verify-react-wrappers.mjs --self-test && node scripts/verify-react-wrappers.mjs",
     "verify:scaffold": "node scripts/verify-scaffold-compiles.mjs",
     "verify:schemas": "node scripts/verify-schemas-exported.mjs",
+    "verify:shader-lazy": "node scripts/verify-shader-lazy.mjs --self-test && node scripts/verify-shader-lazy.mjs",
     "verify:solid-coverage": "node scripts/verify-solid-coverage.mjs",
     "verify:tool-schemas": "node scripts/verify-tool-schemas.mjs",
     "verify:ssr": "node scripts/verify-ssr-imports.mjs && node scripts/verify-ssr-render.mjs",