@chai-ui/core 0.1.0

package/src/engines/openrouter.ts

@@ -0,0 +1,301 @@
+/**
+ * A real text/reasoning `GenerationEngine` backed by OpenRouter
+ * (openrouter.ai) — a fully-supported alternative to the default Fal.ai
+ * (see the Develop page's "Model providers" section). Returns text: prompt
+ * enhancement, media analysis (vision/video/audio understanding), and any
+ * other text-out call.
+ *
+ * Security: this engine never sees an API key and never calls
+ * `openrouter.ai` directly. It POSTs to a same-origin `endpoint` (default
+ * `/api/chai/openrouter/chat`, served by `createChaiHandler`) that a server-side proxy owns — the proxy is the
+ * only thing that reads `OPENROUTER_API_KEY` and attaches the
+ * `Authorization` header. Passing a key into this file would put it in the
+ * browser bundle; don't add one.
+ */
+
+import { readEvaluations, type GenerationEngine } from "../engine.js";
+import type { DroppedMedia, Evaluation, MediaKind, Usage } from "../types.js";
+
+export interface OpenRouterEngineOptions {
+  /** Same-origin proxy path that attaches the real key server-side. */
+  endpoint?: string;
+  /** OpenRouter model id (e.g. "google/gemini-2.5-flash"), used when the caller passes no `modelId` and no `modelByKind` entry matches. */
+  model?: string;
+  /** Per-attached-media-kind model override, e.g. a vision model for images and a different one for audio. */
+  modelByKind?: Partial<Record<MediaKind, string>>;
+  /**
+   * Cap on the model's response length. Required in practice, not just
+   * cost hygiene: some providers/models reject a request with no cap at
+   * all (defaulting to their max, e.g. 65535) once it exceeds the
+   * account's available credits, rather than just truncating. Defaults to
+   * a one-paragraph-ish budget — enough for a "detailed" seed-prompt
+   * description.
+   */
+  maxTokens?: number;
+  /**
+   * USD per million tokens for whichever model this engine calls, if you
+   * want a real cost figure on the returned `usage` instead of just token
+   * counts. Deliberately not defaulted to anything: OpenRouter's real
+   * per-model pricing isn't tracked anywhere in this repo, and a guessed
+   * number would be worse than an honestly absent cost. Pull the real rate
+   * from OpenRouter's `/models` endpoint or your own account dashboard and
+   * pass it here if you want `usage.costUsd` populated.
+   */
+  pricePerMillionTokens?: { input: number; output: number };
+  /** Injectable for tests; defaults to the global `fetch`. */
+  fetchImpl?: typeof fetch;
+}
+
+const DEFAULT_MODEL = "google/gemini-2.5-flash";
+const DEFAULT_MAX_TOKENS = 800;
+
+type ChatContentPart =
+  | { type: "text"; text: string }
+  | { type: "image_url"; image_url: { url: string } }
+  | { type: "video_url"; video_url: { url: string } }
+  | { type: "input_audio"; input_audio: { data: string; format: string } };
+
+interface ChatCompletionResponse {
+  choices?: { message?: { content?: string } }[];
+  // OpenAI-compatible shape OpenRouter itself uses; absent on some
+  // providers routed through it, hence all-optional.
+  usage?: { prompt_tokens?: number; completion_tokens?: number; total_tokens?: number };
+  // `metadata.raw` carries the upstream provider's own JSON error as a
+  // string when OpenRouter's own `message` is just a generic wrapper (e.g.
+  // "Provider returned error") — seen live when Google AI Studio rejected
+  // a malformed image with a much more specific "Provided image is not
+  // valid" underneath.
+  error?: { message?: string; metadata?: { raw?: string } };
+}
+
+/** Converts OpenRouter's raw `usage` into `Usage`, computing `costUsd` only when a real rate was supplied. */
+function toUsage(
+  usage: ChatCompletionResponse["usage"],
+  pricePerMillionTokens?: { input: number; output: number }
+): Usage | undefined {
+  if (!usage) return undefined;
+  const promptTokens = usage.prompt_tokens ?? 0;
+  const completionTokens = usage.completion_tokens ?? 0;
+  const costUsd = pricePerMillionTokens
+    ? (promptTokens * pricePerMillionTokens.input +
+        completionTokens * pricePerMillionTokens.output) /
+      1_000_000
+    : undefined;
+  return {
+    promptTokens,
+    completionTokens,
+    totalTokens: usage.total_tokens ?? promptTokens + completionTokens,
+    costUsd,
+  };
+}
+
+/** Prefers the upstream provider's own error message over OpenRouter's generic wrapper, when both are present. */
+function describeError(json: ChatCompletionResponse, fallback: string): string {
+  const base = json.error?.message ?? fallback;
+  const raw = json.error?.metadata?.raw;
+  if (!raw) return base;
+  try {
+    const parsed = JSON.parse(raw) as { error?: { message?: string } };
+    if (parsed.error?.message && parsed.error.message !== base) {
+      return `${base} — ${parsed.error.message}`;
+    }
+  } catch {
+    // Not JSON; the generic message is all we have.
+  }
+  return base;
+}
+
+/** Builds the one non-text content part for an attached image/video/audio file. */
+export function contentPartForMedia(media: DroppedMedia): ChatContentPart {
+  if (media.kind === "video") {
+    return { type: "video_url", video_url: { url: media.src } };
+  }
+  if (media.kind === "audio") {
+    // OpenRouter's input_audio wants raw base64 + a format string, not a
+    // data: URL — audio can't be passed by URL at all per OpenRouter docs.
+    const match = /^data:audio\/(\w+);base64,(.+)$/.exec(media.src);
+    if (!match) {
+      throw new Error(
+        "openRouterEngine: audio media must be a base64 data URL (data:audio/<format>;base64,...)"
+      );
+    }
+    return { type: "input_audio", input_audio: { data: match[2]!, format: match[1]! } };
+  }
+  return { type: "image_url", image_url: { url: media.src } };
+}
+
+/** Builds the OpenRouter chat-completions request body for a prompt plus any attached media. */
+export function buildChatRequest(args: {
+  model: string;
+  prompt: string;
+  media?: DroppedMedia[];
+  maxTokens?: number;
+}): {
+  model: string;
+  messages: { role: "user"; content: ChatContentPart[] }[];
+  max_tokens: number;
+} {
+  const content: ChatContentPart[] = [{ type: "text", text: args.prompt }];
+  for (const media of args.media ?? []) content.push(contentPartForMedia(media));
+  return {
+    model: args.model,
+    messages: [{ role: "user", content }],
+    max_tokens: args.maxTokens ?? DEFAULT_MAX_TOKENS,
+  };
+}
+
+interface ChatCompletionChunk {
+  choices?: { delta?: { content?: string } }[];
+  usage?: ChatCompletionResponse["usage"];
+  error?: ChatCompletionResponse["error"];
+}
+
+/**
+ * Reads an OpenRouter server-sent-events stream (`stream: true`), calling
+ * `onText` with the accumulated reply as each chunk lands. Handles the
+ * `: OPENROUTER PROCESSING` keep-alive comments and the `[DONE]` sentinel,
+ * and still works if a proxy buffered the whole stream into one body.
+ */
+export async function readChatStream(
+  res: Response,
+  onText: (textSoFar: string) => void
+): Promise<{ text: string; usage?: ChatCompletionResponse["usage"]; evaluations?: Evaluation[] }> {
+  let text = "";
+  let usage: ChatCompletionResponse["usage"];
+  let evaluations: Evaluation[] | undefined;
+  let buffer = "";
+
+  const handleLine = (line: string) => {
+    if (!line.startsWith("data:")) return; // blank separators and ": keep-alive" comments
+    const data = line.slice(5).trim();
+    if (!data || data === "[DONE]") return;
+    let chunk: ChatCompletionChunk;
+    try {
+      chunk = JSON.parse(data) as ChatCompletionChunk;
+    } catch {
+      return;
+    }
+    if (chunk.error) {
+      throw new Error(`openRouterEngine: ${describeError({ error: chunk.error }, "stream error")}`);
+    }
+    if (chunk.usage) usage = chunk.usage;
+    // A backend that checks the output appends its verdicts as their own chunk.
+    evaluations = readEvaluations(chunk) ?? evaluations;
+    const delta = chunk.choices?.[0]?.delta?.content;
+    if (delta) {
+      text += delta;
+      onText(text);
+    }
+  };
+
+  const drain = (final: boolean) => {
+    const lines = buffer.split("\n");
+    buffer = final ? "" : lines.pop()!;
+    for (const line of lines) handleLine(line.trimEnd());
+  };
+
+  if (res.body) {
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      drain(false);
+    }
+    buffer += decoder.decode();
+  } else {
+    buffer = await res.text();
+  }
+  drain(true);
+  return { text, usage, evaluations };
+}
+
+/**
+ * Sends the prompt plus every attached file to OpenRouter via the local
+ * proxy and returns the model's reply as `"text"`. Calls the caller's
+ * `modelId` when given, otherwise `modelByKind` (keyed on the first
+ * attachment's kind), `model`, or the built-in default. Streams (OpenRouter's
+ * `stream: true`) when the caller passes `onText`; the proxy must pass the
+ * response body through rather than buffer it for that to be incremental.
+ */
+export function createOpenRouterEngine(
+  options: OpenRouterEngineOptions = {}
+): GenerationEngine {
+  const endpoint = options.endpoint ?? "/api/chai/openrouter/chat";
+  const fetchImpl = options.fetchImpl ?? fetch;
+
+  return {
+    async generate({ modelId, prompt, attachments, onText, signal }) {
+      const firstKind = attachments[0]?.kind;
+      const model =
+        modelId || (firstKind && options.modelByKind?.[firstKind]) || options.model || DEFAULT_MODEL;
+      const body = buildChatRequest({ model, prompt, media: attachments, maxTokens: options.maxTokens });
+
+      // Aborting closes the connection. On a stream, OpenRouter then stops
+      // the model and billing for providers that support it; a
+      // non-streaming request keeps running at the provider.
+      const res = await fetchImpl(endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(onText ? { ...body, stream: true } : body),
+        signal,
+      });
+
+      // A rejected request comes back as plain JSON even when streaming was
+      // asked for, so only a successful response is read as a stream.
+      if (onText && res.ok) {
+        const { text, usage, evaluations } = await readChatStream(res, onText);
+        if (!text) throw new Error("openRouterEngine: empty response from OpenRouter");
+        return { src: text, kind: "text", usage: toUsage(usage, options.pricePerMillionTokens), evaluations };
+      }
+
+      const json = (await res.json().catch(() => ({}))) as ChatCompletionResponse;
+      if (!res.ok || json.error) {
+        throw new Error(
+          `openRouterEngine: ${describeError(json, `${res.status} ${res.statusText}`)}`
+        );
+      }
+      const text = json.choices?.[0]?.message?.content;
+      if (!text) throw new Error("openRouterEngine: empty response from OpenRouter");
+      return {
+        src: text,
+        kind: "text",
+        usage: toUsage(json.usage, options.pricePerMillionTokens),
+        evaluations: readEvaluations(json),
+      };
+    },
+  };
+}
+
+/**
+ * A minimal, cheap connectivity check — the "use real inference sparingly"
+ * path. Deliberately not a `GenerationEngine` and not exercised by any
+ * automated test: it's meant to be triggered once, by a person, from the
+ * Develop page's "Test connection" button.
+ */
+export async function pingOpenRouter(
+  options: { endpoint?: string; model?: string; fetchImpl?: typeof fetch } = {}
+): Promise<{ ok: true; reply: string } | { ok: false; error: string }> {
+  const endpoint = options.endpoint ?? "/api/chai/openrouter/chat";
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const model = options.model ?? DEFAULT_MODEL;
+  try {
+    const res = await fetchImpl(endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        model,
+        messages: [{ role: "user", content: "Reply with exactly one word: OK." }],
+        max_tokens: 5,
+      }),
+    });
+    const json = (await res.json().catch(() => ({}))) as ChatCompletionResponse;
+    if (!res.ok || json.error) {
+      return { ok: false, error: describeError(json, `${res.status} ${res.statusText}`) };
+    }
+    return { ok: true, reply: json.choices?.[0]?.message?.content?.trim() ?? "" };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from "./types.js";
+export * from "./engine.js";
+export * from "./run.js";
+export * from "./media-analysis-prompts.js";
+export * from "./engines/openrouter.js";
+export * from "./engines/fal.js";
+export * from "./model-routing.js";

