@kitnai/chat 0.7.0 → 0.8.0

package/src/primitives/card-schemas/form.result.schema.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kitn.ai/schemas/card/form.result.schema.json",
+  "title": "kc-form submit-data payload",
+  "description": "The CardEvent {kind:'submit-data'} `data` for a form card: an object that validates against the form-definition schema that was sent down in CardEnvelope.data. Standard JSON Schema validation (type/enum/required/min-max/length/pattern) holds. Optional empty strings are omitted.",
+  "type": "object"
+}

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

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kitn.ai/schemas/card/form.schema.json",
+  "title": "kc-form data (a form definition)",
+  "description": "The CardEnvelope.data for a card of type 'form': a JSON Schema (type:'object') describing the fields kc-form renders, plus optional x-kc-* UI hints. The same schema validates the submission.",
+  "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-kc-order": { "type": "array", "items": { "type": "string" } },
+    "x-kc-inlineMax": { "type": "integer", "minimum": 1 },
+    "x-kc-submitLabel": { "type": "string" },
+    "x-kc-dismissible": { "type": "boolean" },
+    "x-kc-actions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "label"],
+        "properties": {
+          "id": { "type": "string" },
+          "label": { "type": "string" },
+          "variant": { "enum": ["default", "ghost", "outline"] }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kitn.ai/schemas/card/link.schema.json",
+  "title": "LinkCardData",
+  "description": "Rich link / Open-Graph preview payload. The card renders from this; it never fetches.",
+  "type": "object",
+  "x-kc-card-type": "link",
+  "x-kc-contract-version": "1",
+  "required": ["url"],
+  "additionalProperties": false,
+  "properties": {
+    "url": {
+      "type": "string",
+      "format": "uri",
+      "description": "Canonical destination. Opened via the contract `open` verb (target 'tab').",
+      "x-kc-format": "url"
+    },
+    "title": {
+      "type": "string",
+      "description": "OG title (og:title). Falls back to the domain when absent.",
+      "maxLength": 300
+    },
+    "description": {
+      "type": "string",
+      "description": "OG description (og:description). Clamped to 3 lines in the UI.",
+      "maxLength": 1000
+    },
+    "image": {
+      "type": "string",
+      "format": "uri",
+      "description": "Preview image (og:image). Optional; the card degrades gracefully when missing or it fails to load.",
+      "x-kc-format": "url"
+    },
+    "imageAlt": {
+      "type": "string",
+      "description": "Alt text for the preview image. Defaults to the title (or empty = decorative) when omitted.",
+      "maxLength": 300
+    },
+    "favicon": {
+      "type": "string",
+      "format": "uri",
+      "description": "Site favicon shown next to the domain.",
+      "x-kc-format": "url"
+    },
+    "domain": {
+      "type": "string",
+      "description": "Display domain (e.g. 'example.com'). Derived from `url` when omitted.",
+      "maxLength": 253
+    },
+    "siteName": {
+      "type": "string",
+      "description": "OG site name (og:site_name). Shown in place of the domain when present.",
+      "maxLength": 200
+    }
+  }
+}

package/src/primitives/card-schemas/task-list.result.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kitn.ai/schemas/card/task-list.result.schema.json",
+  "title": "TaskListCardResult",
+  "description": "Payload of CardEvent { kind: 'submit-data' } from a task-list card.",
+  "type": "object",
+  "required": ["selected"],
+  "properties": {
+    "selected": {
+      "type": "array",
+      "description": "Ids of the checked tasks, in the order they appear in `tasks`. Subset of the input task ids.",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    }
+  }
+}

