@kitnai/chat 0.7.0 → 0.8.1

package/src/elements/{kitn-tool.stories.tsx → tool.stories.tsx}

@@ -2,15 +2,14 @@ import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { onMount } from 'solid-js';
 import './register'; // side effect: registers the custom elements
 import type { ToolPart } from '../components/tool';
-import { ElementSpec } from '../stories/docs/element-spec';
-import { argTypesFor } from '../stories/docs/element-controls';
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
 
 // The web components are custom DOM elements, so declare the tags for JSX.
 declare module 'solid-js' {
   // eslint-disable-next-line @typescript-eslint/no-namespace
   namespace JSX {
     interface IntrinsicElements {
-      'kitn-tool': JSX.HTMLAttributes<HTMLElement>;
+      'kc-tool': JSX.HTMLAttributes<HTMLElement>;
     }
   }
 }
@@ -28,7 +27,7 @@ const runningTool: ToolPart = {
   input: { query: 'kitn docs' },
 };
 
-/** Render the actual `<kitn-tool>` custom element with a `tool` property. */
+/** Render the actual `<kc-tool>` custom element with a `tool` property. */
 function ToolElement(props: { tool: ToolPart; open?: boolean }) {
   let el: (HTMLElement & { tool?: ToolPart; open?: boolean }) | undefined;
   onMount(() => {
@@ -38,12 +37,12 @@ function ToolElement(props: { tool: ToolPart; open?: boolean }) {
     }
   });
   return (
-    <kitn-tool ref={(e) => (el = e as HTMLElement)} style={{ display: 'block', padding: '16px', 'max-width': '720px' }} />
+    <kc-tool ref={(e) => (el = e as HTMLElement)} style={{ display: 'block', padding: '16px', 'max-width': '720px' }} />
   );
 }
 
 const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
-<kitn-tool id="tool" open></kitn-tool>
+<kc-tool id="tool" open></kc-tool>
 
 <script type="module">
   import '@kitnai/chat/elements';   // registers the custom elements