package/src/media-analysis-prompts.ts

@@ -0,0 +1,45 @@
+/**
+ * The instruction text `MediaAnalyzer` sends to an analysis model — one
+ * complete, final string per (media kind × prompt length), not a template
+ * with placeholders, so tuning the wording is just editing English.
+ *
+ * Phrase optimization (rewriting for the target model's known prompt
+ * style) is folded directly into every prompt's wording below rather than
+ * modeled as a separate option.
+ */
+
+export type MediaAnalysisKind = "image" | "video" | "audio";
+export type MediaAnalysisPromptLength = "terse" | "concise" | "detailed";
+
+const OPTIMIZE_CLAUSE =
+  "Rewrite the description for the selected model's known prompt style before finishing.";
+const RESPOND_ONLY = "Respond only with the description, no preamble.";
+
+export const MEDIA_ANALYSIS_PROMPTS: Record<
+  MediaAnalysisKind,
+  Record<MediaAnalysisPromptLength, string>
+> = {
+  image: {
+    terse: `Analyze the attached image and produce a terse, single-sentence description suitable as a generation seed prompt — subject and composition only. ${OPTIMIZE_CLAUSE} ${RESPOND_ONLY}`,
+    concise: `Analyze the attached image and produce a concise description suitable as a generation seed prompt — subject, composition, and lighting in a few sentences. ${OPTIMIZE_CLAUSE} ${RESPOND_ONLY}`,
+    detailed: `Analyze the attached image and produce a detailed description suitable as a generation seed prompt — subject, composition, lighting, color palette, and style, thorough enough to reproduce it closely. ${OPTIMIZE_CLAUSE} ${RESPOND_ONLY}`,
+  },
+  video: {
+    terse: `Analyze the attached video's key frames and motion and produce a terse, single-sentence description suitable as a generation seed prompt — subject and camera movement only. ${OPTIMIZE_CLAUSE} ${RESPOND_ONLY}`,
+    concise: `Analyze the attached video's key frames and motion — subject, action, camera movement, pacing — and produce a concise description suitable as a generation seed prompt. ${OPTIMIZE_CLAUSE} ${RESPOND_ONLY}`,
+    detailed: `Analyze the attached video's key frames and motion — subject, action, camera movement, pacing, lighting, and style — and produce a detailed description suitable as a generation seed prompt, thorough enough to reproduce the shot closely. ${OPTIMIZE_CLAUSE} ${RESPOND_ONLY}`,
+  },
+  audio: {
+    terse: `Analyze the attached audio and produce a terse, single-sentence description suitable as a generation seed prompt — content and voice/instrumentation only. ${OPTIMIZE_CLAUSE} ${RESPOND_ONLY}`,
+    concise: `Analyze the attached audio — content, voice/instrumentation, tone, pacing — and produce a concise description suitable as a generation seed prompt. ${OPTIMIZE_CLAUSE} ${RESPOND_ONLY}`,
+    detailed: `Analyze the attached audio — content, voice/instrumentation, tone, pacing, and production style — and produce a detailed description suitable as a generation seed prompt, thorough enough to reproduce it closely. ${OPTIMIZE_CLAUSE} ${RESPOND_ONLY}`,
+  },
+};
+
+export const DEFAULT_MEDIA_ANALYSIS_PROMPT_LENGTH: MediaAnalysisPromptLength = "concise";
+
+export const MEDIA_ANALYSIS_PROMPT_LENGTHS: { value: MediaAnalysisPromptLength; label: string }[] = [
+  { value: "terse", label: "Terse" },
+  { value: "concise", label: "Concise" },
+  { value: "detailed", label: "Detailed" },
+];

