@kitn.ai/ui 0.30.0 → 0.31.0

package/dist/construct-cli.es.js

@@ -15,7 +15,14 @@ function isSafeUrl(url) {
   const scheme = schemeOf(url);
   return scheme !== void 0 && SAFE_SCHEMES.includes(scheme);
 }
+const CHAT_MESSAGE_ACTIONS = ["copy", "like", "dislike", "regenerate", "edit", "speak"];
+const BUTTON_VARIANT_NAMES = ["default", "ghost", "subtle", "outline", "destructive"];
 const TAG_RE = /^[a-z][a-z0-9]*-[a-z0-9-]+$/;
+const TriggerEntrySchema = z.object({
+  id: z.string().min(1),
+  label: z.string().min(1),
+  description: z.string().min(1).optional()
+}).strict();
 const ProviderSchema = z.discriminatedUnion("mode", [
   z.object({ mode: z.literal("mock") }).strict(),
   z.object({
@@ -84,7 +91,26 @@ const ConstructSchema = 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()
+    title: z.string().min(1).optional(),
+    /** Renders a theme-toggle Button in ChatThread's header-end region,
+     *  flipping the host's `theme` attribute (the attribute
+     *  defineWebComponent already owns) via the facade's ctx.element —
+     *  codegen work, no new kit surface (B-10). */
+    themeToggle: z.boolean().optional(),
+    /** Header action buttons (label + kit Button variant), rendered in
+     *  the header-end region. Vocabulary-never-logic: the construct
+     *  cannot say what an action DOES, so each click dispatches a
+     *  non-bubbling `kai-header-action` CustomEvent on the host with
+     *  `detail: { label }` — the consumer's listening seam (B-10).
+     *  `variant` derives from the kit Button's own list
+     *  (BUTTON_VARIANT_NAMES — B-6a), never restated. `label` is
+     *  construct-authored untrusted text, JSON.stringify'd at emit. */
+    actions: z.array(
+      z.object({
+        label: z.string().min(1),
+        variant: z.enum(BUTTON_VARIANT_NAMES).optional()
+      }).strict()
+    ).min(1).optional()
   }).strict().optional(),
   /** Greeting shown while the thread is empty (no messages yet) — the
    *  proven "welcome screen" pattern (Intercom-class): title + optional
@@ -193,7 +219,28 @@ const ConstructSchema = z.object({
      *  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()
+    conversations: z.literal(true).optional(),
+    /** Role-scoped default action bars, threaded onto ChatThread's
+     *  `userActions`/`assistantActions` props (B-3/B-7b). Ordered
+     *  arrays; enum ids ONLY, read off the ONE const
+     *  (CHAT_MESSAGE_ACTIONS — B-6): a CustomAction is an id the APP
+     *  must handle, a construct has no app code, so emitting one is a
+     *  dead affordance. Duplicates within one array rejected below
+     *  (superRefine, the slots pattern). min(1): an empty list IS the
+     *  absent key. */
+    messageActions: z.object({
+      user: z.array(z.enum(CHAT_MESSAGE_ACTIONS)).min(1).optional(),
+      assistant: z.array(z.enum(CHAT_MESSAGE_ACTIONS)).min(1).optional()
+    }).strict().optional(),
+    /** The citations STRIP (the `part="citations"` row consecutive
+     *  `source` parts already collapse into — message.tsx). `strip:
+     *  false` hides it (emits ChatThread's `hideSources`); `strip:
+     *  true` or the key absent emits NOTHING — the row already renders,
+     *  the kit default IS the on state, the same anchored-on-the-
+     *  default convention as `reasoning: 'full'` (B-4). */
+    sources: z.object({
+      strip: z.boolean().optional()
+    }).strict().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
@@ -240,109 +287,245 @@ const ConstructSchema = z.object({
     /** 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(),
+  /** Layout-scoped aside geometry, `layout: 'aside'` only (superRefine
+   *  below, mirroring `widget`'s scoping exactly). `position` picks the
+   *  docked inline edge (default 'end', today's hardcoded behavior);
+   *  `width` overrides codegen's 380px default. `width` is construct-
+   *  authored untrusted text: it lands as a JSON.stringify'd VALUE inside
+   *  the emitted Solid `style={{ }}` object — property assignment, the
+   *  same no-CSS-text-interpolation guarantee as setProperty — never
+   *  concatenated into a CSS string (B-2). */
+  aside: z.object({
+    position: z.enum(["start", "end"]).optional(),
+    width: z.string().min(1).optional()
+  }).strict().optional(),
+  /** Construct-wide shell chrome (10a): both members reuse REAL kit
+   *  pieces — command.tsx's CommandList behind a codegen-emitted overlay
+   *  (opened on Mod+K; entries DERIVE from what this construct enables —
+   *  menu-honesty against dead entries), and the documented Dropdown+
+   *  Avatar user-menu recipe. `name`/`plan` are construct-authored
+   *  untrusted text, JSON.stringify'd at emit like every sibling.
+   *  `commandPalette` is presence-only `z.literal(true)`, matching
+   *  `conversations`' pattern. */
+  shell: z.object({
+    commandPalette: z.literal(true).optional(),
+    userMenu: z.object({
+      name: z.string().min(1),
+      plan: z.string().min(1).optional()
+    }).strict().optional()
+  }).strict().optional(),
+  /** Composer chrome — NOT a capability: chrome on the medium, like
+   *  `header` (B-5). `triggers` maps onto ChatThread's real, shipped
+   *  `triggers` prop: `slash` → `{ char: '/', kind: 'command', items }`,
+   *  `mention` → `{ char: '@', kind: 'mention', items }` at emit. */
+  composer: z.object({
+    triggers: z.object({
+      slash: z.array(TriggerEntrySchema).min(1).optional(),
+      mention: z.array(TriggerEntrySchema).min(1).optional()
+    }).strict().optional()
   }).strict().optional()
 }).strict().superRefine((construct, ctx) => {
-  if (construct.slots) {
-    const seen = /* @__PURE__ */ new Set();
-    construct.slots.forEach((name, i) => {
-      if (seen.has(name)) {
+  for (const rule of CROSS_FIELD_RULES) rule.check(construct, ctx);
+});
+const CROSS_FIELD_RULES = [
+  {
+    id: "slots-unique",
+    paths: ["slots"],
+    check: (construct, ctx) => {
+      if (!construct.slots) return;
+      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);
+      });
+    }
+  },
+  {
+    id: "custom-layout-needs-slots",
+    paths: ["layout", "slots"],
+    check: (construct, ctx) => {
+      if (construct.layout === "custom" && (!construct.slots || construct.slots.length === 0)) {
         ctx.addIssue({
           code: z.ZodIssueCode.custom,
-          path: ["slots", i],
-          message: `duplicate slot name "${name}"`
+          path: ["slots"],
+          message: '"custom" layout requires at least one declared slot — custom IS the slots grain'
         });
       }
-      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"
-      });
+  },
+  {
+    id: "split-pane-slot-collision",
+    paths: ["layout", "slots"],
+    check: (construct, ctx) => {
+      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 (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"
-      });
+  },
+  {
+    id: "widget-layout-scope",
+    paths: ["layout", "widget"],
+    check: (construct, ctx) => {
+      if (construct.widget && construct.layout !== "widget") {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["widget"],
+          message: '"widget" is only valid on layout: "widget"'
+        });
+      }
+    }
+  },
+  {
+    id: "aside-layout-scope",
+    paths: ["layout", "aside"],
+    check: (construct, ctx) => {
+      if (construct.aside && construct.layout !== "aside") {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["aside"],
+          message: '"aside" is only valid on layout: "aside"'
+        });
+      }
+    }
+  },
+  {
+    id: "message-actions-unique",
+    paths: ["capabilities.messageActions.user", "capabilities.messageActions.assistant"],
+    check: (construct, ctx) => {
+      const messageActions = construct.capabilities?.messageActions;
+      if (!messageActions) return;
+      for (const role of ["user", "assistant"]) {
+        const list = messageActions[role];
+        if (!list) continue;
+        const seen = /* @__PURE__ */ new Set();
+        list.forEach((id, i) => {
+          if (seen.has(id)) {
+            ctx.addIssue({
+              code: z.ZodIssueCode.custom,
+              path: ["capabilities", "messageActions", role, i],
+              message: `duplicate action id "${id}"`
+            });
+          }
+          seen.add(id);
+        });
+      }
+    }
+  },
+  {
+    id: "launcher-icon-url",
+    paths: ["widget.launcherIcon"],
+    check: (construct, ctx) => {
+      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"
+        });
+      }
+    }
+  },
+  {
+    id: "empty-icon-url",
+    paths: ["empty.icon"],
+    check: (construct, ctx) => {
+      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"
+        });
+      }
+    }
+  },
+  {
+    id: "reasoning-open-scope",
+    paths: ["capabilities.reasoning", "capabilities.reasoningOpen"],
+    check: (construct, ctx) => {
+      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'
+        });
+      }
+    }
+  },
+  {
+    id: "conversations-need-history",
+    paths: ["capabilities.conversations", "capabilities.history"],
+    check: (construct, ctx) => {
+      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'
+        });
+      }
+    }
+  },
+  {
+    id: "home-link-urls",
+    paths: ["home.links"],
+    check: (construct, ctx) => {
+      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"
+          });
+        }
+      }
+    }
+  },
+  {
+    id: "history-endpoint-url",
+    paths: ["capabilities.history.persistence", "capabilities.history.url"],
+    check: (construct, ctx) => {
+      const history = construct.capabilities?.history;
+      if (!history) return;
+      if (history.persistence === "endpoint" && !history.url) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["capabilities", "history", "url"],
+          message: '"endpoint" persistence requires a url'
+        });
+      }
+      if (history.persistence !== "endpoint" && history.url !== void 0) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["capabilities", "history", "url"],
+          message: 'url is only valid with "endpoint" persistence'
+        });
+      }
     }
   }
