@kitn.ai/ui 0.20.1 → 0.22.0

package/src/primitives/use-sequencer.ts

@@ -33,6 +33,25 @@ export function useSequencer(interval: () => number): Accessor<number> {
 
     if (!Number.isFinite(ms) || ms <= 0) return;
     if (typeof requestAnimationFrame === 'undefined') return;
+    if (typeof cancelAnimationFrame === 'undefined') return;
+
+    // Captured at SETUP and closed over, never re-resolved as a global inside
+    // `onCleanup`: cleanup can run after the host removed the DOM globals (a
+    // `kai-*` release is deferred one microtask past detachment, so an
+    // environment teardown gets in between), and a bare `cancelAnimationFrame`
+    // there throws -- from a promise nobody holds, so it lands as an unhandled
+    // rejection that fails the run while every test passes.
+    // See tests/components/teardown-without-dom-globals.test.tsx.
+    //
+    // The FUNCTION, not the view. The `const win = window` capture that fixes a
+    // bare `document` does nothing here: `window === globalThis` -- measured, in
+    // jsdom and in real Chromium/WebKit alike -- and the teardown deletes these
+    // keys off that very object, so `win.cancelAnimationFrame` is undefined by
+    // the time cleanup runs. It only trades the ReferenceError for a TypeError.
+    // `.bind` pins the receiver the WebIDL operation is specified on; Chromium
+    // and WebKit both accept a detached call (measured), so the bind is belt and
+    // braces against an engine that does not, at zero cost.
+    const cancelFrame = cancelAnimationFrame.bind(globalThis);
 
     let raf = 0;
     let last = performance.now();
@@ -46,7 +65,7 @@ export function useSequencer(interval: () => number): Accessor<number> {
     };
 
     raf = requestAnimationFrame(step);
-    onCleanup(() => cancelAnimationFrame(raf));
+    onCleanup(() => cancelFrame(raf));
   });
 
   return tick;

package/src/schemas/from-tool-call.ts

