@kitn.ai/ui 0.25.2 → 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/integrations/anthropic.ts

@@ -317,7 +317,13 @@ function reframeToOpenAISse(body: ReadableStream<Uint8Array>): ReadableStream<Ui
 async function chatHandler(request: Request): Promise<Response> {
   // Both model and tools come from the browser. \`tools\` arrives in OpenAI
   // function form and is converted to this API's shape below.
-  const { model, messages, tools } = await readChatRequest(request);
+  let chatBody: ChatRequestBody;
+  try {
+    chatBody = await readChatRequest(request);
+  } catch (error) {
+    return toChatErrorResponse(error);
+  }
+  const { model, messages, tools } = chatBody;
   const { system, messages: anthropicMessages } = toAnthropicBody(messages);
   const anthropicTools = toAnthropicTools(tools);
 

package/src/agent-tooling/integrations/cloudflare.ts

@@ -24,9 +24,44 @@ import type { OpenAIWireMessage } from '@kitn.ai/ui/wire';
  */
 type ChatRequestBody = { messages: OpenAIWireMessage[] };
 
+class ChatRequestError extends Error {
+  constructor(readonly status: number, message: string) { super(message); }
+}
+
+/** Narrow the JSON body once, at the edge. A bare GET, a malformed body, or a
+ *  missing messages array is a ChatRequestError with a status — NEVER an
+ *  unhandled SyntaxError (findings F-10). */
+async function readChatRequest(request: Request): Promise<ChatRequestBody> {
+  if (request.method !== 'POST') {
+    throw new ChatRequestError(405, \`Method \${request.method} not allowed — POST /api/chat.\`);
+  }
+  let parsed: unknown;
+  try { parsed = await request.json(); } catch {
+    throw new ChatRequestError(400, 'Request body is not valid JSON.');
+  }
+  const body = parsed as ChatRequestBody;
+  if (!Array.isArray(body?.messages)) {
+    throw new ChatRequestError(400, 'Request body must carry a messages array.');
+  }
+  return body;
+}
+
+/** Map a guard rejection to the Response its status demands; rethrow anything
+ *  else — an unexpected error should be loud, not laundered into a 400. */
+function toChatErrorResponse(error: unknown): Response {
+  if (error instanceof ChatRequestError) return Response.json({ error: error.message }, { status: error.status });
+  throw error;
+}
+
 export default {
   async fetch(req: Request, env: Env): Promise<Response> {
-    const { messages } = (await req.json()) as ChatRequestBody;
+    let chatBody: ChatRequestBody;
+    try {
+      chatBody = await readChatRequest(req);
+    } catch (error) {
+      return toChatErrorResponse(error);
+    }
+    const { messages } = chatBody;
 
     let nativeStream: ReadableStream<Uint8Array>;
     try {
@@ -101,7 +136,13 @@ export default {
   },
   webRoute: `async function chatHandler(request: Request): Promise<Response> {
   // Proxy Workers AI over its OpenAI-compatible HTTP endpoint, token server-side.
-  const { messages } = await readChatRequest(request);
+  let chatBody: ChatRequestBody;
+  try {
+    chatBody = await readChatRequest(request);
+  } catch (error) {
+    return toChatErrorResponse(error);
+  }
+  const { messages } = chatBody;
 
   const upstream = await fetch(
     \`https://api.cloudflare.com/client/v4/accounts/\${process.env.CF_ACCOUNT_ID}/ai/v1/chat/completions\`,

package/src/agent-tooling/integrations/langgraph.ts

@@ -31,7 +31,13 @@ const agent = createReactAgent({
 
 // Stream a compiled LangGraph agent to the browser as OpenAI-format SSE.
 async function chatHandler(request: Request): Promise<Response> {
-  const { messages } = await readChatRequest(request);
+  let chatBody: ChatRequestBody;
+  try {
+    chatBody = await readChatRequest(request);
+  } catch (error) {
+    return toChatErrorResponse(error);
+  }
+  const { messages } = chatBody;
 
   // agent.stream() coerces plain {role, content} objects into BaseMessage
   // instances itself, including OpenAI-shaped tool_calls, so the wire messages

package/src/agent-tooling/integrations/mastra.ts

@@ -28,7 +28,13 @@ const mastra = new MastraClient({ baseUrl: MASTRA_URL });
 
 // Proxy a Mastra agent to the browser as OpenAI-format SSE.
 async function chatHandler(request: Request): Promise<Response> {
-  const { messages } = await readChatRequest(request);
+  let chatBody: ChatRequestBody;
+  try {
+    chatBody = await readChatRequest(request);
+  } catch (error) {
+    return toChatErrorResponse(error);
+  }
+  const { messages } = chatBody;
 
   // MastraClient's Agent.stream() takes AI-SDK CoreMessage[], not the OpenAI
   // wire format: each message has ONE literal role (not a union) and content

package/src/agent-tooling/integrations/mock.ts

@@ -35,9 +35,22 @@ import type { Integration } from '../types';
  * Swap `integration` for a real provider (openai, anthropic, openrouter, ollama,
  * …) when ready.
  *
- * It carries an empty `routeTemplates` on purpose: there is no server route to
- * emit. `category: 'mock'` keeps it out of the real provider/gateway/framework/
- * harness catalogs.
+ * THE ROUTE IS OPTIONAL, AND IT EXISTS ANYWAY (rung-2 finding G-04, recurring
+ * since rung 1). Two clean-room builders in a row were told "replies come from a
+ * local dev endpoint that streams a mocked response" and had to hand-invent the
+ * server side, because this was the one integration whose block (2) held prose
+ * where every other integration ships code. So `webRoute` below is the mock's
+ * server half: the SAME `createMockResponder()` frames, written to the wire by a
+ * portable `chatHandler(Request) => Response` that the scaffolder wraps with the
+ * identical per-framework adapters a real integration gets (Vite dev middleware
+ * for the SPA frameworks, POST exports for next/svelte/tanstack, the
+ * Express/Worker/Angular hosts). Nothing about the emitted app REQUIRES it — the
+ * front end streams locally and never fetches — which the emitted block states,
+ * along with the one-expression swap that points onSubmit at it.
+ *
+ * `routeTemplates` stays empty: the handler is web-standard, so there is no
+ * framework whose declaration it cannot be wrapped in. `category: 'mock'` keeps
+ * it out of the real provider/gateway/framework/harness catalogs.
  */
 const mock: Integration = {
   id: 'mock',
@@ -47,26 +60,88 @@ const mock: Integration = {
   streamFormat: 'native',
   envVars: [],
   routeTemplates: {},
+  webRoute: `import { createMockResponder } from '@kitn.ai/ui/state';
+
+// The kit's own mock responder — no provider, no key, no upstream. MODULE
+// scope, not per-request: the responder owns the cursor into its canned
+// replies, so rebuilding it per turn would answer with the first one forever.
+const mockResponse = createMockResponder();
+
+async function chatHandler(request: Request): Promise<Response> {
+  // The responder cycles its replies whatever you send, so the prompt is a
+  // courtesy — but the body is still read exactly the way a real route reads
+  // it, so swapping this handler for a provider's changes nothing upstream of
+  // this file.
+  let chatBody: ChatRequestBody;
+  try {
+    chatBody = await readChatRequest(request);
+  } catch (error) {
+    return toChatErrorResponse(error);
+  }
+  const { messages } = chatBody;
+  const last = [...messages].reverse().find((m) => m.role === 'user');
+  const prompt = last && typeof last.content === 'string' ? last.content : '';
+
+  // createMockResponder() yields COMPLETE OpenAI chat-completions SSE frames —
+  // the same strings the front end's local preview streams — so this route only
+  // writes them out verbatim. No framing is built here; the browser parses them
+  // with readOpenAIStream from @kitn.ai/ui/wire, exactly as it would a real
+  // route's response. Every frame is marked as a mock (a ': kai-mock' banner, a
+  // _kai_mock field, model 'kai-mock', zero usage).
+  const encoder = new TextEncoder();
+  let open = true;
+  const body = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      for await (const frame of mockResponse(prompt)) {
+        // The browser hangs up when the user asks a new question mid-answer;
+        // stop producing frames rather than writing into a cancelled stream.
+        if (!open) return;
+        controller.enqueue(encoder.encode(frame));
+      }
+      controller.close();
+    },
+    cancel() {
+      open = false;
+    },
+  });
+
+  return new Response(body, {
+    status: 200,
+    headers: {
+      'Content-Type': 'text/event-stream; charset=utf-8',
+      // no-transform stops a proxy buffering the stream into one blob.
+      'Cache-Control': 'no-cache, no-transform',
+      Connection: 'keep-alive',
+      // A proxy in front of a preview build would otherwise buffer the whole
+      // stream and the reply would land all at once instead of streaming.
+      'X-Accel-Buffering': 'no',
+    },
+  });
+}`,
   streamMapping:
-    "No backend and no provider, but a real wire. createMockResponder() from @kitn.ai/ui/state yields canned SSE frames and the scaffold reads them with readOpenAIStream from @kitn.ai/ui/wire, on the same code path a real route's response takes: same reader, same part folding, same abort handling. The frames carry the OpenAI chat-completions shape because the mock stands in for your /api/chat ROUTE, not for a provider (every other integration here re-frames its provider to that shape server-side), so going live replaces ONE expression: mockResponse(value) becomes the awaited response from your own chat route, and nothing else in the handler changes. Nothing here can be mistaken for a real turn: the stream opens with a ': kai-mock' SSE comment, every frame carries a _kai_mock field naming createMockResponder, model reports as 'kai-mock' (no provider serves it), and usage is all zeros.",
+    "No backend and no provider, but a real wire. createMockResponder() from @kitn.ai/ui/state yields canned SSE frames and the scaffold reads them with readOpenAIStream from @kitn.ai/ui/wire, on the same code path a real route's response takes: same reader, same part folding, same abort handling. The frames carry the OpenAI chat-completions shape because the mock stands in for your /api/chat ROUTE, not for a provider (every other integration here re-frames its provider to that shape server-side), so going live replaces ONE expression: mockResponse(value) becomes the awaited response from your own chat route, and nothing else in the handler changes. Nothing here can be mistaken for a real turn: the stream opens with a ': kai-mock' SSE comment, every frame carries a _kai_mock field naming createMockResponder, model reports as 'kai-mock' (no provider serves it), and usage is all zeros. Block (2) serves the same frames over HTTP as an OPTIONAL route, so the /api/chat seam can be stood up before any provider exists.",
   runNote:
-    'No backend or API key needed: the reply is generated in the browser and parsed by the same reader a real route feeds. Run the front-end as-is; swap `integration` for a real provider (openai, anthropic, openrouter, ollama) when ready, and the emitted handler differs by one expression.',
+    'No backend or API key needed: the reply is generated in the browser and parsed by the same reader a real route feeds. Run the front-end as-is; swap `integration` for a real provider (openai, anthropic, openrouter, ollama) when ready, and the emitted handler differs by one expression. Block (2) is the OPTIONAL server half: the same mock frames served over HTTP, for standing up the /api/chat seam before any provider exists.',
   docsSlug: 'integrations/mock',
-  // Nothing: there is no HTTP request at all. The frames are produced in-process
-  // by createMockResponder(), so there is no body to forward a model or a tools
-  // array on, and no route that would read one.
+  // Nothing: the front end makes no HTTP request at all, and the optional route
+  // reads only `messages` — and only as a courtesy prompt the responder is free
+  // to ignore. There is no model to pick and no tools array anything would run.
   forwardsFromClient: [],
-  // Nothing to install: there is no route to install anything for.
+  // Nothing to install: the route's one import is the kit itself, which every
+  // scaffold already depends on (registry.test.ts pins deps.npm to the route's
+  // imports minus @kitn.ai/ui).
   deps: { npm: [], pip: [] },
-  // The other 'frontend-safe' entry, and the only one that is true by absence:
-  // no routeTemplates, no webRoute, no envVars. There is no request, no upstream
-  // and no secret, so there is nothing a public bundle could give away. This is
-  // the one place where "declares nothing" genuinely means safe — which is
-  // precisely why it still has to SAY so rather than be left blank.
+  // The other 'frontend-safe' entry. The route now exists (G-04) but changes
+  // nothing here: it holds no credential, sends no auth header and reaches no
+  // upstream, so there is still nothing a public bundle could give away. The
+  // schema's own refinement re-checks that claim against the route source.
   keyExposure: 'frontend-safe',
-  // Nothing at all, and here that is the literal truth rather than a shorthand:
-  // there is no route, no upstream and no process. This is the "No backend"
-  // group of create-kai's gateway prompt all by itself.
+  // Nothing to supply out of band: no upstream, no process, no runtime. The
+  // route is optional — the emitted app streams locally without it — which is
+  // what keeps mock in the "No backend" group of create-kai's gateway prompt
+  // (listGatewayGroups derives that from frontend-safe + outOfBand 'none', not
+  // from the absence of a route, precisely because this route is one nobody
+  // NEEDS).
   outOfBand: 'none',
 };
 

package/src/agent-tooling/integrations/ollama.ts

@@ -20,7 +20,13 @@ const ollama: Integration = {
   // The model is pinned here, not sent by the browser. tools IS forwarded:
   // it is undefined unless the front end declared any, and JSON.stringify
   // drops it, so the same handler serves a tool archetype and a plain chat.
-  const { messages, tools } = await readChatRequest(request);
+  let chatBody: ChatRequestBody;
+  try {
+    chatBody = await readChatRequest(request);
+  } catch (error) {
+    return toChatErrorResponse(error);
+  }
+  const { messages, tools } = chatBody;
 
   const upstream = await fetch('http://localhost:11434/v1/chat/completions', {
     method: 'POST',

package/src/agent-tooling/integrations/openai.ts

@@ -14,7 +14,13 @@ const openai: Integration = {
   // Both model and tools come from the browser. \`tools\` is undefined unless the
   // front end declared any, and JSON.stringify drops it, so the same handler
   // serves a tool archetype and a plain chat.
-  const { model, messages, tools } = await readChatRequest(request);
+  let chatBody: ChatRequestBody;
+  try {
+    chatBody = await readChatRequest(request);
+  } catch (error) {
+    return toChatErrorResponse(error);
+  }
+  const { model, messages, tools } = chatBody;
 
   const upstream = await fetch('https://api.openai.com/v1/chat/completions', {
     method: 'POST',

package/src/agent-tooling/integrations/openrouter.ts

@@ -14,7 +14,13 @@ const openrouter: Integration = {
   webRoute: `async function chatHandler(request: Request): Promise<Response> {
   // tools is undefined unless the front end sent one; JSON.stringify drops it,
   // so the same handler serves a tool archetype and a plain chat.
-  const { model, messages, tools } = await readChatRequest(request);
+  let chatBody: ChatRequestBody;
+  try {
+    chatBody = await readChatRequest(request);
+  } catch (error) {
+    return toChatErrorResponse(error);
+  }
+  const { model, messages, tools } = chatBody;
 
   const upstream = await fetch('https://openrouter.ai/api/v1/chat/completions', {
     method: 'POST',