@kitn.ai/ui 0.20.1 → 0.22.0

package/src/agent-tooling/registry.ts

@@ -1,4 +1,6 @@
 import type { Integration, Archetype } from './types';
+import openai from './integrations/openai';
+import anthropic from './integrations/anthropic';
 import openrouter from './integrations/openrouter';
 import vercelAiSdk from './integrations/vercel-ai-sdk';
 import langgraph from './integrations/langgraph';
@@ -10,7 +12,22 @@ import pydanticAi from './integrations/pydantic-ai';
 import mock from './integrations/mock';
 import { archetypes as _archetypes } from './archetypes';
 
+// The surface axis for the scaffolder's gate, derived from the presets above.
+// Re-exported here because `scripts/verify-scaffold-compiles.mjs` bundles this
+// module for its axes and must not reach past the registry for one of them.
+export {
+  BASE_COMPONENT,
+  listCapabilityGroups,
+  listSurfaceProbes,
+  type CapabilityGroup,
+  type SurfaceProbe,
+} from './archetypes';
+
+// Order is the order a scaffolding agent reads them in. `openai` and `anthropic`
+// lead because they are the two keys a developer is most likely to already hold.
 export const integrations: Integration[] = [
+  openai,
+  anthropic,
   openrouter,
   vercelAiSdk,
   langgraph,
@@ -36,6 +53,63 @@ export function listIntegrations(): Integration[] {
   return integrations;
 }
 
+/** One heading in `create-kai`'s gateway prompt. */
+export interface GatewayGroup {
+  id: 'no-backend' | 'bring-a-key' | 'bring-a-server';
+  title: string;
+  integrations: Integration[];
+}
+
+/**
+ * The gateway prompt's three groups, DERIVED — the thing the spec described and
+ * the catalog could not answer.
+ *
+ * It is here, and not in the CLI, for the reason `deps` is not in the spec's
+ * prose: a grouping maintained next to the menu that renders it is a second copy
+ * of the catalog, and it goes stale the first time an integration lands. Adding
+ * one now moves these groups by itself, because the only inputs are declared
+ * fields.
+ *
+ * THE ORDER OF THE TESTS IS THE DESIGN, not an implementation detail:
+ *
+ *   1. No route at all -> **No backend**. Exactly `mock` today, and derived from
+ *      the absence rather than from `id === 'mock'` or `category === 'mock'`: a
+ *      second no-backend entry (a canned transcript player, say) should land in
+ *      this group without editing this function.
+ *   2. `outOfBand !== 'none'` -> **Bring a server or runtime**, and this is
+ *      checked BEFORE the key test on purpose. `pydantic-ai` needs both a python
+ *      runtime and OPENAI_API_KEY; the groups are not disjoint in reality, so
+ *      something has to win, and the prerequisite does — a key is useless until
+ *      the service it authenticates is running. The prompt still asks for the
+ *      key afterwards; only the HEADING is decided here.
+ *   3. Everything else -> **Bring a key**.
+ *
+ * WHERE THIS DIVERGES FROM THE SPEC, ON PURPOSE. The spec's third group reads
+ * "Ollama, LangGraph, Mastra, Pydantic AI, Pi". `langgraph` comes out of this
+ * function in **Bring a key** instead, because its emitted route compiles the
+ * graph in process and asks for nothing but `OPENAI_API_KEY` — see the comment on
+ * its `outOfBand`. The spec sentence was written before the field existed and is
+ * wrong about that one entry; this is the derivation, so this is the answer.
+ */
+export function listGatewayGroups(): GatewayGroup[] {
+  const hasRoute = (i: Integration) =>
+    i.webRoute !== undefined || Object.keys(i.routeTemplates).length > 0;
+
+  const groups: GatewayGroup[] = [
+    { id: 'no-backend', title: 'No backend', integrations: [] },
+    { id: 'bring-a-key', title: 'Bring a key', integrations: [] },
+    { id: 'bring-a-server', title: 'Bring a server or runtime', integrations: [] },
+  ];
+  const into = (id: GatewayGroup['id']) => groups.find((g) => g.id === id)!;
+
+  for (const integration of integrations) {
+    if (!hasRoute(integration)) into('no-backend').integrations.push(integration);
+    else if (integration.outOfBand !== 'none') into('bring-a-server').integrations.push(integration);
+    else into('bring-a-key').integrations.push(integration);
+  }
+  return groups;
+}
+
 export function listArchetypes(): Archetype[] {
   return archetypes;
 }

package/src/agent-tooling/types.ts

@@ -3,9 +3,159 @@ import { z } from 'zod';
 export const Category = z.enum(['provider', 'gateway', 'framework', 'harness', 'mock']);
 export const Language = z.enum(['ts', 'python']);
 export const StreamFormat = z.enum(['openai-sse', 'ai-sdk', 'native']);
-export const Framework = z.enum(['html', 'react', 'next', 'vue', 'svelte', 'fastapi', 'express', 'worker', 'tanstack-start']);
+/**
+ * The scaffold's target.
+ *
+ * Two of these are NOT web-component consumers, and the difference is load-bearing:
+ *   - `angular` consumes `kai-*` like vue/svelte/html, but needs
+ *     `CUSTOM_ELEMENTS_SCHEMA` and binds arrays/objects with `[prop]="…"`.
+ *   - `solid` consumes the SolidJS components DIRECTLY from the `@kitn.ai/ui`
+ *     root entry. The kit is authored in Solid, so routing a Solid consumer
+ *     through the custom-element facade would ship the Solid runtime twice and
+ *     cross a reactive-context boundary for nothing.
+ */
+export const Framework = z.enum(['html', 'react', 'next', 'vue', 'svelte', 'angular', 'solid', 'fastapi', 'express', 'worker', 'tanstack-start']);
 export const Placement = z.enum(['side', 'full-page', 'docked-widget', 'inline']);
 
+/**
+ * Whether this integration's SECRET may sit in the browser bundle.
+ *
+ * Read `'needs-proxy'` as "a server hop is mandatory" and `'frontend-safe'` as
+ * "the browser may call the upstream itself". This is the flag `create-kai`
+ * consults before it decides where a key goes, so getting it wrong in the
+ * permissive direction writes an API key into client code. There is deliberately
+ * no default and no boolean: the refinement below REJECTS an integration that
+ * declares neither, because "absent" must never read as "safe".
+ *
+ * `'needs-proxy'` covers two cases, and the second is easy to miss:
+ *   1. a secret. The route holds a key, so a static bundle cannot.
+ *   2. a server-only CAPABILITY. `pi` spawns a local process; no key is involved
+ *      and a browser still cannot do it.
+ *
+ * `'frontend-safe'` is the narrow claim: nothing secret AND no server-only
+ * capability. Two integrations qualify, and both were read off their routes —
+ * `ollama` fetches `localhost:11434` with no auth header at all, and `mock`
+ * ships no route to reach.
+ *
+ * Do not infer this from the provider's name. A provider with a CORS-friendly
+ * public endpoint and one that requires a proxy look identical from outside; only
+ * the route says which it is. That is the same lesson `forwardsFromClient` and
+ * `clientToolFormat` were each added to record.
+ */
+export const KeyExposure = z.enum(['frontend-safe', 'needs-proxy']);
+
+/**
+ * What this integration needs the developer to supply OUT OF BAND — beyond an
+ * install and a key.
+ *
+ * `create-kai` groups its gateway prompt three ways: **No backend**, **Bring a
+ * key**, **Bring a server or runtime**. The third group is defined by exactly
+ * this question, and until now the catalog could not answer it. Every derivation
+ * that reproduced the spec's split did so by accident and broke on inspection:
+ *   · `category` does not separate them at all — `provider` holds `openai` and
+ *     `ollama`, `framework` holds `vercel-ai-sdk` and `langgraph`.
+ *   · a non-empty `routeTemplates` picks out `cloudflare`/`pi`/`pydantic-ai`,
+ *     which is a fact about how a route is EXPRESSED, not about what it needs.
+ *   · "declares a secret env var" puts `langgraph` and `pydantic-ai` in the key
+ *     group, which is right for one and wrong for the other.
+ * So it is declared, for the reason `keyExposure`, `forwardsFromClient` and
+ * `clientToolFormat` are each declared: only the route knows.
+ *
+ * The four values, and what makes each its own case for the CLI rather than a
+ * boolean it could have been:
+ *
+ *   · `'none'` ......... `npm install` plus (maybe) a key is the whole story.
+ *     The upstream is a remote HTTPS endpoint, or the agent runs IN the route.
+ *     `langgraph` is the one worth reading twice: it is in the spec's "server or
+ *     runtime" group and does not belong there — its emitted route builds the
+ *     graph in process (`createReactAgent` + `new ChatOpenAI(...)`), so there is
+ *     no LangGraph server anywhere and its runNote asks only for a key.
+ *   · `'local-server'` . a separate process must already be LISTENING before the
+ *     app works. The CLI cannot create it and must say so: `ollama serve` on
+ *     11434, a `mastra dev` server behind `MASTRA_URL`.
+ *   · `'local-binary'` . an executable must be on PATH; the route spawns it on
+ *     demand rather than talking to a port. Nothing is listening beforehand, so
+ *     "start the server" is the wrong instruction — `pi` is the case.
+ *   · `'language-runtime'` the emitted backend runs on a runtime the JS toolchain
+ *     does not provide, and the user starts it themselves. `pydantic-ai` is a
+ *     FastAPI service: `deps.pip`, `uvicorn main:app`, a second port.
+ *
+ * A boolean would collapse the last three, and they are three different sentences
+ * to print next to a menu item. The refinement below REFUSES an integration that
+ * declares nothing, for the same reason `keyExposure` does: a missing value read
+ * as `'none'` is a scaffold that says "npm run dev" to someone who needs to start
+ * Ollama first, and then reports as a broken kit.
+ */
+export const OutOfBand = z.enum(['none', 'local-server', 'local-binary', 'language-runtime']);
+
+/**
+ * The packages an app must install BEYOND `@kitn.ai/ui` to run this
+ * integration's route.
+ *
+ * Derived once, here, from the route's own import statements, so the CLI never
+ * has to re-parse route source to find them. Today this fact only exists as prose
+ * in `runNote`, which no installer can read.
+ *
+ * The rule, enforced by `registry.test.ts`: `npm` is exactly the set of
+ * bare-module specifiers imported by the TS route sources, normalised to package
+ * names (`@langchain/core/tools` counts as `@langchain/core`), minus `node:`
+ * builtins and minus `@kitn.ai/ui` itself, which every scaffold already depends
+ * on. `pip` is a superset of the python route's imports, because a Python app
+ * also needs its ASGI server (`uvicorn`), which nothing imports.
+ *
+ * Type-only packages (`@types/*`) are not listed: nothing imports them, so the
+ * rule cannot see them, and the frameworks that need them already carry them.
+ */
+export const DepsSchema = z.object({
+  npm: z.array(z.string()).default([]),
+  pip: z.array(z.string()).default([]),
+});
+
+/**
+ * An env var name that holds a secret rather than an address.
+ *
+ * Anchored at the END, which is the whole precision of it: `CF_API_TOKEN` and
+ * `AI_GATEWAY_API_KEY` match, while `CF_ACCOUNT_ID` and `MASTRA_URL` do not.
+ * `MASTRA_URL` is the case that stops this being a proxy for "declares any env
+ * var at all" — a base URL is not a credential.
+ *
+ * This is a SAFETY NET over the declaration, never its source. Three integrations
+ * (`langgraph`, `vercel-ai-sdk`, `pydantic-ai`) hold a key their route source
+ * never names, because the SDK reads the env var itself; their `envVars` is what
+ * catches them here, and nothing but the author reading the route would have.
+ *
+ * Exported because the scaffolder names the secrets back at the developer in its
+ * run note ("OPENAI_API_KEY stays on the server"). That sentence and the
+ * refinement below have to agree about which env vars are secret, so there is one
+ * pattern rather than two free to drift apart.
+ */
+export const SECRET_ENV_VAR = /(?:KEY|TOKEN|SECRET|PASSWORD)$/;
+
+/**
+ * A credential written into a request from route source. The second alternative
+ * is Anthropic's spelling, which is not an `Authorization` header at all.
+ */
+const AUTH_HEADER = /Authorization\s*:|['"]x-api-key['"]\s*:/i;
+
+/**
+ * A route that FETCHES a loopback address — so something local has to be
+ * listening. `ollama`'s `fetch('http://localhost:11434/v1/chat/completions')` is
+ * the case this catches.
+ *
+ * Anchored at the fetch/URL call, not matched anywhere in the source, and that
+ * precision is the whole point. Two other routes mention loopback in prose:
+ * mastra's `throw new Error('MASTRA_URL is not set… e.g. http://localhost:4111')`
+ * and pi's `console.log('chat api: http://localhost:3001/api/chat')`. A bare
+ * /localhost/ would flag both — mastra for the right answer by the wrong
+ * evidence, pi for a line about its OWN listening port, which says nothing about
+ * what it depends on. A net that is right by accident is the thing this field
+ * exists to replace, so it is narrowed until it only fires on a real dependency.
+ */
+const LOOPBACK_FETCH = /\b(?:fetch|URL)\s*\(\s*['"`]https?:\/\/(?:localhost|127\.0\.0\.1)/;
+
+/** A route that shells out. The program it names must exist on the host. */
+const SPAWNS_PROCESS = /\bfrom\s+['"]node:child_process['"]|\bspawn\s*\(/;
+
 export const IntegrationSchema = z.object({
   id: z.string(),
   title: z.string(),
@@ -14,9 +164,219 @@ export const IntegrationSchema = z.object({
   streamFormat: StreamFormat,
   envVars: z.array(z.string()).default([]),
   routeTemplates: z.record(z.string(), z.string()), // keyed by Framework value → code string
+  /**
+   * The backend as ONE web-standard handler, `(Request) => Response`, written as
+   * a complete `async function chatHandler(request: Request)` declaration.
+   *
+   * WHY THIS EXISTS. `routeTemplates` is keyed by framework, and in practice
+   * every TS integration only ever filled in `next`. Everything else fell
+   * through to it, so a svelte scaffold emitted a Next.js `export async function
+   * POST(req)` — which TYPECHECKS under SvelteKit and then throws
+   * `req.json is not a function` on the first submit, because SvelteKit calls
+   * `POST(event)`. vue and html got the same snippet with nowhere to put it.
+   *
+   * The handler BODY is portable; only the few lines that declare the route
+   * differ per framework. So integrations write the body once here and the
+   * scaffolder wraps it (see `WEB_ROUTE_ADAPTERS` in mcp/tools/scaffold.ts).
+   * `routeTemplates` stays for routes that genuinely cannot be expressed this
+   * way: a Worker using an `env` binding, an Express `(req, res)` bridge, a
+   * FastAPI service.
+   *
+   * An exact `routeTemplates[framework]` still wins over this.
+   */
+  webRoute: z.string().optional(),
   streamMapping: z.string(),                        // prose: how the stream maps to messages
   runNote: z.string(),
   docsSlug: z.string(),
+  /**
+   * The request-body fields this integration's ROUTE reads off the client and
+   * forwards upstream. Anything not listed is owned by the route or by the agent
+   * behind it.
+   *
+   * The scaffolder emits an editable const for a field only when it appears
+   * here, and that is the whole point: `model` used to be emitted whenever a
+   * route template contained the substring 'model', which is true of any
+   * template that so much as writes `model: 'llama3.2'`, so four integrations
+   * shipped an editable const their route threw away. The mirror-image bug is a
+   * `tools` array that never gets sent, which leaves kai-tool a panel no code
+   * path can populate.
+   *
+   * Empty by default, so a new integration emits nothing until its route really
+   * does forward the field.
+   */
+  forwardsFromClient: z.array(z.enum(['model', 'tools'])).default([]),
+  /**
+   * The tool-definition envelope this integration's ROUTE expects to find in the
+   * `tools` array the client POSTs. Required exactly when `forwardsFromClient`
+   * includes `'tools'`, and meaningless otherwise.
+   *
+   * WHY THIS IS DECLARED AND NOT DERIVED. It used to be looked up from
+   * `streamFormat`, and that is a category error: `streamFormat` describes the
+   * shape of the RESPONSE stream, while the tool envelope is a REQUEST concern.
+   * The two only appeared to agree because every integration that forwarded
+   * tools happened to be `openai-sse`. `anthropic` is where the conflation
+   * becomes visible — it is `streamFormat: 'native'`, which says nothing about
+   * request shape, and the old table mapped `native` to null.
+   *
+   * And keying on the integration's PROVIDER would be wrong too, which is the
+   * part worth reading the route before assuming: `anthropic`'s handler converts
+   * the array itself (`toAnthropicTools` reads `raw.function.name` /
+   * `.function.parameters`), so it wants `'openai'` here. Handing it Anthropic's
+   * own `{ name, input_schema }` shape would yield tools with a blank name. Only
+   * the route knows what it accepts, so only the integration can state it — the
+   * same reason `forwardsFromClient` lives here rather than being sniffed out of
+   * the route source.
+   *
+   * Optional in the type, mandatory in practice: the refinement below rejects an
+   * integration that forwards tools without one. There is deliberately no
+   * default — a default is how a tools array with no card in it ships silently.
+   */
+  clientToolFormat: z.enum(['openai', 'anthropic', 'jsonschema']).optional(),
+  /** See {@link DepsSchema}. Empty is a real answer: a fetch-only route needs nothing. */
+  deps: DepsSchema.default({ npm: [], pip: [] }),
+  /**
+   * See {@link KeyExposure}. Optional in the TYPE only so the refinement below
+   * owns the error message — Zod skips refinements when the base object already
+   * failed, so a plain required field would report "Invalid input" and this is
+   * the one field where the reader needs to be told what is at stake.
+   */
+  keyExposure: KeyExposure.optional(),
+  /**
+   * See {@link OutOfBand}. Optional in the TYPE only so the refinement below owns
+   * the error message — Zod skips refinements when the base object already
+   * failed, so a plain required field would report "Invalid input" and this is a
+   * field whose reader needs to be told what the four values mean.
+   */
+  outOfBand: OutOfBand.optional(),
+}).superRefine((integration, ctx) => {
+  // Enforced against the real catalog by `registry.test.ts`, which parses every
+  // integration through this schema. A new host that forwards tools therefore
+  // cannot reach the scaffolder undeclared: it fails at the catalog boundary,
+  // before any emit path has to decide what to do about it.
+  if (integration.forwardsFromClient.includes('tools') && integration.clientToolFormat === undefined) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['clientToolFormat'],
+      message:
+        `integration '${integration.id}' forwards a 'tools' array but declares no clientToolFormat. ` +
+        `State the envelope its route expects: 'openai' ({ type: 'function', function: { parameters } }), ` +
+        `'anthropic' ({ name, input_schema }), or 'jsonschema' ({ name, description, schema }). ` +
+        `Read the route's own handler to decide — a route that CONVERTS the array server-side wants the ` +
+        `shape it converts FROM, not its own provider's.`,
+    });
+  }
+
+  // ---- keyExposure ----
+  //
+  // Two checks, and the split matters. The first refuses SILENCE. The second
+  // refuses a specific LIE, and only ever in the dangerous direction: it can
+  // turn a 'frontend-safe' claim into an error, never the reverse. Declaring
+  // 'needs-proxy' where a proxy was not strictly required costs a server hop;
+  // declaring 'frontend-safe' where it was required costs the key.
+
+  if (integration.keyExposure === undefined) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['keyExposure'],
+      message:
+        `integration '${integration.id}' declares no keyExposure. State whether its SECRET may reach the ` +
+        `browser bundle: 'needs-proxy' (a key, or a server-only capability such as spawning a process, so ` +
+        `the CLI must keep it behind a server) or 'frontend-safe' (nothing secret and nothing server-only, ` +
+        `so the browser may call the upstream directly). Read the route to decide, not the provider's name: ` +
+        `a public CORS-friendly endpoint and one that requires a proxy are indistinguishable from outside. ` +
+        `There is no default on purpose — a missing flag read as "safe" is how an API key ships in client code.`,
+    });
+  }
+
+  if (integration.keyExposure === 'frontend-safe') {
+    const secrets = integration.envVars.filter((name) => SECRET_ENV_VAR.test(name));
+    if (secrets.length > 0) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['keyExposure'],
+        message:
+          `integration '${integration.id}' claims keyExposure 'frontend-safe' but declares the secret env ` +
+          `var(s) ${secrets.join(', ')}. A frontend bundle is public, so that combination puts a key in ` +
+          `client code. Use 'needs-proxy'.`,
+      });
+    }
+
+    const routeSources = [
+      ...Object.values(integration.routeTemplates),
+      ...(integration.webRoute ? [integration.webRoute] : []),
+    ];
+    if (routeSources.some((code) => AUTH_HEADER.test(code))) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['keyExposure'],
+        message:
+          `integration '${integration.id}' claims keyExposure 'frontend-safe' but its route sends an ` +
+          `authorization header, so it holds a credential a browser bundle must not. Use 'needs-proxy'.`,
+      });
+    }
+  }
+
+  // ---- outOfBand ----
+  //
+  // Same two-check shape as keyExposure, and the same asymmetry. The first
+  // refuses SILENCE. The second refuses a specific LIE, and only in the direction
+  // that costs the developer something: it can turn a `'none'` claim into an
+  // error, never the reverse. Over-declaring prints a prerequisite that was not
+  // strictly needed; under-declaring ships a scaffold that cannot possibly run
+  // and blames the kit.
+
+  if (integration.outOfBand === undefined) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['outOfBand'],
+      message:
+        `integration '${integration.id}' declares no outOfBand. State what the developer must supply ` +
+        `BEYOND an install and a key, because that is the group create-kai's gateway prompt puts it in: ` +
+        `'none' (a remote endpoint, or the agent runs inside the route), 'local-server' (a process must ` +
+        `already be listening, e.g. 'ollama serve'), 'local-binary' (an executable on PATH that the route ` +
+        `spawns), or 'language-runtime' (the emitted backend needs a runtime the JS toolchain does not ` +
+        `provide, e.g. python + uvicorn). Read the route and the runNote to decide, not the category: ` +
+        `'provider' holds both openai and ollama. There is no default on purpose — a missing value read ` +
+        `as 'none' is a scaffold that says "npm run dev" to someone who has nothing to connect to.`,
+    });
+  }
+
+  if (integration.outOfBand === 'none') {
+    const routeSources = [
+      ...Object.values(integration.routeTemplates),
+      ...(integration.webRoute ? [integration.webRoute] : []),
+    ];
+    if (integration.language === 'python') {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['outOfBand'],
+        message:
+          `integration '${integration.id}' claims outOfBand 'none' but its route is python, so a consumer ` +
+          `whose whole toolchain is node cannot run it without an interpreter and an ASGI server they ` +
+          `start themselves. Use 'language-runtime'.`,
+      });
+    }
+    if (routeSources.some((code) => SPAWNS_PROCESS.test(code))) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['outOfBand'],
+        message:
+          `integration '${integration.id}' claims outOfBand 'none' but its route spawns a child process, ` +
+          `so the program it spawns has to be installed on the host — nothing in package.json puts it ` +
+          `there. Use 'local-binary'.`,
+      });
+    }
+    if (routeSources.some((code) => LOOPBACK_FETCH.test(code))) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['outOfBand'],
+        message:
+          `integration '${integration.id}' claims outOfBand 'none' but its route fetches a loopback ` +
+          `address, so something local has to be listening before the first message works. ` +
+          `Use 'local-server'.`,
+      });
+    }
+  }
 });
 export type Integration = z.infer<typeof IntegrationSchema>;
 