package/src/primitives/card-schemas/task-list.schema.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kitn.ai/schemas/card/task-list.schema.json",
+  "title": "TaskListCardData",
+  "description": "Data payload for a `task-list` card (CardEnvelope.data when type='task-list').",
+  "type": "object",
+  "required": ["tasks"],
+  "properties": {
+    "mode": {
+      "type": "string",
+      "enum": ["select"],
+      "default": "select",
+      "description": "v1 supports only 'select' (toggle + confirm). 'progress' (live AG-UI status) is a future enum value; restricting it now keeps the wire forward-compatible.",
+      "x-kc-mode": true
+    },
+    "heading": {
+      "type": "string",
+      "description": "Optional in-body heading; distinct from CardEnvelope.title."
+    },
+    "tasks": {
+      "type": "array",
+      "minItems": 1,
+      "description": "The selectable rows, rendered in order.",
+      "items": {
+        "type": "object",
+        "required": ["id", "label"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Stable id; the selected ids are returned in the result. Unique within `tasks`.",
+            "x-kc-unique": true
+          },
+          "label": { "type": "string", "minLength": 1, "description": "Row label." },
+          "description": { "type": "string", "description": "Optional secondary line under the label." },
+          "checked": {
+            "type": "boolean",
+            "default": false,
+            "description": "Initial checked state of the row."
+          },
+          "disabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "Row is shown but not toggleable (and excluded from select-all)."
+          }
+        }
+      }
+    },
+    "selectAll": {
+      "type": "boolean",
+      "default": false,
+      "description": "Render a master select-all checkbox above the list.",
+      "x-kc-control": "select-all"
+    },
+    "confirmLabel": {
+      "type": "string",
+      "default": "Confirm",
+      "description": "Label for the confirm button."
+    },
+    "allowEmpty": {
+      "type": "boolean",
+      "default": false,
+      "description": "If true, confirm is enabled with zero selected (emits { selected: [] }). If false, confirm is disabled until >=1 selected."
+    },
+    "min": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Optional minimum number that must be selected to confirm.",
+      "x-kc-select-min": true
+    },
+    "max": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Optional maximum selectable; further toggles are blocked once reached.",
+      "x-kc-select-max": true
+    }
+  }
+}

package/src/primitives/card-validate.ts

