@kitn.ai/ui 0.20.1 → 0.21.0

package/src/primitives/card-data-types.ts

@@ -0,0 +1,312 @@
+// src/primitives/card-data-types.ts
+// The five built-in card PAYLOAD types — `CardEnvelope.data`, one per card type —
+// authored beside the schemas they mirror rather than inside the components that
+// render them.
+//
+// THE FOURTH INSTANCE OF ONE DEFECT, AND THE LAST ONE THAT WAS LEFT
+// -----------------------------------------------------------------
+// `BUILTIN_CARD_TAGS` (card-tags.ts), `CardComponentMap` (card-component-types.ts)
+// and the tag map before it were each pulled out of a `.tsx` for the same reason,
+// and each header says so. Read card-tags.ts first; this is the same problem one
+// layer further out, and the reason it is worth a fourth file rather than a fourth
+// exception is that these are the types a BACKEND names, which makes them the ones
+// with the least business living under a Solid component.
+//
+// `tsconfig.mcp.json` is Node-only — `lib: ["ESNext"]`, no `jsx` — and a type import
+// still has to RESOLVE even though it erases. While `ConfirmCardData` and friends
+// lived in components/confirm-card.tsx, any Node/no-DOM project that named one got
+//
+//   error TS6142: Module '../../components/choice-card' was resolved to
+//   '.../src/components/choice-card.tsx', but '--jsx' is not set.
+//
+// measured on this tree, and `@kitn.ai/ui/schemas` — the server-safe entry that
+// exists precisely so a route can hand a model tool definitions — could not
+// re-export them at all without dragging the Solid tree into that pass. So the one
+// language the kit is AUTHORED in was the only one that could not name the contract
+// it publishes: Python and Go read `./schemas/*.json` and get the full shape, while
+// a TypeScript backend building a card envelope got `data: unknown`.
+//
+// Relaxing tsconfig.mcp.json is not the alternative, and that is measured rather
+// than recalled: granting it `jsx: "preserve"` + `jsxImportSource: "solid-js"` takes
+// it from 0 errors to 130 on this exact case (838 without the import source, and
+// card-tags.ts records 1364 for the broader one), almost all `TS2304: Cannot find
+// name 'HTMLDivElement' / 'window'`, because a `jsx` setting drags the whole Solid
+// component tree into a Node-only pass. The Node/no-DOM boundary is load-bearing.
+//
+// WHY THEY ARE `type` ALIASES AND NOT `interface`S — DO NOT "TIDY" THIS BACK
+// --------------------------------------------------------------------------
+// This is the other half of the same story and it is not a style preference.
+// TypeScript gives an object TYPE ALIAS an implicit index signature and gives an
+// INTERFACE none. Measured, both directions, on a two-line file:
+//
+//   interface IFace { a: string }
+//   type    TAlias = { a: string }
+//   const r1: Record<string, unknown> = iface;  // TS2322: Index signature for type
+//                                               // 'string' is missing in type 'IFace'
+//   const r2: Record<string, unknown> = alias;  // OK
+//
+// Every card element's `data` prop is a `Record<string, unknown>` at some point in
+// the chain — the generated `element-types.d.ts` used to declare it that way
+// outright, and `renderType` in scripts/_ts-helpers.mjs still emits exactly that
+// string as its cycle placeholder when it inlines a self-referential type (which
+// `FormField` is). So as interfaces these types were not assignable to the very
+// property each one's own doc comment tells a consumer to assign it to:
+// `el.data = myChoiceCardData` was TS2322 while `<kai-choice>`'s JSDoc said "Import
+// `ChoiceCardData` from `@kitn.ai/ui` for the full shape".
+//
+// Aliases fix that at the root instead of at each of the four call sites, and they
+// are what makes `FormDefinition` work at all: it is self-referential, so the
+// generator can only inline it down to a `Record<string, unknown>` placeholder, and
+// an interface would fail against that placeholder no matter what the elements
+// declare.
+//
+// Nothing here merges declarations, so the one capability `interface` has that
+// `type` lacks is not in use.
+//
+// WHAT THIS FILE MAY CONTAIN
+// --------------------------
+// Types only, and only types with no DOM and no Solid below them. It must stay
+// importable from a Node process with no `jsx`, which is the whole point; the
+// discriminating check is `tsc --noEmit -p tsconfig.mcp.json` on a tree with no
+// `dist/` present, and nothing else is evidence for it. `CardEnvelope` below comes
+// from ./card-contract, which is already a `.ts` for the same reason.
+//
+// Each component re-exports its own types from here, so every existing importer of
+// `components/confirm-card` etc. is unaffected, and `@kitn.ai/ui/schemas` exports
+// them too so a backend route can finally name what it is building.
+
+import type { CardEnvelope } from './card-contract';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// confirm (confirm.schema.json)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type ConfirmActionStyle = 'primary' | 'default' | 'destructive';
+export type ConfirmTone = 'default' | 'warning' | 'danger';
+
+export type ConfirmAction = {
+  id: string;
+  label: string;
+  style?: ConfirmActionStyle;
+  payload?: unknown;
+  default?: boolean;
+};
+
+export type ConfirmCardData = {
+  heading?: string;
+  body?: string;
+  tone?: ConfirmTone;
+  actions: ConfirmAction[]; // 1..4
+  dismissible?: boolean;
+};
+
+export type ConfirmCardEnvelope = CardEnvelope<'confirm', ConfirmCardData>;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// choice (choice.schema.json)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type ChoiceOptionMedia = {
+  image?: string;
+  imageAlt?: string;
+  icon?: string;
+};
+
+export type ChoiceOption = {
+  id: string; // required, unique within the card
+  label: string; // required
+  description?: string;
+  media?: ChoiceOptionMedia;
+  meta?: string; // trailing freeform text (e.g. price/badge)
+  recommended?: boolean; // renders a "Recommended" pill
+  disabled?: boolean; // not selectable; skipped in keyboard nav
+  payload?: unknown; // echoed back in the emitted action
+};
+
+export type ChoiceAllowOther = boolean | { label?: string; placeholder?: string };
+
+export type ChoiceCardData = {
+  prompt?: string; // optional question/body above the options
+  options: ChoiceOption[]; // 1..N
+  allowOther?: ChoiceAllowOther; // free-text escape
+  submitLabel?: string; // label for the Submit button (default 'Submit')
+  dismissible?: boolean; // show a close affordance that emits `dismiss`
+};
+
+export type ChoiceCardEnvelope = CardEnvelope<'choice', ChoiceCardData>;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// tasks (tasks.schema.json)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type TasksTask = {
+  id: string;
+  label: string;
+  description?: string;
+  checked?: boolean;
+  disabled?: boolean;
+};
+
+export type TasksCardData = {
+  /**
+   * `select` (default) = checkbox rows + a confirm button that emits the contract
+   * `submit`. `progress` = an onboarding/checklist look: a header `done / total`
+   * count, circular indicators, per-item title + muted description, and NO confirm
+   * button (checking a row is itself the terminal action). Both share the same
+   * selection model (toggle by id, the `max` gate, `kai-value-change`); `progress`
+   * is purely a presentational variant.
+   */
+  mode?: 'select' | 'progress';
+  heading?: string;
+  tasks: TasksTask[]; // >=1
+  selectAll?: boolean;
+  confirmLabel?: string;
+  allowEmpty?: boolean;
+  min?: number;
+  max?: number;
+  dismissible?: boolean; // show a close affordance that emits `dismiss`
+};
+
+export type TasksCardResult = {
+  selected: string[];
+};
+
+export type TasksCardEnvelope = CardEnvelope<'tasks', TasksCardData>;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// form (form.schema.json)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** A field definition (the JSON Schema subset kai-form renders). */
+export type FormField = {
+  type: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object';
+  title?: string;
+  description?: string;
+  default?: unknown;
+  enum?: unknown[];
+  format?: 'email' | 'uri' | 'url' | 'date' | 'date-time' | 'time';
+  minimum?: number;
+  maximum?: number;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  minItems?: number;
+  maxItems?: number;
+  items?: FormField | { enum: unknown[] };
+  properties?: Record<string, FormField>;
+  required?: string[];
+  readOnly?: boolean;
+  'x-kai-widget'?:
+    | 'textarea'
+    | 'slider'
+    | 'rating'
+    | 'radio'
+    | 'select'
+    | 'checkbox'
+    | 'password'
+    | 'switch';
+  'x-kai-placeholder'?: string;
+  'x-kai-step'?: number;
+};
+
+/** The form definition = CardEnvelope.data for type:'form'. */
+export type FormDefinition = {
+  type: 'object';
+  title?: string;
+  description?: string;
+  required?: string[];
+  properties: Record<string, FormField>;
+  'x-kai-order'?: string[];
+  'x-kai-inlineMax'?: number;
+  'x-kai-submitLabel'?: string;
+  'x-kai-dismissible'?: boolean;
+  'x-kai-actions'?: { id: string; label: string; variant?: 'default' | 'ghost' | 'outline' }[];
+};
+
+export type FormCardEnvelope = CardEnvelope<'form', FormDefinition>;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// artifact (artifact.schema.json)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * One file behind an artifact card: the Code tab's tree row, plus where the
+ * preview loads it.
+ *
+ * The SAME declaration the `FileTree` primitive uses — `components/file-tree.tsx`
+ * re-exports this as `FileTreeFile` and `components/artifact.tsx` aliases that to
+ * `ArtifactFile`, so there is one shape here and not a copy of one. It is authored
+ * in this file rather than in file-tree.tsx for this module's whole reason: it is
+ * reachable from `ArtifactCardData`, so leaving it in a `.tsx` would put TS6142
+ * back on any Node/no-DOM project that names an artifact card payload, and the
+ * extraction would have moved four of five types and quietly failed on the fifth.
+ * It mirrors `artifact.schema.json`'s `files[].items`, which carries the same
+ * fields with `additionalProperties: false`.
+ */
+export type ArtifactCardFile = {
+  /** Tree label/key. Folders are built from `/`-delimited segments. */
+  path: string;
+  /** Where the preview loads it (CDN/S3/dev-server/API). */
+  url?: string;
+  /** Source for the Code tab. */
+  code?: string;
+  /** Language id for syntax highlighting (e.g. `html`, `css`, `tsx`). */
+  language?: string;
+  /** Kind — drives the icon + whether Code applies. */
+  type?: 'html' | 'pdf' | 'image' | 'other';
+  /** Lines added vs the base. Rendered as a trailing `+N` stat (success hue,
+   *  tabular-nums). Only shown when present; omit for a plain file row. */
+  additions?: number;
+  /** Lines removed vs the base. Rendered as a trailing `-N` stat (error hue). */
+  deletions?: number;
+  /** Change status vs the base. Drives a small trailing status letter in the
+   *  conventional VCS hue (added=green, modified=amber, deleted=red,
+   *  renamed=blue, untracked=muted). Only shown when present. */
+  status?: 'added' | 'modified' | 'deleted' | 'renamed' | 'untracked';
+};
+
+/** Which view an artifact card opens on. */
+export type ArtifactCardTab = 'preview' | 'code';
+
+/** The `artifact` card payload: a deliberately NARROW subset of `ArtifactProps`.
+ *
+ *  A card envelope is written by a model, so the surface it can reach has to be
+ *  the part that describes WHAT to show, not how the viewer behaves. Toolbar
+ *  composition (`showNav`/`showTabs`/…), view-state (`maximized`), the iframe
+ *  `sandbox` and the imperative `controllerRef` are all host concerns and stay
+ *  off the wire — a model must not be able to widen its own sandbox or hide the
+ *  chrome the user needs to inspect what it built. */
+export type ArtifactCardData = {
+  /** URL the preview iframe frames. */
+  src?: string;
+  /** Files for the Code tab's tree (+ each file's preview `url`). */
+  files?: ArtifactCardFile[];
+  /** Which view the card OPENS on: `preview` (default) or `code`.
+   *
+   *  Seed only, and deliberately so. This card exists to be revised — `addCard`
+   *  upserts on `envelope.id` — and a revision hands the same live component a
+   *  new envelope. Were this wired to `Artifact`'s CONTROLLED `tab` prop, every
+   *  revision would re-assert it and yank a user who had switched views back to
+   *  the model's choice. A model cannot move the user between tabs after the
+   *  first render; the user's choice wins. */
+  tab?: ArtifactCardTab;
+  /** Path of the file selected in the tree when the card first renders.
+   *
+   *  Seed only, for the same reason as `tab`, but achieved differently:
+   *  `Artifact` has a `defaultTab` prop to seed the tab and no `defaultActiveFile`
+   *  counterpart, so this is read ONCE via `untrack` at setup and handed over as
+   *  a static value. That leaves `Artifact`'s unconditional
+   *  `createEffect(() => setActiveFile(local.activeFile))` with nothing reactive
+   *  to track, so it runs once instead of resetting the user's selection on
+   *  every revision. Keep it static — passing `props.data.activeFile` straight
+   *  through would silently restore that bug. */
+  activeFile?: string;
+  /** Friendly address shown INSTEAD of the real url. Use when `src` is not
+   *  consumer-facing (e.g. a `data:` blob) so a clean address is shown. */
+  displayUrl?: string;
+  /** Frame height. A bare number is px; a string is any CSS length. Defaults to
+   *  `DEFAULT_ARTIFACT_CARD_HEIGHT` — see the note on ArtifactCard. */
+  height?: number | string;
+};
+
+export type ArtifactCardEnvelope = CardEnvelope<'artifact', ArtifactCardData>;

