@kitn.ai/ui 0.28.0 → 0.29.0

package/src/remote/origin.ts

@@ -1,30 +0,0 @@
-export function assertOrigin(actual: string, expected: string): boolean {
-  return typeof actual === 'string' && actual.length > 0 && actual === expected;
-}
-
-/** Fail-closed precondition (H-F): the iframe must be cross-origin to the host so
- *  `allow-same-origin` can't reach host DOM, and `src` must be on the provider origin. */
-export function assertCrossOrigin(src: string, providerOrigin: string, hostOrigin: string): void {
-  const srcOrigin = new URL(src).origin;
-  if (providerOrigin === hostOrigin) throw new Error('[kai-remote] providerOrigin must be cross-origin to the host');
-  if (srcOrigin === hostOrigin) throw new Error('[kai-remote] src must not be same-origin as the host');
-  if (srcOrigin !== providerOrigin) throw new Error('[kai-remote] src origin must equal providerOrigin');
-}
-
-/** Field-positive log redaction (H-H/H-P): keep structural keys, redact secrets +
- *  unknown leaf values by default. nonce + authToken are always redacted. */
-const SAFE_KEYS = new Set(['protocol', 'version', 'dir', 'kind', 'mode', 'locale', 'edge', 'code', 'acceptedVersion', 'supportedVersions', 'cardId', 'type', 'id', 'height', 'target']);
-const ALWAYS_REDACT = new Set(['authToken', 'nonce']);
-export function redactFrame(value: unknown): unknown {
-  if (Array.isArray(value)) return value.map(redactFrame);
-  if (value && typeof value === 'object') {
-    const out: Record<string, unknown> = {};
-    for (const [k, v] of Object.entries(value)) {
-      if (ALWAYS_REDACT.has(k)) out[k] = '[redacted]';
-      else if (typeof v === 'object' && v !== null) out[k] = redactFrame(v);
-      else out[k] = SAFE_KEYS.has(k) ? v : '[redacted]';
-    }
-    return out;
-  }
-  return value;
-}

package/src/remote/provider-runtime.ts

