@kitn.ai/ui 0.20.1 → 0.22.0

package/src/primitives/card-validate-cards.ts

@@ -0,0 +1,255 @@
+// src/primitives/card-validate-cards.ts
+// Two-tier validation of a CardEnvelope's `data` against the card schema for its
+// type, for the NATIVE dispatchers.
+//
+// "The card schema for its type" means one of the seven built-ins, OR a schema the
+// app registered for a card type of its own. The second half arrived with
+// `createCardRegistry` (src/schemas/registry.ts) and is the optional third argument
+// to `validateCardData`. It exists because a developer's real generative UI is THEIR
+// pricing table, not our confirm card, and a validator that covers only the built-ins
+// leaves the one card the app actually cares about as the only unchecked one.
+//
+// THIS MIRRORS src/remote/provider-runtime.ts:139-147, DELIBERATELY.
+// -----------------------------------------------------------------
+// The remote (iframe) transport has validated every incoming envelope since the card
+// contract landed: `validateAgainstSchema(renderer.schema, envelope.data)`, and on
+// failure it renders a placeholder and emits `{ kind: 'error', cardId, message }`.
+// The native path (the Solid `<CardRenderer>` and `<kai-cards>`) checked only that
+// the TYPE was registered, so the same bad payload was caught in an iframe and
+// rendered silently in-process. That asymmetry is what this file closes. The two
+// transports are one behaviour; if you change the shape of the failure here, change
+// it there too, and say so.
+//
+// WHY THIS IS ENFORCEMENT AND NOT A SAFETY NET
+// --------------------------------------------
+// The intended design was that `strict: true` tool definitions would constrain the
+// model so envelopes arrived valid by construction. Measured against both providers'
+// current strict subsets (see src/schemas/provider-subsets.ts), strict mode cannot
+// express ANY of the seven card types today: `form`'s free-form `properties` object
+// collapses to `{}` under the mandatory `additionalProperties: false`, and the other
+// six trip `minLength`/`maxLength`/`format: "uri"`/`allOf`. So the schema guides the
+// model and does not constrain it, and this check is the only thing standing between
+// a wrong shape and the user's screen.
+//
+// WHY THE TIERING IS NOT POLITENESS
+// ---------------------------------
+// This library is pre-1.0 and already in use. Cards that render acceptably today
+// must keep rendering, or turning validation on is a behaviour break dressed up as a
+// fix. So a failure that means the card has NOTHING to render replaces the card with
+// a diagnostic (hard), and a failure that means the card has content which is merely
+// out of bounds renders the card and reports (soft). Both emit `{ kind: 'error' }`,
+// because the developer needs to hear about both; only one changes what the user sees.
+//
+// THE SOFT TIER IS ON BY EVIDENCE, NOT BY CONFIDENCE
+// --------------------------------------------------
+// The plan (2026-08-11-emit-contract.md §9 risk 4) said validation is net-negative if
+// it fires on cards that render fine today, and set the bar at ZERO before the soft
+// tier could default on. That was measured, not assumed:
+// docs/superpowers/specs/2026-08-12-soft-tier-corpus.md.
+//
+// 35 card envelopes recorded from five model configurations across both wires, six
+// card types. ZERO trip the soft tier; zero trip the hard tier. The check was proven
+// live on that same path by seven negative controls (real envelopes mutated into each
+// tier's named failure, each required to trip), and a fifth of the envelopes were
+// confirmed by replaying them through the real app and reading them back off
+// `<kai-thread>.messages`. Margins were wide, not marginal: the worst `link.title`
+// observed was 21 characters against a 300 limit.
+//
+// What that corpus does NOT cover, so it is not claimed: the structured-output path
+// (model-authored envelope JSON, which nothing clamps), live `artifact` cards, and
+// the soft constraints the spike's own tool projection clamps before they can be hit
+// (`tone`/`provider` enums, the generated `id` fields, every `minItems`). If the soft
+// tier ever does turn out to be noisy, that is where to look first, and the fix is the
+// projection rather than the tier.
+//
+// WHAT IS ACTUALLY CHECKED
+// ------------------------
+// The keyword coverage is `validateAgainstSchema`'s, which is a lean subset: `type`,
+// `const`, `enum`, `required`, `properties`, `items`, the numeric bounds,
+// `minLength`/`maxLength`/`pattern`, `minItems`/`maxItems`/`uniqueItems`. It has no
+// applicators and no `additionalProperties`. The consequences are written out per
+// keyword in scripts/gen-card-validation-schemas.mjs's NOT_ENFORCED table, and the
+// generated projection repeats them at the top of card-validate-schemas.ts. The
+// short version, because it bears on what may be claimed: an `embed` missing both
+// `id` and `url`, an `artifact` with neither `src` nor `files`, a `link.url` that is
+// not a URL, and an undeclared extra property are all NOT caught here.
+
+import { validateAgainstSchema, type JsonSchema, type ValidationIssue } from './card-validate';
+import { CARD_VALIDATION_SCHEMAS, type ValidatedCardType } from './card-validate-schemas';
+
+export type { ValidatedCardType } from './card-validate-schemas';
+export { CARD_VALIDATION_SCHEMAS } from './card-validate-schemas';
+
+/** How badly a failed constraint hurts the rendered card. */
+export type CardValidationTier = 'hard' | 'soft';
+
+export interface CardValidationIssue extends ValidationIssue {
+  tier: CardValidationTier;
+}
+
+export interface CardValidationReport {
+  /** True when nothing failed. A SOFT-only report is not `ok`. */
+  ok: boolean;
+  /** `hard` if any issue is hard, else `soft` if any issue is soft, else `ok`. */
+  tier: CardValidationTier | 'ok';
+  /** Every failure, hard and soft, in the validator's order. */
+  issues: CardValidationIssue[];
+  /** The hard issues only. Non-empty exactly when `tier === 'hard'`. */
+  hard: CardValidationIssue[];
+  /** One line naming the failing field paths. Safe to render and to log. */
+  summary: string;
+}
+
+/**
+ * Keyword to tier.
+ *
+ * The line is PRESENCE versus BOUNDS, and it is drawn per keyword rather than per
+ * card because the dispatcher does not know what any given card component does with
+ * a field.
+ *
+ *   hard  the field the card is built around is absent, or is a different kind of
+ *         thing entirely. There is nothing to draw.
+ *   soft  the field is present and of the right kind; there is just too much of it,
+ *         too little, or it is outside a declared range. Something renders.
+ *
+ * THE TWO ENTRIES THAT ARE JUDGEMENT CALLS, RECORDED BECAUSE THEY ARE ARGUABLE:
+ *
+ * `minItems` is HARD while `minLength` is SOFT, and they look like the same shape.
+ * The difference is what is lost. `confirm.actions` has `minItems: 1`, so violating
+ * it means a decision card with no decisions: the entire interactive surface is
+ * gone, and what renders is empty chrome that looks like a bug in this library. The
+ * plan names that case specifically as the one the diagnostic exists for. Violating
+ * `minLength: 1` on `actions[].label` means ONE blank button label; the button is
+ * still there, still focusable, and still emits the correct `id`. Replacing a whole
+ * card with a diagnostic over one blank label is the worse outcome for the user.
+ *
+ * `type` is HARD everywhere, including on optional scalars where a truthy wrong type
+ * would have rendered fine (`dismissible: "yes"`). That is deliberately blunt. A
+ * per-field carve-out would need the dispatcher to know which fields each card
+ * component treats loosely, which it cannot, and a wrong `type` is the single
+ * strongest signal that the model produced something other than what was asked for.
+ */
+const TIER_BY_KEYWORD: Readonly<Record<string, CardValidationTier>> = Object.freeze({
+  // hard: nothing to render
+  type: 'hard',
+  required: 'hard',
+  const: 'hard', // pins a discriminator (`form.data.type` must be `"object"`)
+  minItems: 'hard',
+  // soft: content is present, bounds are not respected
+  enum: 'soft', // cards fall back to their default variant for an unknown value
+  maxItems: 'soft',
+  minLength: 'soft',
+  maxLength: 'soft',
+  pattern: 'soft',
+  minimum: 'soft',
+  maximum: 'soft',
+  exclusiveMinimum: 'soft',
+  exclusiveMaximum: 'soft',
+  uniqueItems: 'soft',
+});
+
+/**
+ * The tier for a keyword the table does not list.
+ *
+ * SOFT, on purpose. An unlisted keyword can only appear by someone adding a check to
+ * `validateAgainstSchema` and not tiering it, and the failure mode of guessing wrong
+ * is asymmetric: guessing soft under-reacts on one new keyword until someone tiers
+ * it, while guessing hard would start blanking cards that render fine today, which
+ * is precisely the regression this design exists to prevent. `card-validate-cards.test.ts`
+ * asserts the table covers every keyword the validator implements, so this default
+ * is a fallback for a tree that is already failing its own test, not a resting state.
+ */
+const DEFAULT_TIER: CardValidationTier = 'soft';
+
+/** True when this envelope type has a BUILT-IN projected schema to validate against. */
+export function isValidatedCardType(type: string): type is ValidatedCardType {
+  return Object.prototype.hasOwnProperty.call(CARD_VALIDATION_SCHEMAS, type);
+}
+
+/**
+ * The schema to check `type` against, consumer-supplied first.
+ *
+ * A consumer schema WINS over a built-in of the same name, matching
+ * `mergeCardTags`/`mergeCardComponents`, where the consumer's entry is spread over
+ * ours. Anything else would mean a developer who replaced our confirm card with their
+ * own still had their data checked against our shape.
+ */
+function schemaFor(
+  type: string,
+  extra: Readonly<Record<string, JsonSchema>> | undefined,
+): JsonSchema | null {
+  if (extra && Object.prototype.hasOwnProperty.call(extra, type)) {
+    const custom = extra[type];
+    if (custom && typeof custom === 'object') return custom;
+  }
+  return isValidatedCardType(type) ? CARD_VALIDATION_SCHEMAS[type] : null;
+}
+
+function summarize(issues: CardValidationIssue[]): string {
+  // Name the FIELD PATHS. "invalid card data" on its own sends a developer to a
+  // debugger; "(root).actions: fewer than minItems 1" sends them to the line.
+  const shown = issues.slice(0, 3).map((i) => i.message);
+  const rest = issues.length - shown.length;
+  return shown.join('; ') + (rest > 0 ? `; and ${rest} more` : '');
+}
+
+/**
+ * Validate a card envelope's `data` against the schema for `type`.
+ *
+ * Returns `null` when there is no schema for the type at all. Returning `null` rather
+ * than an empty pass keeps "we checked and it was fine" distinguishable from "there
+ * was nothing to check", so a caller cannot report the second as the first.
+ *
+ * @param schemas consumer-registered schemas by card type, normally
+ * `registry.validationSchemas` from `createCardRegistry`. Without it this function
+ * knows only the seven built-ins, which would mean a developer's own pricing-table
+ * card, registered perfectly legally through `cardTypes`, is the one card in the app
+ * nothing checks. The custom entry wins over a built-in of the same name; see
+ * {@link schemaFor}.
+ *
+ * A consumer schema is used AS AUTHORED rather than through the build-time lean
+ * projection the built-ins get, because that projection is a bundle-size measure and
+ * cannot run over a schema this package has never seen. The practical difference is
+ * only weight: `validateAgainstSchema` ignores every keyword it does not implement, so
+ * a custom schema is checked to exactly the same depth as a built-in, with the same
+ * NOT_ENFORCED gaps (no `allOf`/`anyOf`/`oneOf`/`if`, no `$ref`, no
+ * `additionalProperties`, no `format`).
+ */
+export function validateCardData(
+  type: string,
+  data: unknown,
+  schemas?: Readonly<Record<string, JsonSchema>>,
+): CardValidationReport | null {
+  const schema = schemaFor(type, schemas);
+  if (schema === null) return null;
+  const result = validateAgainstSchema(schema, data);
+  if (result.valid) return { ok: true, tier: 'ok', issues: [], hard: [], summary: '' };
+
+  const issues: CardValidationIssue[] = result.issues.map((issue) => ({
+    ...issue,
+    tier: TIER_BY_KEYWORD[issue.keyword] ?? DEFAULT_TIER,
+  }));
+  const hard = issues.filter((i) => i.tier === 'hard');
+  return {
+    ok: false,
+    tier: hard.length > 0 ? 'hard' : 'soft',
+    issues,
+    hard,
+    summary: summarize(hard.length > 0 ? hard : issues),
+  };
+}
+
+/**
+ * The message both native dispatchers put on the `error` CardEvent.
+ *
+ * Spelled once, here, and prefixed `invalid card data:` to match what
+ * provider-runtime.ts already emits for the remote transport, so a consumer's
+ * `policy.onError` sees the same string shape regardless of which transport the card
+ * arrived through.
+ */
+export function cardValidationMessage(report: CardValidationReport): string {
+  return `invalid card data (${report.tier}): ${report.summary}`;
+}
+
+/** Exposed for the tier-coverage test, which asserts it against the validator. */
+export const TIERS_BY_KEYWORD = TIER_BY_KEYWORD;

