@kitn.ai/ui 0.20.1 → 0.21.0

package/dist/remote/host-embed.d.ts

@@ -1,4 +1,4 @@
-import { CardEnvelope, CardContext, CardPolicy } from '../primitives/card-contract';
+import { CardEnvelope, CardContext, CardPolicy } from '../primitives/card-contract.js';
 export interface MountRemoteCardOptions {
     /** Where to mount the iframe. */
     container: HTMLElement;

package/dist/remote/index.d.ts

@@ -1,2 +1,2 @@
-export { mountRemoteCard } from './host-embed';
-export type { MountRemoteCardOptions, RemoteCardHandle } from './host-embed';
+export { mountRemoteCard } from './host-embed.js';
+export type { MountRemoteCardOptions, RemoteCardHandle } from './host-embed.js';

package/dist/remote/provider-runtime.d.ts

@@ -1,5 +1,5 @@
-import { CardEnvelope, CardHost } from '../primitives/card-contract';
-import { JsonSchema } from '../primitives/card-validate';
+import { CardEnvelope, CardHost } from '../primitives/card-contract.js';
+import { JsonSchema } from '../primitives/card-validate.js';
 /** A provider-side renderer for one card `type`. Renamed (was CardRenderer) per H-K
  *  to avoid colliding with the exported Solid `<CardRenderer>` component. */
 export interface RemoteCardRenderer {

package/dist/remote/provider.d.ts

@@ -1,2 +1,2 @@
-export { createCardBridge } from './provider-runtime';
-export type { RemoteCardRenderer, CardBridge } from './provider-runtime';
+export { createCardBridge } from './provider-runtime.js';
+export type { RemoteCardRenderer, CardBridge } from './provider-runtime.js';

package/dist/remote/validate.d.ts

@@ -1,4 +1,4 @@
-import { CardEventKind } from '../primitives/card-contract';
+import { CardEventKind } from '../primitives/card-contract.js';
 /** Recursive guard (H-D): nested data/patch/context are forwarded to app handlers. */
 export declare function hasPollutionKey(value: unknown): boolean;
 export declare function isKnownEventKind(k: unknown): k is CardEventKind;

package/dist/remote/wire.d.ts

@@ -1,4 +1,4 @@
-import { CardEnvelope, CardContext, CardEvent } from '../primitives/card-contract';
+import { CardEnvelope, CardContext, CardEvent } from '../primitives/card-contract.js';
 export declare const CARD_WIRE_PROTOCOL: "kitn-card";
 export interface WireFrame<M extends WireMessage = WireMessage> {
     protocol: typeof CARD_WIRE_PROTOCOL;

package/dist/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/dist/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/dist/schemas/from-tool-call.d.ts

@@ -0,0 +1,48 @@
+import { CardEnvelope } from '../primitives/card-contract.js';
+/**
+ * The tool-name prefix that marks a card tool.
+ *
+ * Prefixed so a developer's own `confirm` tool cannot collide with ours, and
+ * exported as a value so `cardTools()` names its tools from here instead of
+ * restating the literal. A prefix written in two places is a prefix that can drift.
+ */
+export declare const KAI_TOOL_PREFIX = "kai_";
+/**
+ * The card type a tool name denotes, or `null` if the name is not a card tool.
+ *
+ * The single decision both public predicates below are derived from. The remainder
+ * after the prefix is used verbatim: card types may contain hyphens
+ * (`kai_pricing-table` -> `pricing-table`), and both providers accept
+ * `[a-zA-Z0-9_-]` in a tool name, so there is nothing to translate. Matching is
+ * case-sensitive, because tool names are.
+ */
+export declare function cardTypeFromToolName(name: string): string | null;
+/** The tool name for a card type. The exact inverse of {@link cardTypeFromToolName}. */
+export declare function toolNameForCardType(type: string): string;
+/**
+ * Is this tool call a card, rather than one of the app's own tools?
+ *
+ * True for any `kai_`-prefixed name with a non-empty remainder. It does NOT claim
+ * the type is registered or the data is valid; see the module header for why those
+ * are the dispatcher's questions.
+ */
+export declare function isCardTool(name: string): boolean;
+/**
+ * Turn a model's tool call into a `CardEnvelope`, or `null` if it is not a card tool.
+ *
+ * @param name  the tool name the model called, e.g. `kai_confirm`
+ * @param input the tool arguments, used verbatim as `CardEnvelope.data`
+ * @param opts.id the provider's `tool_call_id`, used verbatim as `CardEnvelope.id`
+ *
+ * `data` is the input as given: the tool's input schema IS the card-data schema that
+ * `cardTools()` handed the model, so the mapping is identity and nothing is peeled,
+ * renamed or defaulted. In particular no `title` is set. `CardEnvelope.title` is
+ * chrome the host owns and no card-data schema offers the model one (`confirm`
+ * deliberately calls its in-body heading `heading` and says so in its description),
+ * so a caller who wants a title writes `{ ...card, title }`.
+ *
+ * Never throws.
+ */
+export declare function cardFromToolCall(name: string, input: unknown, opts: {
+    id: string;
+}): CardEnvelope | null;

package/dist/schemas/index.d.ts

@@ -0,0 +1,48 @@
+import { JsonSchema } from '../primitives/card-validate.js';
+/**
+ * A card schema document, as authored.
+ *
+ * Wider than {@link JsonSchema} on purpose. `JsonSchema` describes the LEAN subset
+ * `validateAgainstSchema` implements; the files also carry `$schema`, `$id`,
+ * `title`, `description`, `default`, `additionalProperties`, `x-kai-*`, and (in
+ * `embed` and `artifact`) `allOf`/`if`/`then`/`oneOf`. Reading a document as
+ * `JsonSchema` alone would quietly imply the validator understands all of it.
+ */
+export type CardSchema = JsonSchema & Readonly<Record<string, unknown>>;
+/**
+ * The card-DATA schemas: one per built-in `CardEnvelope.type`, describing the
+ * `data` payload for that type. These are the tool candidates. The key IS the
+ * envelope type.
+ */
+export type CardSchemaName = 'artifact' | 'choice' | 'confirm' | 'embed' | 'form' | 'link' | 'tasks';
+/**
+ * The contract shapes: the envelope itself, the event a card emits back up, and the
+ * two result payloads. Not card data and NOT tool candidates — a model is never
+ * asked to emit one of these, so keeping them out of `cardSchemas` is what stops
+ * `cardTools()` offering the model an envelope-shaped tool.
+ */
+export type ContractSchemaName = 'card-envelope' | 'card-event' | 'form.result' | 'tasks.result';
+/** The 7 card-data schemas, keyed by `CardEnvelope.type`. */
+export declare const cardSchemas: Readonly<Record<CardSchemaName, CardSchema>>;
+/** The 4 contract shapes, keyed by file stem. */
+export declare const contractSchemas: Readonly<Record<ContractSchemaName, CardSchema>>;
+/** The built-in card types, in the order `cardSchemas` declares them. */
+export declare const cardSchemaNames: readonly CardSchemaName[];
+/** Narrow an arbitrary string to a built-in card type. */
+export declare function isCardSchemaName(name: string): name is CardSchemaName;
+export type { JsonSchema, ValidationResult } from '../primitives/card-validate.js';
+export type { CardEnvelope } from '../primitives/card-contract.js';
+export type { ArtifactCardData, ArtifactCardEnvelope, ArtifactCardFile, ArtifactCardTab, ChoiceAllowOther, ChoiceCardData, ChoiceCardEnvelope, ChoiceOption, ChoiceOptionMedia, ConfirmAction, ConfirmActionStyle, ConfirmCardData, ConfirmCardEnvelope, ConfirmTone, FormCardEnvelope, FormDefinition, FormField, TasksCardData, TasksCardEnvelope, TasksCardResult, TasksTask, } from '../primitives/card-data-types.js';
+export type { EmbedCardData, EmbedCardEnvelope, EmbedProvider } from '../primitives/embed-providers.js';
+export type { LinkPreviewData, LinkPreviewEnvelope } from '../primitives/link-preview.js';
+export { cardFromToolCall, isCardTool, cardTypeFromToolName, toolNameForCardType, KAI_TOOL_PREFIX } from './from-tool-call.js';
+export { CARD_TOOL_DESCRIPTIONS, UnsupportedCardToolSchemaError, cardTools, toAnthropicTools, toJsonSchemaTools, toOpenAITools, } from './tool-defs.js';
+export type { AnthropicToolDef, CardToolInput, CardToolOptions, CardToolSource, JsonSchemaToolDef, OpenAIToolDef, ToolDef, ToolDefFor, ToolParameters, ToolProvider, UnsupportedCardTool, } from './tool-defs.js';
+export { createCardRegistry } from './registry.js';
+export type { CardRegistry, CardRegistrySpec, CustomCardSpec, IncompletePolicy } from './registry.js';
+export { cardValidationMessage, validateCardData } from '../primitives/card-validate-cards.js';
+export type { CardValidationIssue, CardValidationReport, CardValidationTier } from '../primitives/card-validate-cards.js';
+export { BUILTIN_CARD_TAGS } from '../primitives/card-tags.js';
+export type { CardTagMap } from '../primitives/card-tags.js';
+export { ANTHROPIC_STRICT, OPENAI_STRICT, checkProviderSubset, providerSubsets } from './provider-subsets.js';
+export type { KeywordRule, KeywordStatus, ProviderSubset, StrictProviderId, SubsetViolation } from './provider-subsets.js';

package/dist/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/dist/schemas/provider-subsets.d.ts

@@ -0,0 +1,136 @@
+/** The providers whose strict subsets are documented here. */
+export type StrictProviderId = 'openai' | 'anthropic';
+/**
+ * How a table classifies one keyword.
+ *
+ * `annotation` is not a synonym for `supported`. JSON Schema annotations (
+ * `title`, `description`, `examples`, ...) do not constrain an instance, so a
+ * grammar compiler has nothing to compile from them and cannot reject them. They are
+ * separated from `supported` so that a table entry answers "the provider documents
+ * this" distinctly from "this cannot affect the grammar either way".
+ */
+export type KeywordStatus = 'supported' | 'unsupported' | 'annotation';
+export interface KeywordRule {
+    readonly status: KeywordStatus;
+    /** Why, in the words of the source doc where possible. Surfaced in the error. */
+    readonly note: string;
+    /**
+     * A value-level constraint on an otherwise supported keyword. Returns a reason
+     * string when the specific VALUE is out of subset, or null when it is fine.
+     * This is where `minItems: 2` on Anthropic and `format: "uri"` on OpenAI live:
+     * the keyword is supported, the value is not.
+     */
+    readonly value?: (value: unknown) => string | null;
+}
+export interface ProviderSubset {
+    readonly id: StrictProviderId;
+    readonly label: string;
+    /** The page these rules were read off. Quoted in every violation message. */
+    readonly source: string;
+    /** ISO date the source was last read. Rules go stale; this says how stale. */
+    readonly checkedOn: string;
+    readonly keywords: Readonly<Record<string, KeywordRule>>;
+    /** Every object subschema must carry `additionalProperties: false`. */
+    readonly requireAdditionalPropertiesFalse: boolean;
+    /** Every key of `properties` must appear in `required` (OpenAI's rule, not Anthropic's). */
+    readonly requireAllPropertiesRequired: boolean;
+    /** Whether the ROOT schema may carry `anyOf`. */
+    readonly allowRootAnyOf: boolean;
+    /** Whether `$ref` may point at an ancestor (recursion). */
+    readonly allowRecursion: boolean;
+}
+/**
+ * OpenAI strict function calling / structured outputs.
+ *
+ * SOURCE: https://developers.openai.com/api/docs/guides/structured-outputs
+ * (sections "Supported schemas", "Supported properties", "Some type-specific
+ * keywords are not yet supported"), read 2026-08-11. The older
+ * platform.openai.com/docs/guides/structured-outputs URL 301s here.
+ *
+ * Quoted from that page:
+ * - supported types: "String, Number, Boolean, Integer, Object, Array, Enum, anyOf"
+ * - "Objects have `additionalProperties: false` must always be set"
+ * - "All fields or function parameters must be specified as `required`" (an optional
+ *   field is emulated with a union type including `null`)
+ * - supported String properties: `pattern`, `format`
+ * - supported Number properties: `multipleOf`, `maximum`, `exclusiveMaximum`,
+ *   `minimum`, `exclusiveMinimum`
+ * - supported Array properties: `minItems`, `maxItems`
+ * - not supported, composition: "`allOf`, `not`, `dependentRequired`,
+ *   `dependentSchemas`, `if`, `then`, `else`"
+ * - "Root level object of a schema must be an object, and not use `anyOf`"
+ *
+ * ONE JUDGEMENT CALL, RECORDED BECAUSE IT IS A COIN FLIP.
+ * `minLength` / `maxLength` are absent from "Supported properties", which lists only
+ * `pattern` and `format` for strings. They appear once elsewhere, in the list of what
+ * is "additionally" unsupported for FINE-TUNED models, which can be read as implying
+ * base models do support them. The docs do not settle it. This table takes the
+ * allowlist reading (unsupported) because the two ways of being wrong are not
+ * symmetric: a wrong `supported` is a 400 at request time in the developer's
+ * production app with nothing local to look at, while a wrong `unsupported` is a
+ * throw on their own machine that names the keyword and the source, which they can
+ * read and argue with. If OpenAI clarifies, change this entry and the guard's
+ * expectations follow automatically.
+ */
+export declare const OPENAI_STRICT: ProviderSubset;
+/**
+ * Anthropic strict tool use (`strict: true` on a tool definition).
+ *
+ * SOURCE: https://platform.claude.com/docs/en/build-with-claude/structured-outputs
+ * ("JSON Schema limitations"), read 2026-08-11. The strict-tool-use page
+ * (https://platform.claude.com/docs/en/agents-and-tools/tool-use/strict-tool-use)
+ * carries the envelope shape and defers the keyword list to that section verbatim:
+ * "For the supported JSON Schema subset, see JSON Schema limitations".
+ *
+ * Quoted supported list:
+ * - "All basic types: object, array, string, integer, number, boolean, null"
+ * - "`enum` (strings, numbers, bools, or nulls only - no complex types)"
+ * - "`const`"
+ * - "`anyOf` and `allOf` (with limitations - `allOf` with `$ref` not supported)"
+ * - "`$ref`, `$def`, and `definitions` (external `$ref` not supported)"
+ * - "`default` property for all supported types"
+ * - "`required` and `additionalProperties` (must be set to `false` for objects)"
+ * - "String formats: `date-time`, `time`, `date`, `duration`, `email`, `hostname`,
+ *   `uri`, `ipv4`, `ipv6`, `uuid`"
+ * - "Array `minItems` (only values 0 and 1 supported)"
+ *
+ * Quoted NOT supported list:
+ * - "Recursive schemas"
+ * - "Complex types within enums"
+ * - "External `$ref`"
+ * - "Numerical constraints (such as `minimum`, `maximum`, `multipleOf`)"
+ * - "String constraints (`minLength`, `maxLength`)"
+ * - "Array constraints beyond `minItems` of 0 or 1"
+ * - "`additionalProperties` set to anything other than `false`"
+ *
+ * TWO PLACES THIS DIVERGES FROM WHAT THE PLAN ASSUMED, both checked twice:
+ * 1. `allOf` IS supported here (it is unsupported on OpenAI). What the kit's `embed`
+ *    schema actually trips on under Anthropic is the `if`/`then` INSIDE its `allOf`,
+ *    which the supported list does not mention and which is therefore unsupported.
+ * 2. `pattern` is NOT in the supported list here, though it is on OpenAI. The
+ *    supported string surface on Anthropic is `format` and nothing else.
+ * Optional properties are fine here: the doc's own quick-start example ships
+ * `required: ["location"]` with a second, unlisted `unit` property.
+ */
+export declare const ANTHROPIC_STRICT: ProviderSubset;
+/** The two subsets, by provider id. */
+export declare const providerSubsets: Readonly<Record<StrictProviderId, ProviderSubset>>;
+export interface SubsetViolation {
+    /** Where in the schema, in readable form: `(root)`, `actions`, `actions[].id`. */
+    readonly path: string;
+    /** The offending keyword, NAMED. Never a generic "unsupported schema". */
+    readonly keyword: string;
+    readonly reason: string;
+}
+/**
+ * Check a schema document against a provider's strict subset.
+ *
+ * Returns EVERY violation, not the first, and names the keyword and the path for
+ * each. A caller that only wants to know "can this be strict" checks `.length`.
+ *
+ * This runs against whatever it is handed. Point it at an authored card schema and
+ * it reports what the projection has to deal with; point it at a projected one and
+ * a non-empty result means the projection emitted something the provider would 400
+ * on, which is the self-consistency property `verify:tool-schemas` asserts.
+ */
+export declare function checkProviderSubset(schema: unknown, subset: ProviderSubset): SubsetViolation[];

package/dist/schemas/registry.d.ts

@@ -0,0 +1,140 @@
+import { CardComponentMap } from '../primitives/card-component-types.js';
+import { CardTagMap } from '../primitives/card-tags.js';
+import { JsonSchema } from '../primitives/card-validate.js';
+import { CardValidationReport } from '../primitives/card-validate-cards.js';
+import { CardSchema, CardSchemaName } from './index.js';
+import { CardToolSource } from './tool-defs.js';
+/**
+ * One custom card type: what the model should be told, and what draws it.
+ *
+ * Every member is optional because the useful combinations genuinely differ. A
+ * web-component consumer supplies `tag`; a Solid consumer supplies `component`; a
+ * backend-only registry (a route that builds tool definitions and never renders)
+ * supplies neither. Only `schema` carries a warning when absent, and the reason is on
+ * {@link CardRegistrySpec.onIncomplete}.
+ */
+export interface CustomCardSpec {
+    /**
+     * The JSON Schema for this card type's `data` payload.
+     *
+     * Used for BOTH ends: `cardTools()` projects it into a tool definition, and
+     * `registry.validate()` checks arriving data against it. Authored form is fine, with
+     * the descriptions left in: the projection strips what a provider cannot take, and
+     * the validator ignores keywords it does not implement.
+     *
+     * That last clause is a real limit, not a formality, and it is the same one the
+     * built-ins carry. `validateAgainstSchema` has no applicators, so `allOf`, `anyOf`,
+     * `oneOf`, `if`/`then`, `$ref` and `additionalProperties` in a custom schema are
+     * carried faithfully to the model and NOT enforced on the way back. See the
+     * NOT_ENFORCED table at the top of primitives/card-validate-schemas.ts.
+     */
+    readonly schema?: CardSchema | JsonSchema;
+    /** The custom element that renders it, e.g. `'my-pricing-table'`. Feeds `mergeCardTags`. */
+    readonly tag?: string;
+    /** The Solid component that renders it. Feeds `mergeCardComponents`. */
+    readonly component?: CardComponentMap[string];
+    /**
+     * One sentence of PURPOSE, addressed to the model: when should it reach for this
+     * card? Not a restatement of the shape, which the schema already carries.
+     *
+     * Falls back to the schema's own `description`, then to a generated stub. See
+     * `describe()` in tool-defs.ts.
+     */
+    readonly description?: string;
+}
+/** What to do about a custom card type registered with no schema. */
+export type IncompletePolicy = 'warn' | 'throw' | 'silent';
+export interface CardRegistrySpec {
+    /**
+     * Which BUILT-IN card types this app renders, and therefore which ones the model is
+     * offered.
+     *
+     * Omitted means all seven, which is what `cardTools({ provider })` already does and
+     * what `<kai-chat>` actually renders, so the default describes reality rather than
+     * quietly shrinking it. `use: []` means none of ours: an app whose generative UI is
+     * entirely its own.
+     */
+    readonly use?: readonly CardSchemaName[];
+    /** This app's own card types, keyed by `CardEnvelope.type`. */
+    readonly custom?: Readonly<Record<string, CustomCardSpec>>;
+    /**
+     * How a schema-less custom type is reported. Default `'warn'`.
+     *
+     * `'throw'` for a build or a CI check that wants the hole to be fatal; `'silent'` for
+     * a card type your own code populates and a model never emits, where the warning is
+     * noise. `'silent'` is deliberately a word you have to type, so the acknowledgement is
+     * greppable instead of implied.
+     */
+    readonly onIncomplete?: IncompletePolicy;
+}
+/**
+ * An app's card types, in the one shape both ends take.
+ *
+ * ```ts
+ * // cards.ts, imported by the client AND the route
+ * export const cards = createCardRegistry({
+ *   use: ['confirm', 'choice'],
+ *   custom: { 'pricing-table': { schema: pricingSchema, tag: 'my-pricing-table' } },
+ * });
+ *
+ * // client
+ * chat.cardTypes = cards.tags;
+ * // server
+ * const tools = cardTools(cards, { provider: 'anthropic' });
+ * ```
+ *
+ * Extends {@link CardToolSource}, so `cardTools(registry, opts)` takes it with no
+ * signature change on that side. That interface was left open for exactly this.
+ */
+export interface CardRegistry extends CardToolSource {
+    /**
+     * The card types the model is offered, keyed by type. `use`d built-ins plus every
+     * custom type that HAS a schema. What `cardTools()` reads.
+     */
+    readonly schemas: Readonly<Record<string, CardSchema>>;
+    /** Purpose sentences for custom types (and for any built-in a custom entry overrode). */
+    readonly descriptions: Readonly<Record<string, string>>;
+    /**
+     * Custom `type -> tag`, for `chat.cardTypes` / `mergeCardTags`.
+     *
+     * Custom entries ONLY. The built-in tags are not restated here because
+     * `mergeCardTags` adds all seven itself; listing the `use`d ones would read as if the
+     * others had been excluded, which is not what happens.
+     */
+    readonly tags: CardTagMap;
+    /** Custom `type -> Solid component`, for `<CardRenderer types>` / `mergeCardComponents`. */
+    readonly components: CardComponentMap;
+    /** Every type this registry declares, schema-less ones included. Built-ins first. */
+    readonly types: readonly string[];
+    /** The built-in types in `use`, in `cardSchemas` order. */
+    readonly builtIn: readonly CardSchemaName[];
+    /** The custom types, in declaration order, schema-less ones included. */
+    readonly custom: readonly string[];
+    /** Custom types with no schema: registered, renderable, invisible to the model. */
+    readonly incomplete: readonly string[];
+    /**
+     * Custom schemas in the shape `validateCardData`'s third argument takes, so a caller
+     * that already has a `validateCardData` call can widen it without going through
+     * {@link CardRegistry.validate}.
+     */
+    readonly validationSchemas: Readonly<Record<string, JsonSchema>>;
+    /**
+     * Validate an envelope's `data` against this registry's schema for `type`.
+     *
+     * Custom schemas win over a built-in of the same name, matching `mergeCardTags`'s
+     * consumer-wins rule. `null` means there was nothing to check (a type with no
+     * schema anywhere), which is kept distinguishable from a clean pass so a caller
+     * cannot report the second as the first.
+     *
+     * Covers all seven built-ins regardless of `use`: see the module header.
+     */
+    validate(type: string, data: unknown): CardValidationReport | null;
+}
+/**
+ * Declare the card types this app renders, once, for both ends.
+ *
+ * @throws {TypeError} if `use` names something that is not a built-in card type (a
+ * typo, or a custom type that belongs in `custom`), if a custom key is empty, or if
+ * `onIncomplete: 'throw'` and a custom type has no schema.
+ */
+export declare function createCardRegistry(spec?: CardRegistrySpec): CardRegistry;

package/dist/schemas/tool-defs.d.ts

@@ -0,0 +1,121 @@
+import { CardSchema, CardSchemaName } from './index.js';
+import { ProviderSubset, StrictProviderId, SubsetViolation } from './provider-subsets.js';
+/** A projected schema. Deliberately loose: `type` may become `['string','null']`. */
+export type ToolParameters = Readonly<Record<string, unknown>>;
+/** `POST /v1/chat/completions` and `/v1/responses` tool entries. */
+export interface OpenAIToolDef {
+    readonly type: 'function';
+    readonly function: {
+        readonly name: string;
+        readonly description: string;
+        readonly parameters: ToolParameters;
+        readonly strict?: true;
+    };
+}
+/** `POST /v1/messages` tool entries. Note `input_schema`, NOT `function.parameters`. */
+export interface AnthropicToolDef {
+    readonly name: string;
+    readonly description: string;
+    readonly input_schema: ToolParameters;
+    readonly strict?: true;
+}
+/**
+ * The bare form, for the Vercel AI SDK and anything else that wants the schema
+ * without a provider envelope: `tool({ inputSchema: jsonSchema(def.schema) })`.
+ *
+ * First-class, not a fallback. A developer on `ai@7` defines tools with Zod, and
+ * handing them an OpenAI-shaped envelope they have to unwrap makes our JSON Schema an
+ * awkward second source of truth instead of the one they use.
+ */
+export interface JsonSchemaToolDef {
+    readonly name: string;
+    readonly description: string;
+    readonly schema: ToolParameters;
+}
+export type ToolProvider = 'openai' | 'anthropic' | 'jsonschema';
+export type ToolDefFor<P extends ToolProvider> = P extends 'openai' ? OpenAIToolDef : P extends 'anthropic' ? AnthropicToolDef : JsonSchemaToolDef;
+export type ToolDef = OpenAIToolDef | AnthropicToolDef | JsonSchemaToolDef;
+export interface CardToolOptions<P extends ToolProvider = ToolProvider> {
+    readonly provider: P;
+    /**
+     * Opt in to the provider's grammar-constrained mode.
+     *
+     * Default `false`, because that is the mode the conformance sweep proved cards in
+     * and because, today, `true` throws for every built-in card on both providers.
+     * When it throws it names the card, the path and the keyword.
+     */
+    readonly strict?: boolean;
+}
+/**
+ * Where the card types come from.
+ *
+ * Phase 1 hands this the built-in `cardSchemas` map directly. Phase 2's
+ * `createCardRegistry()` returns an object that is structurally a `CardToolSource`,
+ * so `cardTools(registry, opts)` starts working on custom card types without this
+ * signature changing. That is the seam, left open on purpose and not built yet.
+ */
+export interface CardToolSource {
+    readonly schemas: Readonly<Record<string, CardSchema>>;
+    /** Tool descriptions by card type. Falls back to the built-in copy, then the schema's own. */
+    readonly descriptions?: Readonly<Record<string, string>>;
+}
+export type CardToolInput = CardToolSource | Readonly<Record<string, CardSchema>>;
+/**
+ * What each card is FOR, addressed to a model.
+ *
+ * This is not a sixth copy of a shape. The shape stays in the JSON Schema and is
+ * never restated here; these are one sentence each of purpose, which exists nowhere
+ * else, and which a schema's own `description` ("Data payload for a `confirm` card")
+ * does not provide because it is written for a developer reading the contract.
+ *
+ * Typed as an exhaustive `Record<CardSchemaName, string>`, so adding an eighth card
+ * type fails `tsc` here rather than silently shipping a tool with no description.
+ */
+export declare const CARD_TOOL_DESCRIPTIONS: Readonly<Record<CardSchemaName, string>>;
+export interface UnsupportedCardTool {
+    readonly cardType: string;
+    readonly toolName: string;
+    readonly violations: readonly SubsetViolation[];
+}
+/**
+ * Thrown by `cardTools(..., { strict: true })` when a card cannot be expressed in the
+ * provider's strict subset.
+ *
+ * Carries the structured detail as well as the message, so a build script can render
+ * it however it likes rather than parsing prose.
+ */
+export declare class UnsupportedCardToolSchemaError extends Error {
+    readonly name = "UnsupportedCardToolSchemaError";
+    readonly provider: StrictProviderId;
+    readonly source: string;
+    readonly cards: readonly UnsupportedCardTool[];
+    constructor(subset: ProviderSubset, cards: readonly UnsupportedCardTool[]);
+    /** Every distinct keyword named across every failing card, deduped, in order. */
+    get keywords(): string[];
+}
+/**
+ * Project the card schemas into tool definitions for one provider.
+ *
+ * ```ts
+ * const tools = [...myTools, ...cardTools({ provider: 'openai' })];
+ * const tools = cardTools(cards, { provider: 'anthropic' });
+ * const tools = cardTools({ provider: 'jsonschema' }).map((t) =>
+ *   tool({ description: t.description, inputSchema: jsonSchema(t.schema) }));
+ * ```
+ *
+ * @throws {UnsupportedCardToolSchemaError} with `strict: true`, naming every card,
+ * path and keyword the provider cannot express. See the file header: today that is
+ * every built-in card on both providers.
+ */
+export declare function cardTools<P extends ToolProvider>(opts: CardToolOptions<P>): ToolDefFor<P>[];
+export declare function cardTools<P extends ToolProvider>(registry: CardToolInput, opts: CardToolOptions<P>): ToolDefFor<P>[];
+/** `cardTools(registry, { provider: 'openai' })`, spelled out. */
+export declare function toOpenAITools(registry?: CardToolInput, opts?: {
+    strict?: boolean;
+}): OpenAIToolDef[];
+/** `cardTools(registry, { provider: 'anthropic' })`, spelled out. */
+export declare function toAnthropicTools(registry?: CardToolInput, opts?: {
+    strict?: boolean;
+}): AnthropicToolDef[];
+/** `cardTools(registry, { provider: 'jsonschema' })`, spelled out. */
+export declare function toJsonSchemaTools(registry?: CardToolInput): JsonSchemaToolDef[];