@@ -0,0 +1,95 @@
+// src/primitives/card-validate.ts
+// The single shared lean JSON-Schema validator the contract mandates. Covers the
+// subset cards use; `x-*` keywords (incl. x-kc-*) are ignored. No ajv. Used at
+// every boundary (incoming card data, outgoing payloads) by cards + both transports.
+
+export interface JsonSchema {
+  type?: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object' | 'null';
+  const?: unknown;
+  enum?: unknown[];
+  required?: string[];
+  properties?: Record<string, JsonSchema>;
+  items?: JsonSchema;
+  minimum?: number; maximum?: number;
+  exclusiveMinimum?: number; exclusiveMaximum?: number;
+  minLength?: number; maxLength?: number;
+  pattern?: string;
+  minItems?: number; maxItems?: number;
+  uniqueItems?: boolean;
+  // x-* keywords (e.g. x-kc-widget) are allowed and ignored.
+  [key: `x-${string}`]: unknown;
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+function typeOf(v: unknown): string {
+  if (v === null) return 'null';
+  if (Array.isArray(v)) return 'array';
+  return typeof v;
+}
+
+function matchesType(v: unknown, t: NonNullable<JsonSchema['type']>): boolean {
+  switch (t) {
+    case 'integer': return typeof v === 'number' && Number.isInteger(v);
+    case 'number': return typeof v === 'number' && Number.isFinite(v);
+    case 'array': return Array.isArray(v);
+    case 'null': return v === null;
+    case 'object': return typeOf(v) === 'object';
+    default: return typeof v === t;
+  }
+}
+
+function walk(schema: JsonSchema, value: unknown, path: string, errors: string[]): void {
+  const at = path || '(root)';
+  if (schema.type && !matchesType(value, schema.type)) {
+    errors.push(`${at}: 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)}`);
+  }
+  if (schema.enum && !schema.enum.some((e) => JSON.stringify(e) === JSON.stringify(value))) {
+    errors.push(`${at}: 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 (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 (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.uniqueItems) {
+      const seen = new Set(value.map((v) => JSON.stringify(v)));
+      if (seen.size !== value.length) errors.push(`${at}: items not unique`);
+    }
+    if (schema.items) value.forEach((v, i) => walk(schema.items!, v, `${at}[${i}]`, errors));
+  }
+  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 (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);
+      }
+    }
+  }
+}
+
+/** 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 };
+}

package/src/primitives/embed-providers.ts

@@ -0,0 +1,254 @@
+// src/primitives/embed-providers.ts
+// Pure provider resolution for <kc-embed>: map an EmbedCardData → an embeddable
+// player URL + poster + iframe sandbox/allow. Covers youtube (privacy-enhanced
+// youtube-nocookie), vimeo (dnt=1), and generic (https-only, ORIGIN-ALLOWLISTED).
+// No network, no DOM. See docs/superpowers/specs/2026-06-13-kc-link-embed-cards-design.md.
+import type { CardEnvelope } from './card-contract';
+
+/** Media provider for an embed card. */
+export type EmbedProvider = 'youtube' | 'vimeo' | 'generic';
+
+/** Lazy media-embed payload (YouTube / Vimeo / generic player URL). */
+export interface EmbedCardData {
+  /** Media provider. 'generic' frames `url` directly. */
+  provider: EmbedProvider;
+  /** Provider video id (youtube/vimeo) when not parsing from `url`. */
+  id?: string;
+  /** Full media/watch/embed URL. */
+  url?: string;
+  /** Accessible iframe title + poster label. */
+  title?: string;
+  /** Thumbnail before play; derived for youtube/vimeo when omitted. */
+  poster?: string;
+  /** Start offset, seconds. */
+  start?: number;
+  /** Player aspect ratio. Default '16:9'. */
+  aspectRatio?: '16:9' | '4:3' | '1:1' | '9:16';
+}
+
+/** The full envelope an agent/server emits for an embed card. */
+export type EmbedCardEnvelope = CardEnvelope<'embed', EmbedCardData>;
+
+/** The `type` discriminator for embed cards. */
+export const EMBED_CARD_TYPE = 'embed' as const;
+
+export interface ResolvedEmbed {
+  /** The iframe src loaded on play (already including autoplay/start params). */
+  embedUrl: string;
+  /** Poster/thumbnail to show before play (derived when not supplied). */
+  posterUrl?: string;
+  /** sandbox attribute for the player iframe. */
+  sandbox: string;
+  /** allow attribute (fullscreen, encrypted-media, picture-in-picture, …). */
+  allow: string;
+}
+
+// A provider player NEEDS allow-scripts + allow-same-origin (its OWN origin) to run.
+// That is safe here because the framed origin is a KNOWN, trusted video provider on a
+// DIFFERENT origin than the host — same-origin policy still isolates the host page from
+// the provider. allow-popups(-to-escape-sandbox) lets "watch on YouTube" work. The
+// `allow` attribute (not sandbox) governs autoplay/fullscreen/encrypted-media.
+// Contrast <kc-artifact> (allow-scripts allow-forms, NO allow-same-origin) which frames
+// arbitrary consumer HTML and so trusts nothing.
+const PLAYER_SANDBOX =
+  'allow-scripts allow-same-origin allow-presentation allow-popups allow-popups-to-escape-sandbox';
+const PLAYER_ALLOW =
+  'accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; fullscreen';
+
+// --- generic origin allowlist (security decision) -------------------------
+//
+// A `generic` embed frames an ARBITRARY https URL. An agent-supplied generic URL is a
+// supply-chain risk, so it is REJECTED unless the app has explicitly allowlisted its
+// origin. The allowlist defaults to EMPTY: out of the box, `generic` embeds are blocked.
+const allowedGenericOrigins = new Set<string>();
+
+/**
+ * App opt-in: allow `generic` embeds whose origin is in this list. Origins are
+ * normalized via the URL parser (scheme + host + port). Only https origins are
+ * accepted (a non-https origin is ignored). Call once at app startup.
+ */
+export function configureEmbedAllowlist(origins: string[]): void {
+  for (const o of origins) {
+    const origin = normalizeOrigin(o);
+    if (origin) allowedGenericOrigins.add(origin);
+  }
+}
+
+/** True when `url`'s origin has been allowlisted for `generic` embeds. */
+export function isGenericOriginAllowed(url: string): boolean {
+  const origin = originOf(url);
+  return origin !== undefined && allowedGenericOrigins.has(origin);
+}
+
+/** Test-only: clear the generic allowlist so tests stay isolated. */
+export function __resetEmbedAllowlistForTests(): void {
+  allowedGenericOrigins.clear();
+}
+
+/** Normalize an allowlist entry (a URL or bare origin) to a canonical https origin, or undefined. */
+function normalizeOrigin(input: string): string | undefined {
+  const origin = originOf(input) ?? originOf(`https://${input}`);
+  if (!origin) return undefined;
+  return origin.startsWith('https://') ? origin : undefined;
+}
+
+/** The `scheme://host[:port]` origin of a URL, or undefined when unparseable. */
+function originOf(url: string): string | undefined {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return undefined;
+  }
+}
+
+// --- id parsing -----------------------------------------------------------
+
+/** Extract a YouTube id from a watch / youtu.be / shorts / embed URL. */
+export function parseYouTubeId(url: string): string | undefined {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return undefined;
+  }
+  const host = parsed.hostname.replace(/^www\./, '');
+  if (host === 'youtu.be') {
+    return cleanId(parsed.pathname.slice(1));
+  }
+  if (host === 'youtube.com' || host === 'm.youtube.com' || host === 'youtube-nocookie.com') {
+    const v = parsed.searchParams.get('v');
+    if (v) return cleanId(v);
+    // /shorts/<id>, /embed/<id>, /v/<id>
+    const m = parsed.pathname.match(/^\/(?:shorts|embed|v)\/([^/?#]+)/);
+    if (m) return cleanId(m[1]);
+  }
+  return undefined;
+}
+
+/** Extract a Vimeo id from a vimeo.com/<id> (or player.vimeo.com/video/<id>) URL. */
+export function parseVimeoId(url: string): string | undefined {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return undefined;
+  }
+  const host = parsed.hostname.replace(/^www\./, '');
+  if (host !== 'vimeo.com' && host !== 'player.vimeo.com') return undefined;
+  const m = parsed.pathname.match(/(?:^|\/)(\d+)(?:\/|$)/);
+  return m ? m[1] : undefined;
+}
+
+/** A provider video id must be the [A-Za-z0-9_-] alphabet (matches the schema pattern). */
+function cleanId(id: string): string | undefined {
+  return /^[A-Za-z0-9_-]+$/.test(id) ? id : undefined;
+}
+
+// --- resolution -----------------------------------------------------------
+
+/**
+ * Resolve an EmbedCardData to an embeddable player URL + poster + sandbox/allow.
+ * Throws (with a human message) on a missing/invalid provider id, a non-https
+ * generic URL, or a generic origin not in the app allowlist — the card turns these
+ * into an inline error + an `error` event.
+ */
+export function resolveEmbed(data: EmbedCardData): ResolvedEmbed {
+  const start = data.start ? `&start=${data.start}` : '';
+  switch (data.provider) {
+    case 'youtube': {
+      const id = data.id ?? (data.url ? parseYouTubeId(data.url) : undefined);
+      if (!id) throw new Error('youtube embed: missing or unparseable id/url');
+      return {
+        embedUrl: `https://www.youtube-nocookie.com/embed/${id}?autoplay=1&rel=0${start}`,
+        posterUrl: data.poster ?? `https://i.ytimg.com/vi/${id}/hqdefault.jpg`,
+        sandbox: PLAYER_SANDBOX,
+        allow: PLAYER_ALLOW,
+      };
+    }
+    case 'vimeo': {
+      const id = data.id ?? (data.url ? parseVimeoId(data.url) : undefined);
+      if (!id) throw new Error('vimeo embed: missing or unparseable id/url');
+      return {
+        embedUrl: `https://player.vimeo.com/video/${id}?autoplay=1&dnt=1${
+          data.start ? `#t=${data.start}s` : ''
+        }`,
+        // Vimeo has no static thumbnail URL; rely on a supplied poster (or placeholder).
+        posterUrl: data.poster,
+        sandbox: PLAYER_SANDBOX,
+        allow: PLAYER_ALLOW,
+      };
+    }
+    case 'generic': {
+      if (!data.url) throw new Error('generic embed: missing url');
+      assertHttpsEmbeddable(data.url);
+      if (!isGenericOriginAllowed(data.url)) {
+        throw new Error(
+          `generic embed: origin not allowlisted — call configureEmbedAllowlist([...]) to permit ${
+            originOf(data.url) ?? data.url
+          }`,
+        );
+      }
+      return { embedUrl: data.url, posterUrl: data.poster, sandbox: PLAYER_SANDBOX, allow: PLAYER_ALLOW };
+    }
+  }
+}
+
+/** Reject non-https or javascript:/data: player URLs (defense in depth). */
+function assertHttpsEmbeddable(url: string): void {
+  let protocol: string;
+  try {
+    protocol = new URL(url).protocol;
+  } catch {
+    throw new Error(`generic embed: invalid url "${url}"`);
+  }
+  if (protocol !== 'https:') {
+    throw new Error(`generic embed: only https player URLs are allowed (got ${protocol})`);
+  }
+}
+
+/**
+ * The canonical "watch on the provider" URL for the optional fallback affordance
+ * (emitted as `open`/target:'tab' when an embed is blocked). Returns `undefined`
+ * when there is nothing useful to link to.
+ */
+export function watchUrl(data: EmbedCardData): string | undefined {
+  switch (data.provider) {
+    case 'youtube': {
+      const id = data.id ?? (data.url ? parseYouTubeId(data.url) : undefined);
+      return id ? `https://www.youtube.com/watch?v=${id}` : data.url;
+    }
+    case 'vimeo': {
+      const id = data.id ?? (data.url ? parseVimeoId(data.url) : undefined);
+      return id ? `https://vimeo.com/${id}` : data.url;
+    }
+    case 'generic':
+      return data.url;
+  }
+}
+
+/** Human-readable provider label for the fallback affordance ("Open on YouTube"). */
+export function providerLabel(provider: EmbedProvider): string {
+  switch (provider) {
+    case 'youtube':
+      return 'YouTube';
+    case 'vimeo':
+      return 'Vimeo';
+    case 'generic':
+      return 'site';
+  }
+}
+
+/** CSS aspect-ratio value for a card's aspectRatio (default 16:9). */
+export function aspectRatioValue(aspectRatio: EmbedCardData['aspectRatio']): string {
+  switch (aspectRatio) {
+    case '4:3':
+      return '4 / 3';
+    case '1:1':
+      return '1 / 1';
+    case '9:16':
+      return '9 / 16';
+    case '16:9':
+    default:
+      return '16 / 9';
+  }
+}

package/src/primitives/highlighter.ts

@@ -20,6 +20,8 @@ type Loader = () => Promise<unknown>;
 const DEFAULT_LANGUAGES: Record<string, Loader> = {
   bash: () => import('@shikijs/langs/bash'),
   javascript: () => import('@shikijs/langs/javascript'),
+  typescript: () => import('@shikijs/langs/typescript'),
+  tsx: () => import('@shikijs/langs/tsx'),
   html: () => import('@shikijs/langs/html'),
   css: () => import('@shikijs/langs/css'),
   json: () => import('@shikijs/langs/json'),
@@ -32,6 +34,8 @@ const DEFAULT_THEMES: Record<string, Loader> = {
 
 const DEFAULT_ALIASES: Record<string, string> = {
   js: 'javascript',
+  ts: 'typescript',
+  jsx: 'tsx',
   sh: 'bash',
   shell: 'bash',
 };

package/src/primitives/link-preview.ts

@@ -0,0 +1,87 @@
+// src/primitives/link-preview.ts
+// The optional, app-supplied bare-URL → metadata hook for <kc-link-card>, plus the
+// `link` card's data type. The card stays PURE: it renders from supplied metadata
+// and never touches the network. CORS forbids reading cross-origin HTML in the
+// browser, so there is intentionally NO built-in network implementation here — an
+// app opts in with `configureLinkPreview({ fetchMetadata })` pointing at its OWN
+// backend/proxy. See docs/superpowers/specs/2026-06-13-kc-link-embed-cards-design.md.
+import type { CardEnvelope } from './card-contract';
+
+/** Rich link / Open-Graph preview payload. The card renders from this; it never fetches. */
+export interface LinkCardData {
+  /** Canonical destination; opened via the contract `open` verb. */
+  url: string;
+  /** og:title — falls back to the domain. */
+  title?: string;
+  /** og:description — clamped to 3 lines. */
+  description?: string;
+  /** og:image — degrades gracefully when missing/broken. */
+  image?: string;
+  /** Alt for the preview image (defaults to title / decorative). */
+  imageAlt?: string;
+  /** Site favicon. */
+  favicon?: string;
+  /** Display domain; derived from `url` when omitted. */
+  domain?: string;
+  /** og:site_name; preferred over `domain` when present. */
+  siteName?: string;
+}
+
+/** The full envelope an agent/server emits for a link card. */
+export type LinkCardEnvelope = CardEnvelope<'link', LinkCardData>;
+
+/** The `type` discriminator for link cards. */
+export const LINK_CARD_TYPE = 'link' as const;
+
+/** App-supplied resolver: a bare URL → (partial) OG metadata. Usually hits YOUR backend. */
+export type LinkMetadataFetcher = (url: string) => Promise<Partial<LinkCardData>>;
+
+let fetcher: LinkMetadataFetcher | undefined;
+
+/**
+ * App opt-in: supply a function (usually hitting YOUR backend/proxy) that resolves
+ * a bare URL to OG metadata. CORS forbids reading cross-origin HTML in the browser,
+ * so there is intentionally NO default network implementation.
+ */
+export function configureLinkPreview(opts: { fetchMetadata: LinkMetadataFetcher }): void {
+  fetcher = opts.fetchMetadata;
+}
+
+/** True when an app has registered a fetcher (the bare-URL path is available). */
+export function hasLinkPreviewFetcher(): boolean {
+  return fetcher !== undefined;
+}
+
+/**
+ * Used by LinkCard ONLY when the envelope lacks metadata AND a fetcher is set.
+ * Returns the merged metadata or throws (card shows its fallback/error state).
+ */
+export async function resolveLinkMetadata(url: string): Promise<Partial<LinkCardData>> {
+  if (!fetcher) throw new Error('No link-preview fetcher configured');
+  return fetcher(url);
+}
+
+/** Test-only: clear the configured fetcher so tests stay isolated. */
+export function __resetLinkPreviewForTests(): void {
+  fetcher = undefined;
+}
+
+/** Derive a clean display domain from a URL (strips a leading `www.`). `undefined` if unparseable. */
+export function deriveDomain(url: string): string | undefined {
+  try {
+    return new URL(url).hostname.replace(/^www\./, '');
+  } catch {
+    return undefined;
+  }
+}
+
+const RENDERABLE_SCHEMES = ['http:', 'https:'];
+
+/** True when `url` is a syntactically valid http(s) URL (the only renderable link schemes). */
+export function isRenderableLink(url: string): boolean {
+  try {
+    return RENDERABLE_SCHEMES.includes(new URL(url).protocol);
+  } catch {
+    return false;
+  }
+}