@@ -0,0 +1,151 @@
+// The inverse of `cardTools()`: a model's tool call back into a renderable card.
+//
+// This is the one line a developer adds to their tool loop:
+//
+//   for (const call of pending) {
+//     const card = cardFromToolCall(call.name, call.input ?? {}, { id: call.id });
+//     if (card) {
+//       stream.addCard(card);
+//       applyToolOutput(stream, call.id, { status: 'awaiting_user' });
+//       continue;
+//     }
+//     applyToolOutput(stream, call.id, await runTool(call.name, call.input ?? {}));
+//   }
+//
+// It replaces the hand-written mapper this repo's own reference harness carries
+// (examples/internal/openrouter-spike/src/tools.ts:471-500), whose comment says the
+// model cannot emit a CardEnvelope directly because the schemas are unreachable.
+// They are reachable now (./index.ts), so the mapper does not need to exist.
+//
+// RUNTIME-FREE, DELIBERATELY
+// --------------------------
+// One type import, which erases. No DOM, no Solid, no validator, no schema data.
+// This is imported by a backend route inside a tool loop, so it must weigh nothing
+// and must not drag `cardSchemas` in behind it.
+//
+//
+// THE TWO DESIGN CALLS, AND WHY
+// =============================
+//
+// 1. THE TOOL NAME CARRIES `type`; THE `tool_call_id` CARRIES `id`.
+//
+// `kai_confirm` produces `{ type: 'confirm' }`, and the provider's `tool_call_id`
+// becomes `CardEnvelope.id` unchanged. The id is not a detail: it is already unique
+// per call, and it is already the key `upsertCardPart` (src/state/parts.ts:172)
+// matches on. So a model that revises a card re-sends the same tool call id, and
+// `AssistantStream.addCard` replaces that card in place instead of rendering a
+// second copy of it. Generating an id here would break that for free, which is what
+// the spike's `card-${++cardSeq}` does today.
+//
+// 2. `kai_` DECIDES "CARD TOOL". IT DOES NOT DECIDE "RENDERABLE".
+//
+// Two questions get asked about a `kai_*` call, and they are answered in two places
+// on purpose:
+//
+//   "is this a card tool at all?"   -> here, from the prefix. Returns null if not,
+//                                      so the loop's `if (card)` falls through to
+//                                      the app's own tools. Never throws: an unknown
+//                                      tool name is ordinary, not exceptional.
+//
+//   "can this card render / is the  -> the DISPATCHER. An unregistered type already
+//    data well-formed?"                renders `CardFallback` and emits
+//                                      `{ kind: 'error', cardId }`
+//                                      (components/card-renderer.tsx:33-42), and
+//                                      T1.5 adds the same treatment for data that
+//                                      does not match its schema, mirroring
+//                                      remote/provider-runtime.ts:142.
+//
+// So this module has no validator and must not grow one. Two consequences, both
+// intentional:
+//
+//   - A type the kit does not know (`kai_pricing-table`) still produces an envelope.
+//     Gating on the 7 built-ins instead would send a custom card type, registered
+//     perfectly legally through `cardTypes`/`mergeCardTags`, to
+//     `runTool('kai_pricing-table')` which no app implements, and the card would
+//     vanish with no diagnostic anywhere. The permissive read costs nothing, because
+//     a genuinely unknown type is named on screen by the fallback.
+//
+//   - Malformed `data` still produces an envelope. Returning null would be
+//     indistinguishable from "not a card tool" and would misroute the call to
+//     `runTool`; throwing would kill the whole turn, including the sibling tool calls
+//     in the same batch, for what the plan explicitly treats as a PRODUCTION failure
+//     mode. Keeping the envelope keeps the bad data attributable to the tool call
+//     that produced it, which is what lets the app hand the diagnostic back to the
+//     model, and the model's corrected retry then upserts over the broken card
+//     because it reuses the same tool call id. That healing only works if the
+//     malformed call produced an envelope in the first place.
+//
+// `isCardTool` and `cardFromToolCall` are derived from ONE decision function below,
+// rather than each testing the prefix, so they cannot drift into disagreeing about
+// the same question.
+
+import type { CardEnvelope } from '../primitives/card-contract';
+
+/**
+ * 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 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 function cardTypeFromToolName(name: string): string | null {
+  if (!name.startsWith(KAI_TOOL_PREFIX)) return null;
+  const type = name.slice(KAI_TOOL_PREFIX.length);
+  return type.length > 0 ? type : null;
+}
+
+/** The tool name for a card type. The exact inverse of {@link cardTypeFromToolName}. */
+export function toolNameForCardType(type: string): string {
+  return `${KAI_TOOL_PREFIX}${type}`;
+}
+
+/**
+ * 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 function isCardTool(name: string): boolean {
+  return cardTypeFromToolName(name) !== null;
+}
+
+/**
+ * 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 function cardFromToolCall(
+  name: string,
+  input: unknown,
+  opts: { id: string },
+): CardEnvelope | null {
+  const type = cardTypeFromToolName(name);
+  if (type === null) return null;
+  // `undefined` is the only value here that cannot have come off the wire (a model
+  // calling a tool with no arguments), so it is the only one normalised. `null` is
+  // real JSON and is passed through for the validator to complain about.
+  return { type, id: opts.id, data: input === undefined ? {} : input };
+}

package/src/schemas/index.ts

@@ -0,0 +1,340 @@
+// @kitn.ai/ui/schemas: the card JSON Schemas, reachable.
+//
+// The 11 schema documents under src/primitives/card-schemas/ have been copied into
+// dist/schemas/ on every build and shipped in every tarball since the card contract
+// landed. Nothing could reach them: package.json "exports" is a CLOSED map with no
+// `./schemas` key, so both `@kitn.ai/ui/schemas` and
+// `@kitn.ai/ui/schemas/confirm.schema.json` resolved to TS2307 /
+// ERR_PACKAGE_PATH_NOT_EXPORTED. This repo's own reference harness gave up and
+// hand-derived the confirm schema in
+// examples/internal/openrouter-spike/src/card-schema.ts, saying so in a comment.
+//
+// WHY THIS JS ENTRY IS THE PRIMARY SURFACE
+// ----------------------------------------
+// The raw JSON subpaths ship too (`@kitn.ai/ui/schemas/confirm.schema.json`), and
+// they are the right answer for a Python or Go backend, or for `fetch`. They are
+// the SECONDARY surface for JS/TS consumers because importing JSON breaks three
+// different ways across the framework targets the scaffolder supports: Node ESM and
+// TS `nodenext` need `with { type: 'json' }`, types need `resolveJsonModule` in any
+// mode, and Workers need a `wrangler` rule. A JS entry has none of those problems
+// anywhere, and it picks up `verify:ssr` coverage for free, since that guard derives
+// its entry list from the exports map.
+//
+// SERVER-SAFE, DELIBERATELY
+// -------------------------
+// No DOM, no Solid, no `fetch`. Everything reached from here is data or plain
+// functions, and as of src/primitives/card-component-types.ts that is true of the
+// TYPES too: nothing reachable from this entry resolves to a `.tsx` any more, so a
+// Node/no-DOM project can read the whole graph from source. (`CardComponentMap` used
+// to come from primitives/card-registry.tsx and was the last exception.) This entry
+// is meant to be imported by a backend route that hands tool definitions to a model,
+// so anything that touches a browser global would defeat its purpose. `verify:ssr`
+// asserts the RUNTIME half, by importing the BUILT entry under the `node` condition
+// in its own child process; the compile-time half is `tsc --noEmit -p
+// tsconfig.mcp.json` on a tree with no dist/, and only that one sees a `.tsx` creep
+// back in.
+//
+// WHAT `verify:ssr` DOES NOT CATCH, MEASURED
+// ------------------------------------------
+// It checks the BUILT bundle, so it only sees what survives tree-shaking — and
+// rollup is good enough here that it does not see the mistake you would actually
+// make. Measured, not assumed: pointing the `BUILTIN_CARD_TAGS` re-export below at
+// src/primitives/card-registry.TSX instead of card-tags.ts produces a byte-identical
+// dist/schemas.js with zero `solid-js` references, and imports clean under `node`.
+// Rollup compiles the whole Solid component tree (build time 0.2s -> 3.9s) and then
+// discards all of it, because only the tag map is reachable.
+//
+// So the `.ts` split is NOT holding a runtime guard up, and must not be described as
+// if it were. What it buys is that this entry's server-safety stops depending on
+// tree-shaking staying perfect: one module-scope side effect anywhere under
+// components/ and the discarded tree stops being discardable. Removing the dependency
+// beats relying on it being elided.
+//
+// WHAT IT COSTS, AND WHERE
+// ------------------------
+// dist/schemas.js, measured on this tree, not recalled:
+//
+//   42,658 B min / 11,762 B gzip   before ./registry landed
+//   53,658 B min / 14,669 B gzip   after ./registry  (+11,000 B / +2,907 B gzip)
+//   53,864 B min / 14,739 B gzip   now, with BUILTIN_CARD_TAGS  (+206 B / +70 B gzip)
+//
+// The middle row is this comment's previous "53,656 / 14,667", re-measured rather than
+// carried forward; the 2-byte drift is what a claim costs when it is copied instead of
+// taken again. The last row is the tag map below, measured by building this entry with
+// and without that one export line.
+//
+// The `18,160 B / 5,800 B` this comment used to claim was measured at 0.20.1, before
+// tool-defs and provider-subsets were added to the barrel, and had been stale ever
+// since. Corrected here rather than left, because a size claim nobody re-measures is
+// the same class of thing as a guard nobody watches fail.
+//
+// The delta is ./registry plus what it pulls: primitives/card-validate.ts (the
+// validator) and primitives/card-validate-schemas.ts (the LEAN projection). That last
+// one means the seven card schemas appear TWICE in this bundle, authored and lean.
+// Deliberate, and the alternative is worse: validating built-ins against the authored
+// documents here while the browser validates them against the projection would be two
+// behaviours wearing one name. One function, one answer, 4 KB.
+//
+// All of it is a SERVER cost and does not touch a client bundle. Nothing in the
+// component tree imports this entry, so no consumer pays it unless a route or a
+// build script imports it on purpose. If you are here comparing it against the
+// ~1 KB gzip figure in the emit-contract plan, those are different things: that one
+// is the LEAN projection destined for the browser (descriptions and `$id` stripped,
+// validation keywords only), which is a separate artifact and not this file.
+//
+// NOT RESTATED
+// ------------
+// Every value below is the JSON file itself, imported and inlined by the bundler.
+// There is no hand-copied shape here and there must never be one: `verify:schemas`
+// asserts each exported entry is byte-identical to its file on disk, and that the
+// two maps between them account for every file in the directory and for nothing
+// else. The whole point of this entry is to stop the same shape existing in five
+// places.
+
+import type { JsonSchema } from '../primitives/card-validate';
+
+import artifactSchema from '../primitives/card-schemas/artifact.schema.json';
+import cardEnvelopeSchema from '../primitives/card-schemas/card-envelope.schema.json';
+import cardEventSchema from '../primitives/card-schemas/card-event.schema.json';
+import choiceSchema from '../primitives/card-schemas/choice.schema.json';
+import confirmSchema from '../primitives/card-schemas/confirm.schema.json';
+import embedSchema from '../primitives/card-schemas/embed.schema.json';
+import formResultSchema from '../primitives/card-schemas/form.result.schema.json';
+import formSchema from '../primitives/card-schemas/form.schema.json';
+import linkSchema from '../primitives/card-schemas/link.schema.json';
+import tasksResultSchema from '../primitives/card-schemas/tasks.result.schema.json';
+import tasksSchema from '../primitives/card-schemas/tasks.schema.json';
+
+/**
+ * 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>>;
+
+/**
+ * DO NOT "TIGHTEN" THIS TO `doc as JsonSchema`, OR DELETE THE CAST.
+ *
+ * It reads like laziness and is not. `JsonSchema` (src/primitives/card-validate.ts)
+ * pins `type` to a literal union — `'string' | 'number' | ... | 'null'` — while
+ * TypeScript infers plain `string` for the `"type"` member of an imported JSON
+ * literal, so a schema document is NOT assignable to `JsonSchema` and no narrowing
+ * short of a per-file `as const` would make it so. On top of that the documents
+ * legitimately carry `$schema`, `$id`, `title`, `description`, `default`,
+ * `additionalProperties`, `x-kai-*` and (in `embed` and `artifact`)
+ * `allOf`/`if`/`then`/`oneOf`, which `JsonSchema` does not describe at all.
+ *
+ * So this widens once, at the module boundary, deliberately. It is not a claim
+ * about the contents, and the claim it does NOT make is checked elsewhere:
+ * `verify:schemas` imports the BUILT entry from a temp package outside the repo and
+ * asserts every exported value is byte-identical to its file on disk. A tighter
+ * type here would buy nothing that check does not already prove, and would cost the
+ * ability to represent the schemas we actually ship.
+ */
+const asSchema = (doc: unknown): CardSchema => doc as CardSchema;
+
+/**
+ * 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 const cardSchemas: Readonly<Record<CardSchemaName, CardSchema>> = Object.freeze({
+  artifact: asSchema(artifactSchema),
+  choice: asSchema(choiceSchema),
+  confirm: asSchema(confirmSchema),
+  embed: asSchema(embedSchema),
+  form: asSchema(formSchema),
+  link: asSchema(linkSchema),
+  tasks: asSchema(tasksSchema),
+});
+
+/** The 4 contract shapes, keyed by file stem. */
+export const contractSchemas: Readonly<Record<ContractSchemaName, CardSchema>> = Object.freeze({
+  'card-envelope': asSchema(cardEnvelopeSchema),
+  'card-event': asSchema(cardEventSchema),
+  'form.result': asSchema(formResultSchema),
+  'tasks.result': asSchema(tasksResultSchema),
+});
+
+/** The built-in card types, in the order `cardSchemas` declares them. */
+export const cardSchemaNames: readonly CardSchemaName[] = Object.freeze(
+  Object.keys(cardSchemas) as CardSchemaName[],
+);
+
+/** Narrow an arbitrary string to a built-in card type. */
+export function isCardSchemaName(name: string): name is CardSchemaName {
+  return Object.prototype.hasOwnProperty.call(cardSchemas, name);
+}
+
+// Re-exported so a consumer reading a schema out of these maps can annotate what
+// they hand to the kit's validator without a second import.
+export type { JsonSchema, ValidationResult } from '../primitives/card-validate';
+export type { CardEnvelope } from '../primitives/card-contract';
+
+// The card PAYLOAD types — `CardEnvelope.data`, one per built-in card type — so a
+// TypeScript backend can NAME the shape it is building instead of assembling an
+// `unknown` and hoping.
+//
+// This is the point of the whole entry, restated at the type level. We publish
+// `./schemas/*.json` precisely so a Python or Go route can generate models for
+// these payloads, and until this block existed TypeScript — the language the kit
+// is authored in — was the one that could not: the types lived inside their
+// components' `.tsx`, so naming one from a Node/no-DOM project was TS6142 and
+// re-exporting one from here would have dragged the Solid tree into this entry's
+// graph. They are authored in ../primitives/card-data-types.ts now, which has no
+// DOM and no Solid below it, so this costs the entry nothing — see that file's
+// header, and note that the check which can tell the difference is
+// `tsc --noEmit -p tsconfig.mcp.json` on a tree with no dist/ present.
+//
+// Types only: they erase, so this adds nothing to dist/schemas.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';
+
+// The remaining two payload types, `link` and `embed`.
+//
+// They are NOT in card-data-types.ts, and that is deliberate rather than an
+// oversight to be tidied later: that file exists to rescue types that were
+// trapped inside a `.tsx`, and these two never were. `LinkPreviewData` and
+// `EmbedCardData` have always been authored beside the pure logic that consumes
+// them — `resolveLinkMetadata`, `resolveEmbed`/`watchUrl` — in modules that carry
+// no DOM and no Solid, so they were already importable from a Node/no-DOM
+// project. Moving them would buy nothing and would split each type from the
+// functions written against it.
+//
+// Which is precisely how they got missed. The extraction that created
+// card-data-types.ts swept the `.tsx` files, exported what it found HERE, and
+// the two types that needed no rescuing were never on its list — five of seven
+// payload types landed on this entry and nobody noticed the other two, because
+// both are exported from src/index.ts and every check asked only whether a
+// consumer could reach them from SOME public barrel. A backend cannot import
+// from src/index.ts; that is the Solid-bearing one. See the REACHABILITY note in
+// card-type-parity.test.ts, which now enumerates the payload types from
+// `cardSchemas` and requires each to be reachable from THIS entry specifically.
+//
+// `EmbedProvider` comes along because `EmbedCardData.provider` names it, and a
+// member type a consumer cannot import leaves them writing `provider: 'youtube'
+// as EmbedCardData['provider']`. `ResolvedEmbed` and `LinkMetadataFetcher` stay
+// off this entry on purpose — they describe how a card RENDERS and how an app
+// resolves metadata in the browser, neither of which a route builds.
+export type { EmbedCardData, EmbedCardEnvelope, EmbedProvider } from '../primitives/embed-providers';
+export type { LinkPreviewData, LinkPreviewEnvelope } from '../primitives/link-preview';
+
+// The loop, both directions.
+//
+// `cardTools` projects a card schema INTO a provider tool definition;
+// `cardFromToolCall` turns the model's call back into a renderable envelope. They
+// are the two halves of one contract and the tool-name convention that joins them
+// lives in ./from-tool-call, spelled once. Exporting `from-tool-call` here is not
+// bookkeeping: `verify:schemas` and `verify:ssr` both read the BUILT entry, so a
+// module missing from this barrel is a module no guard covers.
+export { cardFromToolCall, isCardTool, cardTypeFromToolName, toolNameForCardType, KAI_TOOL_PREFIX } from './from-tool-call';
+
+// `tool-defs` imports `cardSchemas` back out of this module so that
+// `cardTools({ provider })` can default to the built-ins. That cycle is deliberate
+// and safe (the read happens inside a function, never at module init); the comment
+// on `builtInSchemas()` over there explains why, and why it must not be hoisted.
+export {
+  CARD_TOOL_DESCRIPTIONS,
+  UnsupportedCardToolSchemaError,
+  cardTools,
+  toAnthropicTools,
+  toJsonSchemaTools,
+  toOpenAITools,
+} from './tool-defs';
+export type {
+  AnthropicToolDef,
+  CardToolInput,
+  CardToolOptions,
+  CardToolSource,
+  JsonSchemaToolDef,
+  OpenAIToolDef,
+  ToolDef,
+  ToolDefFor,
+  ToolParameters,
+  ToolProvider,
+  UnsupportedCardTool,
+} from './tool-defs';
+
+// The registry: "these are the card types THIS app renders", written once and threaded
+// to both ends (`chat.cardTypes = cards.tags` on the client, `cardTools(cards, …)` on
+// the route). It is what turns the `cardTypes` seam from something a developer CAN use
+// into the path they normally take, which is the only thing that stops it rotting again
+// the way it did when the conformance spike's `spike-artifact` workaround was deleted.
+//
+// `registry.ts` imports `cardSchemas` back out of this module, the same deliberate
+// cycle `tool-defs` has and for the same reason; the read happens inside
+// `createCardRegistry`, never at module init.
+export { createCardRegistry } from './registry';
+export type { CardRegistry, CardRegistrySpec, CustomCardSpec, IncompletePolicy } from './registry';
+
+// Re-exported so a route can check a custom card's data server-side, in the tool loop,
+// with the same tiering the browser dispatchers use, rather than a second validator.
+// `registry.validate()` is the ergonomic form; this is the same function underneath.
+export { cardValidationMessage, validateCardData } from '../primitives/card-validate-cards';
+export type { CardValidationIssue, CardValidationReport, CardValidationTier } from '../primitives/card-validate-cards';
+
+// `CardEnvelope.type` -> the `kai-*` element that renders it — exported because a
+// server-side reader needed it and was inventing its own answer instead.
+//
+// src/agent-tooling/mcp/manifest.ts used to RE-DERIVE this map from the element
+// manifest by convention (`kai-<type>`, else the single `kai-<type>-*`). The
+// derivation was correct — it even got `link` -> `kai-link-preview` right, via the
+// prefix branch — but it was a second copy of a fact the repo already held, kept
+// honest only by a test. It re-derived because the authoritative map shared a module
+// with `BUILTIN_CARD_COMPONENTS`, which is nothing but Solid, and the MCP is a
+// Node/no-DOM project (tsconfig.mcp.json: `lib: ["ESNext"]`, no `jsx` — giving it one
+// measures 0 errors -> 1364). src/primitives/card-tags.ts is that data on its own, so
+// the map is now readable from source by anything, with or without a DOM.
+//
+// See "WHAT `verify:ssr` DOES NOT CATCH" above before describing the split as a
+// bundle-safety fix: it is a dependency-graph fix, and the bundle is identical either
+// way today.
+//
+// `mergeCardTags` is deliberately NOT re-exported here: merging a consumer's overrides
+// is a rendering concern, it already ships from the main entry, and this one is for
+// routes.
+export { BUILTIN_CARD_TAGS } from '../primitives/card-tags';
+export type { CardTagMap } from '../primitives/card-tags';
+
+// The two provider subsets, exported rather than kept private, because a developer
+// registering a CUSTOM card schema in Phase 2 needs the same check we run on ours,
+// and because `verify:tool-schemas` reads them out of the BUILT entry rather than
+// re-deriving them (a guard with its own copy of the table proves nothing).
+export { ANTHROPIC_STRICT, OPENAI_STRICT, checkProviderSubset, providerSubsets } from './provider-subsets';
+export type { KeywordRule, KeywordStatus, ProviderSubset, StrictProviderId, SubsetViolation } from './provider-subsets';