@@ -1,262 +0,0 @@
-// src/remote/provider-runtime.ts
-// The provider iframe-side bridge: handshake responder + CardHost impl + auto-height.
-// Security-critical, stateful, vanilla DOM ONLY — NO SolidJS imports (ships in the
-// SolidJS-free `@kitn.ai/ui/provider` bundle). See the iframe-transport design spec
-// (Provider iframe runtime surface + addendum H-A/H-D/H-E/H-J/H-H).
-
-import {
-  type CardEnvelope,
-  type CardContext,
-  type CardEvent,
-  type CardHost,
-} from '../primitives/card-contract';
-import { createPacker, isCardWireFrame, type WireMessage } from './wire';
-import { assertOrigin, redactFrame } from './origin';
-import { negotiateVersion } from './version';
-import { hasPollutionKey } from './validate';
-import { observeDocumentHeight } from '../primitives/use-resize-observer';
-import { validateAgainstSchema, type JsonSchema } from '../primitives/card-validate';
-
-/** 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 {
-  /** The card `type` this renderer handles. */
-  type: string;
-  /** Optional JSON Schema for this type's `data`; validated best-effort before mount. */
-  schema?: JsonSchema;
-  /** Mount into `root`, given the envelope + a CardHost. Return a disposer. */
-  mount(root: HTMLElement, envelope: CardEnvelope, host: CardHost): () => void;
-}
-
-export interface CreateCardBridgeOptions {
-  /** Element the card mounts into + whose height is observed. */
-  root: HTMLElement;
-  /** Renderers by card type. Unknown type → inline "unsupported card" + event{error}. */
-  renderers: RemoteCardRenderer[];
-  /** Versions this runtime supports (default ['1']). */
-  supportedVersions?: string[];
-}
-
-export interface CardBridge {
-  /** Begin: listen for `hello`, complete handshake, render on `render`. */
-  start(): void;
-  /** Stop observers + listeners + dispose current card. */
-  stop(): void;
-}
-
-const DEFAULT_VERSIONS = ['1'];
-
-/** A minimal complete-enough default so `CardHost.context()` never returns undefined
- *  (the contract's return is non-optional) before the first `context` frame. */
-function defaultContext(): CardContext {
-  return { theme: { mode: 'light' }, locale: 'en' };
-}
-
-export function createCardBridge(options: CreateCardBridgeOptions): CardBridge {
-  const { root, renderers } = options;
-  const hostVersions = options.supportedVersions ?? DEFAULT_VERSIONS;
-  const rendererByType = new Map(renderers.map((r) => [r.type, r] as const));
-
-  // ── Locked-after-hello bridge identity (H-A/H-C). null until the first valid hello. ──
-  let lockedSource: unknown = null;
-  let lockedOrigin: string | null = null;
-  let nonce: string | null = null;
-  let negotiated: string | null = null;
-  let packer: ReturnType<typeof createPacker> | null = null;
-  let stopped = false; // tombstone: rejects all inbound once the version is unsupported / stopped
-
-  // ── Render state (H-E). One card at a time in v1. ──
-  let context: CardContext | null = null;
-  let currentId: string | null = null;
-  let currentEnvelope: CardEnvelope | null = null;
-  let dispose: (() => void) | null = null;
-  let stopObserver: (() => void) | null = null;
-  // The theme key applied at the current mount. A `context` push only forces a
-  // dispose+remount when the theme actually changes (renderers apply theme
-  // imperatively at mount); token/locale/a11y refreshes are read on-demand via
-  // host.context() and must NOT wipe in-progress card state.
-  let appliedThemeKey: string | null = null;
-  const themeKey = (c: CardContext | null) => JSON.stringify(c?.theme ?? null);
-
-  function warnDrop(data: unknown): void {
-    try { console.warn('[kai-remote]', redactFrame(data)); } catch { /* best-effort */ }
-  }
-
-  function postUp(message: WireMessage): void {
-    if (!packer || !lockedOrigin) return;
-    try { (parent as Window).postMessage(packer(message), lockedOrigin); } catch { /* best-effort */ }
-  }
-
-  const cardHost: CardHost = {
-    context: () => context ?? defaultContext(),
-    // HOST CONTRACT: the host MUST validate inbound event.cardId against the active card,
-    // because the provider cannot fence a replaced/stale renderer's host.emit calls.
-    emit: (event: CardEvent) => postUp({ dir: 'up', kind: 'event', event }),
-  };
-
-  function disposeCurrent(): void {
-    if (dispose) {
-      try { dispose(); } catch { /* renderer disposer threw — best-effort */ }
-    }
-    dispose = null;
-    currentId = null;
-    currentEnvelope = null;
-    appliedThemeKey = null;
-  }
-
-  function startObserver(): void {
-    // Tear down any existing observer so observeDocumentHeight's internal `last` baseline
-    // re-initializes to -1 and the newly-mounted card always emits its initial height.
-    // observeDocumentHeight (not observeContentHeight) so the reported height covers
-    // the FULL rendered document — root's own padding/border AND the provider page's
-    // body padding above it — not just root's ResizeObserver content-box (D1).
-    stopObserver?.(); stopObserver = null;
-    stopObserver = observeDocumentHeight(root, (height) => {
-      if (!currentId) return;
-      cardHost.emit({ kind: 'resize', cardId: currentId, height });
-    });
-  }
-
-  function renderUnsupported(envelope: CardEnvelope, message: string): void {
-    disposeCurrent();
-    root.replaceChildren();
-    const el = document.createElement('div');
-    el.setAttribute('role', 'alert');
-    el.textContent = `Unsupported card: ${envelope.type}`;
-    root.appendChild(el);
-    currentId = envelope.id;
-    startObserver(); // placeholder has a height the host must know about
-    cardHost.emit({ kind: 'error', cardId: envelope.id, message });
-  }
-
-  function handleRender(envelope: CardEnvelope): void {
-    // Prototype-pollution guard (H-D): nested data is forwarded to app handlers.
-    if (hasPollutionKey(envelope.data)) {
-      renderUnsupported(envelope, 'rejected: payload contains a prohibited key');
-      return;
-    }
-    const renderer = rendererByType.get(envelope.type);
-    if (!renderer) {
-      renderUnsupported(envelope, `no renderer registered for type "${envelope.type}"`);
-      return;
-    }
-    // Best-effort schema validation (H-D). On failure: placeholder + event{error}.
-    if (renderer.schema) {
-      const result = validateAgainstSchema(renderer.schema, envelope.data);
-      if (!result.valid) {
-        renderUnsupported(envelope, `invalid card data: ${result.errors.join('; ')}`);
-        return;
-      }
-    }
-
-    // Re-render rules (H-E): same id OR different id → dispose current, clear, mount new
-    // (v1 has no in-place renderer update path).
-    disposeCurrent();
-    root.replaceChildren();
-    try {
-      dispose = renderer.mount(root, envelope, cardHost) ?? (() => {});
-      currentId = envelope.id;
-      currentEnvelope = envelope;
-      appliedThemeKey = themeKey(context);
-    } catch {
-      // NON-REFLECTIVE fault (H-H): never echo envelope/context content.
-      dispose = null;
-      currentId = envelope.id; // onError needs a cardId even on mount failure
-      postUp({ dir: 'up', kind: 'fault', code: 'render-failed', message: 'card failed to render' });
-      return;
-    }
-    startObserver();
-  }
-
-  function onMessage(event: MessageEvent): void {
-    if (stopped) return;
-    const data = event.data;
-
-    // ── Pre-lock: only the FIRST valid down `hello` from window.parent locks the bridge. ──
-    if (lockedSource === null) {
-      if (!isCardWireFrame(data, 'down')) return;
-      if (data.message.kind !== 'hello') return;
-      if (event.source !== window.parent) return; // host source must be the parent window
-      const supported = (data.message as { supportedVersions: string[] }).supportedVersions;
-      const picked = negotiateVersion(supported, hostVersions);
-      const echoedNonce = data.nonce;
-      const origin = event.origin;
-      if (picked === null) {
-        // No common version → fault with the host's first supported version + received nonce.
-        try {
-          (parent as Window).postMessage(
-            createPacker(hostVersions[0], echoedNonce)({ dir: 'up', kind: 'fault', code: 'version-unsupported', message: 'no compatible protocol version' }),
-            origin,
-          );
-        } catch { /* best-effort */ }
-        stopped = true; // refuse further frames
-        return;
-      }
-      // Lock identity.
-      lockedSource = event.source;
-      lockedOrigin = origin;
-      nonce = echoedNonce;
-      negotiated = picked;
-      packer = createPacker(negotiated, nonce);
-      postUp({ dir: 'up', kind: 'ready', acceptedVersion: negotiated, capabilities: { types: renderers.map((r) => r.type) } });
-      return;
-    }
-
-    // ── Post-lock: ALL gates must pass (H-A source + origin + H-D direction + nonce + version). ──
-    if (event.source !== lockedSource) { warnDrop(data); return; }
-    if (!assertOrigin(event.origin, lockedOrigin!)) { warnDrop(data); return; }
-    if (!isCardWireFrame(data, 'down')) { warnDrop(data); return; }
-    if (data.nonce !== nonce) { warnDrop(data); return; }
-    if (data.version !== negotiated) { warnDrop(data); return; }
-
-    try {
-      const message = data.message;
-      switch (message.kind) {
-        case 'hello':
-          // Re-hello after lock is ignored (bridge identity is fixed for its generation).
-          return;
-        case 'context': {
-          const next = (message as { context: CardContext }).context;
-          context = next;
-          // Live context push. Renderers read host.context() on-demand, so silent
-          // token/locale/a11y refreshes need NO remount — storing the new context is
-          // enough. Only a THEME change requires a dispose+remount, since renderers
-          // apply theme imperatively at mount (v1 has no in-place update hook).
-          if (currentEnvelope && themeKey(next) !== appliedThemeKey) {
-            handleRender(currentEnvelope); // handleRender resets appliedThemeKey
-          }
-          return;
-        }
-        case 'render':
-          handleRender((message as { envelope: CardEnvelope }).envelope);
-          return;
-        case 'teardown':
-          teardown();
-          return;
-        default:
-          warnDrop(data);
-          return;
-      }
-    } catch (e) {
-      // No throw may escape the message handler — the listener must survive.
-      warnDrop(data);
-    }
-  }
-
-  function teardown(): void {
-    disposeCurrent();
-    if (stopObserver) { stopObserver(); stopObserver = null; }
-    root.replaceChildren();
-  }
-
-  return {
-    start() {
-      window.addEventListener('message', onMessage);
-    },
-    stop() {
-      stopped = true;
-      window.removeEventListener('message', onMessage);
-      teardown();
-    },
-  };
-}