@@ -58,20 +57,18 @@ const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
 </script>`;
 
 const meta = {
-  title: 'Web Components/kitn-tool',
+  title: 'Web Components/kc-tool',
   tags: ['autodocs'],
-  argTypes: argTypesFor('kitn-tool'),
+  argTypes: argTypesFor('kc-tool'),
   parameters: {
     layout: 'fullscreen',
     docs: {
-      description: {
-        component: [
-          '`<kitn-tool>` is the framework-agnostic **web component** for a single tool-call panel — a collapsible input/output inspector with a state badge — isolated in **Shadow DOM**.',
+      description: specDescription('kc-tool', [
+          '`<kc-tool>` is the framework-agnostic **web component** for a single tool-call panel — a collapsible input/output inspector with a state badge — isolated in **Shadow DOM**.',
           '**When to use:** rendering an agent/tool-call trace in a non-Solid app. In SolidJS, use the `Tool` primitive directly.',
           "**How to use:** register once with `import '@kitnai/chat/elements'`, set the call via the `tool` **property** (`el.tool = {...}`), and add the `open` flag to start it expanded.",
           'See the **Code** tab for HTML usage.',
-        ].join('\n\n'),
-      },
+        ]),
     },
   },
 } satisfies Meta;
@@ -79,12 +76,6 @@ const meta = {
 export default meta;
 type Story = StoryObj;
 
-/** Full generated API reference — properties, events, tokens, and composed-from. */
-export const API: Story = {
-  render: () => <ElementSpec tag="kitn-tool" />,
-  parameters: { layout: 'padded' },
-};
-
 /** A completed call with input and output, started expanded. */
 export const Completed: Story = {
   render: () => <ToolElement tool={completedTool} open />,

package/src/elements/tool.tsx

@@ -1,5 +1,5 @@
 import { Show } from 'solid-js';
-import { defineKitnElement } from './define';
+import { defineWebComponent } from './define';
 import { Tool, type ToolPart } from '../components/tool';
 
 interface Props extends Record<string, unknown> {
@@ -10,10 +10,10 @@ interface Props extends Record<string, unknown> {
 }
 
 /**
- * `<kitn-tool>` — a collapsible tool-call panel (input/output inspection with a
+ * `<kc-tool>` — a collapsible tool-call panel (input/output inspection with a
  * state badge). Data via the `tool` property; `open` flag starts it expanded.
  */
-defineKitnElement<Props>('kitn-tool', {
+defineWebComponent<Props>('kc-tool', {
   tool: undefined,
   open: false,
 }, (props, { flag }) => (

package/src/elements/{kitn-voice-input.stories.tsx → voice-input.stories.tsx}

@@ -1,22 +1,21 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { onMount } from 'solid-js';
 import './register'; // side effect: registers the custom elements
-import { ElementSpec } from '../stories/docs/element-spec';
-import { argTypesFor } from '../stories/docs/element-controls';
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
 
 // The web components are custom DOM elements, so declare the tags for JSX.
 declare module 'solid-js' {
   // eslint-disable-next-line @typescript-eslint/no-namespace
   namespace JSX {
     interface IntrinsicElements {
-      'kitn-voice-input': JSX.HTMLAttributes<HTMLElement> & {
+      'kc-voice-input': JSX.HTMLAttributes<HTMLElement> & {
         disabled?: boolean | string;
       };
     }
   }
 }
 
-/** Render `<kitn-voice-input>` with a stub `transcribe` function-property. */
+/** Render `<kc-voice-input>` with a stub `transcribe` function-property. */
 function VoiceElement(props: { disabled?: boolean }) {
   let el: (HTMLElement & { transcribe?: (audio: Blob) => Promise<string> }) | undefined;
   onMount(() => {
@@ -33,7 +32,7 @@ function VoiceElement(props: { disabled?: boolean }) {
     });
   });
   return (
-    <kitn-voice-input
+    <kc-voice-input
       ref={(e) => (el = e as HTMLElement)}
       disabled={props.disabled ? true : undefined}
       style={{ display: 'inline-block', padding: '40px' }}
@@ -42,7 +41,7 @@ function VoiceElement(props: { disabled?: boolean }) {
 }
 
 const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
-<kitn-voice-input id="voice"></kitn-voice-input>
+<kc-voice-input id="voice"></kc-voice-input>
 
 <script type="module">
   import '@kitnai/chat/elements';   // registers the custom elements
@@ -57,20 +56,18 @@ const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
 </script>`;
 
 const meta = {
-  title: 'Web Components/kitn-voice-input',
+  title: 'Web Components/kc-voice-input',
   tags: ['autodocs'],
-  argTypes: argTypesFor('kitn-voice-input'),
+  argTypes: argTypesFor('kc-voice-input'),
   parameters: {
     layout: 'fullscreen',
     docs: {
-      description: {
-        component: [
-          '`<kitn-voice-input>` is the framework-agnostic **web component** for a mic button that records and transcribes audio — isolated in **Shadow DOM**. It is the canonical **function-property** element.',
+      description: specDescription('kc-voice-input', [
+          '`<kc-voice-input>` is the framework-agnostic **web component** for a mic button that records and transcribes audio — isolated in **Shadow DOM**. It is the canonical **function-property** element.',
           '**When to use:** adding voice dictation to an input in a non-Solid app. In SolidJS, use the `VoiceInput` primitive.',
           "**How to use:** register once with `import '@kitnai/chat/elements'`, then set the `transcribe` **function property** (`el.transcribe = async blob => '...'`) — a value-returning callback can't be modelled as an event. It also emits `audiocaptured` (raw blob) and `transcription` (text) **CustomEvents**.",
           'See the **Code** tab for HTML usage.',
-        ].join('\n\n'),
-      },
+        ]),
     },
   },
 } satisfies Meta;
