@kitn.ai/ui 0.28.0 → 0.29.0

package/src/agent-tooling/construct/codegen.ts

@@ -1,1635 +0,0 @@
-/**
- * construct → generated Solid mini-project. THE single generation path:
- * kai dev, kai compile and kai eject all call generateProject — the preview IS
- * the artifact (owner-picked option B; no interpreter to drift).
- *
- * Quality bar: the output is the EJECT artifact. Deterministic (no dates, no
- * randomness, object keys emitted in fixed order), idiomatic, readable.
- * Interior is pure Solid composing @kitn.ai/ui/solid; provider glue imports
- * @kitn.ai/ui/state + /wire (never a hand-rolled SSE reader); the one
- * defineWebComponent facade carries the tag, theme default and slots.
- * Styling: kit components + inline styles only — defineWebComponent injects
- * the compiled kit CSS into the shadow root, so the generated project needs no
- * Tailwind, no CSS build, nothing.
- */
-import { createRequire } from 'node:module';
-import { mkdirSync, readFileSync, rmSync, writeFileSync, existsSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import type { Construct } from './schema';
-
-export interface GeneratedFile {
-  path: string;
-  code: string;
-}
-
-export interface GenerateOptions {
-  /** Dependency spec for @kitn.ai/ui in the generated package.json.
-   *  Default: `^<this package's version>` (self-name resolution, mcp/server.ts pattern).
-   *  The gates pass a local tarball path here. */
-  uiSpec?: string;
-}
-
-function kitVersion(): string {
-  const require = createRequire(import.meta.url);
-  const pkg = require('@kitn.ai/ui/package.json') as { version: string };
-  return pkg.version;
-}
-
-const themeMode = (c: Construct): 'light' | 'dark' | 'auto' =>
-  c.theme?.mode === 'light' ? 'light' : c.theme?.mode === 'dark' ? 'dark' : 'auto';
-
-// ── accent contrast (codegen-time, static) ─────────────────────────────────
-// A light accent (e.g. yellow) paired with the kit's default near-white
-// foreground is unreadable, so the construct's accent needs a matching
-// --kai-color-primary-foreground computed at generation time (the accent is
-// static per construct — no reason to compute this at runtime for every
-// browser that can't do it natively). Parses only the numeric CSS color forms
-// (#rgb/#rrggbb/#rrggbbaa, rgb()/rgba(), hsl()/hsla()) — named colors, var(),
-// and anything else exotic are NOT guessed at; see resolveContrastForeground.
-
-/** sRGB channel (0-255) -> linear-light value, per the WCAG relative
- *  luminance formula. */
-function srgbChannelToLinear(c: number): number {
-  const cs = c / 255;
-  return cs <= 0.03928 ? cs / 12.92 : Math.pow((cs + 0.055) / 1.055, 2.4);
-}
-
-/** WCAG relative luminance, 0 (black) to 1 (white). */
-function relativeLuminance(r: number, g: number, b: number): number {
-  return 0.2126 * srgbChannelToLinear(r) + 0.7152 * srgbChannelToLinear(g) + 0.0722 * srgbChannelToLinear(b);
-}
-
-function hslToRgb(h: number, s: number, l: number): [number, number, number] {
-  const hue = ((h % 360) + 360) % 360;
-  const chroma = (1 - Math.abs(2 * l - 1)) * s;
-  const x = chroma * (1 - Math.abs(((hue / 60) % 2) - 1));
-  const m = l - chroma / 2;
-  const [r1, g1, b1] =
-    hue < 60 ? [chroma, x, 0]
-    : hue < 120 ? [x, chroma, 0]
-    : hue < 180 ? [0, chroma, x]
-    : hue < 240 ? [0, x, chroma]
-    : hue < 300 ? [x, 0, chroma]
-    : [chroma, 0, x];
-  return [Math.round((r1 + m) * 255), Math.round((g1 + m) * 255), Math.round((b1 + m) * 255)];
-}
-
-/** Parse the numeric CSS color forms only. Returns null for anything this
- *  can't resolve to concrete RGB without guessing (named colors, var(),
- *  color-mix(), oklch(), etc.) — the caller must decide loudly rather than
- *  silently picking a default for those. */
-function parseAccentRgb(accent: string): [number, number, number] | null {
-  const s = accent.trim();
-  const hex3 = /^#([0-9a-fA-F]{3})$/.exec(s);
-  if (hex3) {
-    const [r, g, b] = hex3[1].split('').map((ch) => parseInt(ch + ch, 16));
-    return [r, g, b];
-  }
-  const hex6 = /^#([0-9a-fA-F]{6})([0-9a-fA-F]{2})?$/.exec(s);
-  if (hex6) {
-    const hex = hex6[1];
-    return [parseInt(hex.slice(0, 2), 16), parseInt(hex.slice(2, 4), 16), parseInt(hex.slice(4, 6), 16)];
-  }
-  const rgbFn = /^rgba?\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})\s*(?:,\s*[\d.]+\s*)?\)$/.exec(s);
-  if (rgbFn) {
-    const [r, g, b] = [rgbFn[1], rgbFn[2], rgbFn[3]].map(Number);
-    return [r, g, b].every((v) => v >= 0 && v <= 255) ? [r, g, b] : null;
-  }
-  const hslFn = /^hsla?\(\s*([\d.]+)\s*,\s*([\d.]+)%\s*,\s*([\d.]+)%\s*(?:,\s*[\d.]+\s*)?\)$/.exec(s);
-  if (hslFn) {
-    return hslToRgb(Number(hslFn[1]), Number(hslFn[2]) / 100, Number(hslFn[3]) / 100);
-  }
-  return null;
-}
-
-/**
- * The paired --kai-color-primary-foreground for a parseable accent, or null
- * when the accent can't be resolved to concrete RGB without guessing.
- *
- * Threshold: white when it sits closer to white than to black on the WCAG
- * relative-luminance scale (L <= 0.5), else black — equivalently "contrast
- * against white (1 - L) >= contrast against black (L)". This is a deliberately
- * simpler comparison than the full WCAG *contrast-ratio* formula (which adds
- * a 0.05 offset to both sides): the ratio formula's asymmetric offset flips
- * the choice for at least one real accent this codegen ships in its own demo
- * fixture (#e91e63, L≈0.1915 — contrast-ratio picks black at 4.83:1 over
- * white's 4.35:1, but a straight luminance-distance comparison, and every
- * reference brand palette pairing that color with white text, picks white).
- * Verified by direct computation, not assumed — see the "accent contrast"
- * describe block in codegen.test.ts for the worked numbers.
- */
-export function resolveContrastForeground(accent: string): '#000000' | '#ffffff' | null {
-  const rgb = parseAccentRgb(accent);
-  if (!rgb) return null;
-  const luminance = relativeLuminance(...rgb);
-  return luminance <= 0.5 ? '#ffffff' : '#000000';
-}
-
-/**
- * Shallow-merge a model's card tool-call args onto a DECLARED form schema's
- * field defaults — "model proposes, user confirms" (CD-1, owner ruling
- * 2026-08-26). Only top-level keys the args and the schema BOTH name are
- * touched; the schema's own field shape (title/type/widget/validation) is
- * never altered, and a key the model sent that isn't a declared field is
- * ignored (the construct's vocabulary wins, not the model's). One level deep
- * only — a nested object field's own defaults are not recursed into; no
- * evidence of need yet (vocabulary-on-evidence).
- *
- * This is the real, module-level version used by this file's own tests
- * (imported directly — see codegen-cards.render.test.tsx). `emitCardsImport`
- * below emits an equivalent function VERBATIM as a string into the
- * construct's own generated App.tsx: that copy is construct-glue code the
- * eject artifact must own standalone (same as every other piece of logic
- * emitCardsImport/emitApplyCardTools already emit inline), not an import
- * from the kit — so the two are kept in sync by hand, not by import. Keep
- * them behaviorally identical if you change one.
- */
-export function mergeToolArgsIntoFormDefaults(
-  schema: Record<string, unknown>,
-  args: Record<string, unknown>,
-): Record<string, unknown> {
-  const declared = schema.properties;
-  if (!declared || typeof declared !== 'object') return schema;
-  const patched: Record<string, unknown> = {};
-  for (const [key, value] of Object.entries(args)) {
-    if (!(key in (declared as Record<string, unknown>))) continue;
-    patched[key] = {
-      ...((declared as Record<string, unknown>)[key] as Record<string, unknown>),
-      default: value,
-    };
-  }
-  return { ...schema, properties: { ...(declared as Record<string, unknown>), ...patched } };
-}
-
-/**
- * Neutralize characters that could break out of a comment before embedding
- * untrusted text in one. Two contexts reuse this: the CLI/dev notice line
- * (plain terminal text — newlines just garble it) and the CSS NOTICE comment
- * emitted into element.tsx, where the two-character close-comment sequence in
- * the accent would otherwise end the comment early and let the rest of the
- * accent's text land as live CSS inside the generated stylesheet.
- */
-function commentSafe(text: string): string {
-  return text.replace(/[\r\n]/g, ' ').replace(/\*\//g, '* /');
-}
-
-const CONTRAST_COLOR_SUPPORTS = '@supports (color: contrast-color(red))';
-
-/**
- * One line for whichever host decides loudly about generation-time notices
- * (the CLI today; `dev`'s watch loop reuses it on every regen). Null when
- * there's nothing to say — no accent, or the accent parsed fine.
- */
-export function accentContrastNotice(construct: Construct): string | null {
-  const accent = construct.theme?.accent;
-  if (!accent || resolveContrastForeground(accent) !== null) return null;
-  return `accent '${commentSafe(accent)}' not parseable for contrast; foreground left at theme default in browsers without CSS contrast-color() support`;
-}
-
-export function generateProject(construct: Construct, opts: GenerateOptions = {}): GeneratedFile[] {
-  const uiSpec = opts.uiSpec ?? `^${kitVersion()}`;
-  const files: GeneratedFile[] = [
-    { path: 'package.json', code: emitPackageJson(construct, uiSpec) },
-    { path: 'tsconfig.json', code: emitTsconfig() },
-    { path: 'vite.config.ts', code: emitViteDev() },
-    { path: 'vite.config.lib.ts', code: emitViteLib(construct) },
-    { path: 'index.html', code: emitIndexHtml(construct) },
-    { path: 'src/element.tsx', code: emitElement(construct) },
-    { path: 'src/App.tsx', code: emitApp(construct) },
-  ];
-  if (construct.cards) files.push({ path: 'src/cards.ts', code: emitCardsRegistry(construct.cards) });
-  return files;
-}
-
-// ── cards ────────────────────────────────────────────────────────────────
-// Named generative-UI card definitions the model can emit as tool calls.
-// Registration only — the projection into provider tool definitions is the
-// kit's OWN `cardTools`/`toOpenAITools`/`toAnthropicTools` (@kitn.ai/ui/schemas,
-// src/schemas/tool-defs.ts), never a second one authored here.
-
-/** `src/cards.ts` — the construct's card registry, verbatim from the
- *  construct. Each schema is `JSON.stringify(schema, null, 2)`'d and reindented
- *  under its key — deterministic because the construct's own key order (and
- *  each schema's own JSON key order) is preserved; nothing here re-sorts. */
-function emitCardsRegistry(cards: NonNullable<Construct['cards']>): string {
-  const entries = cards
-    .map((card) => `  ${card.name}: ${JSON.stringify(card.schema, null, 2).split('\n').join('\n  ')},`)
-    .join('\n');
-  return `// src/cards.ts — the construct's card registry, verbatim from the construct.
-// Tool definitions for YOUR backend derive from this same object via
-// @kitn.ai/ui/schemas (cardTools / toOpenAITools / toAnthropicTools) — one
-// projection, shared with the kit.
-export const cards = {
-${entries}
-} as const;
-`;
-}
-
-/** `, BUILTIN_CARD_COMPONENTS` spliced onto the `@kitn.ai/ui/solid` named-import
- *  list at the top of App.tsx (below) when cards are declared — the built-in
- *  `.form` renderer every declared card routes to. Empty otherwise. */
-function emitCardComponentImport(c: Construct): string {
-  return c.cards ? ', BUILTIN_CARD_COMPONENTS' : '';
-}
-
-/** The `import`s cards need in App.tsx: the registry itself, `BUILTIN_CARD_COMPONENTS`
- *  (@kitn.ai/ui/solid re-exports it from the root entry) so every declared card can
- *  route to the kit's own schema-driven form renderer, `cardFromToolCall` (turns a
- *  settled tool-call ToolPart into a renderable `card` MessagePart — see
- *  emitApplyCardTools) and, for an endpoint construct, the wire-matching tool
- *  projection for the fetch body. Empty when the construct declares no cards at all
- *  (format rule: undeclared -> no affordance, no import).
- *
- *  RULING (supervisor, this task): v1 renders EVERY declared card as the kit's own
- *  `form` card (`BUILTIN_CARD_COMPONENTS.form`, components/form.tsx) — it walks a
- *  JSON-Schema-shaped `data` into real input fields and honors `x-kai-format`/
- *  `x-kai-mask`/`x-kai-mask-guide` hints itself (field-mask.ts); no engine work is
- *  needed for masks specifically. This is deliberately NOT the same precedent as
- *  examples/apps/ops-console/shared/cards.ts's `createCardRegistry` (which maps
- *  several DISTINCT built-in kinds — confirm/form/choice/tasks — onto an app's own
- *  tool names): a construct's `cards` field carries only a `schema`, no `kind`, so
- *  there is no vocabulary yet to route on. Adding a `kind`/`type` field to pick
- *  confirm/choice/tasks is explicitly deferred to vocabulary-on-evidence, not done
- *  here — every construct card is a form until a later task adds that field. */
-function emitCardsImport(c: Construct): string {
-  if (!c.cards) return '';
-  const toolsImport =
-    c.provider.mode === 'endpoint' ? (c.provider.wire === 'openai' ? ', toOpenAITools' : ', toAnthropicTools') : '';
-  return `import { cards } from './cards';
-// Generative-UI cards, v1: every declared card renders as the kit's own
-// schema-driven FORM (BUILTIN_CARD_COMPONENTS.form, components/form.tsx) — it
-// walks the card's JSON Schema into real input fields, honoring
-// x-kai-format/x-kai-mask/x-kai-mask-guide hints itself. ChatThread's own
-// MessageBody already matches \`part.type === 'card'\` in its part rendering and
-// draws it with the kit's own \`CardRenderer\` (components/card-renderer.tsx),
-// which picks the component from \`cardTypes\` (below) by envelope.type — so
-// there is nothing to hand-compose beyond that one map. Turning a model's tool
-// call into that renderable part is \`cardFromToolCall\` (the inverse of
-// \`cardTools\`), applied once per settled turn below; its data is then replaced
-// with the DECLARED card schema (not the model's call arguments) — the fields
-// on screen are the construct's own vocabulary, not whatever shape a model
-// happened to send.
-//
-// UPDATE (CD-1, owner ruling 2026-08-26, Task 19g): the field SHAPE (title/
-// type/widget/validation) still comes from the construct's own declared
-// schema, never the model's — that part is unchanged. But discarding the
-// model's call arguments wholesale also threw away any VALUE it wanted to
-// pre-fill, breaking "model proposes, user confirms" (kai_refund_approval
-// {amount:50} rendered an empty form). So the model's args are now
-// shallow-merged onto the declared schema's field \`default\`s below
-// (mergeToolArgsIntoFormDefaults) before the card is added — see
-// emitApplyCardTools.
-import { cardFromToolCall${toolsImport} } from '@kitn.ai/ui/schemas';
-
-// Every declared card name routes to the SAME form renderer — cardFromToolCall
-// makes envelope.type equal the card's own name (kai_refund_approval ->
-// 'refund_approval'), and CardRenderer resolves a type's component from this
-// map.
-//
-// Deliberately NOT also wiring ChatThread's \`cardSchemas\` prop to this
-// registry below. That prop validates envelope.data AGAINST the named schema,
-// and this card's data IS \`cards[name]\` itself (see emitApplyCardTools) — the
-// construct's declared field schema, not values shaped like it. Wiring it as
-// its own validator asks "does this FormDefinition itself have an \`amount\`
-// key" and a well-formed FormDefinition never does, so every card would
-// render the HARD validation-failure fallback instead of the form (caught
-// live: eject + kai dev showed exactly that "(root).amount: required"
-// failure before this comment existed). The construct's own schema.ts
-// already checks \`cards\` structurally at validate time; there is nothing
-// left for a second, self-referential check here to catch.
-const cardTypes = Object.fromEntries(Object.keys(cards).map((name) => [name, BUILTIN_CARD_COMPONENTS.form] as const));
-
-// CD-1 (owner ruling 2026-08-26, Task 19g): shallow-merge a model's card
-// tool-call args onto a DECLARED form schema's field defaults — "model
-// proposes, user confirms". Only top-level keys the args AND the schema both
-// name are touched; the schema's own field shape (title/type/widget/
-// validation) is never altered, and a key the model sent that isn't a
-// declared field is ignored (the construct's vocabulary wins, not the
-// model's). One level deep only — a nested object field's own defaults are
-// not recursed into; no evidence of need yet (vocabulary-on-evidence).
-function mergeToolArgsIntoFormDefaults(
-  schema: Record<string, unknown> & { properties?: Record<string, unknown> },
-  args: Record<string, unknown>,
-): Record<string, unknown> {
-  const declared = schema.properties;
-  if (!declared || typeof declared !== 'object') return schema;
-  const patched: Record<string, unknown> = {};
-  for (const [key, value] of Object.entries(args)) {
-    if (!(key in declared)) continue;
-    patched[key] = { ...(declared[key] as Record<string, unknown>), default: value };
-  }
-  return { ...schema, properties: { ...schema.properties, ...patched } };
-}`;
-}
-
-/** `cardTypes={cardTypes}` on ChatThread — which component draws each
- *  declared card name (see emitCardsImport for why `cardSchemas` is
- *  deliberately NOT also registered). The host to emit card events off is
- *  already supplied by the ChatThread/kai-chat path (F-26); nothing else to
- *  thread through here. */
-function emitCardTypesProp(c: Construct): string {
-  return c.cards ? ' cardTypes={cardTypes}' : '';
-}
-
-/** Settle a turn's tool calls into cards, called once after the read
- *  resolves and before `stream.done()`/`stream.abort()`. `AssistantStream`
- *  has no getter of its own, so the just-written parts are read back off
- *  `chat.messages()` by the stream's own id — the same pattern the kit's own
- *  `cardFromToolCall` doc comment (schemas/from-tool-call.ts) shows for a
- *  tool loop. A `kai_`-prefixed call becomes a card; anything else is the
- *  construct's own tool and is left as a plain `tool` part.
- *
- *  `cardFromToolCall` supplies the envelope's `type`/`id` and `data` (the
- *  model's raw tool-call `input`, verbatim). `data` is then set to the card's
- *  own DECLARED schema off the registry (`cards[card.type]`) — the form
- *  renders the construct author's fields, matching the supervisor ruling
- *  that every declared card is a schema-driven form in v1 — with the
- *  model's args (`card.data`, read before this replaces it) shallow-merged
- *  onto that schema's field `default`s (CD-1, owner ruling 2026-08-26,
- *  Task 19g: `mergeToolArgsIntoFormDefaults`, emitted above by
- *  emitCardsImport) so "model proposes, user confirms" pre-fills the form
- *  instead of discarding the model's values outright. The `card.type in
- *  cards` guard only fires for a `kai_` call this construct never declared
- *  (an off-vocabulary call slipping through); it is silently dropped rather
- *  than rendered, matching cardFromToolCall's own "not every kai_ call is
- *  renderable" boundary (see its module header). */
-function emitApplyCardTools(c: Construct): string {
-  if (!c.cards) return '';
-  return `
-    for (const part of chat.messages().find((m) => m.id === stream.id)?.parts ?? []) {
-      if (part.type !== 'tool' || part.tool.state !== 'input-available') continue;
-      const card = cardFromToolCall(part.tool.type, part.tool.input, { id: part.tool.toolCallId ?? crypto.randomUUID() });
-      if (card && card.type in cards) {
-        const declared = cards[card.type as keyof typeof cards];
-        const args = card.data as Record<string, unknown> | undefined;
-        const merged = args && typeof args === 'object'
-          ? mergeToolArgsIntoFormDefaults(declared, args)
-          : declared;
-        stream.addCard({ ...card, data: merged });
-      }
-    }`;
-}
-
-/** The endpoint fetch body's `tools` field — the projected tool defs for
- *  every declared card, matching the construct's own wire. No cards, no
- *  field: the format rule (undeclared capability's affordance is OFF) holds
- *  for tools the same way it holds for suggestions/attach/reasoning above. */
-function emitToolsField(c: Construct): string {
-  if (!c.cards || c.provider.mode !== 'endpoint') return '';
-  const toolsFn = c.provider.wire === 'openai' ? 'toOpenAITools' : 'toAnthropicTools';
-  return `, tools: ${toolsFn}(cards)`;
-}
-
-function emitPackageJson(c: Construct, uiSpec: string): string {
-  return `${JSON.stringify(
-    {
-      name: c.name,
-      private: true,
-      type: 'module',
-      scripts: {
-        dev: 'vite',
-        build: 'vite build --config vite.config.lib.ts',
-        typecheck: 'tsc --noEmit',
-      },
-      dependencies: {
-        '@kitn.ai/ui': uiSpec,
-        'solid-js': '^1.9.0',
-      },
-      devDependencies: {
-        typescript: '^5.6.0',
-        vite: '^6.0.0',
-        'vite-plugin-solid': '^2.11.0',
-      },
-    },
-    null,
-    2,
-  )}\n`;
-}
-
-function emitTsconfig(): string {
-  return `${JSON.stringify(
-    {
-      compilerOptions: {
-        target: 'ES2022',
-        module: 'ESNext',
-        moduleResolution: 'bundler',
-        jsx: 'preserve',
-        jsxImportSource: 'solid-js',
-        strict: true,
-        noUnusedLocals: true,
-        skipLibCheck: true,
-        types: ['vite/client'],
-      },
-      include: ['src'],
-    },
-    null,
-    2,
-  )}\n`;
-}
-
-function emitViteDev(): string {
-  return `import { defineConfig } from 'vite';
-import solid from 'vite-plugin-solid';
-
-export default defineConfig({ plugins: [solid()] });
-`;
-}
-
-function emitViteLib(c: Construct): string {
-  return `import { defineConfig } from 'vite';
-import solid from 'vite-plugin-solid';
-
-// kai compile: ONE self-registering .js. Everything is inlined (no externals):
-// the consumer installs nothing but this output.
-export default defineConfig({
-  plugins: [solid()],
-  build: {
-    lib: { entry: 'src/element.tsx', formats: ['es'], fileName: () => '${c.name}.js' },
-  },
-});
-`;
-}
-
-function emitIndexHtml(c: Construct): string {
-  // A demo host page, not the emitted widget: purely so a first-time preview
-  // isn't a mystery blank tab with one small launcher in the corner. Outside
-  // the custom element entirely (a sibling in <body>), inline-styled, and
-  // worded so nobody mistakes it for the construct's own output. Keyed off
-  // `layout`: the "bottom-right corner" wording is only true for `widget` (a
-  // floating launcher) — `fullscreen`/`aside`/`split` (Task 12) fill or dock
-  // the page themselves, so they get no hint at all rather than a wrong one.
-  // Decide loudly by omission, not by a stale claim.
-  const hint =
-    c.layout === 'widget'
-      ? `\n    <p style="position: fixed; top: 50%; left: 50%; transform: translate(-50%, -50%); margin: 0; color: #94a3b8; font: 14px system-ui, sans-serif; text-align: center; max-width: 28rem; padding: 0 1rem;">This blank page stands in for your site. The chat widget is in the bottom-right corner.</p>`
-      : '';
-  // Task 13: when slots are declared, project real demo content into each one
-  // in the copy's own <${c.name}> tag — so the preview shows the escape hatch
-  // WORKING (light-DOM children of a custom element project into its shadow
-  // <slot> natively) rather than a mystery about how to use it. Slot names are
-  // already schema-validated to `^[a-z][a-z0-9-]*$` (schema.ts) — no
-  // quote/backslash payload possible, so no HTML-escaping is needed here,
-  // unlike a free-text construct-authored field.
-  const slotDemo = (c.slots ?? [])
-    .map(
-      (name) =>
-        `\n      <div slot="${name}" style="padding: 0.5rem 1rem; font: 13px system-ui, sans-serif; color: #64748b;">Projected into slot "${name}" — replace with your own markup.</div>`,
-    )
-    .join('');
-  const body = slotDemo ? `\n    <${c.name}>${slotDemo}\n    </${c.name}>` : `\n    <${c.name}></${c.name}>`;
-  return `<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>${c.name} — construct preview</title>
-  </head>
-  <body style="margin: 0;">${hint}${body}
-    <script type="module" src="/src/element.tsx"></script>
-  </body>
-</html>
-`;
-}
-
-function emitElement(c: Construct): string {
-  const accent = c.theme?.accent;
-  const unreadColor = c.theme?.unreadColor;
-  if (!accent && !unreadColor) {
-    // `empty` (Task 14) composes straight into ChatThread's own `emptyContent`
-    // prop now (see emitEmptyContentProp's doc) — a plain JSX value passed down
-    // through App, not a Portal onto the host — so the facade needs no `ctx` and
-    // every construct, `empty` declared or not, keeps this line byte-for-byte
-    // unchanged.
-    const facade = '() => <App />';
-    return `import { defineWebComponent } from '@kitn.ai/ui/define';
-import { App } from './App';
-
-// The one facade. Interior stays pure Solid (no nested element registrations);
-// the kit CSS is injected into the shadow root by defineWebComponent itself.
-defineWebComponent('${c.name}', { theme: '${themeMode(c)}' as 'light' | 'dark' | 'auto' }, ${facade});
-`;
-  }
-
-  // `unreadColor` (owner ruling, 2026-08-26 — unread-indicator round) gets the
-  // exact same setProperty treatment as `accent` below — construct-authored/
-  // untrusted text, JSON.stringify'd at its one interpolation site, carried via
-  // `ctx.element.style.setProperty` rather than interpolated into CSS text (so
-  // it can never break out into a new declaration/rule) — but with NO paired
-  // -foreground computation: unlike the primary accent, --color-unread never
-  // sits behind text, only inside small filled dots (list-row/header/Dock
-  // badge), so there is nothing to contrast-pair against. Emitted
-  // unconditionally alongside accent's setProperty call when present, even if
-  // `accent` itself is absent — this branch is reached whenever EITHER is set.
-  const unreadColorSetProperty = unreadColor
-    ? `\n  ctx.element.style.setProperty('--kai-color-unread', ${JSON.stringify(unreadColor)});`
-    : '';
-
-  if (!accent) {
-    // unreadColor-only construct: no accent, so none of the contrast-pairing
-    // machinery below applies — just the one setProperty call and `ctx`.
-    const facade = `(_props, ctx) => {${unreadColorSetProperty}
-  return <App />;
-}`;
-    return `import { defineWebComponent } from '@kitn.ai/ui/define';
-import { App } from './App';
-
-// The one facade. Interior stays pure Solid (no nested element registrations);
-// the kit CSS is injected into the shadow root by defineWebComponent itself.
-defineWebComponent('${c.name}', { theme: '${themeMode(c)}' as 'light' | 'dark' | 'auto' }, ${facade});
-`;
-  }
-
-  // The accent has to land on the HOST element, not anywhere inside this
-  // shadow root. The kit's --color-primary token is resolved ONCE, by a rule
-  // scoped to `:root, :host` (`@layer theme { :root, :host { --color-primary:
-  // var(--kai-color-primary, <fallback>) } }`) — so --kai-color-primary has to
-  // be set AT the host for that rule to see it; a descendant inside the
-  // shadow tree can set --kai-color-primary on itself all day and it will
-  // never flow back up into a value the :host rule already resolved. This is
-  // why the theme accent rendered nowhere in the T5 demo despite being
-  // "wired": an earlier version set it on a div INSIDE App's own render.
-  //
-  // `ctx.element` (the facade's second argument) IS the host, so this sets it
-  // from the one place inside the shadow root that has a handle to it.
-  // `style.setProperty` is also the safe way to carry the accent, distinct
-  // from string-interpolating it into CSS text: a custom property's value is
-  // an opaque token substituted via var(), so it can never break out into a
-  // new declaration or rule the way raw CSS/JS text interpolation could.
-  //
-  // The PAIRED --kai-color-primary-foreground is a separate concern: a light
-  // accent (yellow) next to the kit's default near-white foreground is
-  // unreadable. That pairing DOES need to live in a CSS block rather than a
-  // second setProperty call, because it has two layers that must be able to
-  // override each other in order: (1) a black/white value computed HERE, at
-  // generation time (the accent is static per construct), as the floor for
-  // browsers without CSS contrast-color() (Baseline Newly Available April
-  // 2026 — Chrome/Edge 147, Firefox 146, Safari 26; Widely Available is not
-  // until ~2028, and this widget embeds in arbitrary sites), and (2) inside
-  // `@supports (color: contrast-color(red))`, the NATIVE answer
-  // (contrast-color(var(--kai-color-primary))), which wins where supported —
-  // including for an accent this codegen couldn't parse. An inline
-  // `style.setProperty` always beats a stylesheet rule (short of
-  // `!important`), so achieving "the native answer wins where present" needs
-  // both layers to be plain `:host {}` declarations in one stylesheet, base
-  // rule first, @supports override after — ordinary cascade order, no
-  // `!important` required.
-  const foreground = resolveContrastForeground(accent);
-  const foregroundCss =
-    foreground !== null
-      ? `:host { --kai-color-primary-foreground: ${foreground}; }\n`
-      : // Not guessed at: an unparseable accent (var(), a named color, a
-        // color-mix()/oklch() call, …) leaves NO base declaration, so the
-        // kit's own theme default stands — except in a browser new enough to
-        // resolve contrast-color() itself, where the @supports block below
-        // still gets it right natively.
-        `/* NOTICE: accent '${commentSafe(accent)}' not parseable for contrast at generation time; the paired foreground falls back to the theme default in browsers without CSS contrast-color() support. */\n`;
-  const styleText =
-    foregroundCss + `${CONTRAST_COLOR_SUPPORTS} {\n  :host { --kai-color-primary-foreground: contrast-color(var(--kai-color-primary)); }\n}`;
-
-  const facade = `(_props, ctx) => {
-  ctx.element.style.setProperty('--kai-color-primary', ${JSON.stringify(accent)});${unreadColorSetProperty}
-  return (
-    <>
-      <style>{${JSON.stringify(styleText)}}</style>
-      <App />
-    </>
-  );
-}`;
-  return `import { defineWebComponent } from '@kitn.ai/ui/define';
-import { App } from './App';
-
-// The one facade. Interior stays pure Solid (no nested element registrations);
-// the kit CSS is injected into the shadow root by defineWebComponent itself.
-defineWebComponent('${c.name}', { theme: '${themeMode(c)}' as 'light' | 'dark' | 'auto' }, ${facade});
-`;
-}
-
-// ── App interior ─────────────────────────────────────────────────────────────
-// The chat spine is IMPLIED: thread + input + streaming are always emitted and
-// wired; the construct declares deviations and additions only. Seams below are
-// where later tasks splice capability code; each is a pure string join, so the
-// determinism test keeps holding.
-
-function emitApp(c: Construct): string {
-  if (c.layout === 'custom') return emitCustomApp(c);
-  return `${emitSolidJsImport(c)}${emitConversationsSignalsImport(c)}import { ChatThread, createKaiChat${emitLayoutImport(c)}${emitCardComponentImport(c)}${emitEmptyComponentImport(c)}${emitHeaderCloseImport(c)} } from '@kitn.ai/ui/solid';
-import type { AttachmentData${emitHistoryTypeImport(c)}${emitConversationsResetTypeImport(c)} } from '@kitn.ai/ui/solid';
-${emitProviderImports(c)}
-${emitCardsImport(c)}
-${emitConversationsImport(c)}
-
-${emitProviderSetup(c)}
-${emitHistorySetup(c)}
-
-// ChatThread is the kit's own MOST-INTEGRATED chat surface — the same
-// composition <kai-chat>'s facade renders (src/elements/chat.tsx). It owns
-// the message list, the composer (padding, focus ring, the send button) and
-// their layout AS ONE UNIT, so nothing here re-derives spacing, alignment or
-// focus styling by hand: every prior version of this file that hand-composed
-// Thread + PromptInput + Button was restating layout the kit already owns,
-// and every visual defect the owner hit (flush composer, a clipped focus
-// ring) traced back to that restatement. Composing ChatThread directly
-// leaves NOTHING here to restate it with.
-//
-// Capability gating (format rule: an undeclared capability's affordance must
-// be OFF). The construct schema carries ONE capability field so far
-// (capabilities.starters, Task 8) — every other affordance below is gated to
-// "off" unconditionally, not per-construct, until there's a field to gate ON.
-//   - webSearch / voice: real ChatThreadProps booleans, default OFF when
-//     omitted — set to \`false\` explicitly rather than left implicit, so the
-//     gating decision is visible in the emitted source, not just inferred
-//     from an absent prop.
-//   - suggestions: ChatThread ALREADY owns starter prompts end to end — its
-//     own \`suggestions\` prop renders the chips, hides them once
-//     \`messages\` is non-empty, and (default \`suggestionMode="submit"\`)
-//     calls \`onSubmit\` with the clicked text exactly like a typed submit.
-//     So capabilities.starters threads straight into that prop; there is
-//     nothing to hand-compose. Omitted (undefined) when no starters are
-//     declared, same off-by-default effect as the booleans above.
-//   - models: omitted (undefined) — no model switcher; no capabilities field yet.
-//   - attachments (the paperclip): gated via ChatThread's \`attach\`/\`accept\`
-//     props (kit gap closed — ChatThread forwards both to DefaultPromptInput,
-//     mirroring webSearch/voice). ChatThread ALREADY owns the whole
-//     round-trip end to end — the paperclip button, staged previews, staging
-//     each file as a data URI (never a blob object URL; see
-//     AttachmentData.url's doc in components/attachment-types.ts), and
-//     handing the staged list back via onSubmit's \`attachments\` — and its
-//     Message component ALREADY groups consecutive file parts into one
-//     attachment row (message.tsx). So there is nothing to hand-compose
-//     here, same lesson as suggestions above: hand-rolling a second picker or
-//     a second file-part renderer would restate what ChatThread/Message
-//     already own. capabilities.attachments threads straight into
-//     attach/accept; the only App.tsx-owned piece is folding the picked
-//     attachments into the outgoing message's parts at the submit site
-//     (see emitProviderSetup) since createKaiChat's own append/streamAssistant
-//     ops don't do that folding themselves.
-//   - reasoning: gated via ChatThread's own \`reasoning\` prop (kit gap closed
-//     — ChatThread forwards it to every MessageBody as \`reasoningMode\`,
-//     mirroring attach/accept). \`'full'\` is both the schema default and
-//     ChatThread's own default, so it and an absent field emit no prop at
-//     all — the SAME off-by-default convention as every other capability
-//     here, just anchored on the medium's existing default instead of an
-//     "off" value, since a reasoning disclosure is normal chat behavior, not
-//     an opt-in affordance like the paperclip or a starter chip.
-//   - empty (the welcome-screen greeting, Task 14): gated via ChatThread's
-//     own \`emptyContent\` prop, plain JSX rendered in the SAME shadow tree
-//     this file's App already composes ChatThread inside of (see
-//     emitEmptyContentProp's own doc for why that boundary needs no Portal
-//     at all). \`capabilities.starters\`' chips and the composer still render
-//     underneath it: ChatThread's own doc comment on \`emptyContent\` is
-//     explicit that it replaces only the empty MESSAGE LIST.
-//   - the widget close control (owner feedback on the live demo): a declared
-//     \`header.title\` on a \`widget\` layout gets its close button threaded
-//     into ChatThread's own header row via \`headerEndContent\`, wired back to
-//     Dock's \`controllerRef\` seam through a local closure — see
-//     emitDockCloseVar/emitHeaderEndContentProp's docs. No header means no
-//     row for it to sit in, so that case is untouched and Dock's own built-in
-//     mobile X keeps covering it.
-//   - conversations (Task 5): gated via ChatThread's own \`conversations\`/
-//     \`store\` props (kit-owned end to end — the prior-conversations list,
-//     list/load/save, autosave on every \`chat.messages()\` change). Requires
-//     capabilities.history persistence \`local\` or \`endpoint\` (schema
-//     superRefine, C-4) and SUBSUMES this file's hand-rolled history effect
-//     when on — see emitHistorySetup's own doc for the persistence-ownership
-//     decision: the store prop is the ONLY persistence mechanism emitted,
-//     never both. ChatThread never mutates \`messages\` itself, so
-//     \`onConversationLoad\` is ALSO wired here (\`chat.setMessages(() =>
-//     messages)\`) — without it, select/new/mount-restore all update
-//     ChatThread's own internal view/list state while the rendered thread
-//     never changes (see emitConversationsProps's own doc for the Task 6
-//     live-browser bug this fixes).
-//   - conversations + widget (owner follow-up): closing the widget while its
-//     list view is open must not leave it there for the next open — see
-//     widgetHasConversationsChrome/emitDockOnOpenChangeProp's docs. Wired only
-//     for \`widget\`, the one layout with something that closes/reopens at all.
-export function App() {
-${emitDockCloseVar(c, '  ')}${emitChatControllerVar(c, '  ')}${emitConversationsSignalsVar(c, '  ')}  return (
-${emitLayoutOpen(c)}${emitSlots(c.slots, '      ')}      <ChatThread messages={chat.messages()} loading={chat.loading()} placeholder="Ask anything" onSubmit={submit} webSearch={false} voice={false}${emitHeaderProp(c)}${emitHeaderEndContentProp(c)}${emitAttachProps(c)}${emitStartersProp(c)}${emitReasoningProp(c)}${emitReasoningOpenProp(c)}${emitEmptyContentProp(c)}${emitCardTypesProp(c)}${emitHomeProp(c)}${emitConversationsProps(c)}${emitChatControllerRefProp(c)}${emitChatThreadUnreadProps(c)} />
-${emitLayoutClose(c)}  );
-}
-`;
-}
-
-/**
- * `layout: 'custom'` — the escape hatch's own layout: minimal/no chrome, just
- * the bare chat spine plus the declared `slots` positioned by the consumer.
- * Composed from `Thread` (the message-list primitive, no composer/header/
- * suggestions of its own — components/thread.tsx) + the `PromptInput`
- * compound primitive, NOT `ChatThread`: `ChatThread` bundles its composer
- * INSIDE itself (`DefaultPromptInput`, internal-only), which leaves no seam to
- * splice a slot between the thread and the input the way this layout's
- * placement rule needs. This is the one layout where hand-composing the spine
- * is correct rather than a restatement — every other layout in this file
- * wraps `ChatThread` precisely to avoid this hand-composition (see emitApp's
- * doc comment above).
- *
- * Slot placement is a fixed, deterministic rule, spelled out in the emitted
- * comment: the FIRST declared slot sits above the thread, every other
- * declared slot sits below the composer, in declaration order. There is no
- * vocabulary for a different arrangement (a `position` per slot, an
- * interleaved grain) — reordering means ejecting and rearranging the JSX by
- * hand, which this format's own rule already commits to (no code-in-JSON).
- *
- * Capability gating: only cards are wired here (`Thread` accepts `cardTypes`
- * natively, same as `ChatThread`). starters/attachments/reasoning/
- * reasoningOpen/header.title/empty/conversations are NOT wired for `custom`
- * in v1 — `Thread`/`PromptInput` don't carry the kit's own plumbing for
- * those (they live inside `ChatThread`'s composer, or — for conversations —
- * ChatThread itself owns the list/load/save wiring), and hand-rolling a
- * second copy here is exactly the restatement this file avoids everywhere
- * else. Decided loudly in the emitted comment below, not silently: this is
- * the eject artifact, so a construct author who needs one of them on
- * `custom` adds it directly to the plain Solid file they now own.
- * capabilities.history persistence itself IS still honored on `custom` (the
- * hand-rolled effect below), independent of whether conversations is also
- * set — see emitHistorySetup's own doc for why `custom` keeps it.
- */
-function emitCustomApp(c: Construct): string {
-  const slots = c.slots ?? [];
-  const [headerSlot, ...restSlots] = slots;
-  const history = c.capabilities?.history;
-  const solidJsNames = ['createSignal', ...(history && history.persistence !== 'none' ? ['createEffect'] : [])];
-  return `import { ${solidJsNames.join(', ')} } from 'solid-js';
-import { Thread, PromptInput, PromptInputTextarea, PromptInputActions, Button, createKaiChat${emitCardComponentImport(c)} } from '@kitn.ai/ui/solid';
-import type { AttachmentData${emitHistoryTypeImport(c)} } from '@kitn.ai/ui/solid';
-${emitProviderImports(c)}
-${emitCardsImport(c)}
-
-${emitProviderSetup(c)}
-${emitHistorySetup(c)}
-
-// layout: custom — minimal chrome, no ChatThread/Dock/PaneGroup. The bare
-// spine (Thread + PromptInput) plus the declared slots, positioned by hand so
-// YOU own the surrounding DOM. Capabilities beyond the spine (starters,
-// attachments, reasoning display-mode, reasoningOpen, header.title, empty,
-// conversations) are NOT wired here in v1 — this file is the eject artifact; add them the
-// way ChatThread composes them (components/chat-thread.tsx in the kit's own
-// source) if this construct needs them on a custom layout.
-export function App() {
-  const [value, setValue] = createSignal('');
-
-  const handleSubmit = () => {
-    const text = value();
-    if (!text.trim() || chat.loading()) return;
-    setValue('');
-    void submit({ value: text, attachments: [] });
-  };
-
-  return (
-    <div style={{ height: '100dvh', display: 'flex', 'flex-direction': 'column' }}>
-${emitSlots(headerSlot ? [headerSlot] : undefined, '      ')}      <Thread messages={chat.messages()} loading={chat.loading()} class="min-h-0 flex-1"${emitCardTypesProp(c)} />
-      {/* Slot placement rule: first declared slot above the thread, every other
-          declared slot below the composer, in declaration order. Reorder by
-          ejecting — this is the whole grain dimmer. */}
-      <PromptInput value={value()} onValueChange={setValue} isLoading={chat.loading()} onSubmit={handleSubmit}>
-        <PromptInputTextarea placeholder="Ask anything" />
-        <PromptInputActions>
-          <Button onClick={handleSubmit}>Send</Button>
-        </PromptInputActions>
-      </PromptInput>
-${emitSlots(restSlots, '      ')}    </div>
-  );
-}
-`;
-}
-
-/** header.title -> ChatThread's own \`chatTitle\` prop. Construct-authored/
- *  untrusted text like starters/theme.accent/provider.url, so JSON.stringify'd
- *  into a real JS string-literal expression. Omitted entirely (not even the
- *  prop) when no header is declared — the same off-by-default gating as every
- *  capability in this file, even though \`header\` isn't itself a capability. */
-function emitHeaderProp(c: Construct): string {
-  const title = c.header?.title;
-  if (!title) return '';
-  return ` chatTitle={${JSON.stringify(title)}}`;
-}
-
-/** `empty` -> ChatThread's own `emptyContent` prop (chat-thread.tsx), a plain
- *  JSX value rendered INSIDE ChatThread's own tree — fully covered by the
- *  shadow root's adopted stylesheet, unlike the `empty`/`slot="empty"` boolean
- *  pairing this used to go through. That boundary was LIGHT-DOM: `<Portal
- *  mount={element}>` manufactured a real child of the host element tagged
- *  `slot="empty"` so ChatThread's `<slot name="empty">` could redistribute it
- *  — a detour needed only because a shadow `<slot>` redistributes light-DOM
- *  children of the HOST, never a Solid sibling's own JSX. It worked, but light
- *  DOM sits outside the shadow root's adopted stylesheet, so the Tailwind
- *  utility classes the kit's own `Empty` composition is built from resolved to
- *  nothing — the greeting rendered, unstyled (owner report against the live
- *  widget: "doesn't look like the empty component"). `App` already composes
- *  `ChatThread` directly as a plain Solid component in the SAME shadow tree
- *  `defineWebComponent` attaches, so there is no boundary to cross here at
- *  all — `emptyContent` just hands the JSX straight down, and it inherits the
- *  same styling as the rest of `App`. No Portal, no host-element param on
- *  `App`, no light-DOM indirection.
- *
- *  `capabilities.starters`' chips and the composer still render underneath
- *  it: ChatThread's own doc comment on `empty`/`emptyContent` is explicit
- *  that this REPLACES only the empty MESSAGE LIST.
- *
- *  Uses the kit's own `Empty`/`EmptyHeader`/`EmptyMedia`/`EmptyTitle`/
- *  `EmptyDescription` composition (components/empty.tsx) rather than hand-
- *  rolled markup — the same "don't restate the kit's own layout" rule
- *  `emitApp`'s header comment states for ChatThread itself. `title`/
- *  `description` are construct-authored/untrusted text, JSON.stringify'd into
- *  real JS string-literal expressions like every other free-text field in
- *  this file; `icon` is schema-validated by `isSafeUrl` (schema.ts) before
- *  codegen ever sees it, the same policy `widget.launcherIcon` uses. */
-function emitEmptyContentProp(c: Construct): string {
-  const empty = c.empty;
-  if (!empty) return '';
-  const title = `<EmptyTitle>{${JSON.stringify(empty.title)}}</EmptyTitle>`;
-  const icon = empty.icon
-    ? `<EmptyMedia><img src={${JSON.stringify(empty.icon)}} alt="" style={{ width: '40px', height: '40px', 'border-radius': '9999px' }} /></EmptyMedia>`
-    : '';
-  const description = empty.description
-    ? `<EmptyDescription>{${JSON.stringify(empty.description)}}</EmptyDescription>`
-    : '';
-  return ` emptyContent={<Empty><EmptyHeader>${icon}${title}${description}</EmptyHeader></Empty>}`;
-}
-
-/** The `Empty` composition components `emitEmptyContentProp` needs, appended
- *  onto the same `@kitn.ai/ui/solid` import ChatThread/createKaiChat already
- *  use — never a second import statement for the same module. `EmptyMedia`/
- *  `EmptyDescription` are named only when `icon`/`description` are actually
- *  declared: `verify:scaffold` compiles emitted output with `tsc --strict
- *  --noUnusedLocals`, so an always-imported-but-sometimes-unused name would
- *  fail that gate the moment a construct omits one. */
-function emitEmptyComponentImport(c: Construct): string {
-  if (!c.empty) return '';
-  let names = ', Empty, EmptyHeader, EmptyTitle';
-  if (c.empty.icon) names += ', EmptyMedia';
-  if (c.empty.description) names += ', EmptyDescription';
-  return names;
-}
-
-/** `widget` layout with a declared `header.title` gets its own close control
- *  integrated INTO ChatThread's header row instead of relying solely on
- *  Dock's own floating mobile X (see `dock.tsx`'s `hideClose` doc for the
- *  "why": a header-row X and a floating X over that same row read as
- *  unintentional together — owner feedback against the live widget). No
- *  header means no row for a close control to sit in at all, so this stays
- *  false and Dock's built-in fallback X keeps covering that case unchanged. */
-function widgetHasHeaderClose(c: Construct): boolean {
-  return c.layout === 'widget' && !!c.header?.title;
-}
-
-/** `widget` layout with `capabilities.conversations` on: whether the widget
- *  needs the close-resets-the-list-view wiring below (owner follow-up,
- *  2026-08-26 — closing the widget while its conversations list was open
- *  left `ChatThread`'s internal `view` state at `'list'`, so the NEXT open
- *  landed back on the list instead of the default chat screen). Only
- *  `widget` has a `Dock` to close/reopen at all; every other layout renders
- *  ChatThread inline with nothing that ever hides it, so the regression
- *  can't occur there and nothing is emitted for them.
- *
- *  ALSO gates unread indicators (owner round, 2026-08-26): the FAB's `Dock
- *  unread` badge and `ChatThread`'s own `hostOpen` prop both need the exact
- *  same `dockOpen` tracking this reset wiring already needs, and both need
- *  the same "is there even a Dock to reflect this on" condition — one gate,
- *  reused, rather than two nearly-identical predicates drifting apart.
- *
- *  Widened (Task 5) to also fire on `home` alone, with no `conversations`
- *  capability: closing the widget must return the view to Home exactly like
- *  it must return to the default chat screen — same regression class, same
- *  reset wiring, and `closeConversationsList()` is a safe no-op when there
- *  never was a conversations list to close. */
-function widgetHasConversationsChrome(c: Construct): boolean {
-  return c.layout === 'widget' && (!!c.capabilities?.conversations || !!c.home);
-}
-
-/** Declares the closure `emitChatControllerRefProp`/`emitDockOnOpenChangeProp`
- *  share: `ChatThread`'s own `controllerRef` (chat-thread.tsx) hands back a
- *  `ChatThreadController` — the existing imperative seam, not a new one — and
- *  this captures it so `Dock`'s `onOpenChange` (a sibling prop on a sibling
- *  element, not a ChatThread descendant) can call
- *  `closeConversationsList()` on it. Declared inside `App()`, not at module
- *  scope, for the same instance-isolation reason as `emitDockCloseVar`. */
-function emitChatControllerVar(c: Construct, indent: string): string {
-  return widgetHasConversationsChrome(c) ? `${indent}let chatController: ChatThreadController | undefined;\n` : '';
-}
-
-/** Threads `emitChatControllerVar`'s closure onto `<ChatThread controllerRef>`. */
-function emitChatControllerRefProp(c: Construct): string {
-  return widgetHasConversationsChrome(c) ? ' controllerRef={(api) => (chatController = api)}' : '';
-}
-
-/** `Dock`'s own `onOpenChange` (ui/dock.tsx) already fires on EVERY close
- *  path — the header X, the launcher toggle, and Escape all resolve through
- *  its single `setOpen` — so wiring it once here covers all three with no
- *  per-path duplication (the alternative `emitDockCloseVar`/`dockClose`
- *  closure above only covers the header-X path, which is why that one isn't
- *  reused for this). The reset half fires ONLY on the close transition
- *  (`!open`) — opening needs no action there, the list stays gone until the
- *  visitor taps the toggle again, and a mid-open reset call would fight
- *  anyone still viewing the list. `setDockOpen(open)` fires on BOTH
- *  transitions unconditionally — it's a plain mirror of Dock's own state
- *  into a signal `ChatThread`'s `hostOpen` prop can read (see
- *  `emitConversationsSignalsVar`'s doc for why a signal, not a variable). */
-function emitDockOnOpenChangeProp(c: Construct): string {
-  return widgetHasConversationsChrome(c)
-    ? ' onOpenChange={(open) => { setDockOpen(open); if (!open) chatController?.closeConversationsList(); }}'
-    : '';
-}
-
-/** `ChatThreadController` is needed only when `emitChatControllerVar` above
- *  declares a variable of that type — appended onto the same `import type`
- *  statement as `AttachmentData`/`ChatMessage`, never a second import
- *  statement for the module (same convention as `emitHistoryTypeImport`). */
-function emitConversationsResetTypeImport(c: Construct): string {
-  return widgetHasConversationsChrome(c) ? ', ChatThreadController' : '';
-}
-
-/** `createSignal` import for `emitConversationsSignalsVar`'s two signals.
- *  Deliberately its OWN `import { createSignal } from 'solid-js'` line, not
- *  folded onto `emitSolidJsImport`'s: that one imports `createEffect` for the
- *  hand-rolled history-restore effect, which is UNEMITTED whenever
- *  `capabilities.conversations` is on (conversations subsumes persistence —
- *  see that function's own doc) — so for every construct this function
- *  actually fires for, `emitSolidJsImport` is already returning `''` and
- *  there's nothing to fold onto. */
-function emitConversationsSignalsImport(c: Construct): string {
-  return widgetHasConversationsChrome(c) ? `import { createSignal } from 'solid-js';\n` : '';
-}
-
-/** Declares the two signals `Dock`'s `onOpenChange` (above) writes and
- *  `ChatThread`'s `hostOpen`/`onUnreadChange` props (below) read/write:
- *  `dockOpen` mirrors whether the panel is currently open — a SIGNAL, not a
- *  plain closure variable like `dockClose`/`chatController` above, because
- *  `ChatThread` reads it REACTIVELY every render (`hostOpen={dockOpen()}`),
- *  not just calls it imperatively on an event; `anyUnread` is the reverse
- *  direction, `ChatThread` writing outward via `onUnreadChange={setAnyUnread}`
- *  so `Dock`'s own `unread` prop (ui/dock.tsx — already exists, already
- *  tested, no change needed there) can mirror it onto the FAB.
- *  `dockOpen`'s initial value matches `widget.defaultOpen` (mirroring
- *  `emitDockDefaultOpen`'s own read of the same field) — a widget that opens
- *  by default has to start "seen", or a message arriving before the first
- *  `onOpenChange` fire would look like it happened while closed. */
-function emitConversationsSignalsVar(c: Construct, indent: string): string {
-  if (!widgetHasConversationsChrome(c)) return '';
-  const w = c.layout === 'widget' ? c.widget : undefined;
-  const defaultOpen = w?.defaultOpen === true ? 'true' : 'false';
-  return `${indent}const [dockOpen, setDockOpen] = createSignal(${defaultOpen});\n${indent}const [anyUnread, setAnyUnread] = createSignal(false);\n`;
-}
-
-/** Threads the two signals above onto `<ChatThread hostOpen>`/
- *  `<ChatThread onUnreadChange>`. */
-function emitChatThreadUnreadProps(c: Construct): string {
-  return widgetHasConversationsChrome(c) ? ' hostOpen={dockOpen()} onUnreadChange={setAnyUnread}' : '';
-}
-
-/** Threads `anyUnread` onto `Dock`'s own (pre-existing, unchanged) `unread`
- *  prop — the FAB's badge while closed. */
-function emitDockUnreadProp(c: Construct): string {
-  return widgetHasConversationsChrome(c) ? ' unread={anyUnread()}' : '';
-}
-
-/** The local closure `emitHeaderEndContentProp`/`emitDockControllerRef` share:
- *  Dock's `controllerRef` hands back `{ open, setOpen }` (ui/dock.tsx) — the
- *  existing imperative seam, not a new one — and this captures `setOpen`
- *  behind a plain function so ChatThread's `headerEndContent` button (which
- *  renders as a sibling, not a Dock descendant) can call it. Declared inside
- *  `App()`, not at module scope: `App()` runs once per widget instance, and a
- *  module-level variable would let one instance's close button reach into
- *  another's Dock if two ever rendered on the same page. */
-function emitDockCloseVar(c: Construct, indent: string): string {
-  return widgetHasHeaderClose(c) ? `${indent}let dockClose: (() => void) | undefined;\n` : '';
-}
-
-/** Threads `emitDockCloseVar`'s closure onto `<Dock controllerRef>`. */
-function emitDockControllerRef(c: Construct): string {
-  return widgetHasHeaderClose(c) ? ' controllerRef={(api) => (dockClose = () => api.setOpen(false))}' : '';
-}
-
-/** Suppresses Dock's own built-in mobile close X (see its `hideClose` doc)
- *  when ChatThread's header row is carrying an equivalent control instead —
- *  otherwise the two stack, one floating over the other's row. */
-function emitDockHideClose(c: Construct): string {
-  return widgetHasHeaderClose(c) ? ' hideClose={true}' : '';
-}
-
-/** ChatThread's `headerEndContent` prop (chat-thread.tsx): the close button
- *  itself, sharing the header row with the title instead of floating as a
- *  second, visually unrelated control — the owner's stated preference over
- *  Dock's previous "reserved dead-row band" fix. Reuses the kit's own
- *  `DockCloseGlyph` (the same X Dock's built-in button draws) and `Button`
- *  (ghost/icon-sm, the same weight ChatThread's own header controls use —
- *  see `ModelSwitcher`'s trigger) rather than hand-rolling either, and calls
- *  back into `emitDockCloseVar`'s closure to actually close the panel —
- *  Dock's own `controllerRef` seam, not a new one. */
-function emitHeaderEndContentProp(c: Construct): string {
-  if (!widgetHasHeaderClose(c)) return '';
-  return ` headerEndContent={<Button variant="ghost" size="icon-sm" aria-label="Close ${c.name}" onClick={() => dockClose?.()}><DockCloseGlyph /></Button>}`;
-}
-
-/** `Button`/`DockCloseGlyph`, needed only by `emitHeaderEndContentProp` above
- *  — appended onto the same `@kitn.ai/ui/solid` import as `emitEmptyComponentImport`,
- *  never a second import statement for the module. */
-function emitHeaderCloseImport(c: Construct): string {
-  return widgetHasHeaderClose(c) ? ', Button, DockCloseGlyph' : '';
-}
-
-/** capabilities.attachments -> ChatThread's own \`attach\`/\`accept\` props.
- *  Undeclared keeps the explicit off-by-default gating (\`attach={false}\`,
- *  matching webSearch/voice above). Declared flips \`attach={true}\` and
- *  threads the accept list through — construct-authored/untrusted like
- *  \`starters\`/\`theme.accent\`/\`provider.url\`, so JSON.stringify'd into a
- *  real JS string-literal expression rather than a raw JSX attribute
- *  string (JSX attribute strings don't interpret escapes the way JS string
- *  literals do, so a raw \`accept="..."\` would be a breakout surface for a
- *  hostile media-type entry containing a \`"\`). */
-function emitAttachProps(c: Construct): string {
-  const attachments = c.capabilities?.attachments;
-  if (!attachments) return ' attach={false}';
-  return ` attach={true} accept={${JSON.stringify(attachments.accept.join(','))}}`;
-}
-
-/** capabilities.starters -> ChatThread's own \`suggestions\` prop. Starter
- *  strings are construct-authored (untrusted the same way theme.accent and
- *  provider.url are) — JSON.stringify produces a real JS array-of-string-
- *  literals expression, the same safe-interpolation convention used for the
- *  accent (element.tsx) and the endpoint url (fetch() above): no quote,
- *  backslash or line-separator payload can break out of it. Omitted
- *  entirely (not even the prop) when no starters are declared, matching the
- *  off-by-default gating for every other capability. */
-function emitStartersProp(c: Construct): string {
-  const starters = c.capabilities?.starters;
-  if (!starters || starters.length === 0) return '';
-  return ` suggestions={${JSON.stringify(starters)}}`;
-}
-
-/** capabilities.reasoning -> ChatThread's own `reasoning` prop. `'full'`
- *  and absent are the SAME thing (the schema default, matching ChatThread's
- *  own default) so both emit nothing at all — the off-by-default gating
- *  convention every other capability in this file follows: only a value that
- *  DEVIATES from the medium's default costs a byte in the emitted source.
- *  `'compact'`/`'off'` are plain string literals, not JSON.stringify'd like
- *  starters/accept/url — the schema already constrains this to one of three
- *  fixed enum members (schema.ts), so unlike those fields there is no
- *  construct-authored free text here to escape. */
-function emitReasoningProp(c: Construct): string {
-  const reasoning = c.capabilities?.reasoning;
-  if (!reasoning || reasoning === 'full') return '';
-  return ` reasoning="${reasoning}"`;
-}
-
-/** capabilities.reasoningOpen -> ChatThread's own `reasoningOpen` prop. Only
- *  `true` costs a byte (off-by-default, matching every capability here);
- *  false/absent matches the kit's own new default (closed chip). */
-function emitReasoningOpenProp(c: Construct): string {
-  return c.capabilities?.reasoningOpen === true ? ' reasoningOpen={true}' : '';
-}
-
-/** capabilities.conversations -> ChatThread's own `conversations`/`store`
- *  props (C-8: this is the ONLY logic codegen contributes — everything else
- *  is kit code behind ChatThread). `local` persistence wires
- *  localStorageStore(name[, userId]); `endpoint` wires fetchStore(url[,
- *  userId]) — both re-exported from @kitn.ai/ui/solid, never hand-rolled
- *  here (composition-over-reauthoring, same discipline as every other
- *  capability in this file). `c.name` is validated against TAG_RE
- *  (schema.ts — lowercase, hyphenated, a valid custom-element tag), so like
- *  the other `'${c.name}'` interpolation sites in this file (defineWebComponent,
- *  the preview HTML's element tag) it is embedded directly rather than
- *  JSON.stringify'd. userId/url ARE construct-authored/untrusted free text,
- *  JSON.stringify'd at their one interpolation site like theme.accent. The
- *  schema's superRefine (C-4) guarantees history is present with persistence
- *  'local' or 'endpoint' whenever conversations is true, so no further guard
- *  is needed here.
- *
- *  BUG FIX (Task 6 live-browser demo, both defects traced to one root cause):
- *  `conversations`/`store` alone only drive ChatThread's OWN internal
- *  view/list/activeId state machine — select/new/mount-restore all resolve
- *  through `store.load()`/a cleared array, but ChatThread never mutates
- *  `props.messages` itself (doc comment on `onConversationLoad`, chat-thread.tsx
- *  line ~144: "this component does not mutate props.messages itself"). Without
- *  `onConversationLoad` wired back to this app's own `chat` store, every
- *  load/new/restore updated ChatThread's internal bookkeeping (active id, list
- *  entry) while the actually-rendered `chat.messages()` never changed — the
- *  exact silent-drop class this codebase's CLAUDE.md calls out ("decide
- *  loudly"), except here the drop was an OMITTED wire, not a decision: "+ New
- *  conversation" appeared to do nothing (same messages kept rendering) and a
- *  reload's mount-time auto-restore updated the list's active row but left the
- *  chat view on the empty/welcome screen. `chat.setMessages(() => messages)`
- *  closes the loop — ChatThread already hands back a FRESH array reference on
- *  every call (`[...messages]` at both call sites in chat-thread.tsx), so no
- *  extra clone is needed here; the updater-returns-new-array form is what the
- *  reactivity contract (CLAUDE.md) requires and is what emitHistorySetup's
- *  own hand-rolled local/endpoint restore already did before conversations
- *  subsumed it. */
-/** `home` -> ChatThread's own `home` prop (chat-thread.tsx, Task 1-4), plain
- *  data threaded straight through as ONE JSON.stringify'd object literal —
- *  vocabulary-never-logic (this format's binding rule): the construct only
- *  ever DECLARES the home screen's content, never wires a handler for it.
- *  `<kai-chat>`'s own `kai-home-link` CustomEvent (Task 2-3) is how a
- *  consumer of the EMITTED app would react to a link click; codegen never
- *  emits an `onHomeLink` listener here for the same reason it never emits
- *  handlers for any other capability in this file. Omitted entirely when no
- *  `home` is declared — the same off-by-default gating as `emitHeaderProp`/
- *  `emitEmptyContentProp` above. */
-function emitHomeProp(c: Construct): string {
-  if (!c.home) return '';
-  return ` home={${JSON.stringify(c.home)}}`;
-}
-
-function emitConversationsProps(c: Construct): string {
-  if (!c.capabilities?.conversations) return '';
-  const history = c.capabilities.history;
-  const storeCall =
-    history?.persistence === 'endpoint'
-      ? `fetchStore(${JSON.stringify(history.url)}${c.userId ? `, ${JSON.stringify(c.userId)}` : ''})`
-      : `localStorageStore('${c.name}'${c.userId ? `, ${JSON.stringify(c.userId)}` : ''})`;
-  return ` conversations={true} store={${storeCall}} onConversationLoad={(messages) => chat.setMessages(() => messages)}`;
-}
-
-/** A dedicated named import for whichever store constructor
- *  emitConversationsProps used — its own statement (mirrors emitCardsImport's
- *  own `import { cards } from './cards'` line) rather than spliced onto the
- *  ChatThread import list, so noUnusedLocals never trips when conversations
- *  is absent. */
-function emitConversationsImport(c: Construct): string {
-  if (!c.capabilities?.conversations) return '';
-  const name = c.capabilities.history?.persistence === 'endpoint' ? 'fetchStore' : 'localStorageStore';
-  return `import { ${name} } from '@kitn.ai/ui/solid';`;
-}
-
-/** capabilities.history -> whether the App module needs `createEffect`
- *  (both persisted variants react to `chat.messages()` changing; `none`/
- *  absent needs no extra Solid import at all, matching the off-by-default
- *  gating everywhere else in this file).
- *
- *  capabilities.conversations SUBSUMES this on every layout EXCEPT `custom`
- *  (CU-1: conversations is one of the capabilities excluded from the custom
- *  layout's escape hatch, so custom never wires the store-based path and
- *  must keep this hand-rolled one). Where it applies, ChatThread's own
- *  conversations feature owns persistence entirely through the `store` prop
- *  (see emitHistorySetup's doc for the full decision) and this file's
- *  hand-rolled effect is never emitted, so it needs no `createEffect` import
- *  either — gate the same way. */
-function emitSolidJsImport(c: Construct): string {
-  const history = c.capabilities?.history;
-  if (!history || history.persistence === 'none' || (c.layout !== 'custom' && c.capabilities?.conversations)) return '';
-  return `import { createEffect } from 'solid-js';\n`;
-}
-
-/** capabilities.history -> whether the AttachmentData type import also needs
- *  ChatMessage (only the persisted variants read/write full ChatMessage[]
- *  arrays). Gated off when capabilities.conversations subsumes persistence
- *  (see emitSolidJsImport's doc — same `layout !== 'custom'` condition) for
- *  the same reason: the hand-rolled block that used this type is never
- *  emitted there. */
-function emitHistoryTypeImport(c: Construct): string {
-  const history = c.capabilities?.history;
-  if (!history || history.persistence === 'none' || (c.layout !== 'custom' && c.capabilities?.conversations)) return '';
-  // The enclosing statement is already `import type { ... }` (AttachmentData),
-  // so this must NOT repeat the `type` modifier inside the braces — `import
-  // type { AttachmentData, type ChatMessage }` is a TS syntax error.
-  return ', ChatMessage';
-}
-
-/** capabilities.history -> the persistence block spliced after
- *  createKaiChat/submit (emitProviderSetup). `none`/absent emits nothing at
- *  all — the format rule (undeclared capability's affordance is OFF).
- *
- *  `local`: keyed by the construct's own tag (one thread per construct, no
- *  cross-construct collision) — restoring on mount MUST hand createKaiChat's
- *  setMessages a NEW array reference (the kit's reactivity contract; see
- *  CLAUDE.md), which the updater-returns-parsed-array form does for free. A
- *  parsed value that is well-formed JSON but the WRONG SHAPE (an object, a
- *  number, ...) is just as dangerous as a storage exception — handing it to
- *  `chat.setMessages` would crash ChatThread's render — so it gets the same
- *  `Array.isArray` gate as the endpoint variant below, not just a try/catch
- *  around the parse.
- *  localStorage access is wrapped: it can throw in private mode or over
- *  quota, and a corrupt/foreign value under the key must not white-screen —
- *  neither failure is guessed at silently, both fall back to running
- *  in-memory (decide loudly: see the comment emitted alongside).
- *  Retention/eviction (how much, how long) is deliberately absent — an
- *  application-layer decision (component-scope-boundary), not this
- *  construct's to make.
- *
- *  `endpoint`: the CONSUMER's own thread route — GET on mount (kit parses
- *  the response as ChatMessage[]; a non-OK response, a rejected fetch, or a
- *  non-array body all fall back to an empty thread rather than throwing or
- *  crashing render — matching the shape-check discipline above), PUT on
- *  every change. Both fetches are wrapped (try/catch around the GET chain,
- *  `.catch` on the PUT) and decide loudly on failure (`console.error`) —
- *  mirroring the adjacent provider-endpoint fetch's own try/catch +
- *  `stream.abort` pattern, not a silent swallow. The `hydrated` flag guards
- *  against the mount-load's own setMessages call immediately re-triggering a
- *  PUT that writes back exactly what was just read — but a FAILED GET must
- *  still flip it, in `finally`: a transient GET failure (offline/CORS/DNS)
- *  degrading to "start fresh, keep saving" is the recoverable failure mode;
- *  leaving `hydrated` false forever would permanently disable every future
- *  PUT for the tab's life over one blip. No retry/backoff — that belongs to
- *  the app, not this construct (component-scope-boundary). url is
- *  construct-authored/untrusted like theme.accent and provider.url, so it is
- *  JSON.stringify'd at both fetch call sites — never string-concatenated
- *  (see the endpoint-provider comment on this same class of bug). */
-/** Top-level userId -> the `x-kai-user-id` header on every emitted fetch that
- *  talks to the consumer's own backend (the endpoint provider's chat POST, and
- *  history's endpoint GET/PUT) — so a route can tell which user's thread this
- *  is. `local` persistence folds it into THREAD_KEY instead (see
- *  emitHistorySetup) — no network call to header there. userId is
- *  construct-authored data (like theme.accent/provider.url), so it is
- *  JSON.stringify'd wherever it is interpolated — never string-concatenated. */
-function emitUserIdHeaderEntry(c: Construct): string {
-  return c.userId ? `, 'x-kai-user-id': ${JSON.stringify(c.userId)}` : '';
-}
-
-function emitHistorySetup(c: Construct): string {
-  const history = c.capabilities?.history;
-  if (!history || history.persistence === 'none') return '';
-
-  // PERSISTENCE-OWNERSHIP DECISION (Task 5): capabilities.conversations
-  // SUBSUMES this hand-rolled block entirely. ChatThread's own conversations
-  // feature (chat-thread.tsx) already autosaves the current thread on every
-  // `chat.messages()` change through whatever ConversationStore its `store`
-  // prop wires — localStorageStore(name) for `local`, fetchStore(url) for
-  // `endpoint` (see emitConversationsProps below), the SAME "keyed by
-  // construct name, local browser storage or a fetch endpoint" mechanism this
-  // block hand-rolls for a single anonymous thread via THREAD_KEY/fetch. With
-  // conversations on there is a real conversation id to save under (the store
-  // contract), so the store path is strictly more correct, not just
-  // redundant. Emitting both would persist through two independent
-  // mechanisms on every change — not corrupting, but wasteful, confusing to
-  // read, and exactly the kind of restatement this file avoids elsewhere
-  // (see emitApp's header comment) — so this function contributes NOTHING
-  // when capabilities.conversations is set: the store prop is the ONE
-  // persistence mechanism in the emitted App. This does NOT apply to the
-  // `custom` layout — CU-1 excludes conversations from custom's escape
-  // hatch (emitCustomApp never calls emitConversationsProps), so custom
-  // must keep this hand-rolled block as its only persistence mechanism even
-  // when capabilities.conversations is set on the construct.
-  if (c.layout !== 'custom' && c.capabilities?.conversations) return '';
-
-  if (history.persistence === 'local') {
-    const key = JSON.stringify(c.userId ? `kai:${c.name}:${c.userId}:thread` : `kai:${c.name}:thread`);
-    return `
-// History: persisted locally in this browser, keyed by the element tag. What to
-// retain and for how long is an app decision — clear the key to reset.
-const THREAD_KEY = ${key};
-try {
-  const saved = localStorage.getItem(THREAD_KEY);
-  if (saved) {
-    const parsed: unknown = JSON.parse(saved);
-    if (Array.isArray(parsed)) {
-      chat.setMessages(() => parsed as ChatMessage[]);
-    } else {
-      console.warn(\`[\${THREAD_KEY}] stored history was not an array; ignoring and starting fresh\`);
-    }
-  }
-} catch { /* storage unavailable or corrupt: run in-memory */ }
-createEffect(() => {
-  try {
-    localStorage.setItem(THREAD_KEY, JSON.stringify(chat.messages()));
-  } catch { /* storage unavailable: run in-memory */ }
-});
-`;
-  }
-
-  const url = JSON.stringify(history.url);
-  return `
-// History: persisted to your endpoint (GET on mount, PUT on every change) —
-// the kit PARSES, this app FETCHES; your route owns the storage and what to
-// retain and for how long. \`hydrated\` guards the mount-load from immediately
-// PUTting back what it just loaded, but still flips on a FAILED load — one
-// offline/CORS/DNS blip degrades to "start fresh, keep saving", not
-// "never save again".
-let hydrated = false;
-(async () => {
-  try {
-    const r = await fetch(${url}${c.userId ? `, { headers: { 'x-kai-user-id': ${JSON.stringify(c.userId)} } }` : ''});
-    const saved: unknown = r.ok ? await r.json() : [];
-    if (Array.isArray(saved)) {
-      chat.setMessages(() => saved as ChatMessage[]);
-    } else {
-      console.warn('history endpoint returned a non-array body; ignoring and starting fresh');
-    }
-  } catch (err) {
-    console.error('history endpoint GET failed; starting fresh (will keep saving)', err);
-  } finally {
-    hydrated = true;
-  }
-})();
-createEffect(() => {
-  const snapshot = chat.messages();
-  if (!hydrated) return;
-  fetch(${url}, {
-    method: 'PUT',
-    headers: { 'content-type': 'application/json'${emitUserIdHeaderEntry(c)} },
-    body: JSON.stringify(snapshot),
-  }).catch((err) => {
-    console.error('history endpoint PUT failed; this change was not persisted', err);
-  });
-});
-`;
-}
-
-function emitProviderImports(c: Construct): string {
-  if (c.provider.mode === 'mock') {
-    return `import { createMockResponder } from '@kitn.ai/ui/state';
-import { readOpenAIStream } from '@kitn.ai/ui/wire';`;
-  }
-  const read = c.provider.wire === 'openai' ? 'readOpenAIStream' : 'readAnthropicStream';
-  const encode = c.provider.wire === 'openai' ? 'toOpenAIMessages' : 'toAnthropicMessages';
-  return `import { ${read}, ${encode} } from '@kitn.ai/ui/wire';`;
-}
-
-function emitProviderSetup(c: Construct): string {
-  // ChatThread owns its own composer draft (uncontrolled — no `value` prop
-  // passed below) and clears it after submit itself; `onSubmit` hands back
-  // the value directly, so there's no PromptInput-specific signal-reading
-  // workaround to carry here any more.
-  if (c.provider.mode === 'mock') {
-    const cardsNote = c.cards
-      ? `
-// Cards demo keylessly: createMockResponder() can already SCRIPT a tool call
-// (\`replies: [{ toolCalls: [...] }]\`, F-35), so a scripted turn calling
-// \`kai_<card name>\` renders exactly like a live model's would, below.`
-      : '';
-    return `// Provider seam: mock — keyless, streams locally, announces itself once.
-// Swap for provider.mode "endpoint" in the construct and re-run kai dev; the
-// generated fetch keeps this exact shape (the seam is the point).${cardsNote}
-const respond = createMockResponder();
-const chat = createKaiChat();
-
-async function submit(detail: { value: string; attachments: AttachmentData[] }) {
-  if (!detail.value.trim() || chat.loading()) return;
-  chat.append({
-    id: crypto.randomUUID(),
-    role: 'user',
-    parts: [
-      { type: 'text', text: detail.value },
-      ...detail.attachments.map((attachment) => ({ type: 'file' as const, attachment })),
-    ],
-  });
-  const stream = chat.streamAssistant();
-  try {
-    await readOpenAIStream(respond(detail.value), stream);${emitApplyCardTools(c)}
-    stream.done();
-  } catch (err) {
-    stream.abort(err instanceof Error ? err.message : String(err));
-  }
-}`;
-  }
-
-  const { url, wire } = c.provider;
-  const read = wire === 'openai' ? 'readOpenAIStream' : 'readAnthropicStream';
-  const encode = wire === 'openai' ? 'toOpenAIMessages' : 'toAnthropicMessages';
-  // provider.url is an UNCONSTRAINED z.string() (schema.ts). It is NEVER
-  // embedded in this comment — a `//` line comment is ended by a raw
-  // U+2028/U+2029 line separator (a valid JS line terminator that
-  // commentSafe's \r\n strip does not catch), so a url containing one of
-  // those code points could close the comment early and let the rest of the
-  // url execute as JS. commentSafe is a comment-escaping tool and this is a
-  // hand-rolled-escaping trap for untrusted input by construction, so the
-  // fix is to never hand-roll it here: the url appears ONLY on the fetch()
-  // line below, via JSON.stringify, which is a real JS string literal (not a
-  // comment) and immune to this class of bug.
-  return `// Provider seam: YOUR endpoint (${wire} wire, see the fetch call below
-// for the URL). The kit PARSES, this component FETCHES — no key, no
-// provider SDK, no client in here. Your route holds the key and re-frames to
-// the provider; the kai MCP scaffold tool emits one for your framework.
-const chat = createKaiChat();
-
-async function submit(detail: { value: string; attachments: AttachmentData[] }) {
-  if (!detail.value.trim() || chat.loading()) return;
-  chat.append({
-    id: crypto.randomUUID(),
-    role: 'user',
-    parts: [
-      { type: 'text', text: detail.value },
-      ...detail.attachments.map((attachment) => ({ type: 'file' as const, attachment })),
-    ],
-  });
-  const stream = chat.streamAssistant();
-  try {
-    const response = await fetch(${JSON.stringify(url)}, {
-      method: 'POST',
-      headers: { 'content-type': 'application/json'${emitUserIdHeaderEntry(c)} },
-      body: JSON.stringify({ messages: ${encode}(chat.messages())${emitToolsField(c)} }),
-    });
-    if (!response.ok) throw new Error(\`endpoint responded \${response.status}\`);
-    await ${read}(response, stream);${emitApplyCardTools(c)}
-    stream.done();
-  } catch (err) {
-    stream.abort(err instanceof Error ? err.message : String(err));
-  }
-}`;
-}
-
-/** The layout-conditional named import spliced onto the `@kitn.ai/ui/solid`
- *  import list in App.tsx: `Dock` only for `widget`, `PaneGroup` only for
- *  `split` — nothing for `fullscreen`/`aside`, which are plain styled
- *  containers (the kit has no dedicated fullscreen/docked-aside component;
- *  see the emitLayoutOpen doc for why that's the honest choice here rather
- *  than a hand-rolled component of our own). Gated so the generated
- *  project's own `noUnusedLocals` never trips on an import used by a layout
- *  that isn't this construct's. */
-function emitLayoutImport(c: Construct): string {
-  switch (c.layout) {
-    case 'widget':
-      return `, Dock${hasLauncherIcon(c) ? ', DockLauncherImage' : ''}`;
-    case 'split':
-      return ', WorkspaceShell';
-    case 'fullscreen':
-    case 'aside':
-      return '';
-    case 'custom':
-      // Unreachable: emitApp special-cases 'custom' into emitCustomApp before
-      // this is ever called (custom's spine is Thread + PromptInput, not
-      // ChatThread, so there is no shared import line to splice onto). Kept
-      // only so this switch stays exhaustive over the widened layout enum.
-      return '';
-  }
-}
-
-/** Declared `slots`, one `<slot name="...">` per entry in declaration order.
- *  Slot names are already schema-validated to `^[a-z][a-z0-9-]*$` (schema.ts)
- *  — a closed character set with no quote/backslash, so they're interpolated
- *  directly into the attribute rather than JSON.stringify'd like the
- *  free-text construct-authored fields (starters, theme.accent, provider.url)
- *  elsewhere in this file. `indent` matches the surrounding JSX depth. */
-function emitSlots(slots: readonly string[] | undefined, indent: string): string {
-  if (!slots || slots.length === 0) return '';
-  return slots.map((name) => `${indent}<slot name="${name}" />\n`).join('');
-}
-
-/**
- * The layout shell wrapping ChatThread — one pair (open above, close below)
- * per `layout`, composing the kit's own layout primitives over a hand-rolled
- * div wherever the kit ships one:
- *
- *  - `widget`: the kit's Dock (launcher + panel + focus contract) — unchanged
- *    from before Task 12. No theming wrapper needed here — the accent lands
- *    on the HOST element from element.tsx's facade (see emitElement), which
- *    reaches both the launcher (a DOM sibling of this panel content, outside
- *    Dock's own `children`) and everything below via normal custom-property
- *    inheritance from :host down through the whole shadow tree.
- *  - `fullscreen`: the kit has no dedicated "fill the viewport" component —
- *    this genuinely is just sizing, not chrome — so a minimally-styled
- *    `<div>` (100dvh, column flex) IS the honest composition, not a
- *    restatement of something the kit already owns.
- *  - `aside`: same reasoning — a persistent, single-edge docked panel is a
- *    styled container (fixed inline-end column, the kit's own
- *    `--kai-color-border` token for the divider), not a kit component. `dvh`/
- *    logical properties (`inset-inline-end`, `border-inline-start`) keep it
- *    correct under RTL and mobile viewport chrome the same way `100dvh` does
- *    for fullscreen.
- *  - `split`: composes the kit's real `WorkspaceShell` (components/
- *    workspace-shell.tsx) for its frame -- chat in `children` (the main
- *    region), the end pane's `<slot name="pane">` seam projected via `end`.
- *    Superseded from Task 12's `PaneGroup` (recorded decision 2): `PaneGroup`
- *    is an editor GROUP contract (src/ui/pane-group.tsx) -- a tab strip over
- *    ONE content area -- so getting two SIMULTANEOUS panes out of it meant a
- *    single always-active tab whose one body was a hand-rolled flex row doing
- *    the actual two-column math; the "kit component" was supplying a frame
- *    the composition didn't use for its defining feature (a resizable split)
- *    at all. `WorkspaceShell` already IS a two-region layout with a REAL
- *    draggable splitter between them (it composes `ResizablePanelGroup`
- *    internally) -- start/end aside width props and collapse are left at
- *    their defaults here (this construct wants exactly one fixed end pane,
- *    not a full workspace chrome); `drawerBelow={480}` IS wired (Task 19d) so
- *    split gets the kit's own mobile takeover at the same breakpoint every
- *    other layout uses, so the split's math is the kit's
- *    own, not a restatement.
- *
- * `custom` is handled entirely by `emitCustomApp` instead (its spine is
- * Thread + PromptInput composed by hand, not ChatThread, so there's no shared
- * chrome to open/close here) — `emitApp` special-cases it before either of
- * these is called. Both switches still carry a `case 'custom'` so they stay
- * exhaustive over the widened layout enum: TypeScript is what caught this
- * exact gap when Task 13 added the enum member, and a `default` would have
- * hidden it again for the next one.
- */
-/** widget.position -> Dock's own `position` prop. A closed DockPosition enum
- *  (schema-constrained), so plain string interpolation is safe — no
- *  construct-authored free text here, unlike launcherIcon below. */
-function emitDockPosition(c: Construct): string {
-  const w = c.layout === 'widget' ? c.widget : undefined;
-  return w?.position ? ` position="${w.position}"` : '';
-}
-
-/** Whether `widgetHasLauncherIcon` (see below) needs the extra import — its
- *  own named predicate so `emitLayoutImport`'s `widget` case reads plainly. */
-function hasLauncherIcon(c: Construct): boolean {
-  return c.layout === 'widget' && !!c.widget?.launcherIcon;
-}
-
-/** widget.launcherIcon -> Dock's `launcher` prop, via `DockLauncherImage`
- *  (ui/dock.tsx) rather than a hand-rolled `<img>`: a construct-authored URL
- *  is exactly as capable of 404ing as any other network fetch (this is what
- *  the fix report found — `kai dev`'s own `owner-widget` fixture pinned a
- *  `https://example.com/logo.png` placeholder that never resolved, so the
- *  FAB rendered a permanently broken image), and `DockLauncherImage` is the
- *  kit's own tested graceful-degradation component for exactly that,
- *  falling back to the built-in glyph on load failure. launcherIcon is
- *  construct-authored/untrusted text (like theme.accent/provider.url
- *  elsewhere in this file), so it is JSON.stringify'd into a real JS
- *  string-literal expression, never interpolated into a raw JSX attribute
- *  string. */
-function emitDockLauncher(c: Construct): string {
-  const w = c.layout === 'widget' ? c.widget : undefined;
-  if (!w?.launcherIcon) return '';
-  return ` launcher={<DockLauncherImage src={${JSON.stringify(w.launcherIcon)}} />}`;
-}
-
-/** widget.defaultOpen -> Dock's own `defaultOpen` prop. Only `true` costs a
- *  byte — `false`/absent matches Dock's own default (closed), same
- *  off-by-default convention as every other capability in this file. */
-function emitDockDefaultOpen(c: Construct): string {
-  const w = c.layout === 'widget' ? c.widget : undefined;
-  return w?.defaultOpen === true ? ' defaultOpen={true}' : '';
-}
-
-function emitLayoutOpen(c: Construct): string {
-  switch (c.layout) {
-    case 'widget':
-      return `    <Dock label="${c.name}"${emitDockPosition(c)}${emitDockLauncher(c)}${emitDockDefaultOpen(c)}${emitDockHideClose(c)}${emitDockControllerRef(c)}${emitDockOnOpenChangeProp(c)}${emitDockUnreadProp(c)}>\n`;
-    case 'fullscreen':
-      return `    <div style={{ height: '100dvh', display: 'flex', 'flex-direction': 'column' }}>\n`;
-    case 'aside':
-      return `    <aside data-kai-layout="aside" style={{ position: 'fixed', 'inset-block': '0', 'inset-inline-end': '0', width: '380px', display: 'flex', 'flex-direction': 'column', 'border-inline-start': '1px solid var(--kai-color-border)' }}>
-      {/* Mirrors Dock's own narrow-viewport full-bleed rule (ui/dock.tsx:229-240)
-          — aside has no dedicated kit component (see the emitLayoutOpen doc
-          comment above), so this is the honest hand-rolled equivalent, not a
-          new responsive strategy. */}
-      <style>{\`@media (max-width: 480px) { [data-kai-layout="aside"] { inset: 0; width: auto; height: auto; border-inline-start: 0; } }\`}</style>
-`;
-    case 'split':
-      // drawerBelow: split's mobile takeover is the kit's OWN WorkspaceShell
-      // capability (components/workspace-shell.tsx), not hand-rolled CSS — wiring
-      // it here is composition-over-reauthoring, not a media-query duplicate. 480
-      // matches Dock's own breakpoint (ui/dock.tsx:229) so every layout takes over
-      // at the same viewport width.
-      return `    <div style={{ height: '100dvh' }}>\n      <WorkspaceShell class="h-full" drawerBelow={480} end={\n        <div style={{ height: '100%', overflow: 'auto' }}>\n          <slot name="pane" />\n        </div>\n      }>\n`;
-    case 'custom':
-      return ''; // unreachable — see the block comment above
-  }
-}
-
-function emitLayoutClose(c: Construct): string {
-  switch (c.layout) {
-    case 'widget':
-      return `    </Dock>\n`;
-    case 'fullscreen':
-      return `    </div>\n`;
-    case 'aside':
-      return `    </aside>\n`;
-    case 'split':
-      // The end pane (WorkspaceShell's `end`, opened above) is a fixed,
-      // always-present projection point for `split` specifically (Task 12) —
-      // orthogonal to Task 13's generic `slots` field, which still emits
-      // above the chat pane the same as every other non-custom layout (see
-      // emitApp). WorkspaceShell supplies its own real draggable splitter
-      // between the two, so there is no hand-rolled two-column math left to
-      // close here.
-      return `      </WorkspaceShell>\n    </div>\n`;
-    case 'custom':
-      return ''; // unreachable — see the block comment above
-  }
-}
-
-// ── kai compile: the d.ts alongside the single .js ─────────────────────────
-
-/** The declaration file `kai compile` writes beside the emitted .js — just
- *  enough for a consumer's TS to know the tag and its one settable prop. */
-export function emitTypes(c: Construct): string {
-  return `declare global {
-  interface HTMLElementTagNameMap {
-    '${c.name}': HTMLElement & { theme: 'light' | 'dark' | 'auto' };
-  }
-}
-export {};
-`;
-}
-
-// ── writing ──────────────────────────────────────────────────────────────────
-
-const MANIFEST = '.kai-manifest.json';
-
-/**
- * Write files; prune anything the PREVIOUS generation wrote that this one
- * didn't. Returns the paths that already existed on disk before this write
- * (i.e. were overwritten) — callers that decide loudly (the CLI's `eject`)
- * use it to say so instead of silently clobbering a file the caller may have
- * hand-edited.
- */
-export function writeProject(files: GeneratedFile[], dir: string): string[] {
-  const manifestPath = join(dir, MANIFEST);
-  const previous: string[] = existsSync(manifestPath)
-    ? (JSON.parse(readFileSync(manifestPath, 'utf8')) as string[])
-    : [];
-  const current = new Set(files.map((f) => f.path));
-  for (const stale of previous) {
-    if (!current.has(stale)) rmSync(join(dir, stale), { force: true });
-  }
-  const overwritten: string[] = [];
-  for (const f of files) {
-    const abs = join(dir, f.path);
-    if (existsSync(abs)) overwritten.push(f.path);
-    mkdirSync(dirname(abs), { recursive: true });
-    writeFileSync(abs, f.code);
-  }
-  writeFileSync(manifestPath, `${JSON.stringify([...current].sort(), null, 2)}\n`);
-  return overwritten;
-}