-  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 };
@@ -639,8 +822,12 @@ function emitIndexHtml(c) {
 function emitElement(c) {
   const accent = c.theme?.accent;
   const unreadColor = c.theme?.unreadColor;
+  const usesCtx = !!accent || !!unreadColor || needsHost(c);
+  const appJsx = needsHost(c) ? "<App host={ctx.element} />" : "<App />";
   if (!accent && !unreadColor) {
-    const facade2 = "() => <App />";
+    const facade2 = usesCtx ? `(_props, ctx) => {
+  return ${appJsx};
+}` : "() => <App />";
     return `import { defineWebComponent } from '@kitn.ai/ui/define';
 import { App } from './App';
 
@@ -653,7 +840,7 @@ defineWebComponent('${c.name}', { theme: '${themeMode(c)}' as 'light' | 'dark' |
   ctx.element.style.setProperty('--kai-color-unread', ${JSON.stringify(unreadColor)});` : "";
   if (!accent) {
     const facade2 = `(_props, ctx) => {${unreadColorSetProperty}
-  return <App />;
+  return ${appJsx};
 }`;
     return `import { defineWebComponent } from '@kitn.ai/ui/define';
 import { App } from './App';
@@ -682,7 +869,7 @@ defineWebComponent('${c.name}', { theme: '${themeMode(c)}' as 'light' | 'dark' |
   return (
     <>
       <style>{${JSON.stringify(styleText)}}</style>
-      <App />
+      ${appJsx}
     </>
   );
 }`;
@@ -696,7 +883,7 @@ defineWebComponent('${c.name}', { theme: '${themeMode(c)}' as 'light' | 'dark' |
 }
 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';
+  return `${emitSolidJsImports(c)}import { ChatThread, createKaiChat${emitLayoutImport(c)}${emitCardComponentImport(c)}${emitEmptyComponentImport(c)}${emitChromeImports(c)} } from '@kitn.ai/ui/solid';
 import type { AttachmentData${emitHistoryTypeImport(c)}${emitConversationsResetTypeImport(c)} } from '@kitn.ai/ui/solid';
 ${emitProviderImports(c)}
 ${emitCardsImport(c)}
@@ -786,10 +973,10 @@ ${emitHistorySetup(c)}
 //     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)}  );
+${emitChromeComment(c)}export function App(${needsHost(c) ? "props: { host: HTMLElement }" : ""}) {
+${emitToggleThemeVar(c, "  ")}${emitDockCloseVar(c, "  ")}${emitChatControllerVar(c, "  ")}${emitConversationsSignalsVar(c, "  ")}${emitShellPaletteVars(c, "  ")}  return (
+${hasShellPalette(c) ? "    <>\n" : ""}${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)}${emitMessageActionsProps(c)}${emitHideSourcesProp(c)}${emitTriggersProp(c)}${emitEmptyContentProp(c)}${emitCardTypesProp(c)}${emitHomeProp(c)}${emitConversationsProps(c)}${emitChatControllerRefProp(c)}${emitChatThreadUnreadProps(c)} />
+${emitLayoutClose(c)}${emitShellPaletteOverlay(c)}${hasShellPalette(c) ? "    </>\n" : ""}  );
 }
 `;
 }
@@ -811,7 +998,8 @@ ${emitHistorySetup(c)}
 // 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
+// conversations, header.themeToggle/actions, composer.triggers, shell) 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() {
@@ -867,22 +1055,68 @@ function widgetHasHeaderClose(c) {
 function widgetHasConversationsChrome(c) {
   return c.layout === "widget" && (!!c.capabilities?.conversations || !!c.home);
 }
+function hasShellPalette(c) {
+  return c.layout !== "custom" && c.shell?.commandPalette === true;
+}
+function emitShellPaletteVars(c, indent) {
+  if (!hasShellPalette(c)) return "";
+  const entries = [
+    `{ id: 'focus-composer', label: 'Focus composer' }`,
+    ...c.capabilities?.conversations ? [`{ id: 'new-conversation', label: 'New conversation' }`] : [],
+    ...c.header?.themeToggle ? [`{ id: 'toggle-theme', label: 'Toggle theme' }`] : []
+  ];
+  const newConversationLine = c.capabilities?.conversations ? `
+${indent}  if (id === 'new-conversation') chatController?.startNewConversation();` : "";
+  const toggleThemeLine = c.header?.themeToggle ? `
+${indent}  if (id === 'toggle-theme') toggleTheme();` : "";
+  return `${indent}// Command palette (shell.commandPalette): Mod+K toggles; Escape/backdrop
+${indent}// close; entries DERIVE from what this construct enables — no dead rows.
+${indent}const [paletteOpen, setPaletteOpen] = createSignal(false);
+${indent}const [paletteQuery, setPaletteQuery] = createSignal('');
+${indent}const PALETTE_COMMANDS = [${entries.join(", ")}];
+${indent}const paletteGroups = () => {
+${indent}  const q = paletteQuery().trim().toLowerCase();
+${indent}  const items = q ? PALETTE_COMMANDS.filter((i) => i.label.toLowerCase().includes(q)) : PALETTE_COMMANDS;
+${indent}  return [{ items }];
+${indent}};
+${indent}const runPaletteCommand = (id: string) => {
+${indent}  setPaletteOpen(false);
+${indent}  if (id === 'focus-composer') chatController?.focus();${newConversationLine}${toggleThemeLine}
+${indent}};
+${indent}onMount(() => {
+${indent}  const onKey = (e: KeyboardEvent) => {
+${indent}    if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'k') { e.preventDefault(); setPaletteOpen((v) => !v); }
+${indent}    if (e.key === 'Escape') setPaletteOpen(false);
+${indent}  };
+${indent}  window.addEventListener('keydown', onKey);
+${indent}  onCleanup(() => window.removeEventListener('keydown', onKey));
+${indent}});
+`;
+}
+function emitShellPaletteOverlay(c) {
+  if (!hasShellPalette(c)) return "";
+  return `    <Show when={paletteOpen()}>
+      <div style={{ position: 'fixed', inset: '0', 'z-index': '50', display: 'flex', 'align-items': 'flex-start', 'justify-content': 'center', 'padding-block-start': '14vh', background: 'rgb(0 0 0 / 0.5)' }} onClick={() => setPaletteOpen(false)}>
+        <div style={{ width: '100%', 'max-width': '32rem', overflow: 'hidden', 'border-radius': '0.75rem', border: '1px solid var(--color-border)', background: 'var(--color-popover)' }} onClick={(e) => e.stopPropagation()}>
+          <Input value={paletteQuery()} onValueInput={setPaletteQuery} placeholder="Search commands..." autofocus />
+          <CommandList groups={paletteGroups()} onSelect={runPaletteCommand} />
+        </div>
+      </div>
+    </Show>
+`;
+}
 function emitChatControllerVar(c, indent) {
-  return widgetHasConversationsChrome(c) ? `${indent}let chatController: ChatThreadController | undefined;
+  return widgetHasConversationsChrome(c) || hasShellPalette(c) ? `${indent}let chatController: ChatThreadController | undefined;
 ` : "";
 }
 function emitChatControllerRefProp(c) {
-  return widgetHasConversationsChrome(c) ? " controllerRef={(api) => (chatController = api)}" : "";
+  return widgetHasConversationsChrome(c) || hasShellPalette(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';
-` : "";
+  return widgetHasConversationsChrome(c) || hasShellPalette(c) ? ", ChatThreadController" : "";
 }
 function emitConversationsSignalsVar(c, indent) {
   if (!widgetHasConversationsChrome(c)) return "";
@@ -908,12 +1142,96 @@ function emitDockControllerRef(c) {
 function emitDockHideClose(c) {
   return widgetHasHeaderClose(c) ? " hideClose={true}" : "";
 }
+function emitToggleThemeVar(c, indent) {
+  if (c.layout === "custom" || !c.header?.themeToggle) return "";
+  return `${indent}const toggleTheme = () => props.host.setAttribute('theme', props.host.getAttribute('theme') === 'dark' ? 'light' : 'dark');
+`;
+}
+function hasHeaderActionsChrome(c) {
+  return c.layout !== "custom" && !!c.header?.actions?.length;
+}
+function hasThemeToggleChrome(c) {
+  return c.layout !== "custom" && c.header?.themeToggle === true;
+}
+function hasUserMenuChrome(c) {
+  return c.layout !== "custom" && !!c.shell?.userMenu;
+}
 function emitHeaderEndContentProp(c) {
-  if (!widgetHasHeaderClose(c)) return "";
-  return ` headerEndContent={<Button variant="ghost" size="icon-sm" aria-label="Close ${c.name}" onClick={() => dockClose?.()}><DockCloseGlyph /></Button>}`;
+  const pieces = [];
+  if (hasHeaderActionsChrome(c)) {
+    for (const a of c.header.actions) {
+      const variant = a.variant ? ` variant="${a.variant}"` : "";
+      pieces.push(
+        `<Button${variant} size="sm" onClick={() => props.host.dispatchEvent(new CustomEvent('kai-header-action', { detail: { label: ${JSON.stringify(a.label)} } }))}>{${JSON.stringify(a.label)}}</Button>`
+      );
+    }
+  }
+  if (hasThemeToggleChrome(c)) {
+    pieces.push(`<Button variant="ghost" size="sm" aria-label="Toggle theme" onClick={toggleTheme}>Theme</Button>`);
+  }
+  if (hasUserMenuChrome(c)) {
+    const m = c.shell.userMenu;
+    const menuLabel = JSON.stringify(`${m.name}${m.plan ? ` — ${m.plan}` : ""} account menu`);
+    const initials = JSON.stringify(m.name.slice(0, 2).toUpperCase());
+    const item = (id, label) => `<DropdownItem onSelect={() => props.host.dispatchEvent(new CustomEvent('kai-user-menu', { detail: { item: '${id}' } }))}>${label}</DropdownItem>`;
+    pieces.push(
+      `<Dropdown><DropdownTrigger aria-label={${menuLabel}}><Avatar fallback={${initials}} size="sm" /></DropdownTrigger><DropdownContent>${item("settings", "Settings")}${item("help", "Get help")}<DropdownSeparator />${item("log-out", "Log out")}</DropdownContent></Dropdown>`
+    );
+  }
+  if (widgetHasHeaderClose(c)) {
+    pieces.push(
+      `<Button variant="ghost" size="icon-sm" aria-label="Close ${c.name}" onClick={() => dockClose?.()}><DockCloseGlyph /></Button>`
+    );
+  }
+  if (pieces.length === 0) return "";
+  const content = pieces.length > 1 ? `<>${pieces.join("")}</>` : pieces[0];
+  return ` headerEndContent={${content}}`;
+}
+function emitChromeImports(c) {
+  let names = "";
+  if (hasHeaderActionsChrome(c) || hasThemeToggleChrome(c) || widgetHasHeaderClose(c)) names += ", Button";
+  if (hasUserMenuChrome(c)) {
+    names += ", Dropdown, DropdownTrigger, DropdownContent, DropdownItem, DropdownSeparator, Avatar";
+  }
+  if (hasShellPalette(c)) names += ", CommandList, Input";
+  if (widgetHasHeaderClose(c)) names += ", DockCloseGlyph";
+  return names;
+}
+function emitChromeComment(c) {
+  const lines = [];
+  if (hasHeaderActionsChrome(c)) {
+    lines.push("// header.actions dispatch 'kai-header-action' on the host, detail: { label }.");
+  }
+  if (hasUserMenuChrome(c)) {
+    lines.push("// shell.userMenu dispatches 'kai-user-menu' on the host, detail: { item }.");
+  }
+  if (hasShellPalette(c)) {
+    lines.push("// shell.commandPalette: Mod+K opens the command palette; entries derive from");
+    lines.push("// what this construct enables (menu-honesty — no dead rows).");
+  }
+  return lines.length ? `${lines.join("\n")}
+` : "";
 }
-function emitHeaderCloseImport(c) {
-  return widgetHasHeaderClose(c) ? ", Button, DockCloseGlyph" : "";
+function emitMessageActionsProps(c) {
+  const actions = c.capabilities?.messageActions;
+  if (!actions) return "";
+  let out = "";
+  if (actions.user) out += ` userActions={${JSON.stringify(actions.user)}}`;
+  if (actions.assistant) out += ` assistantActions={${JSON.stringify(actions.assistant)}}`;
+  return out;
+}
+function emitHideSourcesProp(c) {
+  return c.capabilities?.sources?.strip === false ? " hideSources={true}" : "";
+}
+function emitTriggersProp(c) {
+  const triggers = c.composer?.triggers;
+  if (!triggers) return "";
+  const defs = [
+    ...triggers.slash ? [{ char: "/", kind: "command", items: triggers.slash }] : [],
+    ...triggers.mention ? [{ char: "@", kind: "mention", items: triggers.mention }] : []
+  ];
+  if (defs.length === 0) return "";
+  return ` triggers={${JSON.stringify(defs)}}`;
 }
 function emitAttachProps(c) {
   const attachments = c.capabilities?.attachments;
@@ -948,10 +1266,17 @@ function emitConversationsImport(c) {
   const name = c.capabilities.history?.persistence === "endpoint" ? "fetchStore" : "localStorageStore";
   return `import { ${name} } from '@kitn.ai/ui/solid';`;
 }
-function emitSolidJsImport(c) {
+function needsCreateEffect(c) {
   const history = c.capabilities?.history;
-  if (!history || history.persistence === "none" || c.layout !== "custom" && c.capabilities?.conversations) return "";
-  return `import { createEffect } from 'solid-js';
+  return !!history && history.persistence !== "none" && !(c.layout !== "custom" && c.capabilities?.conversations);
+}
+function emitSolidJsImports(c) {
+  const names = [];
+  if (needsCreateEffect(c)) names.push("createEffect");
+  if (widgetHasConversationsChrome(c) || hasShellPalette(c)) names.push("createSignal");
+  if (hasShellPalette(c)) names.push("Show", "onMount", "onCleanup");
+  if (names.length === 0) return "";
+  return `import { ${names.join(", ")} } from 'solid-js';
 `;
 }
 function emitHistoryTypeImport(c) {
@@ -1119,6 +1444,9 @@ function emitSlots(slots, indent) {
   return slots.map((name) => `${indent}<slot name="${name}" />
 `).join("");
 }
+function needsHost(c) {
+  return hasThemeToggleChrome(c) || hasHeaderActionsChrome(c) || hasUserMenuChrome(c);
+}
 function emitDockPosition(c) {
   const w = c.layout === "widget" ? c.widget : void 0;
   return w?.position ? ` position="${w.position}"` : "";
@@ -1143,14 +1471,19 @@ function emitLayoutOpen(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)' }}>
+    case "aside": {
+      const position = c.aside?.position ?? "end";
+      const width = JSON.stringify(c.aside?.width ?? "380px");
+      const inset = position === "start" ? "'inset-inline-start': '0'" : "'inset-inline-end': '0'";
+      const borderSide = position === "start" ? "border-inline-end" : "border-inline-start";
+      return `    <aside data-kai-layout="aside" style={{ position: 'fixed', 'inset-block': '0', ${inset}, width: ${width}, display: 'flex', 'flex-direction': 'column', '${borderSide}': '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>
+      <style>{\`@media (max-width: 480px) { [data-kai-layout="aside"] { inset: 0; width: auto; height: auto; ${borderSide}: 0; } }\`}</style>
 `;
+    }
     case "split":
       return `    <div style={{ height: '100dvh' }}>
       <WorkspaceShell class="h-full" drawerBelow={480} end={
@@ -1216,6 +1549,7 @@ const USAGE = `usage: npx @kitn.ai/ui <command>   (or \`kai <command>\` once @ki
   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
+  kai dev --builder [construct.json]     visual builder + live preview (no file = start from a template)
   kai compile <construct.json> [outDir]  one self-registering .js
 `;
 function homeRecentConversationWarning(construct) {
@@ -1254,6 +1588,12 @@ function parseUiFlag(rest) {
   const positional = uiFlag >= 0 ? rest.filter((_, i) => i !== uiFlag && i !== uiFlag + 1) : rest;
   return { uiSpec, positional };
 }
+function parseDevArgs(rest) {
+  const { uiSpec, positional } = parseUiFlag(rest);
+  const builder = positional.includes("--builder");
+  const path = positional.filter((a) => a !== "--builder")[0];
+  return { uiSpec, builder, path };
+}
 async function runCli(argv, io = defaultIo) {
   const [command, ...rest] = argv;
   switch (command) {
@@ -1284,13 +1624,17 @@ async function runCli(argv, io = defaultIo) {
       return 0;
     }
     case "dev": {
-      const { uiSpec, positional } = parseUiFlag(rest);
-      const path = positional[0];
+      const { uiSpec, builder, path } = parseDevArgs(rest);
+      if (builder) {
+        const { devBuilder } = await import("./assets/dev-DwzHsqYD.js");
+        await devBuilder(path, { io, uiSpec });
+        return 0;
+      }
       if (!path) {
         io.error(USAGE);
         return 2;
       }
-      const { dev } = await import("./assets/dev-5XzXYR21.js");
+      const { dev } = await import("./assets/dev-DwzHsqYD.js");
       await dev(path, { io, uiSpec });
       return 0;
     }
@@ -1304,7 +1648,7 @@ async function runCli(argv, io = defaultIo) {
       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 { workDirFor, ensureInstalled } = await import("./assets/dev-DwzHsqYD.js");
       const dir = workDirFor(construct.name, process.cwd());
       const files = generateProject(construct, { uiSpec });
       writeProject(files, dir);