package/src/remote/provider.ts

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

package/src/remote/validate.ts

@@ -1,22 +0,0 @@
-import type { CardEventKind } from '../primitives/card-contract';
-
-const POLLUTION = new Set(['__proto__', 'constructor', 'prototype']);
-/** Recursive guard (H-D): nested data/patch/context are forwarded to app handlers. */
-export function hasPollutionKey(value: unknown): boolean {
-  if (Array.isArray(value)) return value.some(hasPollutionKey);
-  if (value && typeof value === 'object') {
-    for (const k of Object.keys(value)) {
-      if (POLLUTION.has(k)) return true;
-      if (hasPollutionKey((value as Record<string, unknown>)[k])) return true;
-    }
-  }
-  return false;
-}
-
-// Verbs MUST match CardEventKind in card-contract.ts (verify against source).
-const KINDS: ReadonlySet<string> = new Set<CardEventKind>([
-  'ready', 'submit', 'action', 'send-prompt', 'open', 'resize', 'state', 'dismiss', 'error',
-] as CardEventKind[]);
-export function isKnownEventKind(k: unknown): k is CardEventKind {
-  return typeof k === 'string' && KINDS.has(k);
-}

package/src/remote/version.ts

@@ -1,12 +0,0 @@
-/** Contract versions are decimal integer strings ('1','2',…). */
-export function isValidVersion(s: string): boolean {
-  return /^[0-9]+$/.test(s);
-}
-
-/** Highest version both sides support; null if disjoint or any candidate is malformed. */
-export function negotiateVersion(hostVersions: string[], mine: string[]): string | null {
-  const set = new Set(mine.filter(isValidVersion));
-  const common = hostVersions.filter((v) => isValidVersion(v) && set.has(v));
-  if (common.length === 0) return null;
-  return common.sort((a, b) => Number(b) - Number(a))[0];
-}

