@kitn.ai/ui 0.27.0 → 0.29.0

package/dist/construct-cli.es.js

@@ -57,6 +57,21 @@ const ConstructSchema = z.object({
   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
@@ -90,6 +105,30 @@ const ConstructSchema = z.object({
     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.
@@ -143,7 +182,18 @@ const ConstructSchema = z.object({
      *  Meaningless when `reasoning` is `'compact'` (no expandable
      *  content exists) or `'off'` (nothing renders); rejected on both,
      *  loudly, below. */
-    reasoningOpen: z.boolean().optional()
+    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
@@ -253,6 +303,30 @@ const ConstructSchema = z.object({
     });
   }
   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({
@@ -564,11 +638,26 @@ function emitIndexHtml(c) {
 }
 function emitElement(c) {
   const accent = c.theme?.accent;
-  if (!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});
@@ -589,7 +678,7 @@ defineWebComponent('${c.name}', { theme: '${themeMode(c)}' as 'light' | 'dark' |
   :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)});
+  ctx.element.style.setProperty('--kai-color-primary', ${JSON.stringify(accent)});${unreadColorSetProperty}
   return (
     <>
       <style>{${JSON.stringify(styleText)}}</style>
@@ -607,10 +696,11 @@ defineWebComponent('${c.name}', { theme: '${themeMode(c)}' as 'light' | 'dark' |
 }
 function emitApp(c) {
   if (c.layout === "custom") return emitCustomApp(c);
-  return `${emitSolidJsImport(c)}import { ChatThread, createKaiChat${emitLayoutImport(c)}${emitCardComponentImport(c)}${emitEmptyComponentImport(c)}${emitHeaderCloseImport(c)} } from '@kitn.ai/ui/solid';
-import type { AttachmentData${emitHistoryTypeImport(c)} } from '@kitn.ai/ui/solid';
+  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)}
@@ -679,9 +769,26 @@ ${emitHistorySetup(c)}
 //     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, "  ")}  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)} />
+${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)}  );
 }
 `;
@@ -703,8 +810,8 @@ ${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)
-// are NOT wired here in v1 — this file is the eject artifact; add them the
+// 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() {
@@ -757,6 +864,40 @@ function emitEmptyComponentImport(c) {
 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;
 ` : "";
@@ -792,15 +933,30 @@ function emitReasoningProp(c) {
 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") return "";
+  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") return "";
+  if (!history || history.persistence === "none" || c.layout !== "custom" && c.capabilities?.conversations) return "";
   return ", ChatMessage";
 }
 function emitUserIdHeaderEntry(c) {
@@ -809,6 +965,7 @@ function emitUserIdHeaderEntry(c) {
 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 `
@@ -947,7 +1104,7 @@ async function submit(detail: { value: string; attachments: AttachmentData[] })
 function emitLayoutImport(c) {
   switch (c.layout) {
     case "widget":
-      return ", Dock";
+      return `, Dock${hasLauncherIcon(c) ? ", DockLauncherImage" : ""}`;
     case "split":
       return ", WorkspaceShell";
     case "fullscreen":
@@ -966,10 +1123,13 @@ 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={<img src={${JSON.stringify(w.launcherIcon)}} alt="" style={{ width: '24px', height: '24px', 'border-radius': '9999px' }} />}`;
+  return ` launcher={<DockLauncherImage src={${JSON.stringify(w.launcherIcon)}} />}`;
 }
 function emitDockDefaultOpen(c) {
   const w = c.layout === "widget" ? c.widget : void 0;
@@ -978,7 +1138,7 @@ function emitDockDefaultOpen(c) {
 function emitLayoutOpen(c) {
   switch (c.layout) {
     case "widget":
-      return `    <Dock label="${c.name}"${emitDockPosition(c)}${emitDockLauncher(c)}${emitDockDefaultOpen(c)}${emitDockHideClose(c)}${emitDockControllerRef(c)}>
+      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' }}>
@@ -1051,13 +1211,19 @@ function writeProject(files, dir) {
   return overwritten;
 }
 const defaultIo = { log: (s) => console.log(s), error: (s) => console.error(s) };
-const USAGE = `usage: kai <command>
+const USAGE = `usage: npx @kitn.ai/ui <command>   (or \`kai <command>\` once @kitn.ai/ui is installed)
 
   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)
+  kai dev <construct.json>               live preview with reload-on-edit
+  kai compile <construct.json> [outDir]  one self-registering .js
 `;
+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;
@@ -1095,6 +1261,8 @@ async function runCli(argv, io = defaultIo) {
       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": {

package/dist/construct.d.ts

@@ -0,0 +1,5 @@
+// GENERATED by scripts/emit-subpath-dts.mjs — do not edit.
+// Sibling declarations for dist/construct.js, so that RELATIVE imports
+// of this bundle (which bypass package.json "exports") still resolve to types.
+// Without this, tsc resolves the path to the .js and reports TS7016.
+export * from './agent-tooling/construct/public.js';