@kitn.ai/ui 0.14.1

package/src/elements/voice-input.stories.tsx

@@ -0,0 +1,88 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+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 {
+      'kai-voice-input': JSX.HTMLAttributes<HTMLElement> & {
+        disabled?: boolean | string;
+      };
+    }
+  }
+}
+
+/** Render `<kai-voice-input>` with a stub `transcribe` function-property. */
+function VoiceElement(props: { disabled?: boolean }) {
+  let el: (HTMLElement & { transcribe?: (audio: Blob) => Promise<string> }) | undefined;
+  onMount(() => {
+    if (!el) return;
+    // transcribe MUST be set as a JS property — a value-returning callback
+    // can't be modelled as an attribute.
+    el.transcribe = async () => {
+      await new Promise((r) => setTimeout(r, 400));
+      return 'transcribed text';
+    };
+    el.addEventListener('kai-transcription', (e) => {
+      const ev = e as CustomEvent<{ text: string }>;
+      console.log('kai-transcription', ev.detail.text);
+    });
+  });
+  return (
+    <kai-voice-input
+      ref={(e) => (el = e as HTMLElement)}
+      disabled={props.disabled ? true : undefined}
+      style={{ display: 'inline-block', padding: '40px' }}
+    />
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kai-voice-input id="voice"></kai-voice-input>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';   // registers the custom elements
+
+  const voice = document.getElementById('voice');
+  // transcribe is a FUNCTION property — your async transcriber
+  voice.transcribe = async (blob) => {
+    const text = await myTranscriptionApi(blob);
+    return text;
+  };
+  voice.addEventListener('kai-transcription', (e) => console.log(e.detail.text));
+</script>`;
+
+const meta = {
+  title: 'Components/VoiceInput',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kai-voice-input'),
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: specDescription('kai-voice-input', [
+          '`<kai-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.',
+          '**Placement:** inline beside the prompt input field or as an icon button in the composer toolbar; renders as an inline-block sized to the mic button.',
+          "**How to use:** register once with `import '@kitn.ai/ui/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 `kai-audio-captured` (raw blob) and `kai-transcription` (text) **CustomEvents**.",
+          'See the **Code** tab for HTML usage.',
+        ]),
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** A working mic button wired to a stub transcriber. */
+export const Default: Story = {
+  render: () => <VoiceElement />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** A disabled mic button (non-interactive). */
+export const Disabled: Story = {
+  render: () => <VoiceElement disabled />,
+};

package/src/elements/voice-input.tsx

@@ -0,0 +1,41 @@
+import { defineWebComponent } from './define';
+import { VoiceInput } from '../components/voice-input';
+
+interface Props extends Record<string, unknown> {
+  /**
+   * Transcriber the host supplies — records audio, returns the text. This is a
+   * **function-valued property** (`el.transcribe = async blob => '...'`) because
+   * a value-returning callback can't be modelled as a fire-and-forget event.
+   */
+  transcribe?: (audio: Blob) => Promise<string>;
+  /** Disable the mic button (non-interactive). */
+  disabled?: boolean;
+}
+
+/** Events fired by `<kai-voice-input>`. */
+interface Events {
+  /** Raw audio captured (before transcription) — for hosts that prefer to
+   *  handle transcription themselves instead of via the `transcribe` property. */
+  'kai-audio-captured': { blob: Blob };
+  /** Transcription completed (the `transcribe` property resolved). */
+  'kai-transcription': { text: string };
+}
+
+/**
+ * `<kai-voice-input>` — a mic button that records and transcribes. The
+ * canonical **function-property** element: set `el.transcribe` to your async
+ * transcriber. Also emits `kai-audio-captured` (raw blob) and `kai-transcription` (text).
+ */
+defineWebComponent<Props, Events>('kai-voice-input', {
+  transcribe: undefined,
+  disabled: false,
+}, (props, { dispatch, flag }) => (
+  <VoiceInput
+    disabled={flag('disabled')}
+    onTranscribe={async (blob) => {
+      dispatch('kai-audio-captured', { blob });
+      return props.transcribe ? props.transcribe(blob) : '';
+    }}
+    onTranscription={(text) => dispatch('kai-transcription', { text })}
+  />
+));

package/src/index.ts

@@ -0,0 +1,253 @@
+// Shared types (folded in from @tab-zen/shared)
+export type { ModelOption, SearchFilters, ConversationScope, ConversationSummary, ConversationGroup } from './types';
+
+// Utilities
+export { cn } from './utils/cn';
+
+// Layer 1: Headless Primitives
+export { useAutoResize } from './primitives/use-auto-resize';
+export { useStickToBottom } from './primitives/use-stick-to-bottom';
+export { useTextStream } from './primitives/use-text-stream';
+export type { UseTextStreamOptions, TextStreamSegment } from './primitives/use-text-stream';
+export { useVoiceRecorder } from './primitives/use-voice-recorder';
+export type { UseVoiceRecorderOptions } from './primitives/use-voice-recorder';
+export { ChatConfig, useChatConfig, proseClass, textClass } from './primitives/chat-config';
+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, CardResolution, CardHost, CardPolicy,
+} from './primitives/card-contract';
+export { applyResolution, resolutionFromEvent } from './primitives/card-resolution';
+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';
+
+// Remote host SDK (iframe transport — host side only; provider runtime ships via ./provider subpath)
+export { mountRemoteCard } from './remote/host-embed';
+export type { MountRemoteCardOptions, RemoteCardHandle } from './remote/host-embed';
+
+// Card dispatcher (generative-UI host glue)
+export { CardRenderer, renderCard } from './components/card-renderer';
+export type { CardRendererProps } from './components/card-renderer';
+export { CardFallback } from './components/card-fallback';
+export type { CardFallbackProps } from './components/card-fallback';
+export {
+  BUILTIN_CARD_TAGS, BUILTIN_CARD_COMPONENTS, mergeCardTags, mergeCardComponents,
+} from './primitives/card-registry';
+export type { CardComponent, CardComponentMap, CardTagMap } from './primitives/card-registry';
+
+// Card: kai-card (base shell) + kai-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: kai-confirm (approval) + kai-tasks (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 {
+  TasksCard,
+  TASKS_CARD_TYPE,
+  normalizeTasks,
+  initialSelected,
+  selectedInOrder,
+  toggleableIds,
+  selectAllState,
+  showSelectAll,
+  canConfirm,
+  isMaxReached,
+  confirmReason,
+} from './components/tasks-card';
+export type {
+  TasksCardProps,
+  TasksTask,
+  TasksCardData,
+  TasksCardResult,
+  TasksCardEnvelope,
+  SelectAllState,
+} from './components/tasks-card';
+
+// Card: kai-choice (single-select option card)
+export {
+  ChoiceCard,
+  CHOICE_CARD_TYPE,
+  OTHER_ACTION,
+  normalizeOptions,
+  resolveOtherConfig,
+  nextEnabledIndex,
+  firstEnabledIndex,
+} from './components/choice-card';
+export type {
+  ChoiceCardProps,
+  ChoiceOption,
+  ChoiceOptionMedia,
+  ChoiceAllowOther,
+  ChoiceCardData,
+  ChoiceCardEnvelope,
+} from './components/choice-card';
+
+// Card: kai-link-preview (OG/link preview) + kai-embed (lazy media embed)
+export { LinkPreview } from './components/link-preview';
+export type { LinkPreviewProps } from './components/link-preview';
+export { Embed } from './components/embed';
+export type { EmbedProps } from './components/embed';
+export {
+  configureLinkPreview,
+  resolveLinkMetadata,
+  hasLinkPreviewFetcher,
+  LINK_PREVIEW_TYPE,
+} from './primitives/link-preview';
+export type { LinkPreviewData, LinkPreviewEnvelope, 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';
+export type { ButtonProps } from './ui/button';
+export { Avatar } from './ui/avatar';
+export type { AvatarProps } from './ui/avatar';
+export { Tooltip } from './ui/tooltip';
+export { HoverCard } from './ui/hover-card';
+export { Collapsible, CollapsibleTrigger, CollapsibleContent } from './ui/collapsible';
+export { ScrollArea } from './ui/scroll-area';
+export { Dropdown, DropdownTrigger, DropdownContent, DropdownItem } from './ui/dropdown';
+export { Textarea } from './ui/textarea';
+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, 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 {
+  ChatContainer, ChatContainerRoot, ChatContainerContent, ChatContainerScrollAnchor,
+  useChatContainer,
+} from './components/chat-container';
+export { Message, MessageAvatar, MessageContent, MessageActions, MessageAction, MessageCopyButton } from './components/message';
+export type { MessageCopyButtonProps } from './components/message';
+export { MessageSkills } from './components/message-skills';
+export type { Skill as MessageSkill } from './components/message-skills';
+export {
+  PromptInput, PromptInputTextarea, PromptInputActions, PromptInputAction,
+  usePromptInput,
+} from './components/prompt-input';
+export { SlashCommand } from './components/slash-command';
+export type { SlashCommandItem, SlashCommandProps } from './components/slash-command';
+export { ResponseStream } from './components/response-stream';
+export { Markdown } from './components/markdown';
+export { CodeBlock, CodeBlockCode, CodeBlockGroup } from './components/code-block';
+export { Loader } from './components/loader';
+export type { LoaderVariant, LoaderSize, LoaderProps } from './components/loader';
+export {
+  CircularLoader, ClassicLoader, PulseLoader, PulseDotLoader,
+  DotsLoader, TypingLoader, WaveLoader, BarsLoader,
+  TerminalLoader, TextBlinkLoader, TextShimmerLoader, TextDotsLoader,
+} from './components/loader';
+export { FeedbackBar, type FeedbackValue, type FeedbackDetail } from './components/feedback-bar';
+export {
+  ChainOfThought, ChainOfThoughtStep, ChainOfThoughtTrigger,
+  ChainOfThoughtContent, ChainOfThoughtItem,
+} from './components/chain-of-thought';
+export { Source, SourceTrigger, SourceContent, SourceList } from './components/source';
+export { PromptSuggestion } from './components/prompt-suggestion';
+export {
+  Empty, EmptyHeader, EmptyMedia, EmptyTitle, EmptyDescription, EmptyContent, emptyMediaVariants,
+} from './components/empty';
+export type {
+  EmptyProps, EmptyHeaderProps, EmptyMediaProps, EmptyTitleProps, EmptyDescriptionProps, EmptyContentProps,
+} from './components/empty';
+export { ScrollButton } from './components/scroll-button';
+export { TextShimmer } from './components/text-shimmer';
+export { Checkpoint, CheckpointIcon, CheckpointTrigger } from './components/checkpoint';
+export type { CheckpointProps, CheckpointIconProps, CheckpointTriggerProps } from './components/checkpoint';
+export {
+  Context,
+  ContextTrigger,
+  ContextContent,
+  ContextContentHeader,
+  ContextContentBody,
+  ContextContentFooter,
+  ContextInputUsage,
+  ContextOutputUsage,
+  ContextReasoningUsage,
+  ContextCacheUsage,
+} from './components/context';
+export type {
+  ContextProps,
+  ContextTriggerProps,
+  ContextContentProps,
+  ContextContentHeaderProps,
+  ContextContentBodyProps,
+  ContextContentFooterProps,
+  ContextUsageRowProps,
+} from './components/context';
+export { VoiceInput } from './components/voice-input';
+export { ConversationList } from './components/conversation-list';
+export { ConversationItem } from './components/conversation-item';
+export { ModelSwitcher } from './components/model-switcher';
+export { ChatScopePicker } from './components/chat-scope-picker';
+export { Tool } from './components/tool';
+export type { ToolPart, ToolProps } from './components/tool';
+export { ThinkingBar } from './components/thinking-bar';
+export type { ThinkingBarProps } from './components/thinking-bar';
+export { Reasoning, ReasoningTrigger, ReasoningContent } from './components/reasoning';
+export type { ReasoningProps, ReasoningTriggerProps, ReasoningContentProps } from './components/reasoning';
+export { Image } from './components/image';
+export type { ImageProps, GeneratedImageLike } from './components/image';
+export { FileUpload, FileUploadTrigger, FileUploadContent } from './components/file-upload';
+export type { FileUploadProps, FileUploadTriggerProps, FileUploadContentProps } from './components/file-upload';
+export {
+  Attachments, Attachment, AttachmentPreview, AttachmentInfo, AttachmentRemove,
+  AttachmentHoverCard, AttachmentHoverCardTrigger, AttachmentHoverCardContent,
+  AttachmentEmpty, getMediaCategory, getAttachmentLabel,
+  useAttachmentsContext, useAttachmentContext,
+} from './components/attachments';
+export type {
+  AttachmentData, AttachmentMediaCategory, AttachmentVariant,
+  AttachmentsProps, AttachmentProps, AttachmentPreviewProps,
+  AttachmentInfoProps, AttachmentRemoveProps, AttachmentEmptyProps,
+  AttachmentHoverCardProps, AttachmentHoverCardTriggerProps, AttachmentHoverCardContentProps,
+} from './components/attachments';

package/src/primitives/card-contract.ts

@@ -0,0 +1,71 @@
+// src/primitives/card-contract.ts
+// The frozen Card Contract: the one typed contract every card speaks across both
+// transports (native <kai-*> + 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;
+  /** Set when the user has resolved this card; renders the chromed read-only view. */
+  resolution?: CardResolution;
+}
+
+/** 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'; 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'];
+
+/** How a card was resolved by the user — the re-hydration channel for the chromed
+ *  read-only state. Mirrors the two terminal CardEvents (minus `cardId`): the
+ *  resolution is just the event that resolved the card. `at` is optional ISO-8601
+ *  provenance (data only; never rendered). Additive — does not bump the contract
+ *  version. */
+export type CardResolution =
+  | { kind: 'action'; action: string; payload?: unknown; at?: string }
+  | { kind: 'submit'; data: unknown; at?: string };
+
+/** 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 {
+  onSubmit?: (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 <kai-chat>/<CardProvider> use this; bare cards fall back to the bubbling
+// kai-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-registry.tsx

@@ -0,0 +1,67 @@
+// src/primitives/card-registry.tsx
+// One source of truth mapping a CardEnvelope.type to a renderer, for both layers:
+//   - CardComponentMap drives the Solid <CardRenderer>.
+//   - CardTagMap drives the <kai-cards> web component (child kai-* elements).
+// Built-ins cover the 5 contract card types; consumers extend/override via a `types`
+// prop (merged OVER the built-ins). kai-card (bare shell) is intentionally NOT a target.
+import type { Component } from 'solid-js';
+import type { CardEnvelope, CardHost } from './card-contract';
+import { Form } from '../components/form';
+import { ConfirmCard } from '../components/confirm-card';
+import { TasksCard } from '../components/tasks-card';
+import { ChoiceCard } from '../components/choice-card';
+import { LinkPreview } from '../components/link-preview';
+import { Embed } from '../components/embed';
+
+/** Solid renderer for one envelope. `host` is the resolved CardHost so each wrapper
+ *  can bridge its card's emit convention (form/confirm/tasks take `host`;
+ *  link/embed take `onEmit`). */
+export type CardComponent = Component<{ envelope: CardEnvelope; host?: CardHost }>;
+export type CardComponentMap = Record<string, CardComponent>;
+
+/** Web-component layer: envelope type → kai-* tag name. */
+export type CardTagMap = Record<string, string>;
+
+export const BUILTIN_CARD_TAGS: CardTagMap = {
+  form: 'kai-form',
+  confirm: 'kai-confirm',
+  'tasks': 'kai-tasks',
+  choice: 'kai-choice',
+  link: 'kai-link-preview',
+  embed: 'kai-embed',
+};
+
+export const BUILTIN_CARD_COMPONENTS: CardComponentMap = {
+  form: (p) => (
+    <Form data={p.envelope.data as never} cardId={p.envelope.id} heading={p.envelope.title}
+      resolution={p.envelope.resolution} host={p.host} />
+  ),
+  confirm: (p) => (
+    <ConfirmCard data={p.envelope.data as never} cardId={p.envelope.id} heading={p.envelope.title}
+      resolution={p.envelope.resolution} host={p.host} />
+  ),
+  'tasks': (p) => (
+    <TasksCard data={p.envelope.data as never} cardId={p.envelope.id} heading={p.envelope.title}
+      resolution={p.envelope.resolution} host={p.host} />
+  ),
+  choice: (p) => (
+    <ChoiceCard data={p.envelope.data as never} cardId={p.envelope.id} heading={p.envelope.title}
+      resolution={p.envelope.resolution} host={p.host} />
+  ),
+  // link/embed have no `heading` and emit via an onEmit callback (no context).
+  link: (p) => (
+    <LinkPreview data={p.envelope.data as never} cardId={p.envelope.id} onEmit={(e) => p.host?.emit(e)} />
+  ),
+  embed: (p) => (
+    <Embed data={p.envelope.data as never} cardId={p.envelope.id} onEmit={(e) => p.host?.emit(e)} />
+  ),
+};
+
+/** Built-ins with the consumer's overrides merged on top (consumer wins). */
+export function mergeCardComponents(types?: CardComponentMap): CardComponentMap {
+  return types ? { ...BUILTIN_CARD_COMPONENTS, ...types } : { ...BUILTIN_CARD_COMPONENTS };
+}
+
+export function mergeCardTags(types?: CardTagMap): CardTagMap {
+  return types ? { ...BUILTIN_CARD_TAGS, ...types } : { ...BUILTIN_CARD_TAGS };
+}

