@kitn.ai/ui 0.27.0 → 0.28.0

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

@@ -84,6 +84,21 @@ export const ConstructSchema = 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()
@@ -125,6 +140,37 @@ export const ConstructSchema = z
       })
       .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({
@@ -186,6 +232,17 @@ export const ConstructSchema = z
          *  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(),
@@ -312,6 +369,30 @@ export const ConstructSchema = z
       });
     }
     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({