package/src/model-routing.ts

@@ -0,0 +1,104 @@
+/**
+ * Auto-select model routing: a reasoning model reads the request and picks
+ * one model from the builder's own list. The instruction is plain English
+ * in `buildModelRoutingPrompt` below, so tuning it is just editing text;
+ * pass your own builder to the hooks' `routingPrompt` option to replace it.
+ */
+
+import { normalizeGenerationError, type GenerationEngine } from "./engine.js";
+import type { DroppedMedia, MediaKind, ModelOption } from "./types.js";
+
+export interface ModelRoutingInput {
+  /** What the person typed. Empty for media-only requests (e.g. Media Analyzer). */
+  prompt: string;
+  /** What the request produces, e.g. "image" for Create image, "text" for analysis. */
+  outputKind: MediaKind;
+  /** Kinds of media attached, if any. */
+  attachmentKinds: MediaKind[];
+  /** The candidates: only models the builder offers for this request. */
+  models: ModelOption[];
+}
+
+export function buildModelRoutingPrompt({ prompt, outputKind, attachmentKinds, models }: ModelRoutingInput): string {
+  const roster = models.map((m) => `- ${m.id}: ${m.label} (${m.provider}, ${m.speed})`).join("\n");
+  const attached = attachmentKinds.length ? attachmentKinds.join(", ") : "none";
+  const request = prompt.trim() ? prompt.trim() : "(no text; the attached media is the request)";
+  return [
+    `Pick the one model best suited to this request. The output is ${outputKind}.`,
+    `Weigh what the request needs (subject, detail, style, length, attached media) against each model's strengths. Prefer a faster model when the request is simple.`,
+    ``,
+    `Request: ${request}`,
+    `Attached media: ${attached}`,
+    ``,
+    `Models:`,
+    roster,
+    ``,
+    `Reply with only the chosen model id, exactly as written above, and nothing else.`,
+  ].join("\n");
+}
+
+/** Finds the model id in a reasoning model's reply, or `undefined` if it named none of `models`. */
+export function parseModelRoutingReply(reply: string, models: ModelOption[]): string | undefined {
+  const cleaned = reply.trim().replace(/^[`"'*\s]+|[`"'*.\s]+$/g, "");
+  const exact = models.find((m) => m.id === cleaned);
+  if (exact) return exact.id;
+  // A chatty reply ("I'd pick openai/gpt-5.2 because…"): take the longest
+  // id it contains, so "x/model-pro" wins over its prefix "x/model".
+  return [...models].sort((a, b) => b.id.length - a.id.length).find((m) => reply.includes(m.id))?.id;
+}
+
+export type ModelRoutingResult =
+  | { status: "routed"; modelId: string }
+  | {
+      status: "fallback";
+      modelId: string;
+      reason: "no-reasoning" | "request-failed" | "invalid-reply";
+      /** The provider's own message when the reasoning call failed. */
+      error?: string;
+    };
+
+export interface RouteModelArgs extends ModelRoutingInput {
+  /** The reasoning engine and model. Omit both and routing falls back without a call. */
+  engine?: GenerationEngine;
+  model?: string;
+  attachments?: DroppedMedia[];
+  /** Replaces `buildModelRoutingPrompt`. */
+  routingPrompt?: (input: ModelRoutingInput) => string;
+  /** Stops the reasoning call; the result is then a `"request-failed"` fallback. */
+  signal?: AbortSignal;
+}
+
+/**
+ * Asks the reasoning model to pick from `models`. Never throws: when it
+ * can't route (no reasoning model, a failed call, an answer not in the
+ * list) it falls back to the first listed model and says why, so a
+ * routing problem never blocks the request itself.
+ */
+export async function routeModel(args: RouteModelArgs): Promise<ModelRoutingResult> {
+  const fallback = args.models[0]?.id;
+  if (!fallback) throw new Error("routeModel: `models` is empty; there's nothing to pick from.");
+  if (args.models.length === 1) return { status: "routed", modelId: fallback };
+  if (!args.engine || !args.model) return { status: "fallback", modelId: fallback, reason: "no-reasoning" };
+
+  const input: ModelRoutingInput = {
+    prompt: args.prompt,
+    outputKind: args.outputKind,
+    attachmentKinds: args.attachmentKinds,
+    models: args.models,
+  };
+  try {
+    const { src } = await args.engine.generate({
+      modelId: args.model,
+      prompt: (args.routingPrompt ?? buildModelRoutingPrompt)(input),
+      // The media itself helps (e.g. a photo needing an edit-capable model).
+      attachments: args.attachments ?? [],
+      signal: args.signal,
+    });
+    const picked = parseModelRoutingReply(src, args.models);
+    return picked
+      ? { status: "routed", modelId: picked }
+      : { status: "fallback", modelId: fallback, reason: "invalid-reply" };
+  } catch (err) {
+    return { status: "fallback", modelId: fallback, reason: "request-failed", error: normalizeGenerationError(err).message };
+  }
+}

package/src/run.ts

@@ -0,0 +1,145 @@
+/**
+ * The the design data model — Request/Run/Result — plus the pure state
+ * transitions over it: pure, framework-free logic here; `useComposer`
+ * (`@chai-ui/react`) is the thin React binding on top.
+ */
+
+import type { DroppedMedia, Evaluation, GenerationUseCase, MediaKind, Usage } from "./types.js";
+
+export interface Request {
+  /** The specific generation use case, when one could be derived — see `deriveGenerationUseCase`. Undefined when the use case (or its kind) has no `GenerationUseCase` match yet, e.g. audio. */
+  mode?: GenerationUseCase;
+  prompt: string;
+  attachments: DroppedMedia[];
+  modelIds: string[];
+  params: Record<string, unknown>;
+  presetId?: string;
+}
+
+/** `"cancelled"`: the person stopped it. A streamed text result keeps the text that arrived. */
+export type ResultStatus = "queued" | "running" | "done" | "error" | "cancelled";
+
+export interface Result {
+  id: string;
+  runId: string;
+  modelId: string;
+  status: ResultStatus;
+  output?: { src: string; kind: MediaKind };
+  usage?: Usage;
+  /** Verdicts from the builder's own backend checks on this output — see `Evaluation`. */
+  evaluations?: Evaluation[];
+  error?: { message: string; reasons?: string[] };
+  /** Set by `startResult` — internal bookkeeping for `durationMs`, not meant to be read directly by a consumer (it's a raw `Date.now()`, not itself a duration). */
+  startedAt?: number;
+  /** How long this result took from `startResult` to `resolveResult`/`failResult`, in ms — `undefined` if it resolved without ever going through `startResult` (e.g. resolved directly from `"queued"`). ResultCard's info-flip is what actually surfaces this (reference: the Figma mock's "3.03s" chip). */
+  durationMs?: number;
+}
+
+export interface Run {
+  id: string;
+  request: Request;
+  createdAt: number;
+  results: Result[];
+}
+
+let idCounter = 0;
+function nextId(prefix: string): string {
+  idCounter += 1;
+  return `${prefix}_${idCounter}_${Math.random().toString(36).slice(2, 7)}`;
+}
+
+/**
+ * Fans a `Request` out into one `"queued"` `Result` per model — a run's
+ * results all exist from the start, so a caller can render "3 of 4 done"
+ * immediately rather than watching the list grow.
+ */
+export function createRun(request: Request): Run {
+  const id = nextId("run");
+  return {
+    id,
+    request,
+    createdAt: Date.now(),
+    results: request.modelIds.map((modelId) => ({
+      id: nextId("result"),
+      runId: id,
+      modelId,
+      status: "queued",
+    })),
+  };
+}
+
+function updateResult(run: Run, resultId: string, fn: (result: Result) => Result): Run {
+  return { ...run, results: run.results.map((r) => (r.id === resultId ? fn(r) : r)) };
+}
+
+export function startResult(run: Run, resultId: string): Run {
+  return updateResult(run, resultId, (r) => ({ ...r, status: "running", startedAt: Date.now() }));
+}
+
+/**
+ * Folds partial streamed text into a running result: `output` fills in
+ * while `status` stays `"running"`, so "running with output" is what a
+ * streaming result looks like. A no-op once the result has settled, so a
+ * late chunk can't overwrite a final `resolveResult`/`failResult`.
+ */
+export function streamResult(run: Run, resultId: string, textSoFar: string): Run {
+  return updateResult(run, resultId, (r) =>
+    r.status === "running" ? { ...r, output: { src: textSoFar, kind: "text" } } : r
+  );
+}
+
+export function resolveResult(
+  run: Run,
+  resultId: string,
+  output: Result["output"],
+  usage?: Usage,
+  evaluations?: Evaluation[]
+): Run {
+  return updateResult(run, resultId, (r) => ({
+    ...r,
+    status: "done",
+    output,
+    usage,
+    evaluations,
+    durationMs: r.startedAt != null ? Date.now() - r.startedAt : undefined,
+  }));
+}
+
+export function failResult(run: Run, resultId: string, error: Result["error"]): Run {
+  return updateResult(run, resultId, (r) => ({
+    ...r,
+    status: "error",
+    error,
+    durationMs: r.startedAt != null ? Date.now() - r.startedAt : undefined,
+  }));
+}
+
+/** Marks a queued or running result as stopped by the person. A settled result is left as it is. */
+export function cancelResult(run: Run, resultId: string): Run {
+  return updateResult(run, resultId, (r) =>
+    r.status === "queued" || r.status === "running"
+      ? { ...r, status: "cancelled", durationMs: r.startedAt != null ? Date.now() - r.startedAt : undefined }
+      : r
+  );
+}
+
+/**
+ * Derives a `GenerationUseCase` from Composer's own `{ kind, label }` use
+ * case plus whether anything is attached — this is real derivation logic,
+ * not just plumbing: the same `kind: "video"` means `"text-to-video"` with
+ * nothing attached but `"image-to-video"` once an image is. Returns
+ * `undefined` for "audio" (no `GenerationUseCase` member exists yet;
+ * audio generation is planned). `"text"` is a text request: a reply to
+ * the prompt, or a description of the attached media ("vision").
+ */
+export function deriveGenerationUseCase(
+  useCase: { kind: MediaKind } | null | undefined,
+  attachments: DroppedMedia[]
+): GenerationUseCase | undefined {
+  if (!useCase) return undefined;
+  const hasMedia = attachments.length > 0;
+  if (useCase.kind === "video") return hasMedia ? "image-to-video" : "text-to-video";
+  if (useCase.kind === "image") return hasMedia ? "image-edit" : "text-to-image";
+  if (useCase.kind === "text") return hasMedia ? "vision" : "text-to-text";
+  return undefined;
+}