package/src/remote/wire.ts

@@ -1,48 +0,0 @@
-import { type CardEnvelope, type CardContext, type CardEvent } from '../primitives/card-contract';
-
-export const CARD_WIRE_PROTOCOL = 'kitn-card' as const;
-
-export interface WireFrame<M extends WireMessage = WireMessage> {
-  protocol: typeof CARD_WIRE_PROTOCOL;
-  /** The NEGOTIATED contract version (set by the per-bridge packer). */
-  version: string;
-  /** Per-bridge instance nonce (host-minted, echoed on every up-frame). */
-  nonce: string;
-  message: M;
-}
-
-export type DownMessage =
-  | { dir: 'down'; kind: 'hello'; supportedVersions: string[] }
-  | { dir: 'down'; kind: 'render'; envelope: CardEnvelope }
-  | { dir: 'down'; kind: 'context'; context: CardContext }
-  | { dir: 'down'; kind: 'teardown' };
-
-export type UpMessage =
-  | { dir: 'up'; kind: 'ready'; acceptedVersion: string; capabilities?: { types?: string[] } }
-  | { dir: 'up'; kind: 'event'; event: CardEvent }
-  | { dir: 'up'; kind: 'focus-edge'; edge: 'start' | 'end' }
-  | { dir: 'up'; kind: 'fault'; code: WireFaultCode; message: string };
-
-export type WireFaultCode = 'version-unsupported' | 'bad-frame' | 'render-failed' | 'origin-rejected';
-export type WireMessage = DownMessage | UpMessage;
-
-export function createPacker(version: string, nonce: string) {
-  return function pack<M extends WireMessage>(message: M): WireFrame<M> {
-    return { protocol: CARD_WIRE_PROTOCOL, version, nonce, message };
-  };
-}
-
-/** Structural + direction guard. Host calls with 'up', runtime with 'down'.
- *  STRUCTURAL only — nonce/version equality + schema validation happen after. */
-export function isCardWireFrame(data: unknown, expectedDir: 'up' | 'down'): data is WireFrame {
-  if (typeof data !== 'object' || data === null) return false;
-  const d = data as Record<string, unknown>;
-  const m = d.message as Record<string, unknown> | undefined;
-  return (
-    d.protocol === CARD_WIRE_PROTOCOL &&
-    typeof d.version === 'string' &&
-    typeof d.nonce === 'string' &&
-    typeof m === 'object' && m !== null &&
-    m.dir === expectedDir
-  );
-}

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

@@ -1,151 +0,0 @@
-// 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 };
-}