@@ -78,12 +75,6 @@ const meta = {
 export default meta;
 type Story = StoryObj;
 
-/** Full generated API reference — properties, events, tokens, and composed-from. */
-export const API: Story = {
-  render: () => <ElementSpec tag="kitn-voice-input" />,
-  parameters: { layout: 'padded' },
-};
-
 /** A working mic button wired to a stub transcriber. */
 export const Default: Story = {
   render: () => <VoiceElement />,

package/src/elements/voice-input.tsx

@@ -1,4 +1,4 @@
-import { defineKitnElement } from './define';
+import { defineWebComponent } from './define';
 import { VoiceInput } from '../components/voice-input';
 
 interface Props extends Record<string, unknown> {
@@ -12,7 +12,7 @@ interface Props extends Record<string, unknown> {
   disabled?: boolean;
 }
 
-/** Events fired by `<kitn-voice-input>`. */
+/** Events fired by `<kc-voice-input>`. */
 interface Events {
   /** Raw audio captured (before transcription) — for hosts that prefer to
    *  handle transcription themselves instead of via the `transcribe` property. */
@@ -22,11 +22,11 @@ interface Events {
 }
 
 /**
- * `<kitn-voice-input>` — a mic button that records and transcribes. The
+ * `<kc-voice-input>` — a mic button that records and transcribes. The
  * canonical **function-property** element: set `el.transcribe` to your async
  * transcriber. Also emits `audiocaptured` (raw blob) and `transcription` (text).
  */
-defineKitnElement<Props, Events>('kitn-voice-input', {
+defineWebComponent<Props, Events>('kc-voice-input', {
   transcribe: undefined,
   disabled: false,
 }, (props, { dispatch, flag }) => (

package/src/index.ts

@@ -15,6 +15,92 @@ export { ChatConfig, useChatConfig, proseClass, textClass } from './primitives/c
 export type { ChatConfigValue, ProseSize, ChatConfigProps } from './primitives/chat-config';
 export { configureCodeHighlighting, isCodeHighlightingEnabled } from './primitives/highlighter';
 export type { CodeHighlightingOptions } from './primitives/highlighter';
+export { configurePdfPreview, isPdfPreviewEnabled } from './primitives/pdf-preview';
+export type { PdfPreviewOptions } from './primitives/pdf-preview';
+
+// Card Contract (generative-UI foundation)
+export { CARD_CONTRACT_VERSION } from './primitives/card-contract';
+export type {
+  CardEnvelope, CardContext, CardEvent, CardEventKind, CardHost, CardPolicy,
+} from './primitives/card-contract';
+export { CardProvider, useCardHost } from './primitives/card-host';
+export type { CardProviderProps } from './primitives/card-host';
+export { CARD_EVENT_NAME, emitCardEvent, routeCardEvent, listenForCardEvents } from './primitives/card-routing';
+export { validateAgainstSchema } from './primitives/card-validate';
+export type { JsonSchema, ValidationResult } from './primitives/card-validate';
+
+// Card: kc-card (base shell) + kc-form (JSON-Schema form renderer)
+export { Card } from './components/card';
+export type { CardProps } from './components/card';
+export { Form, validateForm, buildResult, widgetFor, orderedKeys, coerceValue } from './components/form';
+export type {
+  FormProps,
+  FormField,
+  FormDefinition,
+  FormCardEnvelope,
+  FormValidation,
+  WidgetKind,
+} from './components/form';
+
+// Card: kc-confirm (approval) + kc-task-list (selectable plan)
+export {
+  ConfirmCard,
+  CONFIRM_CARD_TYPE,
+  buttonVariantForStyle,
+  normalizeActions,
+  defaultActionId,
+} from './components/confirm-card';
+export type {
+  ConfirmCardProps,
+  ConfirmAction,
+  ConfirmActionStyle,
+  ConfirmTone,
+  ConfirmCardData,
+  ConfirmCardEnvelope,
+} from './components/confirm-card';
+export {
+  TaskListCard,
+  TASK_LIST_CARD_TYPE,
+  normalizeTasks,
+  initialSelected,
+  selectedInOrder,
+  toggleableIds,
+  selectAllState,
+  showSelectAll,
+  canConfirm,
+  isMaxReached,
+  confirmReason,
+} from './components/task-list-card';
+export type {
+  TaskListCardProps,
+  TaskListTask,
+  TaskListCardData,
+  TaskListCardResult,
+  TaskListCardEnvelope,
+  SelectAllState,
+} from './components/task-list-card';
+
+// Card: kc-link-card (OG/link preview) + kc-embed (lazy media embed)
+export { LinkCard } from './components/link-card';
+export type { LinkCardProps } from './components/link-card';
+export { Embed } from './components/embed';
+export type { EmbedProps } from './components/embed';
+export {
+  configureLinkPreview,
+  resolveLinkMetadata,
+  hasLinkPreviewFetcher,
+  LINK_CARD_TYPE,
+} from './primitives/link-preview';
+export type { LinkCardData, LinkCardEnvelope, LinkMetadataFetcher } from './primitives/link-preview';
+export {
+  resolveEmbed,
+  parseYouTubeId,
+  parseVimeoId,
+  configureEmbedAllowlist,
+  isGenericOriginAllowed,
+  EMBED_CARD_TYPE,
+} from './primitives/embed-providers';
+export type { EmbedCardData, EmbedCardEnvelope, EmbedProvider, ResolvedEmbed } from './primitives/embed-providers';
 
 // Layer 2: UI Primitives
 export { Button, buttonVariants } from './ui/button';
@@ -31,9 +117,15 @@ export type { TextareaProps } from './ui/textarea';
 export { Badge } from './ui/badge';
 export type { BadgeProps } from './ui/badge';
 export { Separator } from './ui/separator';
-export { ResizablePanelGroup, ResizablePanel, ResizableHandle } from './ui/resizable';
-export type { ResizablePanelGroupProps, ResizablePanelProps, ResizableHandleProps } from './ui/resizable';
+export { ResizablePanelGroup, ResizablePanel, ResizableHandle, Resizable, normalizeSize, resolveToPx } from './ui/resizable';
+export type { ResizablePanelGroupProps, ResizablePanelProps, ResizableHandleProps, ResizableProps, SizeValue } from './ui/resizable';
 export { Skeleton } from './ui/skeleton';
+export { FileTree, buildFileTree } from './components/file-tree';
+export type {
+  FileTreeProps, FileTreeFile, FileTreeNode, FileTreeFolderNode, FileTreeFileNode,
+} from './components/file-tree';
+export { Artifact } from './components/artifact';
+export type { ArtifactProps, ArtifactFile, ArtifactTab } from './components/artifact';
 
 // Layer 3: AI/Feature Components
 export {

package/src/primitives/card-contract.ts

@@ -0,0 +1,60 @@
+// src/primitives/card-contract.ts
+// The frozen Card Contract: the one typed contract every card speaks across both
+// transports (native <kc-*> + remote iframe). Pure types only — no runtime, no DOM.
+// See docs/superpowers/specs/2026-06-13-card-contract-design.md.
+
+/** Bumped on any BREAKING change to the shapes below. Additive/optional fields do not bump it. */
+export const CARD_CONTRACT_VERSION = '1' as const;
+
+/** A card the agent/server asks the chat to render. `data` conforms to the card
+ *  type's own published JSON Schema (one schema per `type`). */
+export interface CardEnvelope<TType extends string = string, TData = unknown> {
+  type: TType;
+  id: string;
+  data: TData;
+  title?: string;
+}
+
+/** Context the host pushes to every card; updated when it changes (theme, etc.). */
+export interface CardContext {
+  theme: { mode: 'light' | 'dark'; tokens?: Record<string, string> };
+  locale: string;
+  conversationId?: string;
+  /** Remote (iframe) cards only: short-lived signed token. Never long-lived. */
+  authToken?: string;
+  /** Host-resolved a11y prefs (e.g. reduced-motion, which doesn't cross the iframe). */
+  a11y?: { reducedMotion?: boolean };
+}
+
+/** Everything a card can ask the host to do. The host authorizes + routes each. */
+export type CardEvent =
+  | { kind: 'ready'; cardId: string }
+  | { kind: 'submit-data'; cardId: string; data: unknown }
+  | { kind: 'action'; cardId: string; action: string; payload?: unknown }
+  | { kind: 'send-prompt'; cardId: string; text: string; mode?: 'compose' | 'send'; context?: unknown }
+  | { kind: 'open'; cardId: string; url: string; target?: 'tab' | 'artifact' }
+  | { kind: 'resize'; cardId: string; height: number }
+  | { kind: 'state'; cardId: string; patch: unknown }
+  | { kind: 'dismiss'; cardId: string }
+  | { kind: 'error'; cardId: string; message: string };
+
+export type CardEventKind = CardEvent['kind'];
+
+/** What every card is handed (via native context or the iframe bridge). */
+export interface CardHost {
+  context(): CardContext;
+  emit(event: CardEvent): void;
+}
+
+/** How the host routes each verb. Consumers supply handlers; defaults applied otherwise. */
+export interface CardPolicy {
+  onSubmitData?: (cardId: string, data: unknown) => void;
+  onAction?: (cardId: string, action: string, payload?: unknown) => void;
+  onSendPrompt?: (text: string, opts: { mode: 'compose' | 'send'; context?: unknown }) => void;
+  onOpen?: (url: string, target: 'tab' | 'artifact') => void;
+  onState?: (cardId: string, patch: unknown) => void;
+  onDismiss?: (cardId: string) => void;
+  onError?: (cardId: string, message: string) => void;
+  /** Cap on send-prompt: 'compose' (default) forbids silent sends. 'send' to allow. */
+  maxSendPromptMode?: 'compose' | 'send';
+}

package/src/primitives/card-host.tsx

@@ -0,0 +1,35 @@
+// src/primitives/card-host.tsx
+// The native transport: a Solid context exposing a CardHost (context() + emit()).
+// emit() routes through the contract policy via the shared routeCardEvent. Cards
+// inside <kc-chat>/<CardProvider> use this; bare cards fall back to the bubbling
+// kc-card event (see card-routing.listenForCardEvents).
+import { createContext, useContext, type JSX } from 'solid-js';
+import type { CardContext, CardEvent, CardHost, CardPolicy } from './card-contract';
+import { routeCardEvent } from './card-routing';
+
+const CardHostContext = createContext<CardHost>();
+
+export interface CardProviderProps {
+  /** Ambient context, static or a reactive getter. */
+  context: CardContext | (() => CardContext);
+  /** Routing policy applied to every emitted event. */
+  policy?: CardPolicy;
+  children: JSX.Element;
+}
+
+export function CardProvider(props: CardProviderProps): JSX.Element {
+  // Never destructure props (Solid norm). Resolve context lazily so a getter stays reactive.
+  const host: CardHost = {
+    context: () =>
+      typeof props.context === 'function'
+        ? (props.context as () => CardContext)()
+        : props.context,
+    emit: (event: CardEvent) => routeCardEvent(props.policy, event),
+  };
+  return <CardHostContext.Provider value={host}>{props.children}</CardHostContext.Provider>;
+}
+
+/** Read the current CardHost. `undefined` when no provider is present (bare card). */
+export function useCardHost(): CardHost | undefined {
+  return useContext(CardHostContext);
+}

package/src/primitives/card-routing.ts

@@ -0,0 +1,79 @@
+// src/primitives/card-routing.ts
+// Framework-agnostic card-event plumbing: the bubbling kc-card emitter, the single
+// policy router (used by BOTH the native listener and the remote transport), and a
+// host-side listener helper for the bare-element path.
+import type { CardEvent, CardPolicy } from './card-contract';
+
+/** The single contract event name. */
+export const CARD_EVENT_NAME = 'kc-card';
+
+/** Dispatch a CardEvent as the bubbling, composed `kc-card` event a host listener
+ *  routes. NB: this is deliberately different from defineWebComponent's built-in
+ *  non-bubbling dispatch. */
+export function emitCardEvent(element: HTMLElement, event: CardEvent): void {
+  element.dispatchEvent(
+    new CustomEvent<CardEvent>(CARD_EVENT_NAME, { detail: event, bubbles: true, composed: true }),
+  );
+}
+
+const SAFE_SCHEMES = ['http:', 'https:', 'mailto:'];
+function isSafeUrl(url: string): boolean {
+  try { return SAFE_SCHEMES.includes(new URL(url, 'http://_invalid_base').protocol); } catch { return false; }
+}
+function warnNoHandler(kind: string): void {
+  // eslint-disable-next-line no-console
+  console.warn(`[kc-card] no policy handler for "${kind}"`);
+}
+
+/** Apply the contract's policy to one event. The ONE place routing lives. */
+export function routeCardEvent(policy: CardPolicy | undefined, event: CardEvent): void {
+  const p: CardPolicy = policy ?? {};
+  switch (event.kind) {
+    case 'ready':
+      break; // lifecycle; host may react via its own listener
+    case 'submit-data':
+      p.onSubmitData ? p.onSubmitData(event.cardId, event.data) : warnNoHandler('submit-data');
+      break;
+    case 'action':
+      p.onAction ? p.onAction(event.cardId, event.action, event.payload) : warnNoHandler('action');
+      break;
+    case 'send-prompt': {
+      const requested = event.mode ?? 'compose';
+      const mode = p.maxSendPromptMode === 'send' ? requested : 'compose';
+      p.onSendPrompt ? p.onSendPrompt(event.text, { mode, context: event.context }) : warnNoHandler('send-prompt');
+      break;
+    }
+    case 'open': {
+      if (!isSafeUrl(event.url)) {
+        p.onError ? p.onError(event.cardId, `Blocked unsafe url: ${event.url}`) : warnNoHandler('open(unsafe)');
+        break;
+      }
+      const target = event.target ?? 'tab';
+      if (p.onOpen) p.onOpen(event.url, target);
+      else if (typeof window !== 'undefined') window.open(event.url, '_blank', 'noopener,noreferrer');
+      break;
+    }
+    case 'state':
+      p.onState ? p.onState(event.cardId, event.patch) : warnNoHandler('state');
+      break;
+    case 'dismiss':
+      p.onDismiss ? p.onDismiss(event.cardId) : warnNoHandler('dismiss');
+      break;
+    case 'error':
+      p.onError ? p.onError(event.cardId, event.message) : warnNoHandler('error');
+      break;
+    case 'resize':
+      break; // transport plumbing (iframe height); not an app-policy concern natively
+  }
+}
+
+/** Attach a host-level `kc-card` listener that routes every bubbling card event
+ *  through `policy`. Returns an unsubscribe fn. For the bare-element path. */
+export function listenForCardEvents(
+  root: HTMLElement | Document,
+  policy: CardPolicy,
+): () => void {
+  const handler = (e: Event) => routeCardEvent(policy, (e as CustomEvent<CardEvent>).detail);
+  root.addEventListener(CARD_EVENT_NAME, handler as EventListener);
+  return () => root.removeEventListener(CARD_EVENT_NAME, handler as EventListener);
+}

package/src/primitives/card-schemas/card-envelope.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kitn.ai/schemas/card/card-envelope.schema.json",
+  "title": "CardEnvelope",
+  "description": "A card the agent/server asks the chat to render. `data` validates against the per-type schema.",
+  "type": "object",
+  "required": ["type", "id", "data"],
+  "properties": {
+    "type": { "type": "string", "minLength": 1 },
+    "id": { "type": "string", "minLength": 1 },
+    "data": {},
+    "title": { "type": "string" }
+  }
+}

package/src/primitives/card-schemas/card-event.schema.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kitn.ai/schemas/card/card-event.schema.json",
+  "title": "CardEvent",
+  "description": "An event a card emits up to the host. `kind` discriminates the payload.",
+  "type": "object",
+  "required": ["kind"],
+  "properties": {
+    "kind": { "enum": ["ready", "submit-data", "action", "send-prompt", "open", "resize", "state", "dismiss", "error"] },
+    "cardId": { "type": "string" }
+  }
+}

package/src/primitives/card-schemas/confirm.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kitn.ai/schemas/card/confirm.schema.json",
+  "title": "ConfirmCardData",
+  "description": "Data payload for a `confirm` card (CardEnvelope.data when type='confirm').",
+  "type": "object",
+  "required": ["actions"],
+  "properties": {
+    "heading": {
+      "type": "string",
+      "description": "Optional in-body heading. Distinct from CardEnvelope.title (the card chrome title)."
+    },
+    "body": {
+      "type": "string",
+      "description": "Body text. Plain text in v1 (rendered safely; no HTML injection)."
+    },
+    "tone": {
+      "type": "string",
+      "enum": ["default", "warning", "danger"],
+      "default": "default",
+      "description": "Overall card tone; 'danger' adds a warning icon + accent for destructive approvals.",
+      "x-kc-control": "tone"
+    },
+    "actions": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 4,
+      "description": "The choice set. Rendered as buttons in order; max 4 keeps it a decision, not a menu.",
+      "items": {
+        "type": "object",
+        "required": ["id", "label"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Emitted as CardEvent.action. Must be unique within `actions`.",
+            "x-kc-unique": true
+          },
+          "label": { "type": "string", "minLength": 1, "description": "Visible button label." },
+          "style": {
+            "type": "string",
+            "enum": ["primary", "default", "destructive"],
+            "default": "default",
+            "description": "Button emphasis. 'destructive' = red/danger; 'primary' = filled accent.",
+            "x-kc-control": "button-style"
+          },
+          "payload": {
+            "description": "Optional opaque payload echoed back in CardEvent.payload (any JSON)."
+          },
+          "default": {
+            "type": "boolean",
+            "default": false,
+            "description": "If true, this action is the keyboard default (Enter) and gets initial focus. At most one should be true; the card uses the first if several are.",
+            "x-kc-default-action": true
+          }
+        }
+      }
+    },
+    "dismissible": {
+      "type": "boolean",
+      "default": false,
+      "description": "Show a close affordance that emits the `dismiss` verb."
+    }
+  }
+}

package/src/primitives/card-schemas/embed.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kitn.ai/schemas/card/embed.schema.json",
+  "title": "EmbedCardData",
+  "description": "Lazy media-embed payload (YouTube / Vimeo / generic player URL).",
+  "type": "object",
+  "x-kc-card-type": "embed",
+  "x-kc-contract-version": "1",
+  "required": ["provider"],
+  "additionalProperties": false,
+  "properties": {
+    "provider": {
+      "type": "string",
+      "enum": ["youtube", "vimeo", "generic"],
+      "description": "Media provider. 'generic' frames `url` directly (must be an https embeddable player URL whose origin is app-allowlisted).",
+      "x-kc-control": "select"
+    },
+    "id": {
+      "type": "string",
+      "description": "Provider video id (required for youtube/vimeo when `url` is absent). e.g. 'dQw4w9WgXcQ'.",
+      "maxLength": 64,
+      "pattern": "^[A-Za-z0-9_-]+$"
+    },
+    "url": {
+      "type": "string",
+      "format": "uri",
+      "description": "Full media/watch URL. For youtube/vimeo it is parsed to an id; for 'generic' it is the embeddable player src (https only).",
+      "x-kc-format": "url"
+    },
+    "title": {
+      "type": "string",
+      "description": "Accessible title for the player iframe + the poster label. Strongly recommended for a11y.",
+      "maxLength": 300
+    },
+    "poster": {
+      "type": "string",
+      "format": "uri",
+      "description": "Thumbnail shown before play. When omitted, youtube/vimeo derive a default thumbnail; 'generic' shows a neutral play placeholder.",
+      "x-kc-format": "url"
+    },
+    "start": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Optional start offset in seconds.",
+      "x-kc-unit": "seconds"
+    },
+    "aspectRatio": {
+      "type": "string",
+      "enum": ["16:9", "4:3", "1:1", "9:16"],
+      "default": "16:9",
+      "description": "Player box aspect ratio (CSS aspect-ratio).",
+      "x-kc-control": "select"
+    }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "provider": { "const": "generic" } } },
+      "then": { "required": ["url"] }
+    },
+    {
+      "if": { "properties": { "provider": { "enum": ["youtube", "vimeo"] } } },
+      "then": { "anyOf": [{ "required": ["id"] }, { "required": ["url"] }] }
+    }
+  ]
+}