package/src/primitives/card-resolution.ts

@@ -0,0 +1,36 @@
+// Pure consumer-facing helpers for the re-hydration round-trip. Feed a terminal
+// CardEvent back into the cards array so a resolved card survives reload:
+//   el.cards = applyResolution(el.cards, e.detail)
+// Deterministic — no Date (the optional `at` provenance is left to the consumer).
+import type { CardEnvelope, CardEvent, CardResolution } from './card-contract';
+
+/** Map a terminal CardEvent (`action` | `submit`) to a CardResolution.
+ *  Returns undefined for every non-terminal verb (ready/error/resize/state/…). */
+export function resolutionFromEvent(event: CardEvent): CardResolution | undefined {
+  if (event.kind === 'action') {
+    return {
+      kind: 'action',
+      action: event.action,
+      ...(event.payload !== undefined ? { payload: event.payload } : {}),
+    };
+  }
+  if (event.kind === 'submit') {
+    return { kind: 'submit', data: event.data };
+  }
+  return undefined;
+}
+
+/** Return a new cards array with the envelope matching `event.cardId` stamped with its
+ *  resolution. Non-terminal events or an unknown cardId return the SAME array reference
+ *  (cheap no-op; safe to call on every event). Never mutates the input. */
+export function applyResolution(cards: CardEnvelope[], event: CardEvent): CardEnvelope[] {
+  const resolution = resolutionFromEvent(event);
+  if (!resolution) return cards;
+  let changed = false;
+  const next = cards.map((c) => {
+    if (c.id !== event.cardId) return c;
+    changed = true;
+    return { ...c, resolution };
+  });
+  return changed ? next : cards;
+}

package/src/primitives/card-routing.ts

@@ -0,0 +1,79 @@
+// src/primitives/card-routing.ts
+// Framework-agnostic card-event plumbing: the bubbling kai-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 = 'kai-card';
+
+/** Dispatch a CardEvent as the bubbling, composed `kai-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(`[kai-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':
+      p.onSubmit ? p.onSubmit(event.cardId, event.data) : warnNoHandler('submit');
+      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 `kai-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);
+}