create-kai 0.1.0

package/dist/templates/tanstack-start/serve.traversal.test.mjs

@@ -0,0 +1,445 @@
+// Static-file guard tests for serve.mjs. Zero dependencies: `node --test`.
+//
+//   node --test examples/starters/tanstack-start/serve.traversal.test.mjs
+//
+// This starter is deliberately NOT a pnpm workspace member (see pnpm-workspace.yaml
+// -- it is a standalone `file:` consumer with its own npm lockfile), so it has no
+// vitest and no nx `test` target. Node's built-in runner is the only thing available
+// that costs no dependency and no lockfile churn.
+//
+// The tests spawn the REAL serve.mjs, byte-for-byte, against a synthetic fixture
+// tree, and speak raw HTTP/1.0 over a socket so the request target arrives exactly
+// as written. `fetch`/undici normalises or rejects several of these targets before
+// they leave the client, which would quietly turn a probe into a no-op.
+//
+// ---------------------------------------------------------------------------
+// WHY THE `not vacuous` BLOCK EXISTS -- read this before deleting it
+// ---------------------------------------------------------------------------
+// A traversal suite that has only ever run against fixed code proves nothing: the
+// pre-fix serve.mjs never decoded anything, so every payload below would have
+// passed against it *by accident*, and a green run would have been evidence of
+// exactly nothing. The `not vacuous` block pins that down by re-running the same
+// probes against two deliberately wrong implementations -- the two fixes a
+// reasonable person actually writes -- and asserting they LEAK. If someone
+// reorders the real guard back to either shape, the block that proves the suite
+// can fail is itself the thing that starts failing.
+import { test, describe, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import net from 'node:net';
+import { spawn } from 'node:child_process';
+import { mkdtemp, mkdir, writeFile, readFile, rm } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REAL_SERVE = join(HERE, 'serve.mjs');
+
+// Markers. A response body containing one of these means the file was read.
+const TOP_SECRET = 'TOP-SECRET-OUTSIDE-CLIENT-DIR';
+const SIBLING_LEAK = 'SIBLING-DIR-LEAK';
+const HASHED_ASSET = 'hashed-asset-ok';
+const SPACE_ASSET = 'space-asset-ok';
+const SSR = 'SSR-FALLBACK';
+
+/** A stub of the fetch handler `vite build` emits at dist/server/server.js. */
+const SERVER_STUB = `export default {
+  fetch: async () => new Response(${JSON.stringify(SSR)}, {
+    status: 200,
+    headers: { 'content-type': 'text/html' },
+  }),
+};
+`;
+
+/**
+ * Replace the whole `serveStatic` function in serve.mjs's source. Used only by the
+ * `not vacuous` block. Fails loudly rather than silently no-op'ing, so a refactor of
+ * serve.mjs surfaces as a broken test instead of a test that stopped testing.
+ */
+function withServeStatic(source, replacement) {
+  const re = /async function serveStatic\(pathname\) \{[\s\S]*?\n\}\n/;
+  assert.match(
+    source,
+    re,
+    'could not find `async function serveStatic(pathname) { ... }` in serve.mjs -- ' +
+      'the variant injection in the `not vacuous` block needs updating',
+  );
+  return source.replace(re, replacement);
+}
+
+// The classic wrong order: containment is checked on the ENCODED path, and the
+// decode that produces the string the filesystem actually sees happens afterwards.
+// `%2e%2e` sails past a guard that already declared the path safe.
+const VARIANT_GUARD_BEFORE_DECODE = `async function serveStatic(pathname) {
+  if (pathname === '/' || pathname.endsWith('/')) return null;
+  const filePath = join(clientDir, pathname);
+  if (!filePath.startsWith(clientDir)) return null; // guard runs on the ENCODED path
+  const onDisk = decodeURIComponent(filePath);     // ...and the decode happens AFTER it
+  try {
+    if (!(await stat(onDisk)).isFile()) return null;
+  } catch {
+    return null;
+  }
+  const body = await readFile(onDisk);
+  return new Response(body, {
+    headers: { 'content-type': TYPES[extname(onDisk)] ?? 'application/octet-stream' },
+  });
+}
+`;
+
+// Decodes in the right place, but compares with a bare prefix match. `dist/client`
+// is a string prefix of `dist/client-secret`, so a sibling directory is reachable.
+// Also lets decodeURIComponent's URIError escape as a 500.
+const VARIANT_PREFIX_MATCH = `async function serveStatic(pathname) {
+  if (pathname === '/' || pathname.endsWith('/')) return null;
+  const filePath = join(clientDir, decodeURIComponent(pathname));
+  if (!filePath.startsWith(clientDir)) return null; // no separator boundary
+  try {
+    if (!(await stat(filePath)).isFile()) return null;
+  } catch {
+    return null;
+  }
+  const body = await readFile(filePath);
+  return new Response(body, {
+    headers: { 'content-type': TYPES[extname(filePath)] ?? 'application/octet-stream' },
+  });
+}
+`;
+
+async function freePort() {
+  const probe = net.createServer();
+  await new Promise((resolve) => probe.listen(0, '127.0.0.1', resolve));
+  const { port } = probe.address();
+  await new Promise((resolve) => probe.close(resolve));
+  return port;
+}
+
+/**
+ * Build a fixture tree and spawn serve.mjs against it.
+ *
+ *   <fixture>/secret.txt                    <- TWO levels above clientDir
+ *   <fixture>/dist/client-secret/leak.txt   <- SIBLING whose name has clientDir as a prefix
+ *   <fixture>/dist/client/assets/app.js     <- an ordinary hashed asset
+ *   <fixture>/dist/client/assets/a b.js     <- a name only reachable once %20 is decoded
+ */
+async function startServer({ transform = (s) => s } = {}) {
+  const dir = await mkdtemp(join(tmpdir(), 'kai-tss-serve-'));
+  await mkdir(join(dir, 'dist', 'server'), { recursive: true });
+  await mkdir(join(dir, 'dist', 'client', 'assets'), { recursive: true });
+  await mkdir(join(dir, 'dist', 'client-secret'), { recursive: true });
+
+  await writeFile(join(dir, 'secret.txt'), TOP_SECRET);
+  await writeFile(join(dir, 'dist', 'client-secret', 'leak.txt'), SIBLING_LEAK);
+  await writeFile(join(dir, 'dist', 'server', 'server.js'), SERVER_STUB);
+  await writeFile(join(dir, 'dist', 'client', 'assets', 'app.js'), HASHED_ASSET);
+  await writeFile(join(dir, 'dist', 'client', 'assets', 'a b.js'), SPACE_ASSET);
+
+  const source = await readFile(REAL_SERVE, 'utf8');
+  await writeFile(join(dir, 'serve.mjs'), transform(source));
+
+  const port = await freePort();
+  const child = spawn(process.execPath, ['serve.mjs'], {
+    cwd: dir,
+    env: { ...process.env, PORT: String(port) },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  let stderr = '';
+  child.stderr.on('data', (d) => {
+    stderr += d;
+  });
+
+  await new Promise((resolve, reject) => {
+    const timer = setTimeout(
+      () => reject(new Error(`serve.mjs did not start in 10s. stderr:\n${stderr}`)),
+      10_000,
+    );
+    child.stdout.on('data', (d) => {
+      if (String(d).includes('http://localhost:')) {
+        clearTimeout(timer);
+        resolve();
+      }
+    });
+    child.on('exit', (code) => {
+      clearTimeout(timer);
+      reject(new Error(`serve.mjs exited early (code ${code}). stderr:\n${stderr}`));
+    });
+  });
+
+  return {
+    port,
+    stderr: () => stderr,
+    async stop() {
+      child.kill('SIGKILL');
+      await rm(dir, { recursive: true, force: true });
+    },
+  };
+}
+
+/**
+ * Send one request over a raw socket so the request target is byte-exact.
+ * HTTP/1.0 keeps the response unchunked and closes the connection, so the body is
+ * simply everything after the header block.
+ *
+ * A socket-level failure (Node's HTTP parser rejecting the target outright) resolves
+ * as status 0 -- for a malicious payload that is a perfectly good outcome, and the
+ * assertions below treat it as one.
+ */
+function get(port, target) {
+  return new Promise((resolve) => {
+    const socket = net.connect(port, '127.0.0.1');
+    const chunks = [];
+    socket.setTimeout(5000);
+    socket.on('connect', () => {
+      socket.write(`GET ${target} HTTP/1.0\r\nHost: 127.0.0.1:${port}\r\n\r\n`);
+    });
+    socket.on('data', (d) => chunks.push(d));
+    socket.on('timeout', () => {
+      socket.destroy();
+      resolve({ status: 0, head: '', body: '', note: 'TIMEOUT' });
+    });
+    socket.on('error', (err) => resolve({ status: 0, head: '', body: '', note: err.code ?? String(err) }));
+    socket.on('close', () => {
+      const text = Buffer.concat(chunks).toString('utf8');
+      const split = text.indexOf('\r\n\r\n');
+      const head = split === -1 ? text : text.slice(0, split);
+      const body = split === -1 ? '' : text.slice(split + 4);
+      const matched = /^HTTP\/\d\.\d (\d{3})/.exec(head);
+      resolve({ status: matched ? Number(matched[1]) : 0, head, body, note: '' });
+    });
+  });
+}
+
+// Payloads that reach serveStatic STILL ENCODED, because the WHATWG URL parser
+// leaves %2f/%5c alone. These are the ones that can actually escape, and they are
+// the ones the `not vacuous` block below uses to prove the suite bites.
+const LIVE_PAYLOADS = [
+  ['encoded slash', '/..%2f..%2fsecret.txt', TOP_SECRET],
+  ['encoded slash, upper case', '/..%2F..%2Fsecret.txt', TOP_SECRET],
+  ['fully encoded segment', '/%2e%2e%2f%2e%2e%2fsecret.txt', TOP_SECRET],
+  ['fully encoded, upper case', '/%2E%2E%2F%2E%2E%2Fsecret.txt', TOP_SECRET],
+  ['fully encoded, mixed case', '/%2e%2E%2f%2E%2e%2Fsecret.txt', TOP_SECRET],
+  ['double encoded', '/%252e%252e/%252e%252e/secret.txt', TOP_SECRET],
+  ['double encoded slash', '/..%252f..%252fsecret.txt', TOP_SECRET],
+  ['triple encoded', '/%25252e%25252e/%25252e%25252e/secret.txt', TOP_SECRET],
+  ['sibling dir sharing a name prefix', '/..%2fclient-secret%2fleak.txt', SIBLING_LEAK],
+  ['sibling dir, fully encoded', '/%2e%2e%2fclient-secret%2fleak.txt', SIBLING_LEAK],
+  ['encoded backslash', '/..%5c..%5csecret.txt', TOP_SECRET],
+  ['encoded backslash, upper case', '/..%5C..%5Csecret.txt', TOP_SECRET],
+  ['mixed separators', '/%2e%2e%5c%2e%2e%2fsecret.txt', TOP_SECRET],
+  ['deep climb', '/%2e%2e%2f%2e%2e%2f%2e%2e%2f%2e%2e%2f%2e%2e%2fetc%2fpasswd', 'root:'],
+  ['encoded absolute path', '/%2fetc%2fpasswd', 'root:'],
+];
+
+// Payloads the WHATWG URL parser already collapses before serveStatic sees them
+// (`new URL` treats `%2e` as a dot for path normalisation). Kept deliberately: they
+// are defence in depth, and they become live again the moment anyone stops routing
+// the request target through `new URL` -- e.g. by splitting `req.url` on '?' by hand.
+// The `relies on` block below pins the upstream behaviour so a Node change surfaces
+// here rather than as a silent regression.
+const NEUTRALISED_UPSTREAM = [
+  ['plain dot-dot', '/../../secret.txt', TOP_SECRET],
+  ['encoded dot-dot', '/%2e%2e/%2e%2e/secret.txt', TOP_SECRET],
+  ['encoded dot-dot, upper case', '/%2E%2E/%2E%2E/secret.txt', TOP_SECRET],
+  ['encoded dot-dot, mixed case', '/%2e%2E/%2E%2e/secret.txt', TOP_SECRET],
+  ['encoded dot-dot then sibling', '/%2e%2e/client-secret/leak.txt', SIBLING_LEAK],
+  ['plain backslash', '/..\\..\\secret.txt', TOP_SECRET],
+  ['absolute path, plain', '/etc/passwd', 'root:'],
+];
+
+/** Every payload that must never reach a file outside dist/client. */
+const TRAVERSAL_PAYLOADS = [...LIVE_PAYLOADS, ...NEUTRALISED_UPSTREAM];
+
+describe('serve.mjs static guard', () => {
+  let server;
+  before(async () => {
+    server = await startServer();
+  });
+  after(async () => {
+    await server.stop();
+  });
+
+  for (const [name, target, marker] of TRAVERSAL_PAYLOADS) {
+    test(`refuses traversal: ${name} -- ${target}`, async () => {
+      const res = await get(server.port, target);
+      assert.ok(
+        !res.body.includes(marker),
+        `LEAKED. ${target} returned ${res.status} with a body containing ${JSON.stringify(marker)}:\n${res.body.slice(0, 400)}`,
+      );
+      assert.notEqual(res.status, 500, `${target} should not 500 (got head:\n${res.head})`);
+    });
+  }
+
+  test('a decode that throws is a 400, not a crash', async () => {
+    // decodeURIComponent('%') throws URIError.
+    const res = await get(server.port, '/%');
+    assert.equal(res.status, 400, `expected 400 for "/%", got ${res.status}\n${res.head}`);
+  });
+
+  test('an invalid escape sequence is a 400', async () => {
+    const res = await get(server.port, '/assets/%zz.js');
+    assert.equal(res.status, 400, `expected 400 for "/assets/%zz.js", got ${res.status}\n${res.head}`);
+  });
+
+  test('a lone trailing percent is a 400', async () => {
+    const res = await get(server.port, '/assets/app.js%');
+    assert.equal(res.status, 400, `expected 400 for "/assets/app.js%", got ${res.status}\n${res.head}`);
+  });
+
+  test('a null byte is rejected, not passed to the filesystem', async () => {
+    const res = await get(server.port, '/assets/app.js%00.png');
+    assert.equal(res.status, 400, `expected 400 for an embedded null byte, got ${res.status}\n${res.head}`);
+    assert.ok(!res.body.includes(HASHED_ASSET), 'null-byte truncation served the asset');
+  });
+
+  test('a backslash is rejected rather than treated as a name character', async () => {
+    const res = await get(server.port, '/assets%5capp.js');
+    assert.equal(res.status, 400, `expected 400 for an encoded backslash, got ${res.status}\n${res.head}`);
+  });
+
+  test('the server survives the whole payload list and still serves assets', async () => {
+    for (const [, target] of TRAVERSAL_PAYLOADS) await get(server.port, target);
+    const res = await get(server.port, '/assets/app.js');
+    assert.equal(res.status, 200, `server stopped serving after the payload run\n${server.stderr()}`);
+    assert.ok(res.body.includes(HASHED_ASSET));
+  });
+});
+
+describe('serve.mjs still serves ordinary traffic', () => {
+  let server;
+  before(async () => {
+    server = await startServer();
+  });
+  after(async () => {
+    await server.stop();
+  });
+
+  test('a hashed asset is served from disk with its content type', async () => {
+    const res = await get(server.port, '/assets/app.js');
+    assert.equal(res.status, 200, res.head);
+    assert.ok(res.body.includes(HASHED_ASSET), `body was ${JSON.stringify(res.body)}`);
+    assert.match(res.head, /content-type: text\/javascript/i);
+  });
+
+  test('a percent-encoded space resolves to the real filename', async () => {
+    const res = await get(server.port, '/assets/a%20b.js');
+    assert.equal(res.status, 200, res.head);
+    assert.ok(
+      res.body.includes(SPACE_ASSET),
+      `"/assets/a%20b.js" must serve the file named "a b.js"; got ${res.status}: ${JSON.stringify(res.body)}`,
+    );
+    assert.match(res.head, /content-type: text\/javascript/i);
+  });
+
+  test('an unknown extension falls back to octet-stream', async () => {
+    const res = await get(server.port, '/assets/a%20b.js');
+    assert.equal(res.status, 200, res.head);
+  });
+
+  test('/ falls through to the SSR handler', async () => {
+    const res = await get(server.port, '/');
+    assert.equal(res.status, 200, res.head);
+    assert.ok(res.body.includes(SSR), `body was ${JSON.stringify(res.body)}`);
+  });
+
+  test('an SPA route falls through to the SSR handler', async () => {
+    const res = await get(server.port, '/some/deep/route');
+    assert.equal(res.status, 200, res.head);
+    assert.ok(res.body.includes(SSR), `body was ${JSON.stringify(res.body)}`);
+  });
+
+  test('a missing asset falls through to the SSR handler', async () => {
+    const res = await get(server.port, '/assets/does-not-exist.js');
+    assert.equal(res.status, 200, res.head);
+    assert.ok(res.body.includes(SSR), `body was ${JSON.stringify(res.body)}`);
+  });
+
+  test('a trailing-slash path falls through to the SSR handler', async () => {
+    const res = await get(server.port, '/assets/');
+    assert.equal(res.status, 200, res.head);
+    assert.ok(res.body.includes(SSR), `body was ${JSON.stringify(res.body)}`);
+  });
+});
+
+describe('serve.mjs relies on `new URL` collapsing dot-segments', () => {
+  // serve.mjs hands serveStatic `url.pathname`, never the raw `req.url`. The WHATWG
+  // URL parser resolves dot-segments AND treats a percent-encoded `%2e` as a dot
+  // while doing it, so `..` and `%2e%2e` are gone before the handler runs. It does
+  // NOT decode `%2f`, which is why the encoded slash is the vector that survives.
+  //
+  // Written down as an executable assertion rather than a comment because the whole
+  // NEUTRALISED_UPSTREAM list is only safe for as long as this holds. Whoever swaps
+  // `new URL` for hand-rolled `req.url.split('?')[0]` parsing needs this to fail.
+  test('`..` and `%2e%2e` segments are resolved away', () => {
+    for (const raw of ['/../../secret.txt', '/%2e%2e/%2e%2e/secret.txt', '/%2E%2E/%2E%2E/secret.txt']) {
+      assert.equal(new URL(raw, 'http://h').pathname, '/secret.txt', `for ${raw}`);
+    }
+  });
+
+  test('a percent-encoded slash is NOT decoded, so it reaches the handler intact', () => {
+    assert.equal(new URL('/..%2f..%2fsecret.txt', 'http://h').pathname, '/..%2f..%2fsecret.txt');
+    assert.equal(new URL('/%2e%2e%2fsecret.txt', 'http://h').pathname, '/%2e%2e%2fsecret.txt');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Proof the block above can fail. See the header comment.
+// ---------------------------------------------------------------------------
+describe('the guard suite is not vacuous', () => {
+  describe('a build that checks containment BEFORE decoding', () => {
+    let server;
+    before(async () => {
+      server = await startServer({
+        transform: (s) => withServeStatic(s, VARIANT_GUARD_BEFORE_DECODE),
+      });
+    });
+    after(async () => {
+      await server.stop();
+    });
+
+    for (const target of [
+      '/..%2f..%2fsecret.txt',
+      '/..%2F..%2Fsecret.txt',
+      '/%2e%2e%2f%2e%2e%2fsecret.txt',
+    ]) {
+      test(`leaks a file two directories above dist/client via ${target}`, async () => {
+        const res = await get(server.port, target);
+        assert.ok(
+          res.body.includes(TOP_SECRET),
+          'the wrong-order build did NOT leak, so this payload proves nothing. ' +
+            `Got ${res.status}: ${JSON.stringify(res.body.slice(0, 200))}`,
+        );
+      });
+    }
+  });
+
+  describe('a build that decodes first but prefix-matches without a separator', () => {
+    let server;
+    before(async () => {
+      server = await startServer({ transform: (s) => withServeStatic(s, VARIANT_PREFIX_MATCH) });
+    });
+    after(async () => {
+      await server.stop();
+    });
+
+    for (const target of ['/..%2fclient-secret%2fleak.txt', '/%2e%2e%2fclient-secret%2fleak.txt']) {
+      test(`leaks a sibling directory whose name starts with the client dir via ${target}`, async () => {
+        const res = await get(server.port, target);
+        assert.ok(
+          res.body.includes(SIBLING_LEAK),
+          'the bare-prefix build did NOT leak the sibling, so that payload proves nothing. ' +
+            `Got ${res.status}: ${JSON.stringify(res.body.slice(0, 200))}`,
+        );
+      });
+    }
+
+    test('turns a URIError into a 500 instead of a 400', async () => {
+      const res = await get(server.port, '/%');
+      assert.equal(
+        res.status,
+        500,
+        `expected the unguarded decode to blow up as a 500; got ${res.status}. ` +
+          'If this is now 400 the variant no longer models the bug.',
+      );
+    });
+  });
+});

package/dist/templates/tanstack-start/src/chat-data.ts

@@ -0,0 +1,124 @@
+// Self-contained sample data + the kit's shared mock responder — no backend.
+//
+// THIS MODULE IS EVALUATED TWICE: once on the server while the route is being
+// rendered, and once in the browser. Everything in it is therefore plain data and
+// pure functions — nothing here touches `window`, `document` or `customElements`,
+// which is the rule for any module a server-rendered route imports.
+//
+// The date helper below is the one thing that produces a DIFFERENT value on each
+// of those two evaluations, and it is safe for a specific reason worth knowing:
+// `CONVERSATIONS` is only ever handed to `<kai-conversations>` as a JS PROPERTY,
+// and the React wrappers assign properties in a layout effect, which never runs on
+// the server. So no timestamp reaches the server-rendered HTML and there is
+// nothing for hydration to compare. Render one of these into JSX and that stops
+// being true — that is the shape of a real hydration mismatch.
+import type { MessagePart } from '@kitn.ai/ui';
+import { createMockResponder } from '@kitn.ai/ui/state';
+
+export interface Conversation {
+  id: string;
+  title: string;
+  scope: { type: 'document' | 'collection' };
+  messageCount: number;
+  lastMessageAt: string;
+  updatedAt: string;
+}
+
+export interface Msg {
+  id: string;
+  role: 'user' | 'assistant';
+  parts: MessagePart[];
+}
+
+export function newId(): string {
+  return typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
+    ? crypto.randomUUID()
+    : 'id-' + Math.random().toString(36).slice(2);
+}
+
+const iso = (daysAgo = 0) => new Date(Date.now() - daysAgo * 86_400_000).toISOString();
+
+export const CONVERSATIONS: Conversation[] = [
+  { id: 'c1', title: 'Server rendering', scope: { type: 'collection' }, messageCount: 2, lastMessageAt: iso(0), updatedAt: iso(0) },
+  { id: 'c2', title: 'Composing your own chat', scope: { type: 'collection' }, messageCount: 2, lastMessageAt: iso(0), updatedAt: iso(0) },
+  { id: 'c3', title: 'Theming + dark mode', scope: { type: 'collection' }, messageCount: 2, lastMessageAt: iso(1), updatedAt: iso(1) },
+];
+
+export const THREADS: Record<string, Msg[]> = {
+  c1: [
+    { id: 'c1u', role: 'user', parts: [{ type: 'text', text: 'How do the `kai-*` elements survive server rendering?' }] },
+    { id: 'c1a', role: 'assistant', parts: [{ type: 'text', text: "They server-render as **bare tags**. The React wrappers register their element inside a layout effect, which never runs on the server, so the SSR pass emits `<kai-thread></kai-thread>` and nothing more. After hydration the wrapper defines the element and assigns `messages` as a live JS **property** — arrays and objects go across unstringified, so nothing has to be serialized into an attribute.\n\nView source on this page: you'll find the empty tags. Then watch this reply stream in — that's the same property channel still working, one new array reference per chunk." }] },
+  ],
+  c2: [
+    { id: 'c2u', role: 'user', parts: [{ type: 'text', text: 'How do I build my own chat instead of dropping in `<kai-chat>`?' }] },
+    { id: 'c2a', role: 'assistant', parts: [{ type: 'text', text: "Put a `<Thread>` in a scroll area, a `<PromptInput>` below it, and let `useKaiChat` own the message array and the streaming. That's exactly what this route does — read `src/routes/index.tsx`." }] },
+  ],
+  c3: [
+    { id: 'c3u', role: 'user', parts: [{ type: 'text', text: 'How does dark mode work?' }] },
+    { id: 'c3a', role: 'assistant', parts: [{ type: 'text', text: "Each element takes a `theme` prop (`light` / `dark` / `auto`). Drive it from route state — toggle it with the button top-right. The kit's `--color-*` tokens flip under a `.dark` class for your own surrounding chrome." }] },
+  ],
+};
+
+export const SUGGESTIONS = [
+  'What survives server rendering?',
+  'How do I install it?',
+  'Show me some markdown',
+];
+
+// Rich entity triggers for the prompt input: typing `/` opens the skills menu,
+// `@` opens the agents menu. Each selection inserts an atomic pill. Set on
+// <PromptInput> as the `triggers` JS property (a TriggerDef[]).
+export const TRIGGERS = [
+  {
+    char: '/',
+    kind: 'skill',
+    items: [
+      { id: 'summarize', label: 'Summarize', description: 'Summarize the thread', promptText: 'Summarize the thread.' },
+      { id: 'translate', label: 'Translate', description: 'Translate to English', promptText: 'Translate to English.' },
+      { id: 'rewrite', label: 'Rewrite', description: 'Rewrite for clarity', promptText: 'Rewrite this for clarity.' },
+    ],
+  },
+  {
+    char: '@',
+    kind: 'agent',
+    items: [
+      { id: 'researcher', label: 'Researcher', description: 'Deep web research', group: 'Agents' },
+      { id: 'coder', label: 'Coder', description: 'Writes and edits code', group: 'Agents' },
+      { id: 'designer', label: 'Designer', description: 'UI and visual design', group: 'Agents' },
+    ],
+  },
+];
+
+// The replies the mock cycles through, one per turn. Markdown-rich on purpose:
+// the thread renders markdown, code blocks and blockquotes, so the canned replies
+// exercise that instead of only proving text arrives.
+//
+// The first one says it is a mock in words. That is the WEAKEST of the responder's
+// tells and the only one a real model could imitate, which is exactly why it is
+// not the only one — the rest are on the wire, below.
+const MOCK_REPLIES = [
+  "This reply streams token-by-token from the kit's own mock responder — no API key, no backend, no provider was contacted. Replace `mockResponse(text)` with a real model call (Anthropic, OpenAI, your own route) to ship a real app.",
+  "Install it:\n\n```bash\nnpm install @kitn.ai/ui\n```\n\nThen import the wrappers + tokens:\n\n```tsx\nimport { Thread, PromptInput } from '@kitn.ai/ui/react';\nimport '@kitn.ai/ui/theme.tokens.css';\n```",
+  "I render **bold**, *italic*, `inline code`, lists, and code blocks:\n\n```ts\nconst stream = chat.streamAssistant();\nawait readOpenAIStream(mockResponse(text), stream);\nstream.done();\n```\n\n> Blockquotes too.",
+  "Nothing about this thread came from the server. TanStack Start rendered the **empty** `<kai-thread>` tag, the browser hydrated it, and every chunk you are reading now arrived as a new `messages` array assigned to that element as a JS property.",
+];
+
+/**
+ * The kit's own mock responder, shared with the `kai` MCP scaffolder and
+ * `create-kai` so there is ONE implementation of this and not seven.
+ *
+ * It yields canned SSE frames in the OpenAI chat-completions shape, which
+ * `readOpenAIStream` parses exactly as it parses a real provider's. So this
+ * no-backend preview runs the kit's REAL streaming path — the SSE reader, the
+ * part folding, all of it — rather than a hand-rolled loop that merely resembles
+ * it. Going live then changes one expression, not the handler.
+ *
+ * It also cannot be mistaken for a real turn: the stream opens with a `: kai-mock`
+ * SSE comment, every frame carries a `_kai_mock` field, `model` reports as
+ * `kai-mock` (no provider serves that, so an echoed mock frame is rejected
+ * upstream rather than quietly believed), and usage is all zeros.
+ *
+ * MODULE scope, not per-send: the responder owns the cursor into the replies
+ * above, so rebuilding it each turn would answer with the first one forever.
+ */
+export const mockResponse = createMockResponder({ replies: MOCK_REPLIES });

package/dist/templates/tanstack-start/src/components/Composer.tsx

@@ -0,0 +1,87 @@
+import { useCallback, useRef } from 'react';
+import { PromptInput, useVoiceInput } from '@kitn.ai/ui/react';
+import type { PromptInputProps } from '@kitn.ai/ui/react';
+import type { Theme } from '../theme';
+
+interface ComposerProps {
+  theme: Theme;
+  loading: boolean;
+  suggestions: string[];
+  triggers: PromptInputProps['triggers'];
+  onSubmit: (value: string) => void;
+  onSuggestionClick: (value: string) => void;
+}
+
+/**
+ * The bottom composer. Wraps `<kai-prompt-input>` and owns the input-DOM concerns:
+ * the element ref, a live text mirror, clear-on-submit, and seeding voice.
+ *
+ * The prompt input stays UNCONTROLLED so the `/`+`@` trigger menus keep a live
+ * caret. Assigning a plain STRING `value` flips the element into controlled mode,
+ * which re-applies the property and collapses the shadow-DOM selection — that
+ * disables the caret-anchored menu. So we NEVER push a string: clear-on-submit
+ * goes through the element's `clear()` method, and voice seeds a ComposerDoc (a
+ * non-string value is a one-time seed that leaves the input uncontrolled). We keep
+ * the live text mirrored into `textRef` (from `onValueChange`) so voice can append.
+ *
+ * SERVER-RENDERING NOTE. `useVoiceInput` reports `supported: false` on the server
+ * (there is no `window.SpeechRecognition` there) and true in Chromium, so that
+ * flag is read ONLY inside the click handler and never during render. Branching
+ * render output on it would put a different tree in the server HTML than the
+ * client builds on hydration, which is the textbook hydration mismatch.
+ */
+export function Composer({ theme, loading, suggestions, triggers, onSubmit, onSuggestionClick }: ComposerProps) {
+  // Ref to the underlying <kai-prompt-input> element for the imperative pushes
+  // (clear() on submit, ComposerDoc seed from voice); textRef mirrors the live text.
+  const promptRef = useRef<HTMLElement>(null);
+  const textRef = useRef('');
+
+  const { supported: voiceSupported, start: startVoice } = useVoiceInput((transcript) => {
+    const next = (textRef.current ? textRef.current + ' ' : '') + transcript;
+    textRef.current = next;
+    const el = promptRef.current as (HTMLElement & { value?: unknown }) | null;
+    if (el) el.value = [{ type: 'text', text: next }];
+  });
+
+  const handleVoice = useCallback(() => {
+    // Mic is Chromium-only; degrade gracefully everywhere else.
+    if (!voiceSupported) {
+      alert('Voice input needs a Chromium browser.');
+      return;
+    }
+    startVoice();
+  }, [voiceSupported, startVoice]);
+
+  const handleSubmit = useCallback(
+    (value: string) => {
+      // Clear our own uncontrolled input first — reset the mirror + call the
+      // element's clear() method (uncontrolled-safe; never a string assignment) —
+      // then hand the text up. The route owns append + streaming.
+      textRef.current = '';
+      (promptRef.current as (HTMLElement & { clear?: () => void }) | null)?.clear?.();
+      onSubmit(value);
+    },
+    [onSubmit],
+  );
+
+  return (
+    <div className="composer">
+      <PromptInput
+        ref={promptRef}
+        theme={theme}
+        placeholder="Message the demo…"
+        loading={loading}
+        suggestions={suggestions}
+        triggers={triggers}
+        voice
+        onVoice={handleVoice}
+        onValueChange={(e) => { textRef.current = e.detail.value; }}
+        onSubmit={(e) => handleSubmit(e.detail.value)}
+        onSuggestionClick={(e) => onSuggestionClick(e.detail.value)}
+      />
+      <p className="composer-hint">
+        Type <kbd>/</kbd> for skills · <kbd>@</kbd> for agents
+      </p>
+    </div>
+  );
+}