@kitn.ai/ui 0.25.2 → 0.26.0

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

@@ -1,17 +1,138 @@
 import { z } from 'zod';
+import themeCss from '../../../../theme.css?raw';
 import type { Tool } from './types';
 
 /**
  * theme — produce a `--kai-*` CSS token override block from a brand color or
- * description. Tokens are sourced exclusively from the real names in theme.css.
+ * description.
  *
- * Real --kai-color-* names (verified against repo-root theme.css):
- *   --kai-color-primary            → brand color
- *   --kai-color-primary-foreground → AA-contrast fg (white or black)
- *   --kai-color-ring               → focus ring (brand color)
- *   --kai-color-accent             → tinted accent surface
- *   --kai-color-accent-foreground  → text on accent surface
+ * WHICH tokens get branded is a curated product call (see BRAND_TOKENS below).
+ * Their NAMES are not: every one is resolved against theme.css, whose text is
+ * inlined above, so a name this tool emits is a name theme.css declares.
+ *
+ * That import is the whole fix and the reason it is an import rather than a
+ * `readFile`. This module ships inside dist/mcp.es.js, an SSR bundle a consumer
+ * runs from bin/mcp.js in their node_modules — a runtime read of a repo-root
+ * path resolves to nothing there, and the src/ and dist/ depths differ anyway.
+ * `?raw` bakes the bytes in at build time from the SAME theme.css that
+ * package.json `files` ships (and `exports` publishes as "./theme.css"), so the
+ * tarball's tool and the tarball's stylesheet cannot disagree by construction,
+ * and there is no runtime I/O at all.
+ *
+ * Before this, the names were five string literals and a docblock claiming they
+ * had been "verified against repo-root theme.css" — nothing read that file, so
+ * renaming a token left the tool emitting the dead name, its test green, and an
+ * agent pasting CSS that themes nothing.
+ */
+
+// ─── token names, read out of theme.css ──────────────────────────────────────
+
+/**
+ * Every `--kai-*` knob theme.css declares. Anchored on `var(` because that is
+ * the only place a knob is really wired up — each kit token is written
+ * `--color-x: var(--kai-color-x, <default>)`. Prose in the file mentions
+ * wildcards like `--kai-color-*`, which a bare `--kai-` scan would pick up as
+ * fictional token names.
+ */
+function declaredKaiTokens(css: string): ReadonlySet<string> {
+  const names = new Set<string>();
+  for (const m of css.matchAll(/var\(\s*(--kai-[a-zA-Z0-9-]+)\s*[,)]/g)) names.add(m[1]);
+  return names;
+}
+
+const DECLARED_TOKENS = declaredKaiTokens(themeCss);
+
+/**
+ * Resolve one `--kai-color-<suffix>` against theme.css, or fail naming it.
+ *
+ * Refusing is deliberate — emitting a token nothing reads is the whole defect
+ * this file exists to prevent — but it happens on the HANDLER path, not at
+ * module load. `server.ts` imports all four tools statically at top level, so a
+ * module-scope throw here took `reference`, `scaffold` and `debug` down with it;
+ * measured against an installed tarball, `initialize` never returned and the
+ * server exited before answering anything. Nothing was bought for that: the
+ * guard in theme.test.ts calls `theme.handler(...)` directly, so it goes red on
+ * exactly the same rename with exactly the same message either way. Handler
+ * scope is pure isolation — `theme` alone reports the error, its three
+ * neighbours keep working.
+ */
+function colorToken(suffix: string): string {
+  const name = `--kai-color-${suffix}`;
+  if (!DECLARED_TOKENS.has(name)) {
+    throw new Error(
+      `[kai mcp: theme] theme.css declares no \`${name}\`. The tool brands that token, ` +
+        `so emitting it would hand the caller CSS that themes nothing. Either the token was ` +
+        `renamed in packages/ui/theme.css (update the BRAND_TOKENS suffix in ` +
+        `src/agent-tooling/mcp/tools/theme.ts to match) or it was removed (drop the entry). ` +
+        `Known --kai-color-* names: ${[...DECLARED_TOKENS].filter((n) => n.startsWith('--kai-color-')).sort().join(', ')}`,
+    );
+  }
+  return name;
+}
+
+interface TokenSet {
+  primary: string;
+  primaryFg: string;
+  ring: string;
+  accent: string;
+  accentFg: string;
+}
+
+interface BrandToken {
+  /** Which computed value from a TokenSet fills this token. */
+  key: keyof TokenSet;
+  /** `--kai-color-<suffix>`, checked against theme.css. */
+  suffix: string;
+  /** One-line explanation, rendered in the "Tokens emitted" list. */
+  purpose: string;
+}
+
+/**
+ * The tokens a brand override needs, in emit order. This LIST is the curated
+ * part — it is a judgement about what rebranding means, not a fact theme.css can
+ * be asked for. It declares far more knobs than this (the error in colorToken
+ * prints the current set); dumping all of them would be a worse answer than
+ * picking the ones that carry a brand. The `suffix` of each is what gets checked.
  */