package/src/components/artifact-card.tsx

@@ -0,0 +1,120 @@
+// src/components/artifact-card.tsx
+// The `artifact` built-in card: chrome + sizing around <Artifact>, plus the
+// bridge from its observation callbacks onto the frozen Card Contract.
+import { createUniqueId, untrack, Show, type JSX } from 'solid-js';
+import type { CardHost } from '../primitives/card-contract';
+import { Artifact } from './artifact';
+
+// `ArtifactCardData` is AUTHORED IN ../primitives/card-data-types.ts, along with
+// `ArtifactCardFile` — the same declaration `FileTree`/`Artifact` use, which is
+// why nothing here restates the file shape. See the note in confirm-card.tsx, or
+// that file's header, for why the card payload types left a `.tsx` and why they
+// are `type` aliases. Re-exported here unchanged.
+
+import type { ArtifactCardData } from '../primitives/card-data-types';
+
+export type {
+  ArtifactCardData,
+  ArtifactCardEnvelope,
+  ArtifactCardFile,
+  ArtifactCardTab,
+} from '../primitives/card-data-types';
+
+/** Height the artifact card falls back to. Tall enough that a framed page is
+ *  actually legible in a thread, short enough to leave the conversation visible. */
+export const DEFAULT_ARTIFACT_CARD_HEIGHT = '420px';
+
+function resolveHeight(height: number | string | undefined): string {
+  if (typeof height === 'number') return `${height}px`;
+  if (typeof height === 'string' && height.trim() !== '') return height;
+  return DEFAULT_ARTIFACT_CARD_HEIGHT;
+}
+
+export interface ArtifactCardProps {
+  data: ArtifactCardData;
+  cardId: string;
+  heading?: string;
+  host?: CardHost;
+}
+
+/** Chrome + sizing around `<Artifact>` for the `artifact` card type.
+ *
+ *  WHY A WRAPPER IS REQUIRED, not cosmetic. `<Artifact>`'s root is
+ *  `flex h-full w-full flex-col` — it is built to FILL a container that already
+ *  has a height (a resizable panel, a split view). A message thread gives its
+ *  parts no height at all, so `h-full` resolves against an auto-height parent,
+ *  the frame computes to ZERO, and the card renders as an invisible nothing.
+ *  The explicit `height` here is what makes the card visible; `data.height`
+ *  overrides it.
+ *
+ *  `part`/`data-card-type` are stable handles. `CardRenderer` renders card
+ *  components bare, and in the web-component path `cardComponentsFromTags` maps a
+ *  non-overridden built-in straight to its Solid component — so there is no
+ *  `<kai-artifact>` tag in the DOM to point at. This wrapper is the only stable
+ *  thing to select, which is what lets a test count rendered artifacts inside
+ *  `<kai-thread>`'s shadow root.
+ *
+ *  `part="card"` matches the other chromed cards, which get it from `<Card>`;
+ *  this one hand-rolls its chrome and so states it directly. The artifact-specific
+ *  handle is `data-card-type`, NOT a second part token: every `::part` name has to
+ *  be declared in `elements/slots.ts` (the drift guard in `slots.test.ts` enforces
+ *  it), so adding an `artifact` part is a deliberate public-API decision to make
+ *  there, not something to smuggle in from a component.
+ *
+ *  `envelope.title` renders as a HEADING above the frame rather than being folded
+ *  into `displayUrl`: the address field states where the preview is pointing, and
+ *  overwriting it with a title would make it lie. A heading is also what the four
+ *  other chromed cards (form/confirm/tasks/choice) already do with `title`.
+ *
+ *  `tab`/`activeFile` are SEEDS, never re-asserted — see their notes on
+ *  `ArtifactCardData`. A revised envelope must not undo what the user did.
+ *
+ *  The three observation callbacks emit the contract's EXISTING `state` verb —
+ *  the contract is frozen, and a new kind would force a CARD_CONTRACT_VERSION
+ *  bump. Each patch key mirrors a `data` field name, so a host can merge the
+ *  patch straight back into `envelope.data` and re-send it; `addCard` upserts on
+ *  `envelope.id`, so that round-trip revises the card instead of duplicating it. */
+export function ArtifactCard(props: ArtifactCardProps): JSX.Element {
+  const headingId = createUniqueId();
+  // Read ONCE, non-reactively: these seed the view and must not be re-asserted
+  // when a revision replaces the envelope. See ArtifactCardData.activeFile.
+  const seedTab = untrack(() => props.data.tab);
+  const seedActiveFile = untrack(() => props.data.activeFile);
+  const patch = (p: Record<string, unknown>) =>
+    props.host?.emit({ kind: 'state', cardId: props.cardId, patch: p });
+
+  return (
+    <div
+      part="card"
+      data-card-type="artifact"
+      data-card-id={props.cardId}
+      role="group"
+      aria-labelledby={props.heading ? headingId : undefined}
+      aria-label={props.heading ? undefined : 'Artifact'}
+      style={{ height: resolveHeight(props.data.height) }}
+      class="flex w-full flex-col overflow-hidden rounded-xl border border-border bg-card"
+    >
+      <Show when={props.heading}>
+        <h3
+          id={headingId}
+          class="shrink-0 truncate border-b border-border px-3 py-2 text-sm font-medium text-foreground"
+        >
+          {props.heading}
+        </h3>
+      </Show>
+      <div class="min-h-0 flex-1">
+        <Artifact
+          src={props.data.src}
+          files={props.data.files}
+          defaultTab={seedTab}
+          activeFile={seedActiveFile}
+          displayUrl={props.data.displayUrl}
+          iframeTitle={props.heading ? `${props.heading} preview` : 'Artifact preview'}
+          onNavigate={(url) => patch({ src: url })}
+          onTabChange={(tab) => patch({ tab })}
+          onFileSelect={(path) => patch({ activeFile: path })}
+        />
+      </div>
+    </div>
+  );
+}

package/src/components/audio-visualizer/index.tsx

@@ -326,6 +326,15 @@ export function AudioVisualizer(props: AudioVisualizerProps): JSX.Element {
     void load()
       .then((m) => { if (!cancelled) setShader(() => m.default); })
       .catch((err) => {
+        // Same `cancelled` check as the `.then` above. The two handlers were
+        // asymmetric: a rejection arriving after this effect was disposed
+        // still warned, even though there is no longer a component to fall
+        // back to and nothing the message could usefully tell anyone. Worse,
+        // the warning surfaces against whatever is running by the time the
+        // rejection lands rather than against the mount that asked for the
+        // chunk, so it reads as a fault in unrelated code -- in a test run,
+        // in an unrelated test.
+        if (cancelled) return;
         console.warn(
           `<kai-audio-visualizer variant="${v}">: failed to load the shader chunk, falling back to bars.`,
           err,