package/src/primitives/card-validate-generator.testlib.ts

@@ -0,0 +1,38 @@
+// Test-only loader for scripts/gen-card-validation-schemas.mjs.
+//
+// The specifier is a runtime variable on purpose, the same way
+// src/elements/inline-element-types.test.ts loads gen-element-types.mjs: the script
+// is plain ESM outside `include`, and a static import would need `allowJs`.
+//
+// The interface below is a hand-written type for a JavaScript module, which is a
+// restatement and therefore a drift risk. It is kept as narrow as the tests need,
+// and the drift it could hide is the harmless direction: a wrong shape here fails at
+// runtime in the test that uses it, immediately, rather than passing while covering
+// nothing. The alternative (a sibling `.d.mts`) would be a WIDER restatement of the
+// same module with the same risk.
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+/** One keyword the projection could not account for, with where it was found. */
+export interface UnclassifiedKeyword {
+  path: string;
+  keyword: string;
+}
+
+export interface CardValidationGenerator {
+  CARD_TYPES: string[];
+  STRIPPED: Readonly<Record<string, string>>;
+  NOT_ENFORCED: Readonly<Record<string, string>>;
+  OUT_FILE: string;
+  enforcedKeywords(source?: string): Set<string>;
+  scanUnclassified(doc: unknown, enforced: Set<string>): UnclassifiedKeyword[];
+  projectSchema(doc: unknown, enforced: Set<string>): Record<string, unknown> | undefined;
+  build(): { enforced: Set<string>; projections: Record<string, unknown>; source: string };
+}
+
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
+
+export async function loadGenerator(): Promise<CardValidationGenerator> {
+  const url = pathToFileURL(resolve(PKG_ROOT, 'scripts/gen-card-validation-schemas.mjs')).href;
+  return (await import(/* @vite-ignore */ url)) as CardValidationGenerator;
+}