+const BRAND_TOKENS: readonly BrandToken[] = [
+  { key: 'primary', suffix: 'primary', purpose: 'primary brand color' },
+  {
+    key: 'primaryFg',
+    suffix: 'primary-foreground',
+    purpose: 'AA-contrast foreground on primary (auto-selected black/white)',
+  },
+  { key: 'ring', suffix: 'ring', purpose: 'keyboard focus ring' },
+  { key: 'accent', suffix: 'accent', purpose: 'tinted accent surface' },
+  { key: 'accentFg', suffix: 'accent-foreground', purpose: 'text on accent surface' },
+];
+
+interface EmittedTokens {
+  readonly tokens: readonly { key: keyof TokenSet; name: string; purpose: string }[];
+  /** Value-column offset, derived so the block stays aligned when a name changes length. */
+  readonly valueColumn: number;
+}
+
+let memo: EmittedTokens | undefined;
+
+/**
+ * BRAND_TOKENS with each name resolved against theme.css, memoized.
+ *
+ * Called from the handler, so the resolution failure lands on the one tool that
+ * cannot do its job (see colorToken). Only a SUCCESSFUL resolution is cached —
+ * a failing one re-throws per call, which is what keeps the error the same on
+ * the second request as on the first.
+ */
+function emittedTokens(): EmittedTokens {
+  if (!memo) {
+    const tokens = BRAND_TOKENS.map((t) => ({
+      key: t.key,
+      name: colorToken(t.suffix),
+      purpose: t.purpose,
+    }));
+    memo = { tokens, valueColumn: Math.max(...tokens.map((t) => t.name.length + 1)) + 2 };
+  }
+  return memo;
+}
 
 // ─── hex color utilities (no deps) ──────────────────────────────────────────
 
