@kitn.ai/ui 0.26.0 → 0.28.0

package/dist/construct-cli.es.js

@@ -0,0 +1,1337 @@
+import { existsSync, readFileSync, rmSync, mkdirSync, writeFileSync, copyFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { join, dirname, resolve } from "node:path";
+import { z } from "zod";
+import { createRequire } from "node:module";
+const SAFE_SCHEMES = ["http:", "https:", "mailto:"];
+function schemeOf(url) {
+  try {
+    return new URL(url, "http://_invalid_base").protocol;
+  } catch {
+    return void 0;
+  }
+}
+function isSafeUrl(url) {
+  const scheme = schemeOf(url);
+  return scheme !== void 0 && SAFE_SCHEMES.includes(scheme);
+}
+const TAG_RE = /^[a-z][a-z0-9]*-[a-z0-9-]+$/;
+const ProviderSchema = z.discriminatedUnion("mode", [
+  z.object({ mode: z.literal("mock") }).strict(),
+  z.object({
+    mode: z.literal("endpoint"),
+    /** The CONSUMER's chat route. Kit parses, consumer fetches. */
+    url: z.string().min(1),
+    wire: z.enum(["openai", "anthropic"])
+  }).strict()
+]);
+const ConstructSchema = z.object({
+  $schema: z.string().optional(),
+  /** The emitted tag: <acme-support>. Must satisfy customElements.define. */
+  name: z.string().regex(TAG_RE, 'must be a valid custom-element tag: lowercase, with a hyphen (e.g. "acme-support")'),
+  // Widened progressively: fullscreen/aside/split landed in Task 12, custom in Task 13.
+  layout: z.enum(["widget", "fullscreen", "aside", "split", "custom"]),
+  provider: ProviderSchema,
+  /** Plain (unsigned) identity passthrough — no signing/auth infra (owner
+   *  ruling, 2026-08-26: signed JWT/HMAC identity is later additive
+   *  vocabulary, not this field). TOP-LEVEL, not nested under `provider`:
+   *  local history scoping (`capabilities.history.persistence: 'local'`)
+   *  needs userId independent of provider mode — nesting it inside the
+   *  provider union would make it silently inert for `mode: 'mock'` +
+   *  local history, a real and common combination. Threaded as the
+   *  `x-kai-user-id` header on every emitted fetch to the CONSUMER's own
+   *  backend (the endpoint provider's chat POST, history's endpoint
+   *  GET/PUT), and folded into the localStorage key for `local` history so
+   *  different users on the same browser profile don't share one thread.
+   *  Constrained to printable-ASCII (no CR/LF, no non-ISO-8859-1 code
+   *  points) beyond the usual construct-authored-text escaping: this value
+   *  reaches an HTTP HEADER VALUE, not just a JS string literal, and
+   *  `fetch()` throws at RUNTIME on a header value containing CR/LF or
+   *  outside ISO-8859-1 — a bad userId would surface as an opaque crash in
+   *  the CONSUMER's generated app, not a construct-validation error. Reject
+   *  loudly here instead, where the author gets a path + message. */
+  userId: z.string().min(1).regex(
+    /^[\x20-\x7E]+$/,
+    "must be printable ASCII with no line breaks (it becomes an HTTP header value)"
+  ).optional(),
+  theme: z.object({
+    /** Any CSS color; becomes --kai-color-primary on the host. */
+    accent: z.string().optional(),
+    /** Any CSS color; becomes --kai-color-unread on the host (owner
+     *  ruling, 2026-08-26 — the unread-indicator round). Same treatment
+     *  as `accent` in every way that matters for safety: construct-
+     *  authored/untrusted text, carried to the emitted facade via
+     *  `ctx.element.style.setProperty('--kai-color-unread',
+     *  JSON.stringify(...))` — never string-interpolated into CSS
+     *  text — so it can never break out into a new declaration or rule
+     *  (see emitElement's doc on why `accent` uses setProperty at all).
+     *  Unlike `accent`, this has no paired -foreground to compute: the
+     *  three surfaces that read --color-unread (the conversation-list
+     *  row dot, the header toggle's badge, Dock's own closed-launcher
+     *  badge) are all small filled dots with no text sitting ON them, so
+     *  there is nothing to contrast-pair — the value is set and used
+     *  as-is. */
+    unreadColor: z.string().optional(),
+    mode: z.enum(["light", "dark", "system"]).default("system")
+  }).strict().optional(),
+  /** Construct-wide header chrome, valid on every layout (not layout-scoped
+   *  like `widget`, and not a capability toggle — a header is a construct-
+   *  wide fact, like `theme`). Rendered inside ChatThread's own built-in
+   *  header bar; a logo/icon projects through the kit's EXISTING
+   *  `header-start` named slot (`slots` vocabulary above), not a second
+   *  image-prop convention here. */
+  header: z.object({
+    /** Rendered in ChatThread's built-in header bar (left side). Construct-
+     *  authored/untrusted text, like theme.accent/provider.url — JSON.stringify'd
+     *  at its one emit site, never a raw JSX attribute string. */
+    title: z.string().min(1).optional()
+  }).strict().optional(),
+  /** Greeting shown while the thread is empty (no messages yet) — the
+   *  proven "welcome screen" pattern (Intercom-class): title + optional
+   *  description + optional icon above, with `capabilities.starters`'
+   *  chips and the composer still rendering below (ChatThread's `empty`
+   *  REPLACE slot only stands in for the empty MESSAGE LIST — see
+   *  chat-thread.tsx's own doc comment on `empty` — so the chips are
+   *  never lost). Construct-wide like `header`, not a capability: it's a
+   *  fact about the empty state, not a toggleable affordance.
+   *  `title`/`description` are construct-authored/untrusted text, like
+   *  `header.title`/`theme.accent`/`provider.url` — JSON.stringify'd at
+   *  their one emit site, never a raw JSX attribute string. `icon` is a
+   *  URL reaching an `<img src>` sink in emitted code, exactly like
+   *  `widget.launcherIcon` — same `isSafeUrl` policy, same superRefine
+   *  shape, below. */
+  empty: z.object({
+    title: z.string().min(1),
+    description: z.string().min(1).optional(),
+    icon: z.string().min(1).optional()
+  }).strict().optional(),
+  /** Home screen (spec 2026-08-27, H-1..H-5): Intercom-style landing view behind
+   *  a Home/Messages tab bar. PRESENCE of `home` enables the tab chrome (H-4) —
+   *  no `enabled` boolean, like `header`/`empty`. Every sub-key optional;
+   *  `home: {}` still means "tabs on, defaults". Never requires another
+   *  capability (H-3): the recent card simply renders nothing without
+   *  `capabilities.conversations` (the CLI warns — see cli.ts). All strings are
+   *  construct-authored/untrusted: JSON.stringify'd at every emit site; hrefs
+   *  and URL-shaped icons through isSafeUrl in superRefine below. */
+  home: z.object({
+    greeting: z.object({ title: z.string().min(1).optional(), subtitle: z.string().min(1).optional() }).strict().optional(),
+    recentConversation: z.literal(true).optional(),
+    newConversation: z.object({ label: z.string().min(1).optional() }).strict().optional(),
+    links: z.array(
+      z.object({
+        label: z.string().min(1),
+        href: z.string().min(1).optional(),
+        description: z.string().min(1).optional(),
+        /** renderIcon name (e.g. 'book-open') or a safe URL — the icon NAME
+         *  list is renderIcon's own vocabulary, never restated here; unknown
+         *  names warn loudly at DEV runtime. */
+        icon: z.string().min(1).optional()
+      }).strict()
+    ).optional()
+  }).strict().optional(),
+  // Capability vocabulary, widened one field at a time by later tasks.
+  capabilities: z.object({
+    /** Starter prompts shown on the empty thread; clicking one sends it.
+     *  1-6 non-empty strings — construct-authored text, escaped like
+     *  `theme.accent`/`provider.url` at every emit interpolation site. */
+    starters: z.array(z.string().min(1)).min(1).max(6).optional(),
+    /** Enables the paperclip attach affordance; accept is a non-empty
+     *  list of media types/globs, e.g. ["image/*", "application/pdf"] —
+     *  WHETHER stays with the construct author (this field), HOW stays
+     *  with the kit (ChatThread's own attach/accept props, threaded
+     *  through by codegen). */
+    attachments: z.object({
+      /** Accept-list of media types/globs, e.g. ["image/*", "application/pdf"]. */
+      accept: z.array(z.string().min(1)).min(1)
+    }).strict().optional(),
+    /** Conversation persistence. `none` (default, nothing emitted): the
+     *  thread lives only in memory for the tab's lifetime. `local`:
+     *  persisted to this browser's localStorage, keyed by the construct's
+     *  tag — a mechanism decision (WHERE); what to retain and for how
+     *  long stays an app decision (component-scope-boundary), so no
+     *  retention count/quota lands here. `endpoint`: the CONSUMER's own
+     *  thread route (GET returns ChatMessage[], PUT stores them) —
+     *  requires `url`; `url` is rejected for any other persistence
+     *  (superRefine below, both directions loud). */
+    history: z.object({
+      persistence: z.enum(["none", "local", "endpoint"]),
+      /** endpoint persistence only: the CONSUMER's thread routes (GET returns
+       *  ChatMessage[], PUT stores them). Refined below. */
+      url: z.string().min(1).optional()
+    }).strict().optional(),
+    /** How the model's thinking (reasoning parts) renders. `'full'`
+     *  (the default when omitted — see codegen.ts's emitReasoningProp)
+     *  is the collapsible "Thinking" disclosure, shimmering while it
+     *  streams. `'compact'` shows only a shimmer/typing loader while
+     *  reasoning streams, with no expandable detail. `'off'` hides
+     *  reasoning entirely. This is HOW an existing medium fact (the
+     *  model's thinking) displays — the kit's call — so it maps straight
+     *  onto ChatThread's own `reasoning` prop; there is no app-layer
+     *  quota or retention decision hiding in it. Left `.optional()`
+     *  rather than `.default('full')`, matching every sibling field in
+     *  this object: a zod `.default()` here would make `reasoning`
+     *  REQUIRED on the inferred input type (z.infer is the output type),
+     *  breaking every `capabilities: {...}` object literal in this file
+     *  and its tests that doesn't mention it. */
+    reasoning: z.enum(["full", "compact", "off"]).optional(),
+    /** Seeds the reasoning disclosure open AND keeps it tracking the
+     *  stream (open while streaming, closes when it settles) — the
+     *  pre-Task-19f `full` behavior. Default false/absent: the panel
+     *  starts closed (just the "Thinking" shimmer chip) and only opens
+     *  on click — the current default (owner ruling, 2026-08-26).
+     *  Meaningless when `reasoning` is `'compact'` (no expandable
+     *  content exists) or `'off'` (nothing renders); rejected on both,
+     *  loudly, below. */
+    reasoningOpen: z.boolean().optional(),
+    /** Turns on the prior-conversations list (C-1..C-9 of the
+     *  conversations design). `true` only — there is no `false` form,
+     *  matching this schema's other presence-only capability flags.
+     *  Requires `capabilities.history.persistence` to be `local` or
+     *  `endpoint` (superRefine below, loud): a conversation list with
+     *  nowhere to persist conversations is not a coherent construct.
+     *  WHAT persists (this field, plus history) stays construct
+     *  vocabulary; HOW it persists (the ConversationStore adapter,
+     *  localStorage vs. a fetch endpoint) is codegen's call, never
+     *  vocabulary here (C-3 — no transport-layer vocabulary). */
+    conversations: z.literal(true).optional()
+  }).strict().optional(),
+  /** Named generative-UI card definitions the model can emit as tool calls,
+   *  rendered in the thread. Top-level (not a capability): a card is
+   *  something the construct's model can DO at any point once a card is
+   *  declared, not a thread-affordance toggle like starters/attachments/
+   *  reasoning. Reuses the kit's own card-tool projection end to end
+   *  (`cardTools`/`toOpenAITools`/`toAnthropicTools`, `@kitn.ai/ui/schemas`)
+   *  — never a second one authored here. `schema` is validated structurally
+   *  only; deep card validation (incl. `x-kai-format` mask hints) is the
+   *  kit's own card contract at render time. */
+  cards: z.array(
+    z.object({
+      /** Tool-facing card name, e.g. "refund_approval". */
+      name: z.string().regex(/^[a-z][a-z0-9_]*$/),
+      /** The kit's card schema JSON (incl. x-kai-format mask hints).
+       *  Validated structurally here; deep card validation is the kit's
+       *  own card contract at render time. */
+      schema: z.record(z.string(), z.unknown())
+    }).strict()
+  ).min(1).optional(),
+  /** Named `<slot>` projection points the emitted web component exposes —
+   *  the format's ONLY escape hatch (named slots, no code-in-JSON). Each
+   *  name must be a valid HTML slot-attribute value AND a legible
+   *  identifier: kebab-case, starting with a letter (the same shape as a
+   *  CSS custom-ident) — `slot name="Header!"` is rejected, not sanitized,
+   *  matching the format's loud-rejection discipline everywhere else.
+   *  1-8 entries, no duplicates (superRefine below — a regex alone can't
+   *  see across array entries). `layout: 'custom'` requires at least one
+   *  declared slot (superRefine below): `custom` IS the slots grain — a
+   *  `custom` layout with nothing to project into is not meaningfully
+   *  different from `fullscreen`. */
+  slots: z.array(z.string().regex(/^[a-z][a-z0-9-]*$/, "slot names must be kebab-case, starting with a letter")).min(1).max(8).optional(),
+  /** Layout-scoped FAB chrome, `layout: 'widget'` only (superRefine below).
+   *  Purely additive sibling to `layout` (widen-never-restructure) — mirrors
+   *  Dock's own props verbatim, threaded through by codegen's emitLayoutOpen. */
+  widget: z.object({
+    /** Which corner. Mirrors Dock's own DockPosition enum verbatim — not a
+     *  new left/right binary. Omitted keeps Dock's own default (bottom-end). */
+    position: z.enum(["bottom-end", "bottom-start", "top-end", "top-start"]).optional(),
+    /** An image URL for the closed-state launcher glyph, replacing Dock's
+     *  built-in chat-bubble icon. Construct-authored/untrusted text, like
+     *  theme.accent and provider.url — escaped the same way at its one emit site. */
+    launcherIcon: z.string().min(1).optional(),
+    /** Seed Dock's open state at mount. Uncontrolled — never steals focus (Dock's
+     *  own focus contract, dock.tsx). Omitted keeps Dock's own default (closed). */
+    defaultOpen: z.boolean().optional()
+  }).strict().optional()
+}).strict().superRefine((construct, ctx) => {
+  if (construct.slots) {
+    const seen = /* @__PURE__ */ new Set();
+    construct.slots.forEach((name, i) => {
+      if (seen.has(name)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["slots", i],
+          message: `duplicate slot name "${name}"`
+        });
+      }
+      seen.add(name);
+    });
+  }
+  if (construct.layout === "custom" && (!construct.slots || construct.slots.length === 0)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["slots"],
+      message: '"custom" layout requires at least one declared slot — custom IS the slots grain'
+    });
+  }
+  if (construct.layout === "split" && construct.slots) {
+    const i = construct.slots.indexOf("pane");
+    if (i !== -1) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["slots", i],
+        message: `"pane" collides with the "split" layout's own fixed <slot name="pane"> — choose a different slot name`
+      });
+    }
+  }
+  if (construct.widget && construct.layout !== "widget") {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["widget"],
+      message: '"widget" is only valid on layout: "widget"'
+    });
+  }
+  if (construct.widget?.launcherIcon && !isSafeUrl(construct.widget.launcherIcon)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["widget", "launcherIcon"],
+      message: "launcherIcon must be an http(s)/mailto or relative URL — no javascript:/data: schemes"
+    });
+  }
+  if (construct.empty?.icon && !isSafeUrl(construct.empty.icon)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["empty", "icon"],
+      message: "icon must be an http(s)/mailto or relative URL — no javascript:/data: schemes"
+    });
+  }
+  const reasoning = construct.capabilities?.reasoning;
+  const reasoningOpen = construct.capabilities?.reasoningOpen;
+  if (reasoningOpen !== void 0 && (reasoning === "compact" || reasoning === "off")) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["capabilities", "reasoningOpen"],
+      message: '"reasoningOpen" only applies when reasoning is "full" or omitted — "compact"/"off" have no disclosure to open'
+    });
+  }
+  const history = construct.capabilities?.history;
+  if (construct.capabilities?.conversations && (!history || history.persistence === "none")) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["capabilities", "conversations"],
+      message: '"conversations" requires capabilities.history.persistence to be "local" or "endpoint" — a conversation list needs somewhere to persist conversations'
+    });
+  }
+  const URL_SHAPED = /^[a-zA-Z][a-zA-Z0-9+.-]*:|^\/\//;
+  for (const [i, link] of (construct.home?.links ?? []).entries()) {
+    if (link.href && !isSafeUrl(link.href)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["home", "links", i, "href"],
+        message: "href must be an http(s)/mailto or relative URL — no javascript:/data: schemes"
+      });
+    }
+    if (link.icon && URL_SHAPED.test(link.icon) && !isSafeUrl(link.icon)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["home", "links", i, "icon"],
+        message: "icon must be a kit icon name or an http(s)/relative URL — no javascript:/data: schemes"
+      });
+    }
+  }
+  if (!history) return;
+  if (history.persistence === "endpoint" && !history.url) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["capabilities", "history", "url"],
+      message: '"endpoint" persistence requires a url'
+    });
+  }
+  if (history.persistence !== "endpoint" && history.url !== void 0) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["capabilities", "history", "url"],
+      message: 'url is only valid with "endpoint" persistence'
+    });
+  }
+});
+function validateConstruct(input) {
+  const parsed = ConstructSchema.safeParse(input);
+  if (parsed.success) return { ok: true, construct: parsed.data };
+  return {
+    ok: false,
+    problems: parsed.error.issues.flatMap((issue) => {
+      if (issue.code === "unrecognized_keys") {
+        return issue.keys.map((key) => ({
+          path: [...issue.path.map(String), key].join("."),
+          message: `"${key}" is not construct vocabulary`
+        }));
+      }
+      return [
+        {
+          path: issue.path.map(String).join("."),
+          message: issue.message
+        }
+      ];
+    })
+  };
+}
+function kitVersion() {
+  const require2 = createRequire(import.meta.url);
+  const pkg = require2("@kitn.ai/ui/package.json");
+  return pkg.version;
+}
+const themeMode = (c) => c.theme?.mode === "light" ? "light" : c.theme?.mode === "dark" ? "dark" : "auto";
+function srgbChannelToLinear(c) {
+  const cs = c / 255;
+  return cs <= 0.03928 ? cs / 12.92 : Math.pow((cs + 0.055) / 1.055, 2.4);
+}
+function relativeLuminance(r, g, b) {
+  return 0.2126 * srgbChannelToLinear(r) + 0.7152 * srgbChannelToLinear(g) + 0.0722 * srgbChannelToLinear(b);
+}
+function hslToRgb(h, s, l) {
+  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)];
+}
+function parseAccentRgb(accent) {
+  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;
+}
+function resolveContrastForeground(accent) {
+  const rgb = parseAccentRgb(accent);
+  if (!rgb) return null;
+  const luminance = relativeLuminance(...rgb);
+  return luminance <= 0.5 ? "#ffffff" : "#000000";
+}
+function commentSafe(text) {
+  return text.replace(/[\r\n]/g, " ").replace(/\*\//g, "* /");
+}
+const CONTRAST_COLOR_SUPPORTS = "@supports (color: contrast-color(red))";
+function accentContrastNotice(construct) {
+  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`;
+}
+function generateProject(construct, opts = {}) {
+  const uiSpec = opts.uiSpec ?? `^${kitVersion()}`;
+  const files = [
+    { 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;
+}
+function emitCardsRegistry(cards) {
+  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;
+`;
+}
+function emitCardComponentImport(c) {
+  return c.cards ? ", BUILTIN_CARD_COMPONENTS" : "";
+}
+function emitCardsImport(c) {
+  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 } };
+}`;
+}
+function emitCardTypesProp(c) {
+  return c.cards ? " cardTypes={cardTypes}" : "";
+}
+function emitApplyCardTools(c) {
+  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 });
+      }
+    }`;
+}
+function emitToolsField(c) {
+  if (!c.cards || c.provider.mode !== "endpoint") return "";
+  const toolsFn = c.provider.wire === "openai" ? "toOpenAITools" : "toAnthropicTools";
+  return `, tools: ${toolsFn}(cards)`;
+}
+function emitPackageJson(c, uiSpec) {
+  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
+  )}
+`;
+}
+function emitTsconfig() {
+  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
+  )}
+`;
+}
+function emitViteDev() {
+  return `import { defineConfig } from 'vite';
+import solid from 'vite-plugin-solid';
+
+export default defineConfig({ plugins: [solid()] });
+`;
+}
+function emitViteLib(c) {
+  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) {
+  const hint = c.layout === "widget" ? `
+    <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>` : "";
+  const slotDemo = (c.slots ?? []).map(
+    (name) => `
+      <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 ? `
+    <${c.name}>${slotDemo}
+    </${c.name}>` : `
+    <${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) {
+  const accent = c.theme?.accent;
+  const unreadColor = c.theme?.unreadColor;
+  if (!accent && !unreadColor) {
+    const facade2 = "() => <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' }, ${facade2});
+`;
+  }
+  const unreadColorSetProperty = unreadColor ? `
+  ctx.element.style.setProperty('--kai-color-unread', ${JSON.stringify(unreadColor)});` : "";
+  if (!accent) {
+    const facade2 = `(_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' }, ${facade2});
+`;
+  }
+  const foreground = resolveContrastForeground(accent);
+  const foregroundCss = foreground !== null ? `:host { --kai-color-primary-foreground: ${foreground}; }
+` : (
+    // 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. */
+`
+  );
+  const styleText = foregroundCss + `${CONTRAST_COLOR_SUPPORTS} {
+  :host { --kai-color-primary-foreground: contrast-color(var(--kai-color-primary)); }
+}`;
+  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});
+`;
+}
+function emitApp(c) {
+  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)}  );
+}
+`;
+}
+function emitCustomApp(c) {
+  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] : void 0, "      ")}      <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>
+  );
+}
+`;
+}
+function emitHeaderProp(c) {
+  const title = c.header?.title;
+  if (!title) return "";
+  return ` chatTitle={${JSON.stringify(title)}}`;
+}
+function emitEmptyContentProp(c) {
+  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>}`;
+}
+function emitEmptyComponentImport(c) {
+  if (!c.empty) return "";
+  let names = ", Empty, EmptyHeader, EmptyTitle";
+  if (c.empty.icon) names += ", EmptyMedia";
+  if (c.empty.description) names += ", EmptyDescription";
+  return names;
+}
+function widgetHasHeaderClose(c) {
+  return c.layout === "widget" && !!c.header?.title;
+}
+function widgetHasConversationsChrome(c) {
+  return c.layout === "widget" && (!!c.capabilities?.conversations || !!c.home);
+}
+function emitChatControllerVar(c, indent) {
+  return widgetHasConversationsChrome(c) ? `${indent}let chatController: ChatThreadController | undefined;
+` : "";
+}
+function emitChatControllerRefProp(c) {
+  return widgetHasConversationsChrome(c) ? " controllerRef={(api) => (chatController = api)}" : "";
+}
+function emitDockOnOpenChangeProp(c) {
+  return widgetHasConversationsChrome(c) ? " onOpenChange={(open) => { setDockOpen(open); if (!open) chatController?.closeConversationsList(); }}" : "";
+}
+function emitConversationsResetTypeImport(c) {
+  return widgetHasConversationsChrome(c) ? ", ChatThreadController" : "";
+}
+function emitConversationsSignalsImport(c) {
+  return widgetHasConversationsChrome(c) ? `import { createSignal } from 'solid-js';
+` : "";
+}
+function emitConversationsSignalsVar(c, indent) {
+  if (!widgetHasConversationsChrome(c)) return "";
+  const w = c.layout === "widget" ? c.widget : void 0;
+  const defaultOpen = w?.defaultOpen === true ? "true" : "false";
+  return `${indent}const [dockOpen, setDockOpen] = createSignal(${defaultOpen});
+${indent}const [anyUnread, setAnyUnread] = createSignal(false);
+`;
+}
+function emitChatThreadUnreadProps(c) {
+  return widgetHasConversationsChrome(c) ? " hostOpen={dockOpen()} onUnreadChange={setAnyUnread}" : "";
+}
+function emitDockUnreadProp(c) {
+  return widgetHasConversationsChrome(c) ? " unread={anyUnread()}" : "";
+}
+function emitDockCloseVar(c, indent) {
+  return widgetHasHeaderClose(c) ? `${indent}let dockClose: (() => void) | undefined;
+` : "";
+}
+function emitDockControllerRef(c) {
+  return widgetHasHeaderClose(c) ? " controllerRef={(api) => (dockClose = () => api.setOpen(false))}" : "";
+}
+function emitDockHideClose(c) {
+  return widgetHasHeaderClose(c) ? " hideClose={true}" : "";
+}
+function emitHeaderEndContentProp(c) {
+  if (!widgetHasHeaderClose(c)) return "";
+  return ` headerEndContent={<Button variant="ghost" size="icon-sm" aria-label="Close ${c.name}" onClick={() => dockClose?.()}><DockCloseGlyph /></Button>}`;
+}
+function emitHeaderCloseImport(c) {
+  return widgetHasHeaderClose(c) ? ", Button, DockCloseGlyph" : "";
+}
+function emitAttachProps(c) {
+  const attachments = c.capabilities?.attachments;
+  if (!attachments) return " attach={false}";
+  return ` attach={true} accept={${JSON.stringify(attachments.accept.join(","))}}`;
+}
+function emitStartersProp(c) {
+  const starters = c.capabilities?.starters;
+  if (!starters || starters.length === 0) return "";
+  return ` suggestions={${JSON.stringify(starters)}}`;
+}
+function emitReasoningProp(c) {
+  const reasoning = c.capabilities?.reasoning;
+  if (!reasoning || reasoning === "full") return "";
+  return ` reasoning="${reasoning}"`;
+}
+function emitReasoningOpenProp(c) {
+  return c.capabilities?.reasoningOpen === true ? " reasoningOpen={true}" : "";
+}
+function emitHomeProp(c) {
+  if (!c.home) return "";
+  return ` home={${JSON.stringify(c.home)}}`;
+}
+function emitConversationsProps(c) {
+  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)}`;
+}
+function emitConversationsImport(c) {
+  if (!c.capabilities?.conversations) return "";
+  const name = c.capabilities.history?.persistence === "endpoint" ? "fetchStore" : "localStorageStore";
+  return `import { ${name} } from '@kitn.ai/ui/solid';`;
+}
+function emitSolidJsImport(c) {
+  const history = c.capabilities?.history;
+  if (!history || history.persistence === "none" || c.layout !== "custom" && c.capabilities?.conversations) return "";
+  return `import { createEffect } from 'solid-js';
+`;
+}
+function emitHistoryTypeImport(c) {
+  const history = c.capabilities?.history;
+  if (!history || history.persistence === "none" || c.layout !== "custom" && c.capabilities?.conversations) return "";
+  return ", ChatMessage";
+}
+function emitUserIdHeaderEntry(c) {
+  return c.userId ? `, 'x-kai-user-id': ${JSON.stringify(c.userId)}` : "";
+}
+function emitHistorySetup(c) {
+  const history = c.capabilities?.history;
+  if (!history || history.persistence === "none") return "";
+  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) {
+  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) {
+  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";
+  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));
+  }
+}`;
+}
+function emitLayoutImport(c) {
+  switch (c.layout) {
+    case "widget":
+      return `, Dock${hasLauncherIcon(c) ? ", DockLauncherImage" : ""}`;
+    case "split":
+      return ", WorkspaceShell";
+    case "fullscreen":
+    case "aside":
+      return "";
+    case "custom":
+      return "";
+  }
+}
+function emitSlots(slots, indent) {
+  if (!slots || slots.length === 0) return "";
+  return slots.map((name) => `${indent}<slot name="${name}" />
+`).join("");
+}
+function emitDockPosition(c) {
+  const w = c.layout === "widget" ? c.widget : void 0;
+  return w?.position ? ` position="${w.position}"` : "";
+}
+function hasLauncherIcon(c) {
+  return c.layout === "widget" && !!c.widget?.launcherIcon;
+}
+function emitDockLauncher(c) {
+  const w = c.layout === "widget" ? c.widget : void 0;
+  if (!w?.launcherIcon) return "";
+  return ` launcher={<DockLauncherImage src={${JSON.stringify(w.launcherIcon)}} />}`;
+}
+function emitDockDefaultOpen(c) {
+  const w = c.layout === "widget" ? c.widget : void 0;
+  return w?.defaultOpen === true ? " defaultOpen={true}" : "";
+}
+function emitLayoutOpen(c) {
+  switch (c.layout) {
+    case "widget":
+      return `    <Dock label="${c.name}"${emitDockPosition(c)}${emitDockLauncher(c)}${emitDockDefaultOpen(c)}${emitDockHideClose(c)}${emitDockControllerRef(c)}${emitDockOnOpenChangeProp(c)}${emitDockUnreadProp(c)}>
+`;
+    case "fullscreen":
+      return `    <div style={{ height: '100dvh', display: 'flex', 'flex-direction': 'column' }}>
+`;
+    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":
+      return `    <div style={{ height: '100dvh' }}>
+      <WorkspaceShell class="h-full" drawerBelow={480} end={
+        <div style={{ height: '100%', overflow: 'auto' }}>
+          <slot name="pane" />
+        </div>
+      }>
+`;
+    case "custom":
+      return "";
+  }
+}
+function emitLayoutClose(c) {
+  switch (c.layout) {
+    case "widget":
+      return `    </Dock>
+`;
+    case "fullscreen":
+      return `    </div>
+`;
+    case "aside":
+      return `    </aside>
+`;
+    case "split":
+      return `      </WorkspaceShell>
+    </div>
+`;
+    case "custom":
+      return "";
+  }
+}
+function emitTypes(c) {
+  return `declare global {
+  interface HTMLElementTagNameMap {
+    '${c.name}': HTMLElement & { theme: 'light' | 'dark' | 'auto' };
+  }
+}
+export {};
+`;
+}
+const MANIFEST = ".kai-manifest.json";
+function writeProject(files, dir) {
+  const manifestPath = join(dir, MANIFEST);
+  const previous = existsSync(manifestPath) ? JSON.parse(readFileSync(manifestPath, "utf8")) : [];
+  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 = [];
+  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)}
+`);
+  return overwritten;
+}
+const defaultIo = { log: (s) => console.log(s), error: (s) => console.error(s) };
+const USAGE = `usage: kai <command>
+
+  kai validate <construct.json>          check a construct, print problems with paths
+  kai eject <construct.json> <outDir>    write the generated Solid project (it's yours)
+  kai dev <construct.json>               live preview with reload-on-edit (Task 5)
+  kai compile <construct.json> [outDir]  one self-registering .js (Task 6)
+`;
+function homeRecentConversationWarning(construct) {
+  if (construct.home?.recentConversation && !construct.capabilities?.conversations) {
+    return "warning: home.recentConversation is set but capabilities.conversations is not — the recent-conversation card will render nothing without it.";
+  }
+  return null;
+}
+function loadConstruct(path, io) {
+  const abs = resolve(path);
+  let raw;
+  try {
+    raw = readFileSync(abs, "utf8");
+  } catch {
+    io.error(`cannot read ${abs}`);
+    return null;
+  }
+  let json;
+  try {
+    json = JSON.parse(raw);
+  } catch (err) {
+    io.error(`${abs} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    return null;
+  }
+  const out = validateConstruct(json);
+  if (!out.ok) {
+    io.error(`${abs} is not a valid construct:`);
+    for (const p of out.problems) io.error(`  ${p.path || "(root)"}: ${p.message}`);
+    return null;
+  }
+  return out.construct;
+}
+function parseUiFlag(rest) {
+  const uiFlag = rest.indexOf("--ui");
+  const uiSpec = uiFlag >= 0 ? rest[uiFlag + 1] : void 0;
+  const positional = uiFlag >= 0 ? rest.filter((_, i) => i !== uiFlag && i !== uiFlag + 1) : rest;
+  return { uiSpec, positional };
+}
+async function runCli(argv, io = defaultIo) {
+  const [command, ...rest] = argv;
+  switch (command) {
+    case "validate": {
+      const construct = loadConstruct(rest[0] ?? "", io);
+      if (!construct) return 1;
+      io.log(`valid construct: <${construct.name}> (layout: ${construct.layout}, provider: ${construct.provider.mode})`);
+      const warning = homeRecentConversationWarning(construct);
+      if (warning) io.log(warning);
+      return 0;
+    }
+    case "eject": {
+      const { uiSpec, positional } = parseUiFlag(rest);
+      const [path, outDir] = positional;
+      if (!path || !outDir) {
+        io.error(USAGE);
+        return 2;
+      }
+      const construct = loadConstruct(path, io);
+      if (!construct) return 1;
+      const overwritten = writeProject(generateProject(construct, { uiSpec }), resolve(outDir));
+      if (overwritten.length > 0) {
+        io.log(`overwriting ${overwritten.length} existing file(s)`);
+      }
+      const notice = accentContrastNotice(construct);
+      if (notice) io.log(notice);
+      io.log(`ejected <${construct.name}> to ${resolve(outDir)} — npm install && npm run dev. The source is yours.`);
+      return 0;
+    }
+    case "dev": {
+      const { uiSpec, positional } = parseUiFlag(rest);
+      const path = positional[0];
+      if (!path) {
+        io.error(USAGE);
+        return 2;
+      }
+      const { dev } = await import("./assets/dev-5XzXYR21.js");
+      await dev(path, { io, uiSpec });
+      return 0;
+    }
+    case "compile": {
+      const { uiSpec, positional } = parseUiFlag(rest);
+      const [path, outArg] = positional;
+      if (!path) {
+        io.error(USAGE);
+        return 2;
+      }
+      const construct = loadConstruct(path, io);
+      if (!construct) return 1;
+      const outDir = resolve(outArg ?? "dist-construct");
+      const { workDirFor, ensureInstalled } = await import("./assets/dev-5XzXYR21.js");
+      const dir = workDirFor(construct.name, process.cwd());
+      const files = generateProject(construct, { uiSpec });
+      writeProject(files, dir);
+      await ensureInstalled(dir, files, io);
+      await new Promise((done, fail) => {
+        const child = spawn("npm", ["run", "build"], { cwd: dir, stdio: "inherit" });
+        child.on("exit", (code) => code === 0 ? done() : fail(new Error(`vite build exited ${code}`)));
+      });
+      mkdirSync(outDir, { recursive: true });
+      copyFileSync(join(dir, "dist", `${construct.name}.js`), join(outDir, `${construct.name}.js`));
+      writeFileSync(join(outDir, `${construct.name}.d.ts`), emitTypes(construct));
+      writeProject(files, join(outDir, "source"));
+      io.log(`compiled <${construct.name}> → ${outDir}/${construct.name}.js (source beside it in source/).`);
+      io.log(`endpoint backends: the kai MCP scaffold tool emits a matching route — see its output for your framework.`);
+      return 0;
+    }
+    default:
+      io.error(USAGE);
+      return 2;
+  }
+}
+runCli(process.argv.slice(2)).then((code) => {
+  process.exitCode = code;
+});
+export {
+  accentContrastNotice as a,
+  generateProject as g,
+  validateConstruct as v,
+  writeProject as w
+};