@kitn.ai/ui 0.20.1 → 0.21.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,

package/src/agent-tooling/types.ts

@@ -3,9 +3,96 @@ 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']);
+
+/**
+ * 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;
+
 export const IntegrationSchema = z.object({
   id: z.string(),
   title: z.string(),
@@ -14,9 +101,150 @@ 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(),
+}).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'.`,
+      });
+    }
+  }
 });
 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,

package/src/components/audio-visualizer/labs/lab-choreography.ts

@@ -0,0 +1,187 @@
+import type { LabLook } from './lab-shaders';
+
+/** The agent states the kit's visualizers respond to, plus manual free play. */
+export type LabState = 'manual' | 'idle' | 'connecting' | 'listening' | 'thinking' | 'speaking';
+
+export const LAB_STATES: LabState[] = ['manual', 'idle', 'connecting', 'listening', 'thinking', 'speaking'];
+
+/** Every tunable the lab shaders read. Flat on purpose: story args map 1:1. */
+export interface LabParams {
+  baseR: number; ampIdle: number; ampVoice: number; radVoice: number;
+  sigma: number; gain: number; f1: number; f2: number; s1: number; s2: number;
+  envSpd: number; sepSpd: number; whiteLo: number; whiteHi: number;
+  bloomMul: number; bloomGain: number; delta: number; off: number;
+  wWidth: number; wMin: number; fillGain: number; edgeGain: number;
+  flut: number; twistSpd: number; warpAmp: number; lens: number; spec: number;
+  tint: number; vSpeed: number; presence: number; gather: number;
+  core: number; neural: number; boltJag: number; boltWidth: number; boltRate: number;
+}
+
+const SHARED: LabParams = {
+  baseR: 0.33, ampIdle: 0.017, ampVoice: 0.043, radVoice: 0.24,
+  sigma: 0.022, gain: 0.42, f1: 6, f2: 10, s1: 0.55, s2: 0.85,
+  envSpd: 0.21, sepSpd: 0.38, whiteLo: 1.35, whiteHi: 2.3,
+  bloomMul: 2.6, bloomGain: 0.18, delta: 0.35, off: 0.024,
+  wWidth: 0.045, wMin: 0.006, fillGain: 0.38, edgeGain: 0.7,
+  flut: 0.01, twistSpd: 0.55, warpAmp: 0.75, lens: 0.85, spec: 0.35,
+  tint: 0.25, vSpeed: 2.2, presence: 1, gather: 0,
+  core: 0, neural: 0, boltJag: 0.5, boltWidth: 3, boltRate: 0.25,
+};
+
+/** Hand-tuned in the aurora playground; per-look starting points. */
+export const LOOK_DEFAULTS: Record<LabLook, LabParams> = {
+  braid: { ...SHARED },
+  ribbon: {
+    ...SHARED,
+    baseR: 0.315, ampIdle: 0.012, ampVoice: 0.032, radVoice: 0.09,
+    sigma: 0.014, gain: 0.6, f1: 3, f2: 9, s1: 1.1, s2: 2.2,
+    envSpd: 0.5, whiteLo: 1.0, whiteHi: 2.4, bloomMul: 2.5, bloomGain: 0.15,
+    wWidth: 0.085, wMin: 0.009, fillGain: 0.85, edgeGain: 0.35, twistSpd: 1.9,
+  },
+  planet: {
+    ...SHARED,
+    radVoice: 0, gain: 1.0, fillGain: 0.75, edgeGain: 0.5,
+    f2: 12, s1: 1, s2: 1, twistSpd: 1.0, warpAmp: 0.9,
+    whiteLo: 1.2, whiteHi: 2.6,
+  },
+  orb: {
+    ...SHARED,
+    radVoice: 0, gain: 1.1, fillGain: 0.65, edgeGain: 0.45,
+    f2: 10, s1: 1, s2: 1, twistSpd: 1.2, warpAmp: 1.0,
+    lens: 0.8, spec: 0.3, vSpeed: 3.0,
+  },
+};
+
+const ORB_LOOKS: LabLook[] = ['planet', 'orb'];
+
+/** Loudness loop standing in for a live voice while `speaking` (dB per third-second). */
+const ENV_DB = [-60.9, -49.0, -46.7, -54.1, -50.0, -47.8, -49.3, -53.3, -53.5, -50.4,
+  -46.9, -53.0, -50.2, -52.5, -53.9, -50.6, -50.8, -49.2, -55.1, -48.7,
+  -48.4, -47.4, -49.6, -50.7, -49.0, -46.9, -50.8, -52.9, -52.2, -46.6,
+  -46.6, -46.2];
+
+function envelopeAt(sec: number): number {
+  const x = (sec % 10.6) * 3;
+  const i = Math.max(0, Math.min(ENV_DB.length - 1, Math.floor(x)));
+  const j = Math.min(ENV_DB.length - 1, i + 1);
+  const f = x - i;
+  const db = ENV_DB[i] * (1 - f) + ENV_DB[j] * f;
+  return Math.max(0, Math.min(1, (db + 58) / 14));
+}
+
+interface Slow {
+  presence: number; gather: number; tintAdd: number; warpMul: number;
+  deltaAdd: number; f2Add: number; gainMul: number; neural: number;
+}
+
+export interface LabFrame {
+  t: number;
+  level: number;
+  values: LabParams;
+}
+
+/**
+ * The state choreography from the playground, per frame. Slow targets glide
+ * over seconds (presence slowest, so smoke visibly forms and dissipates);
+ * tempo runs on an accumulated warped clock, so state changes never jump the
+ * animation phase; the ember beats and the bolts fire in real time.
+ */
+export function createChoreography(getLook: () => LabLook, getState: () => LabState, getParams: () => LabParams) {
+  let tAnim = 0;
+  let rateSm = 1;
+  let smooth = 0;
+  let elapsed = 0;
+  const slow: Slow = { presence: 1, gather: 0, tintAdd: 0, warpMul: 1, deltaAdd: 0, f2Add: 0, gainMul: 1, neural: 0 };
+
+  const step = (dt: number): LabFrame => {
+    elapsed += dt;
+    const P = getParams();
+    const state = getState();
+    const orb = ORB_LOOKS.includes(getLook());
+    const base = orb ? 0.35 : 1.0;
+
+    const drive = envelopeAt(elapsed);
+    const k = drive > smooth ? 0.25 : 0.06;
+    smooth += (drive - smooth) * k;
+
+    const beat = Math.pow(0.5 + 0.5 * Math.sin((elapsed / 1.2) * Math.PI * 2), 3.0);
+    const flick = 0.5 + 0.5 * Math.sin((elapsed / 0.35) * Math.PI * 2);
+
+    let target: Slow;
+    let rate: number;
+    let level: number;
+    let core: number;
+    let gpulse = 0;
+    switch (state) {
+      case 'idle':
+        target = orb
+          ? { presence: 0.12, gather: -0.8, tintAdd: 0, warpMul: 1, deltaAdd: 0, f2Add: 0, gainMul: 0.85, neural: 0 }
+          : { presence: P.presence, gather: P.gather, tintAdd: 0, warpMul: 1, deltaAdd: 0, f2Add: 0, gainMul: 0.8, neural: 0 };
+        rate = base; level = 0; core = orb ? 0.06 : 0;
+        break;
+      case 'connecting':
+        target = orb
+          ? { presence: 0.22, gather: -0.25, tintAdd: 0, warpMul: 1, deltaAdd: 0, f2Add: 0, gainMul: 0.9, neural: 0 }
+          : { presence: P.presence, gather: P.gather, tintAdd: 0, warpMul: 1, deltaAdd: 0, f2Add: 0, gainMul: 0.85, neural: 0 };
+        rate = base * 1.4; level = 0.04; core = orb ? 0.18 + 0.55 * beat : 0;
+        if (!orb) gpulse = 0.2 * beat;
+        break;
+      case 'listening':
+        target = orb
+          ? { presence: 0.8, gather: 0.5, tintAdd: 0.05, warpMul: 1, deltaAdd: 0, f2Add: 0, gainMul: 1, neural: 0 }
+          : { presence: P.presence, gather: P.gather, tintAdd: 0, warpMul: 1, deltaAdd: 0, f2Add: 0, gainMul: 1, neural: 0 };
+        rate = base * 1.7; level = 0.2; core = orb ? 0.12 : 0;
+        break;
+      case 'thinking':
+        target = orb
+          ? { presence: 1, gather: 0.6, tintAdd: 0.5, warpMul: 1.3, deltaAdd: 0, f2Add: 0, gainMul: 1, neural: 1 }
+          : { presence: P.presence, gather: P.gather, tintAdd: 0, warpMul: 1, deltaAdd: 0.5, f2Add: 3, gainMul: 1, neural: 0 };
+        rate = orb ? 2.2 : 2.5; level = 0.12 + 0.2 * flick; core = orb ? 0.05 : 0;
+        if (!orb) gpulse = 0.1 * flick;
+        break;
+      case 'speaking':
+        target = orb
+          ? { presence: 1, gather: 0, tintAdd: 0, warpMul: 1.25, deltaAdd: 0, f2Add: 0, gainMul: 1.05, neural: 0 }
+          : { presence: P.presence, gather: P.gather, tintAdd: 0, warpMul: 1, deltaAdd: 0, f2Add: 0, gainMul: 1, neural: 0 };
+        rate = base * 1.5 + 5.5 * smooth; level = Math.min(1, smooth * 1.35);
+        core = orb ? 0.08 + 0.6 * smooth : 0;
+        break;
+      default:
+        target = { presence: P.presence, gather: P.gather, tintAdd: 0, warpMul: 1, deltaAdd: 0, f2Add: 0, gainMul: 1, neural: P.neural };
+        rate = base + P.vSpeed * smooth; level = smooth; core = P.core;
+    }
+
+    const mixTo = (cur: number, tgt: number, tc: number): number =>
+      cur + (tgt - cur) * (1 - Math.exp(-dt / tc));
+    slow.presence = mixTo(slow.presence, target.presence, 1.4);
+    slow.gather = mixTo(slow.gather, target.gather, 1.0);
+    slow.tintAdd = mixTo(slow.tintAdd, target.tintAdd, 0.6);
+    slow.warpMul = mixTo(slow.warpMul, target.warpMul, 0.6);
+    slow.deltaAdd = mixTo(slow.deltaAdd, target.deltaAdd, 0.6);
+    slow.f2Add = mixTo(slow.f2Add, target.f2Add, 0.6);
+    slow.gainMul = mixTo(slow.gainMul, target.gainMul, 0.6);
+    slow.neural = mixTo(slow.neural, target.neural, 0.6);
+
+    rateSm += (rate - rateSm) * (1 - Math.exp(-dt / 0.4));
+    tAnim += dt * rateSm;
+
+    return {
+      t: tAnim,
+      level,
+      values: {
+        ...P,
+        presence: slow.presence,
+        gather: slow.gather,
+        core,
+        neural: slow.neural,
+        tint: Math.min(1, P.tint + slow.tintAdd),
+        warpAmp: P.warpAmp * slow.warpMul,
+        delta: P.delta + slow.deltaAdd,
+        f2: P.f2 + slow.f2Add,
+        gain: P.gain * slow.gainMul * (1 + gpulse),
+      },
+    };
+  };
+
+  return { step };
+}