@@ -185,14 +306,6 @@ function resolveBrand(
 
 // ─── CSS block builders ───────────────────────────────────────────────────────
 
-interface TokenSet {
-  primary: string;
-  primaryFg: string;
-  ring: string;
-  accent: string;
-  accentFg: string;
-}
-
 function buildTokenSet(r: number, g: number, b: number): TokenSet {
   const primary = toHex(r, g, b);
   const primaryFg = foreground(r, g, b);
@@ -228,14 +341,12 @@ function buildDarkTokenSet(r: number, g: number, b: number): TokenSet {
   };
 }
 
-function cssBlock(selector: string, tokens: TokenSet): string {
+function cssBlock(selector: string, values: TokenSet, emitted: EmittedTokens): string {
   return [
     `${selector} {`,
-    `  --kai-color-primary:             ${tokens.primary};`,
-    `  --kai-color-primary-foreground:  ${tokens.primaryFg};`,
-    `  --kai-color-ring:                ${tokens.ring};`,
-    `  --kai-color-accent:              ${tokens.accent};`,
-    `  --kai-color-accent-foreground:   ${tokens.accentFg};`,
+    ...emitted.tokens.map(
+      (t) => `  ${`${t.name}:`.padEnd(emitted.valueColumn)}${values[t.key]};`,
+    ),
     `}`,
   ].join('\n');
 }
@@ -274,6 +385,10 @@ export const theme: Tool = {
       mode = 'light',
     } = args as { brand?: string; description?: string; mode?: 'light' | 'dark' | 'both' };
 
+    // Resolve the token names against theme.css FIRST, so a name it no longer
+    // declares fails this call and nothing else (see emittedTokens/colorToken).
+    const emitted = emittedTokens();
+
     const { hex, r, g, b, note } = resolveBrand(brand, description);
 
     const lightTokens = buildTokenSet(r, g, b);
@@ -282,10 +397,10 @@ export const theme: Tool = {
     // Which blocks to emit
     const blocks: string[] = [];
     if (mode === 'light' || mode === 'both') {
-      blocks.push(cssBlock(':root', lightTokens));
+      blocks.push(cssBlock(':root', lightTokens, emitted));
     }
     if (mode === 'dark' || mode === 'both') {
-      blocks.push(cssBlock('.dark', darkTokens));
+      blocks.push(cssBlock('.dark', darkTokens, emitted));
     }
 
     const cssOutput = blocks.join('\n\n');
@@ -293,6 +408,11 @@ export const theme: Tool = {
     const noteLabel = note.startsWith('Could not parse') ? 'Note' : 'Assumption';
     const noteSection = note ? `\n> **${noteLabel}:** ${note}\n` : '';
 
+    // Same list, same source, so the prose can't describe a different set of
+    // tokens than the CSS block above it.
+    const tokenList = emitted.tokens.map((t) => `- \`${t.name}\` — ${t.purpose}`).join('\n');
+    const firstToken = emitted.tokens[0].name;
+
     const text = `\
 ## AI/UI theme override — \`${hex}\`
 ${noteSection}
@@ -304,14 +424,10 @@ ${cssOutput}
 
 ### How it works
 
-The \`--kai-color-*\` tokens pierce the Shadow DOM via CSS custom-property inheritance. Every \`kai-*\` element reads them through a \`var(--kai-color-primary, <default>)\` fallback chain defined in \`theme.css\`. Setting them on \`:root\` (or a wrapper element) is enough to rebrand everything globally.
+The \`--kai-color-*\` tokens pierce the Shadow DOM via CSS custom-property inheritance. Every \`kai-*\` element reads them through a \`var(${firstToken}, <default>)\` fallback chain defined in \`theme.css\`. Setting them on \`:root\` (or a wrapper element) is enough to rebrand everything globally.
 
-**Tokens emitted** (verified names from \`theme.css\`):
-- \`--kai-color-primary\` — primary brand color
-- \`--kai-color-primary-foreground\` — AA-contrast foreground on primary (auto-selected black/white)
-- \`--kai-color-ring\` — keyboard focus ring
-- \`--kai-color-accent\` — tinted accent surface
-- \`--kai-color-accent-foreground\` — text on accent surface
+**Tokens emitted** (names read from \`theme.css\`):
+${tokenList}
 
 ### Apply to a subtree only
 

package/src/agent-tooling/mcp/validate-args.ts

@@ -0,0 +1,141 @@
+import { z } from 'zod';
+
+/**
+ * The ONE argument-validation path for every AI/UI MCP tool. server.ts calls
+ * this at dispatch, before any handler runs.
+ *
+ * Why it exists: every tool advertises `additionalProperties: false` and a
+ * `required` list over the protocol, and dispatch used to enforce neither —
+ * `request.params.arguments` went straight to the handler. The observed cost
+ * (ladder spec candidate A, twice reproduced): `component_reference` called
+ * with `{ element: "kai-chat" }` instead of `{ name: "kai-chat" }` silently
+ * returned the full element index with `isError` unset — an answer to a
+ * question nobody asked, indistinguishable from success. Decide loudly.
+ *
+ * Scope: unknown keys and missing required keys — the two failures the declared
+ * schema promises to reject and the handler cannot see (an unknown key is
+ * invisible to a handler that only reads the keys it knows). Value TYPES stay
+ * with the handlers, which already own them with better context (e.g. the
+ * provider guard in reference.ts, the registry checks in scaffold.ts).
+ *
+ * Everything here is DERIVED from the tool's zod schema — key list, requiredness
+ * (does the key's schema accept `undefined`?), type words — never restated, so a
+ * schema change moves the error text on its own.
+ */
+
+/** Levenshtein distance, for near-miss key suggestions ("framwork" → "framework"). */
+function editDistance(a: string, b: string): number {
+  const prev = new Array<number>(b.length + 1);
+  for (let j = 0; j <= b.length; j++) prev[j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    let diag = prev[0];
+    prev[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const tmp = prev[j];
+      prev[j] = Math.min(
+        prev[j] + 1,
+        prev[j - 1] + 1,
+        diag + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+      diag = tmp;
+    }
+  }
+  return prev[b.length];
+}
+
+/** A short type word for one property, read off the tool's advertised JSON Schema. */
+function typeWord(prop: Record<string, unknown> | undefined): string {
+  if (!prop) return 'value';
+  if (Array.isArray(prop.enum)) return prop.enum.map((v) => JSON.stringify(v)).join(' | ');
+  if (prop.type === 'array') {
+    const items = prop.items as Record<string, unknown> | undefined;
+    return `array of ${typeof items?.type === 'string' ? items.type : 'values'}`;
+  }
+  return typeof prop.type === 'string' ? prop.type : 'value';
+}
+
+/**
+ * Which schema key an unknown key most likely meant.
+ *
+ * 1. Spelling: edit distance ≤ 2 to a schema key ("framwork" → "framework").
+ * 2. Value shape: if exactly one NOT-yet-supplied schema key accepts the value
+ *    the caller passed, that's the one ("element": "kai-chat" → "name", because
+ *    `name` takes a string and `provider`'s enum rejects it). Two candidates
+ *    means guessing, so no suggestion — the expected-arguments block below the
+ *    message still teaches.
+ */
+function suggestKey(
+  unknownKey: string,
+  value: unknown,
+  shape: z.ZodRawShape,
+  supplied: readonly string[],
+): string | undefined {
+  const keys = Object.keys(shape);
+  let best: string | undefined;
+  let bestDistance = 3; // accept ≤ 2
+  for (const key of keys) {
+    const d = editDistance(unknownKey.toLowerCase(), key.toLowerCase());
+    if (d < bestDistance) {
+      bestDistance = d;
+      best = key;
+    }
+  }
+  if (best !== undefined) return best;
+
+  const byValue = keys.filter(
+    (key) => !supplied.includes(key) && z.safeParse(shape[key] as z.ZodType, value).success,
+  );
+  return byValue.length === 1 ? byValue[0] : undefined;
+}
+
+/**
+ * Validate `args` against a tool's declared zod object schema. Returns the full
+ * teaching error text on failure, or `undefined` when the arguments conform.
+ */
+export function validateToolArgs(
+  toolName: string,
+  schema: z.ZodObject<z.ZodRawShape>,
+  args: Record<string, unknown>,
+): string | undefined {
+  const shape = schema.shape;
+  const keys = Object.keys(shape);
+  const supplied = Object.keys(args);
+
+  const problems: string[] = [];
+
+  for (const key of supplied) {
+    if (keys.includes(key)) continue;
+    const suggestion = suggestKey(key, args[key], shape, supplied);
+    problems.push(
+      `unknown argument ${JSON.stringify(key)}` +
+        (suggestion ? ` — did you mean ${JSON.stringify(suggestion)}?` : ''),
+    );
+  }
+
+  for (const key of keys) {
+    // Required = the key's own schema refuses `undefined`. Derived, not listed.
+    if (!(key in args) && !z.safeParse(shape[key] as z.ZodType, undefined).success) {
+      problems.push(`missing required argument ${JSON.stringify(key)}`);
+    }
+  }
+
+  if (problems.length === 0) return undefined;
+
+  // The expected-arguments block, from the same JSON Schema the tool advertises.
+  const json = z.toJSONSchema(schema) as {
+    properties?: Record<string, Record<string, unknown>>;
+    required?: string[];
+  };
+  const required = new Set(json.required ?? []);
+  const argLines = keys.map((key) => {
+    const kind = required.has(key) ? 'required' : 'optional';
+    return `  ${key} (${kind}) — ${typeWord(json.properties?.[key])}`;
+  });
+
+  return (
+    `${toolName}: ${problems.join('; ')}.\n\n` +
+    `Nothing was returned for this call — answering anyway could look like a reply ` +
+    `to the question you meant to ask.\n\n` +
+    `Expected arguments for ${toolName}:\n${argLines.join('\n')}`
+  );
+}

package/src/agent-tooling/registry.ts

@@ -72,10 +72,18 @@ export interface GatewayGroup {
  *
  * THE ORDER OF THE TESTS IS THE DESIGN, not an implementation detail:
  *
- *   1. No route at all -> **No backend**. Exactly `mock` today, and derived from
- *      the absence rather than from `id === 'mock'` or `category === 'mock'`: a
- *      second no-backend entry (a canned transcript player, say) should land in
- *      this group without editing this function.
+ *   1. `keyExposure === 'frontend-safe' && outOfBand === 'none'` -> **No
+ *      backend**. Exactly `mock` today, and still derived from declared facts
+ *      rather than from `id === 'mock'` or `category === 'mock'`: a second
+ *      no-backend entry (a canned transcript player, say) lands here by
+ *      declaring the same two. This USED to be "has no route at all", and the
+ *      G-04 fix broke that derivation on purpose: mock now ships an OPTIONAL
+ *      route (the same responder frames over HTTP), and a route the app runs
+ *      fine without must not move its heading. What "no backend" really claims
+ *      is that the browser can do the whole job — nothing secret or server-only
+ *      (frontend-safe) and nothing to install or start out of band ('none') —
+ *      so that pair is the derivation. `ollama` is the near-miss that keeps it
+ *      honest: frontend-safe, but 'local-server' — something must be listening.
  *   2. `outOfBand !== 'none'` -> **Bring a server or runtime**, and this is
  *      checked BEFORE the key test on purpose. `pydantic-ai` needs both a python
  *      runtime and OPENAI_API_KEY; the groups are not disjoint in reality, so
@@ -92,8 +100,12 @@ export interface GatewayGroup {
  * wrong about that one entry; this is the derivation, so this is the answer.
  */
 export function listGatewayGroups(): GatewayGroup[] {
-  const hasRoute = (i: Integration) =>
-    i.webRoute !== undefined || Object.keys(i.routeTemplates).length > 0;
+  // The browser can do the whole job: nothing secret or server-only, nothing to
+  // install or start. NOT "has no route" — mock's G-04 route is optional, and a
+  // route the app runs fine without must not move its heading (see the comment
+  // above).
+  const selfContained = (i: Integration) =>
+    i.keyExposure === 'frontend-safe' && i.outOfBand === 'none';
 
   const groups: GatewayGroup[] = [
     { id: 'no-backend', title: 'No backend', integrations: [] },
@@ -103,7 +115,7 @@ export function listGatewayGroups(): GatewayGroup[] {
   const into = (id: GatewayGroup['id']) => groups.find((g) => g.id === id)!;
 
   for (const integration of integrations) {
-    if (!hasRoute(integration)) into('no-backend').integrations.push(integration);
+    if (selfContained(integration)) into('no-backend').integrations.push(integration);
     else if (integration.outOfBand !== 'none') into('bring-a-server').integrations.push(integration);
     else into('bring-a-key').integrations.push(integration);
   }

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

@@ -135,9 +135,33 @@ const CHAT_REQUEST_BODY_DECL = [
   `  tools?: unknown[];`,
   `};`,
   ``,
-  `/** Narrow the JSON body once, at the edge. */`,
+  `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: one killed a Vite dev server (findings F-10). */`,
   `async function readChatRequest(request: Request): Promise<ChatRequestBody> {`,
-  `  return (await request.json()) as 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;`,
   `}`,
 ];
 

package/src/components/attachment-types.ts

@@ -9,5 +9,51 @@ export interface AttachmentData {
   title?: string;
 }
 
-export type AttachmentMediaCategory = 'image' | 'video' | 'audio' | 'document' | 'source' | 'unknown';
+/**
+ * How an attachment is DRAWN, derived from what the wire can do with it.
+ *
+ * ★ THIS IS NOT A LIST OF MEDIA TYPES, and that is the whole point. It used to
+ * be one in disguise (`image | video | audio | document`, decided by a prefix
+ * switch in `attachments.tsx`), and it disagreed with `wire/media-types.ts` in
+ * both directions: SVG and MP4 drew a convincing preview that then threw at
+ * encode time, while PDF and text — the formats the wire handles best — drew
+ * the same anonymous icon as a `.zip`. `getMediaCategory` now asks the media
+ * policy and returns what it says, so there is one declaration and this is a
+ * projection of it.
+ *
+ * `image` / `document` / `text` ARE `EncodableKind` from `wire/media-types.ts`.
+ * They are spelled out rather than imported because this module is deliberately
+ * JSX-free and dependency-free for the framework-neutral consumers; the runtime
+ * agreement is pinned by `attachment-media-policy.test.tsx`, whose drift guard
+ * derives both sides from the policy.
+ *
+ * `video` and `audio` are GONE on purpose. No wire this kit ships can carry
+ * either, so they were categories whose only job was to make an unsendable file
+ * look sendable; both now land in `unsendable`.
+ */
+export type AttachmentMediaCategory =
+  /** A raster image in one of the four formats both APIs document. */
+  | 'image'
+  /** A PDF. Named for the Anthropic `document` block it becomes. */
+  | 'document'
+  /** Text content — `text/*`, JSON, XML, YAML. Rides as text on both wires. */
+  | 'text'
+  /** A RAG citation chip, not something the user staged. Never encoded. */
+  | 'source'
+  /**
+   * No wire format this kit ships can carry this type — SVG, BMP, video, audio,
+   * archives. That is a fact about the kit's encoders, knowable at render time
+   * and true of every provider, which is why it is safe to show the user.
+   *
+   * It is NOT "this will fail to send": the renderer does not know which
+   * provider a thread is bound for, and must not pretend to.
+   */
+  | 'unsendable'
+  /**
+   * Nobody named this file, so nothing is known yet. Its bytes decide it (see
+   * `classifyAttachment`), and they have not been read at render time. Marking
+   * it `unsendable` would be a guess wearing a fact's clothes.
+   */
+  | 'unknown';
+
 export type AttachmentVariant = 'grid' | 'inline' | 'list';