package/src/primitives/card-validate-schemas.ts

@@ -0,0 +1,58 @@
+// GENERATED by scripts/gen-card-validation-schemas.mjs. Do not edit by hand.
+//
+// Run `node scripts/gen-card-validation-schemas.mjs` (or any build, which does it in
+// `prebuild`) to regenerate. `card-validate-schemas.sync.test.ts` fails if this file
+// and the authored schemas in src/primitives/card-schemas/ disagree.
+//
+// WHAT THIS IS
+// ------------
+// The 7 card-data schemas with everything the browser cannot act on removed:
+// `$schema`, `$id`, `title`, `description`, `default`, every `x-*` hint, and every
+// keyword `validateAgainstSchema` does not implement. The authored documents remain
+// the source of truth and ship unchanged at `@kitn.ai/ui/schemas` for the server.
+//
+// ENFORCED here, read out of validateAgainstSchema's body by the generator:
+//   const, enum, exclusiveMaximum, exclusiveMinimum, items, maxItems, maxLength, maximum, minItems, minLength, minimum, pattern, properties, required, type, uniqueItems
+//
+// NOT ENFORCED, and therefore NOT in this projection. Each is a real constraint the
+// authored schema makes that nothing checks at render time:
+//   `additionalProperties`: unknown properties are NOT rejected. `artifact`, `embed` and `link` set `additionalProperties: false`; a model adding a field they do not declare renders exactly as it does today. Implementing it would make every extra field a validation failure on cards that render fine, which is the regression the tiering exists to avoid.
+//   `allOf`: conditional requirements are NOT checked. This is `embed`'s entire provider/url rule (generic needs `url`; youtube/vimeo need `id` or `url`), so an embed card missing both validates here and renders an empty player. Fixing it means implementing applicators, not widening this table.
+//   `anyOf`: branch alternatives are NOT checked. This is `artifact`'s root `[{required:["src"]},{required:["files"]}]` rule, so an artifact card carrying NEITHER a `src` nor a `files` list validates here and renders empty chrome. It is also half of `embed`'s youtube/vimeo `id`-or-`url` rule.
+//   `oneOf`: exactly-one-of is NOT checked. `artifact.height` is `oneOf: [number, string]`, and because that subschema has no other keyword it drops out of the projection entirely: a `height` of `true` or `{}` is not caught.
+//   `if`: the conditional applicator is NOT evaluated; see `allOf`.
+//   `then`: the conditional consequent is NOT evaluated; see `allOf`.
+//   `else`: the conditional alternative is NOT evaluated; see `allOf`.
+//   `not`: negation is NOT evaluated; a value the schema explicitly forbids validates here. Unused by any card schema today.
+//   `format`: string formats are NOT checked. `link`, `embed` and `artifact` use `format: "uri"`; a non-URL string in `link.url` validates here. The cards themselves guard what they will actually navigate to or frame, which is where a URL check belongs (a validator that only warns cannot stop a bad origin loading).
+//   `$ref`: references are NOT resolved; a `$ref`-ed subschema is not checked at all. No card schema uses one today.
+//   `$defs`: definition blocks are NOT reachable without `$ref`, so their contents are never checked.
+//   `definitions`: the draft-07 spelling of `$defs`; its contents are NOT checked either, for the same reason. Listed separately so a schema written in the older dialect cannot slip past this table.
+import type { JsonSchema } from './card-validate';
+
+/** The built-in `CardEnvelope.type` values that have a schema to validate against. */
+export type ValidatedCardType = "artifact" | "choice" | "confirm" | "embed" | "form" | "link" | "tasks";
+
+/**
+ * One widening cast, at the module boundary, for the same reason
+ * src/schemas/index.ts has one: TypeScript infers `string` for a `"type"` member
+ * written as a literal in an object literal, while `JsonSchema['type']` is a union
+ * of string literals, so these documents are not assignable without it. The
+ * alternative (`as const` throughout) makes every `required` array `readonly`,
+ * which `JsonSchema` does not accept either.
+ *
+ * The cast is not a claim about the contents. What it would otherwise hide is
+ * checked by the sync test, which re-runs this generator and compares byte for byte.
+ */
+export const CARD_VALIDATION_SCHEMAS = {
+  "artifact": {"type":"object","properties":{"src":{"type":"string"},"files":{"type":"array","maxItems":500,"items":{"type":"object","required":["path"],"properties":{"path":{"type":"string","maxLength":1024},"url":{"type":"string"},"code":{"type":"string"},"language":{"type":"string","maxLength":40},"type":{"type":"string","enum":["html","pdf","image","other"]},"additions":{"type":"integer","minimum":0},"deletions":{"type":"integer","minimum":0},"status":{"type":"string","enum":["added","modified","deleted","renamed","untracked"]}}}},"tab":{"type":"string","enum":["preview","code"]},"activeFile":{"type":"string","maxLength":1024},"displayUrl":{"type":"string","maxLength":2048}}},
+  "choice": {"type":"object","required":["options"],"properties":{"prompt":{"type":"string"},"submitLabel":{"type":"string"},"options":{"type":"array","minItems":1,"items":{"type":"object","required":["id","label"],"properties":{"id":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"description":{"type":"string"},"media":{"type":"object","properties":{"image":{"type":"string"},"imageAlt":{"type":"string"},"icon":{"type":"string"}}},"meta":{"type":"string"},"recommended":{"type":"boolean"},"disabled":{"type":"boolean"}}}},"dismissible":{"type":"boolean"}}},
+  "confirm": {"type":"object","required":["actions"],"properties":{"heading":{"type":"string"},"body":{"type":"string"},"tone":{"type":"string","enum":["default","warning","danger"]},"actions":{"type":"array","minItems":1,"maxItems":4,"items":{"type":"object","required":["id","label"],"properties":{"id":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"style":{"type":"string","enum":["primary","default","destructive"]},"default":{"type":"boolean"}}}},"dismissible":{"type":"boolean"}}},
+  "embed": {"type":"object","required":["provider"],"properties":{"provider":{"type":"string","enum":["youtube","vimeo","generic"]},"id":{"type":"string","maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"url":{"type":"string"},"title":{"type":"string","maxLength":300},"poster":{"type":"string"},"start":{"type":"integer","minimum":0},"aspectRatio":{"type":"string","enum":["16:9","4:3","1:1","9:16"]}}},
+  "form": {"type":"object","required":["type","properties"],"properties":{"type":{"const":"object"},"title":{"type":"string"},"description":{"type":"string"},"required":{"type":"array","items":{"type":"string"}},"properties":{"type":"object"},"x-kai-order":{"type":"array","items":{"type":"string"}},"x-kai-inlineMax":{"type":"integer","minimum":1},"x-kai-submitLabel":{"type":"string"},"x-kai-dismissible":{"type":"boolean"},"x-kai-actions":{"type":"array","items":{"type":"object","required":["id","label"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"variant":{"enum":["default","ghost","outline"]}}}}}},
+  "link": {"type":"object","required":["url"],"properties":{"url":{"type":"string"},"title":{"type":"string","maxLength":300},"description":{"type":"string","maxLength":1000},"image":{"type":"string"},"imageAlt":{"type":"string","maxLength":300},"favicon":{"type":"string"},"domain":{"type":"string","maxLength":253},"siteName":{"type":"string","maxLength":200}}},
+  "tasks": {"type":"object","required":["tasks"],"properties":{"mode":{"type":"string","enum":["select","progress"]},"heading":{"type":"string"},"tasks":{"type":"array","minItems":1,"items":{"type":"object","required":["id","label"],"properties":{"id":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"description":{"type":"string"},"checked":{"type":"boolean"},"disabled":{"type":"boolean"}}}},"selectAll":{"type":"boolean"},"confirmLabel":{"type":"string"},"allowEmpty":{"type":"boolean"},"min":{"type":"integer","minimum":0},"max":{"type":"integer","minimum":1},"dismissible":{"type":"boolean"}}},
+} as unknown as Readonly<Record<ValidatedCardType, JsonSchema>>;
+
+/** The card types this projection covers, in a stable order. */
+export const VALIDATED_CARD_TYPES: readonly ValidatedCardType[] = ["artifact","choice","confirm","embed","form","link","tasks"];

package/src/primitives/card-validate.ts

@@ -20,9 +20,34 @@ export interface JsonSchema {
   [key: `x-${string}`]: unknown;
 }
 
+/**
+ * One failed constraint, with the KEYWORD that failed kept separate from the prose.
+ *
+ * `errors` (the string form) is what every existing caller reads and it is unchanged.
+ * This structured twin exists because the native card dispatcher has to TIER a
+ * failure (a missing `required` field means the card cannot render, a `maxItems`
+ * overrun means it renders five buttons instead of four), and the only honest way to
+ * tell those apart is the keyword. Re-parsing the prose to recover it would be a
+ * second, silently-drifting copy of the same fact.
+ */
+export interface ValidationIssue {
+  /** Where, in readable form: `(root)`, `(root).actions`, `(root).actions[0].id`. */
+  path: string;
+  /** The JSON Schema keyword that failed. `required` for a missing property. */
+  keyword: string;
+  /** The human-readable message; identical to the matching entry in `errors`. */
+  message: string;
+}
+
 export interface ValidationResult {
   valid: boolean;
   errors: string[];
+  /**
+   * The same failures as `errors`, one-for-one and in the same order, with the
+   * keyword and path kept as data. Added alongside `errors` rather than replacing
+   * it so no existing caller changes.
+   */
+  issues: ValidationIssue[];
 }
 
 function typeOf(v: unknown): string {
@@ -42,46 +67,49 @@ function matchesType(v: unknown, t: NonNullable<JsonSchema['type']>): boolean {
   }
 }
 
-function walk(schema: JsonSchema, value: unknown, path: string, errors: string[]): void {
+function walk(schema: JsonSchema, value: unknown, path: string, issues: ValidationIssue[]): void {
   const at = path || '(root)';
+  const fail = (keyword: string, message: string, where = at): void => {
+    issues.push({ path: where, keyword, message: `${where}: ${message}` });
+  };
   if (schema.type && !matchesType(value, schema.type)) {
-    errors.push(`${at}: expected ${schema.type}, got ${typeOf(value)}`);
+    fail('type', `expected ${schema.type}, got ${typeOf(value)}`);
     return; // type wrong → downstream checks are meaningless
   }
   if ('const' in schema && JSON.stringify(value) !== JSON.stringify(schema.const)) {
-    errors.push(`${at}: must equal const ${JSON.stringify(schema.const)}`);
+    fail('const', `must equal const ${JSON.stringify(schema.const)}`);
   }
   if (schema.enum && !schema.enum.some((e) => JSON.stringify(e) === JSON.stringify(value))) {
-    errors.push(`${at}: must be one of ${JSON.stringify(schema.enum)}`);
+    fail('enum', `must be one of ${JSON.stringify(schema.enum)}`);
   }
   if (typeof value === 'number') {
-    if (schema.minimum !== undefined && value < schema.minimum) errors.push(`${at}: < minimum ${schema.minimum}`);
-    if (schema.maximum !== undefined && value > schema.maximum) errors.push(`${at}: > maximum ${schema.maximum}`);
-    if (schema.exclusiveMinimum !== undefined && value <= schema.exclusiveMinimum) errors.push(`${at}: <= exclusiveMinimum`);
-    if (schema.exclusiveMaximum !== undefined && value >= schema.exclusiveMaximum) errors.push(`${at}: >= exclusiveMaximum`);
+    if (schema.minimum !== undefined && value < schema.minimum) fail('minimum', `< minimum ${schema.minimum}`);
+    if (schema.maximum !== undefined && value > schema.maximum) fail('maximum', `> maximum ${schema.maximum}`);
+    if (schema.exclusiveMinimum !== undefined && value <= schema.exclusiveMinimum) fail('exclusiveMinimum', '<= exclusiveMinimum');
+    if (schema.exclusiveMaximum !== undefined && value >= schema.exclusiveMaximum) fail('exclusiveMaximum', '>= exclusiveMaximum');
   }
   if (typeof value === 'string') {
-    if (schema.minLength !== undefined && value.length < schema.minLength) errors.push(`${at}: shorter than minLength ${schema.minLength}`);
-    if (schema.maxLength !== undefined && value.length > schema.maxLength) errors.push(`${at}: longer than maxLength ${schema.maxLength}`);
-    if (schema.pattern !== undefined && !new RegExp(schema.pattern).test(value)) errors.push(`${at}: does not match pattern`);
+    if (schema.minLength !== undefined && value.length < schema.minLength) fail('minLength', `shorter than minLength ${schema.minLength}`);
+    if (schema.maxLength !== undefined && value.length > schema.maxLength) fail('maxLength', `longer than maxLength ${schema.maxLength}`);
+    if (schema.pattern !== undefined && !new RegExp(schema.pattern).test(value)) fail('pattern', 'does not match pattern');
   }
   if (Array.isArray(value)) {
-    if (schema.minItems !== undefined && value.length < schema.minItems) errors.push(`${at}: fewer than minItems ${schema.minItems}`);
-    if (schema.maxItems !== undefined && value.length > schema.maxItems) errors.push(`${at}: more than maxItems ${schema.maxItems}`);
+    if (schema.minItems !== undefined && value.length < schema.minItems) fail('minItems', `fewer than minItems ${schema.minItems}`);
+    if (schema.maxItems !== undefined && value.length > schema.maxItems) fail('maxItems', `more than maxItems ${schema.maxItems}`);
     if (schema.uniqueItems) {
       const seen = new Set(value.map((v) => JSON.stringify(v)));
-      if (seen.size !== value.length) errors.push(`${at}: items not unique`);
+      if (seen.size !== value.length) fail('uniqueItems', 'items not unique');
     }
-    if (schema.items) value.forEach((v, i) => walk(schema.items!, v, `${at}[${i}]`, errors));
+    if (schema.items) value.forEach((v, i) => walk(schema.items!, v, `${at}[${i}]`, issues));
   }
   if (typeOf(value) === 'object') {
     const obj = value as Record<string, unknown>;
     for (const key of schema.required ?? []) {
-      if (!(key in obj) || obj[key] === undefined) errors.push(`${at}.${key}: required`);
+      if (!(key in obj) || obj[key] === undefined) fail('required', 'required', `${at}.${key}`);
     }
     if (schema.properties) {
       for (const [key, sub] of Object.entries(schema.properties)) {
-        if (key in obj && obj[key] !== undefined) walk(sub, obj[key], `${at}.${key}`, errors);
+        if (key in obj && obj[key] !== undefined) walk(sub, obj[key], `${at}.${key}`, issues);
       }
     }
   }
@@ -89,7 +117,7 @@ function walk(schema: JsonSchema, value: unknown, path: string, errors: string[]
 
 /** Validate `value` against the lean JSON-Schema subset. */
 export function validateAgainstSchema(schema: JsonSchema, value: unknown): ValidationResult {
-  const errors: string[] = [];
-  walk(schema, value, '', errors);
-  return { valid: errors.length === 0, errors };
+  const issues: ValidationIssue[] = [];
+  walk(schema, value, '', issues);
+  return { valid: issues.length === 0, errors: issues.map((i) => i.message), issues };
 }

package/src/primitives/create-tween.ts

@@ -50,8 +50,22 @@ function cubicBezier(x1: number, y1: number, x2: number, y2: number): (t: number
 
 // Matches motion's named curves so the visualizers feel like their LiveKit
 // counterparts rather than a plausible-looking approximation.
+//
+// Every easing here is TOTAL: it clamps `t` into [0, 1] itself rather than
+// trusting its caller. `cubicBezier` already did (its Newton solve needs `t`
+// in range to converge); `linear` was the bare identity and passed anything
+// straight through. `step()` below clamps the top but not the bottom, so a
+// frame timestamp EARLIER than the origin `to()` captured yields a negative
+// `t` and, through an unclamped easing, a tween that runs backwards.
+//
+// That timestamp cannot occur in a browser -- requestAnimationFrame's
+// timestamp and `performance.now()` share a time origin per spec -- so this is
+// robustness, not a live bug. It does occur under vitest + jsdom, where the
+// two do not share an origin. The clamp lives in the easings rather than at
+// the `step()` call site so the tests can drive a negative `t` through each
+// curve individually and prove which ones guard.
 const EASINGS = {
-  linear: (t: number) => t,
+  linear: (t: number) => Math.min(1, Math.max(0, t)),
   easeIn: cubicBezier(0.42, 0, 1, 1),
   easeOut: cubicBezier(0, 0, 0.58, 1),
   easeInOut: cubicBezier(0.42, 0, 0.58, 1),
@@ -63,8 +77,15 @@ const EASINGS = {
  * `bounce` maps to the damping ratio: 0 is critically damped (no overshoot),
  * higher values overshoot more. Matches the feel of motion's spring defaults
  * closely enough for shader uniforms, without the dependency.
+ *
+ * `t` is clamped at 0 for the same reason the named easings are (see EASINGS),
+ * and the failure here is far louder than theirs: the decay term is
+ * `Math.exp(-zeta * omega * t)`, so a negative `t` makes it GROW rather than
+ * decay. At t = -0.25 with bounce 0.4 this returned ~5.9 instead of something
+ * in [0, ~1.3]. No top clamp: overshooting past 1 is what a spring is for.
  */
 function spring(t: number, bounce: number): number {
+  t = Math.max(0, t);
   const zeta = Math.max(0.05, 1 - Math.min(0.95, bounce));
   const omega = 10;
   const damped = omega * Math.sqrt(Math.max(0, 1 - zeta * zeta));
@@ -108,8 +129,39 @@ export function createTween(initial: number): {
   let raf = 0;
   let disposed = false;
 
+  /**
+   * `cancelAnimationFrame`, captured at SETUP.
+   *
+   * `stop()` below runs at dispose, and dispose is not guaranteed to happen
+   * while the page that mounted this tween is still standing -- a host can tear
+   * its DOM globals down in between (`component-register`'s
+   * `disconnectedCallback` defers a microtask; a test environment deletes the
+   * globals synchronously right after detaching). A bare `cancelAnimationFrame`
+   * there throws from a promise nobody holds, so it surfaces as an unhandled
+   * rejection that fails a run in which every test passed. 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.
+   *
+   * GUARDED because "setup" for this primitive is the component body, and a
+   * server render executes component bodies. Node has no `cancelAnimationFrame`
+   * at all, so an unguarded capture here would trade the disposal crash for an
+   * SSR crash -- measured, not hypothesised. Nothing can be scheduled without
+   * `requestAnimationFrame` either, so the no-op fallback is exactly right.
+   */
+  const cancelFrame = typeof cancelAnimationFrame === 'function'
+    ? cancelAnimationFrame.bind(globalThis)
+    : () => {};
+
   const stop = () => {
-    if (raf) cancelAnimationFrame(raf);
+    if (raf) cancelFrame(raf);
     raf = 0;
   };
 

package/src/primitives/message-feedback.ts

@@ -9,6 +9,7 @@
 
 import { createSignal, onCleanup } from 'solid-js';
 import type { ChatMessage, FeedbackVote } from '../elements/chat-types';
+import { partsToText } from '../state';
 import { toast } from './toast-store';
 
 /** Detail shape emitted by the action row. `state` is present only for the
@@ -38,7 +39,7 @@ export interface MessageFeedback {
   /** Whether a message's copy button should currently show its check. */
   isCopied: (id: string) => boolean;
   /** Route a clicked action through copy / vote / passthrough handling. */
-  handleAction: (m: Pick<ChatMessage, 'id' | 'content' | 'feedback'>, action: string) => void;
+  handleAction: (m: Pick<ChatMessage, 'id' | 'parts' | 'feedback'>, action: string) => void;
 }
 
 const DEFAULT_COPIED_DURATION = 2000;
@@ -96,7 +97,7 @@ export function createMessageFeedback(opts: MessageFeedbackOptions): MessageFeed
   const handleAction: MessageFeedback['handleAction'] = (m, action) => {
     if (action === 'copy') {
       // Clipboard may be unavailable (insecure context / jsdom); fail soft.
-      try { navigator.clipboard?.writeText(m.content); } catch { /* ignore */ }
+      try { navigator.clipboard?.writeText(partsToText(m.parts)); } catch { /* ignore */ }
       markCopied(m.id);
       toast('Copied to clipboard', { target: opts.target?.() });
       opts.emit({ messageId: m.id, action });

package/src/primitives/use-audio-analysis.ts

@@ -237,6 +237,25 @@ export function useAudioAnalysis(
     const ctx = getContext();
     if (!ctx) return; // SSR, or a browser without Web Audio.
     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);
 
     const stopResume = resumeOnGesture(ctx);
 
@@ -302,7 +321,7 @@ export function useAudioAnalysis(
     raf = requestAnimationFrame(step);
 
     onCleanup(() => {
-      cancelAnimationFrame(raf);
+      cancelFrame(raf);
       stopResume();
       bandsAnalyser.disconnect();
       volumeAnalyser.disconnect();