package/src/primitives/card-recovery.ts

@@ -96,9 +96,20 @@ function resolutionOf(cards: CardEnvelope[], cardId: string): CardResolution | u
   return cards.find((c) => c.id === cardId)?.resolution;
 }
 
+// On the return type — `Required<Pick<…>>`, not a bare `Pick`. Both members are
+// optional on CardPolicy, which is right there, where a host supplies one, the other,
+// or neither; but `Pick` carries the `?` across even though the body below returns
+// both handlers on every path, so the declaration said "may be missing" about two
+// things that never are. That was consumer-facing, not internal tidiness: this
+// function is exported from src/index.ts and the MCP scaffolder emits
+// `const { onDismiss, onReopen } = dismissRecovery({…})`, so anyone who destructured
+// and then INVOKED a handler hit TS2722 in code we generated for them. Assigning the
+// result straight into a CardPolicy stays fine either way, both fields being optional
+// there, which is why it stayed invisible. tests/primitives/card-recovery.test.ts pins
+// the runtime side over the full cross-product of the optional options.
 /**
  * Build the `{ onDismiss, onReopen }` policy handlers for the card dismiss/recovery
- * flow over a host store (`get`/`set`).
+ * flow over a host store (`get`/`set`). Both handlers are always returned.
  *
  * - `onDismiss(cardId)` — stamps `{ kind:'dismissed', at }` immutably and, when a
  *   `toast` is injected, shows "Dismissed" with an Undo that restores the card's
@@ -108,7 +119,7 @@ function resolutionOf(cards: CardEnvelope[], cardId: string): CardResolution | u
  */
 export function dismissRecovery(
   opts: DismissRecoveryOptions,
-): Pick<CardPolicy, 'onDismiss' | 'onReopen'> {
+): Required<Pick<CardPolicy, 'onDismiss' | 'onReopen'>> {
   const now = opts.now ?? (() => Date.now());
   const reopenable = opts.isReopenable ?? ((env: ReopenEnv) => defaultIsReopenable(env, opts.staleAfterMs));
   const undoMs = opts.undoMs ?? 6000;

package/src/primitives/card-registry.tsx

@@ -2,34 +2,43 @@
 // 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`
+// Built-ins cover the 7 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';
+//
+// THE TAG HALF NOW LIVES IN ./card-tags — AND MUST STAY THERE.
+// `BUILTIN_CARD_TAGS` / `mergeCardTags` / `CardTagMap` are plain data with no Solid in
+// them, but while they shared this module with `BUILTIN_CARD_COMPONENTS` no Node/no-DOM
+// project could import them AS SOURCE, and the `kai` MCP re-derived the map by
+// convention as a result. ./card-tags.ts is that data on its own so
+// `@kitn.ai/ui/schemas` can export it; the re-export below keeps every existing
+// importer of this module working unchanged. Do not move them back — see the header
+// of ./card-tags.ts for the measured cost of the alternative (0 -> 1364 tsc errors).
+//
+// THE COMPONENT TYPES NOW LIVE IN ./card-component-types — SAME REASON, SECOND TIME.
+// `CardComponent` / `CardComponentMap` are named in the PUBLIC surface of
+// `@kitn.ai/ui/schemas` (src/schemas/registry.ts), so a Node/no-DOM project resolving
+// that entry's types reached this `.tsx` and hit TS6142. The types went to a `.ts`;
+// `BUILTIN_CARD_COMPONENTS` and `mergeCardComponents` stayed, because they are JSX and
+// have nowhere to go. Re-exported below, so this module's surface is unchanged.
+import type { CardComponentMap } from './card-component-types';
 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';
+import { ArtifactCard, type ArtifactCardData } from '../components/artifact-card';
 
-/** 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>;
+// The tag half, re-exported so this module's surface is unchanged. Authored in
+// ./card-tags.ts because that file has no Solid below it and can therefore be read
+// from a Node process; this one cannot.
+export { BUILTIN_CARD_TAGS, mergeCardTags } from './card-tags';
+export type { CardTagMap } from './card-tags';
 
-/** 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',
-};
+// The component TYPES, re-exported for the same reason. Authored in
+// ./card-component-types.ts because resolving a `.tsx` is what a no-`jsx` project
+// cannot do; the values below stay here because they are JSX.
+export type { CardComponent, CardComponentMap } from './card-component-types';
 
 export const BUILTIN_CARD_COMPONENTS: CardComponentMap = {
   form: (p) => (
@@ -55,13 +64,15 @@ export const BUILTIN_CARD_COMPONENTS: CardComponentMap = {
   embed: (p) => (
     <Embed data={p.envelope.data as never} cardId={p.envelope.id} onEmit={(e) => p.host?.emit(e)} />
   ),
+  // artifact owns real chrome of its own (sizing + heading), so like the four
+  // above it lives in components/ and gets only a thin wrapper here.
+  artifact: (p) => (
+    <ArtifactCard data={p.envelope.data as ArtifactCardData} cardId={p.envelope.id}
+      heading={p.envelope.title} host={p.host} />
+  ),
 };
 
 /** 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-schemas/artifact.schema.json

@@ -0,0 +1,92 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kitn.ai/schemas/card/artifact.schema.json",
+  "title": "ArtifactCardData",
+  "description": "Generated-artifact viewer payload: a framed preview plus the source files behind it. A deliberately NARROW subset of the Artifact component's props — it says WHAT to show, never how the viewer behaves. Toolbar composition, view-state and the iframe `sandbox` are host-owned and stay off the wire, so a model cannot widen its own sandbox or hide the chrome the user needs to inspect what it built.",
+  "type": "object",
+  "additionalProperties": false,
+  "anyOf": [{ "required": ["src"] }, { "required": ["files"] }],
+  "properties": {
+    "src": {
+      "type": "string",
+      "format": "uri",
+      "description": "URL the preview iframe frames, and the target of the Home button. Omit for a source-only artifact (`tab: 'code'` with `files`).",
+      "x-kai-format": "url"
+    },
+    "files": {
+      "type": "array",
+      "description": "Files behind the artifact: the Code tab's tree, each optionally carrying its own preview url and source.",
+      "maxItems": 500,
+      "items": {
+        "type": "object",
+        "required": ["path"],
+        "additionalProperties": false,
+        "properties": {
+          "path": {
+            "type": "string",
+            "description": "Tree label/key. Folders are built from `/`-delimited segments.",
+            "maxLength": 1024
+          },
+          "url": {
+            "type": "string",
+            "format": "uri",
+            "description": "Where the preview loads this file. Defaults to `path` resolved against `src`.",
+            "x-kai-format": "url"
+          },
+          "code": {
+            "type": "string",
+            "description": "Source shown in the Code tab. Omit for binary files (image/pdf), which have no code view."
+          },
+          "language": {
+            "type": "string",
+            "description": "Language id for syntax highlighting (e.g. 'html', 'css', 'tsx').",
+            "maxLength": 40
+          },
+          "type": {
+            "type": "string",
+            "enum": ["html", "pdf", "image", "other"],
+            "description": "File kind. Drives the tree icon and whether the Code view applies; 'pdf' also routes the preview to the inline PDF viewer.",
+            "x-kai-control": "select"
+          },
+          "additions": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Lines added vs the base. Rendered as a trailing '+N' stat."
+          },
+          "deletions": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Lines removed vs the base. Rendered as a trailing '-N' stat."
+          },
+          "status": {
+            "type": "string",
+            "enum": ["added", "modified", "deleted", "renamed", "untracked"],
+            "description": "Change status vs the base. Drives a trailing status letter in the conventional VCS hue.",
+            "x-kai-control": "select"
+          }
+        }
+      }
+    },
+    "tab": {
+      "type": "string",
+      "enum": ["preview", "code"],
+      "default": "preview",
+      "description": "Which view the card OPENS on. SEED ONLY: the user can switch freely afterwards and a revision of this card will NOT move them back, because the user's choice wins over the model's. A switch is reported back as a `state` patch.",
+      "x-kai-control": "select"
+    },
+    "activeFile": {
+      "type": "string",
+      "description": "Path of the file selected in the tree when the card FIRST renders (must match a `files[].path`). Seeds the tree highlight, the Code source and the preview. SEED ONLY, like `tab`: revising this card will not move a user who has since selected a different file.",
+      "maxLength": 1024
+    },
+    "displayUrl": {
+      "type": "string",
+      "description": "Friendly address shown in the path field INSTEAD of the real url, which also makes the field read-only. Use when `src` is not consumer-facing (e.g. a `data:` blob) so a clean address is shown rather than leaking it.",
+      "maxLength": 2048
+    },
+    "height": {
+      "description": "Frame height. A bare number is px; a string is any CSS length. Defaults to 420px. REQUIRED CONCEPT, not decoration: the viewer is built to fill its container, and a message thread supplies no height, so the card sets one explicitly or the artifact collapses to zero and renders invisible.",
+      "oneOf": [{ "type": "number", "minimum": 1 }, { "type": "string", "maxLength": 32 }]
+    }
+  }
+}

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

@@ -4,8 +4,6 @@
   "title": "EmbedCardData",
   "description": "Lazy media-embed payload (YouTube / Vimeo / generic player URL).",
   "type": "object",
-  "x-kai-card-type": "embed",
-  "x-kai-contract-version": "1",
   "required": ["provider"],
   "additionalProperties": false,
   "properties": {

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

@@ -4,8 +4,6 @@
   "title": "LinkPreviewData",
   "description": "Rich link / Open-Graph preview payload. The card renders from this; it never fetches.",
   "type": "object",
-  "x-kai-card-type": "link",
-  "x-kai-contract-version": "1",
   "required": ["url"],
   "additionalProperties": false,
   "properties": {

package/src/primitives/card-tags.ts

@@ -0,0 +1,61 @@
+// src/primitives/card-tags.ts
+// `CardEnvelope.type` -> the `kai-*` element that renders it. The authoritative map,
+// and the ONLY place it is written down.
+//
+// WHY IT IS ALONE IN A `.ts`
+// --------------------------
+// It used to live in card-registry.tsx beside `BUILTIN_CARD_COMPONENTS`, which is
+// nothing but Solid. The map itself has no Solid in it — it is `Record<string, string>`
+// — but sharing a module with the component map meant no Node/no-DOM project could
+// import it AS SOURCE, and the `kai` MCP server is exactly that: tsconfig.mcp.json is
+// Node-only, `lib: ["ESNext"]`, no `jsx`. So src/agent-tooling/mcp/manifest.ts
+// RE-DERIVED each tag by convention (`kai-<type>`, else the single `kai-<type>-*`) —
+// a second copy of a fact this repo already held, one that happened to agree.
+//
+// Relaxing tsconfig.mcp.json instead is not an option and was measured, not guessed:
+// giving that project a `jsx` setting drags the Solid component tree into a Node-only
+// pass and takes it from 0 errors to 1364. The Node/no-DOM boundary is load-bearing.
+// Splitting the data out is the fix; this file is that split.
+//
+// Because it is plain data with no DOM and no Solid runtime below it,
+// `@kitn.ai/ui/schemas` — the server-safe entry a backend route imports — re-exports
+// it, so the MCP and any consumer route read the same map instead of guessing at it.
+// card-registry.tsx re-exports everything here in turn, so every existing importer of
+// `BUILTIN_CARD_TAGS` / `mergeCardTags` / `CardTagMap` is unaffected.
+//
+// WHAT THIS SPLIT DOES NOT DO, MEASURED
+// -------------------------------------
+// It does not change dist/schemas.js. Routing that entry's re-export back through
+// card-registry.tsx yields a byte-identical bundle with zero `solid-js` references
+// that imports clean under `node`: rollup compiles the Solid tree and discards it,
+// since only the tag map is reachable. So no runtime guard tells the two apart, and
+// this file must not be sold as one. What it changes is the dependency GRAPH — the
+// server-safe entry no longer reaches the component tree at all, instead of reaching
+// it and counting on tree-shaking to undo that. See src/schemas/index.ts.
+//
+// Built-ins cover the 7 contract card types; consumers extend/override via a `types`
+// prop (merged OVER the built-ins). kai-card (bare shell) is intentionally NOT a target.
+
+/** Web-component layer: envelope type → kai-* tag name. */
+export type CardTagMap = Record<string, string>;
+
+/**
+ * The seven built-in card types and the element that draws each one.
+ *
+ * Note `link` → `kai-link-preview`: the one entry that is NOT `kai-<type>`, and the
+ * reason inferring these from the tag list is a guess rather than a lookup.
+ */
+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',
+  artifact: 'kai-artifact',
+};
+
+/** Built-ins with the consumer's overrides merged on top (consumer wins). */
+export function mergeCardTags(types?: CardTagMap): CardTagMap {
+  return types ? { ...BUILTIN_CARD_TAGS, ...types } : { ...BUILTIN_CARD_TAGS };
+}