@kitn.ai/ui 0.28.0 → 0.29.0

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

@@ -1,452 +0,0 @@
-/**
- * The construct format, v1 — Zod is the SINGLE SOURCE OF TRUTH.
- *
- * The published JSON Schema (apps/docs/public/schemas/construct/v1.json) and the
- * checked-in construct.v1.schema.json are DERIVED from this object by
- * scripts/gen-construct-schema.mjs (build:api, drift-guarded). Never edit those
- * by hand; never restate an enum from here anywhere else — read it off
- * `ConstructSchema.shape` or the generated artifact.
- *
- * Format rules (spec, binding): vocabulary never logic — no handlers, no
- * expressions; `.strict()` everywhere so an unknown key is a loud rejection,
- * not a silently ignored one. No secrets, no client: `provider` can name a URL
- * and a wire format, nothing else.
- */
-import { z } from 'zod';
-// REPO-INTERNAL ONLY: isSafeUrl is not reachable from the published package
-// (see agent-tooling/catalog/invariants.ts's own note on this), so the
-// emitted App.tsx cannot import it — the sink codegen writes to
-// (launcherIcon -> <img src>) has no guard it can reach at runtime. Enforcing
-// the SAME policy here, at authoring time, is the reachable equivalent: a
-// hostile launcherIcon is rejected before a construct ever validates, so
-// codegen never has an unsafe value to emit. Reuses the kit's one existing
-// URL-sink policy (markdown.tsx's image renderer, artifact.tsx) rather than
-// authoring a second one. Imported from url-scheme-policy.ts, NOT
-// card-routing.ts: this file compiles under tsconfig.mcp.json's Node-only, no-
-// DOM-lib pass (transitively, via mcp/tools/construct.ts), and card-routing.ts
-// pulls in HTMLElement/window/CustomEvent that pass can't see.
-import { isSafeUrl } from '../../primitives/url-scheme-policy';
-
-export const CONSTRUCT_SCHEMA_URL = 'https://ui.kitn.ai/schemas/construct/v1.json';
-
-/** A valid custom-element tag: lowercase, starts with a letter, contains a hyphen. */
-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(),
-]);
-
-export 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 = new Set<string>();
-      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 !== undefined && (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 !== undefined) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        path: ['capabilities', 'history', 'url'],
-        message: 'url is only valid with "endpoint" persistence',
-      });
-    }
-  });
-
-export type Construct = z.infer<typeof ConstructSchema>;
-
-export interface ConstructProblem {
-  /** Dotted path into the construct, '' for the root. */
-  path: string;
-  message: string;
-}
-
-export type ValidationOutcome =
-  | { ok: true; construct: Construct }
-  | { ok: false; problems: ConstructProblem[] };
-
-/**
- * Validate one construct. The ONLY doorway to codegen: a failure never reaches
- * generation — the problems go back to the author/agent with paths and reasons.
- */
-export function validateConstruct(input: unknown): ValidationOutcome {
-  const parsed = ConstructSchema.safeParse(input);
-  if (parsed.success) return { ok: true, construct: parsed.data };
-  return {
-    ok: false,
-    problems: parsed.error.issues.flatMap((issue) => {
-      // zod's unrecognized-key issue names the keys in its message but paths the
-      // OBJECT; surface each unknown key as its own problem so the agent sees
-      // exactly which word is not vocabulary.
-      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,
-        },
-      ];
-    }),
-  };
-}