@chai-ui/core 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,85 @@
+/**
+ * CHAI UI — shared data types for the component library.
+ */
+/** The kinds of media a component can take in or produce. */
+export type MediaKind = "image" | "video" | "audio" | "text";
+/**
+ * A piece of media a person attached (or an engine received) — just enough
+ * to know its kind and where it lives.
+ */
+export interface DroppedMedia {
+    src: string;
+    kind: MediaKind;
+    /** Original file name, for the upload-summary UI. Absent for non-file sources. */
+    name?: string;
+    /** Original file size in bytes, for the upload-summary UI. */
+    size?: number;
+}
+/**
+ * Token/cost accounting for one model call, when the engine reports one.
+ * `costUsd` is deliberately separate from the token counts: an engine may
+ * know real token counts but have no verified per-model pricing to convert
+ * them with (see `ModelOption.pricePerMillionTokens`) — degrade to showing
+ * tokens without a cost rather than guessing a price.
+ */
+export interface Usage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    costUsd?: number;
+}
+/**
+ * The verdict of one quality check the builder's own backend ran on a
+ * generated output (e.g. brand safety, prompt adherence), appended to the
+ * model call's response. CHAI never runs or scores a check; it only
+ * renders the verdict: `passed` true is green, false is red.
+ */
+export interface Evaluation {
+    id: string;
+    label: string;
+    passed: boolean;
+}
+/**
+ * The thin value-in/value-out shape a form control satisfies (e.g.
+ * `Toggle`) — deliberately minimal so most existing components already
+ * qualify without an adapter.
+ */
+export interface PrimitiveProps<T = unknown> {
+    value: T;
+    onChange: (next: T) => void;
+    disabled?: boolean;
+}
+/** One labeled option, for option-list controls (e.g. Composer's aspect ratios). */
+export interface ParameterOption<T> {
+    value: T;
+    label: string;
+}
+/** A model a component can offer or route to. */
+export interface ModelOption {
+    id: string;
+    label: string;
+    provider: string;
+    /** Rough cost/latency signal, for future cost/latency-aware routing. */
+    speed: "fast" | "standard" | "slow";
+    /**
+     * USD per million tokens, if known — lets real token counts convert into
+     * a real cost. Deliberately optional and absent by default: provider
+     * pricing changes and isn't tracked anywhere in this repo yet, so a wrong
+     * hardcoded number would be worse than no cost at all. Set this per model
+     * only from a source you're actively keeping current.
+     */
+    pricePerMillionTokens?: {
+        input: number;
+        output: number;
+    };
+}
+/**
+ * A specific generation use case. These names deliberately match the
+ * leaderboard categories at github.com/oolong-tea-2026/arena-ai-leaderboards,
+ * so a future model-ranking lookup can join on it directly, plus
+ * "text-to-text" for a plain text request (a Composer with no use case
+ * picked). That repo has no audio-generation category at all, a real gap
+ * for any future audio use case.
+ */
+export type GenerationUseCase = "text-to-image" | "image-edit" | "text-to-video" | "image-to-video" | "video-edit" | "vision" | "text-to-text";
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,6DAA6D;AAC7D,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC;AAE7D;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,SAAS,CAAC;IAChB,kFAAkF;IAClF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,MAAM,WAAW,KAAK;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO;IACzC,KAAK,EAAE,CAAC,CAAC;IACT,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;IAC5B,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,oFAAoF;AACpF,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,KAAK,EAAE,CAAC,CAAC;IACT,KAAK,EAAE,MAAM,CAAC;CACf;AAED,iDAAiD;AACjD,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC;IACpC;;;;;;OAMG;IACH,qBAAqB,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3D;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GACzB,eAAe,GACf,YAAY,GACZ,eAAe,GACf,gBAAgB,GAChB,YAAY,GACZ,QAAQ,GACR,cAAc,CAAC"}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * CHAI UI — shared data types for the component library.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@chai-ui/core",
+  "version": "0.1.0",
+  "description": "CHAI UI headless core — the Request/Run/Result data model and pluggable generation engines (Fal.ai, OpenRouter, mock). No framework, no rendering.",
+  "license": "MIT",
+  "author": "kazarazat",
+  "homepage": "https://chai-ui.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kazarazat/chai-ui.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/kazarazat/chai-ui/issues"
+  },
+  "keywords": [
+    "ai",
+    "generative-ai",
+    "design-system",
+    "ai-ui",
+    "headless",
+    "ai-engine",
+    "fal",
+    "openrouter"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.*"
+  ],
+  "devDependencies": {
+    "@vitest/coverage-v8": "3.2.7",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.7"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rimraf dist && tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "lint": "echo \"(no lint configured yet)\"",
+    "clean": "rimraf dist",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage --coverage.reporter=lcov --coverage.reporter=text-summary"
+  }
+}

package/src/engine.ts

@@ -0,0 +1,237 @@
+/**
+ * A pluggable generation engine — the one interface every model provider
+ * (`createFalEngine`, `createOpenRouterEngine`, `mockEngine`, or your own)
+ * implements, and the one `useComposer` calls. One call = one model run:
+ * a prompt plus any attached media in, one piece of output back.
+ *
+ * `mockEngine` stands in for a real model API during prototyping: it
+ * "generates" a small deterministic placeholder image without any network
+ * call or API key. Swap in a real engine without touching any component —
+ * that's the whole point of keeping this behind an interface.
+ */
+
+import type { DroppedMedia, Evaluation, MediaKind, Usage } from "./types.js";
+
+export interface GenerationEngine {
+  generate(args: {
+    /**
+     * The model the person picked. An engine uses it when set and falls
+     * back to its own configured default when it isn't.
+     */
+    modelId?: string;
+    prompt: string;
+    attachments: DroppedMedia[];
+    /**
+     * Optional streaming hook for text output. An engine that can stream
+     * calls this with the full text received so far (not a delta) each time
+     * more arrives; one that can't simply never calls it. The returned
+     * promise's value is still the authoritative final output.
+     */
+    onText?: (textSoFar: string) => void;
+    /**
+     * Aborted when the person stops the request. An engine that can cancel
+     * at the provider does so, then rejects with an `AbortError` (see
+     * `abortError`). Cancellation is best effort: some providers keep
+     * running, and billing, once a request has started.
+     */
+    signal?: AbortSignal;
+  }): Promise<{ src: string; kind: MediaKind; usage?: Usage; evaluations?: Evaluation[] }>;
+}
+
+/** The error an engine rejects with when its `signal` was aborted. */
+export function abortError(): Error {
+  return new DOMException("The request was cancelled.", "AbortError");
+}
+
+/** True for an `AbortError`, the way an engine reports a cancelled call. */
+export function isAbortError(err: unknown): boolean {
+  return typeof err === "object" && err !== null && (err as { name?: unknown }).name === "AbortError";
+}
+
+/** Resolves after `ms`, or rejects with an `AbortError` as soon as `signal` aborts. */
+export function abortableSleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(abortError());
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(abortError());
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+/**
+ * Thrown by a `GenerationEngine` to fail a call with structured,
+ * user-facing content — `reasons` can render as a bullet list, `message`
+ * alone as a single sentence. A real engine should unwrap its provider's
+ * specific error into this shape rather than let a bare network/HTTP error
+ * reach the UI.
+ */
+export class GenerationError extends Error {
+  reasons?: string[];
+  constructor(message: string, reasons?: string[]) {
+    super(message);
+    this.name = "GenerationError";
+    this.reasons = reasons;
+  }
+}
+
+/**
+ * Reads the top-level `evaluations` field a builder's backend proxy
+ * appended to a provider response, the convention both built-in engines
+ * follow. Malformed entries are dropped rather than rendered as verdicts
+ * nobody actually returned.
+ */
+export function readEvaluations(json: unknown): Evaluation[] | undefined {
+  const raw = (json as { evaluations?: unknown } | null)?.evaluations;
+  if (!Array.isArray(raw)) return undefined;
+  const valid = raw.filter(
+    (e): e is Evaluation =>
+      !!e && typeof e.id === "string" && typeof e.label === "string" && typeof e.passed === "boolean"
+  );
+  return valid.length ? valid.map(({ id, label, passed }) => ({ id, label, passed })) : undefined;
+}
+
+/** Turns anything an engine threw into the `{ message, reasons }` shape a `Result`'s `error` holds. */
+export function normalizeGenerationError(err: unknown): { message: string; reasons?: string[] } {
+  if (err instanceof GenerationError) {
+    return { message: err.message, reasons: err.reasons };
+  }
+  if (err instanceof Error) return { message: err.message };
+  return { message: "Something went wrong. Please try again." };
+}
+
+function hash(input: string): number {
+  let h = 0;
+  for (let i = 0; i < input.length; i++) {
+    h = (h << 5) - h + input.charCodeAt(i);
+    h |= 0;
+  }
+  return Math.abs(h);
+}
+
+function placeholderSvg(seed: string, caption: string): string {
+  const h = hash(seed);
+  const hue = h % 360;
+  const hue2 = (hue + 40 + (h % 60)) % 360;
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="480" height="360">
+  <defs>
+    <linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="hsl(${hue} 55% 38%)" />
+      <stop offset="100%" stop-color="hsl(${hue2} 60% 24%)" />
+    </linearGradient>
+  </defs>
+  <rect width="480" height="360" fill="url(#g)" />
+  <text x="24" y="332" font-family="ui-monospace, monospace" font-size="13" fill="rgba(255,255,255,0.85)">${escapeXml(
+    caption
+  )}</text>
+</svg>`;
+  return `data:image/svg+xml;utf8,${encodeURIComponent(svg)}`;
+}
+
+function escapeXml(s: string): string {
+  return s.replace(
+    /[&<>"']/g,
+    (c) =>
+      ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&apos;" })[
+        c
+      ] ?? c
+  );
+}
+
+/**
+ * A plausible text reply for a text-output mock (e.g. standing in for a
+ * reasoning/vision model) — still not a real model call, just a more
+ * honest stand-in than a gradient image would be.
+ */
+function mockText(prompt: string, modelId: string): string {
+  const stylePhrases = [
+    "warm, diffused daylight",
+    "a shallow depth of field",
+    "muted, desaturated tones",
+    "a centered, symmetrical composition",
+    "soft shadows and high contrast",
+  ];
+  const subjectPhrases = [
+    "a single object resting on a plain surface",
+    "a figure positioned slightly off-center",
+    "an outdoor scene with layered depth",
+    "a close-up study of texture and material",
+  ];
+  const style = stylePhrases[hash(modelId + "style") % stylePhrases.length];
+  const subject = subjectPhrases[hash(modelId + "subject") % subjectPhrases.length];
+  const detail = prompt.includes("detailed")
+    ? " Rendered here with extra material and lighting detail, per the requested length."
+    : "";
+  return `${subject}, shot with ${style}.${detail} (mock — ${modelId})`;
+}
+
+/**
+ * A plausible, deterministic-per-call token/cost fabrication, so a demo can
+ * show usage without a real tokenizer or pricing API. `costUsd` uses an
+ * illustrative, not verified, rate — a real engine should only ever report
+ * a cost it actually derived from real pricing.
+ */
+function mockUsage(seed: string): Usage {
+  const promptTokens = 180 + (hash(seed + "prompt") % 420);
+  const completionTokens = 40 + (hash(seed + "completion") % 260);
+  const illustrativeRatePerMillion = { input: 0.15, output: 0.6 };
+  const costUsd =
+    (promptTokens * illustrativeRatePerMillion.input +
+      completionTokens * illustrativeRatePerMillion.output) /
+    1_000_000;
+  return { promptTokens, completionTokens, totalTokens: promptTokens + completionTokens, costUsd };
+}
+
+export interface MockEngineOptions {
+  /** What the mock "generates". Defaults to "image" (a placeholder gradient); "text" returns a plausible text reply instead. */
+  outputKind?: "image" | "text";
+  /**
+   * Fraction of calls that fail with `GenerationError`, 0-1. Default 0 —
+   * pass 1 to force every call to fail (a UI-testing convenience for
+   * previewing error states on demand).
+   */
+  failureRate?: number;
+}
+
+let mockCallCount = 0;
+
+export function createMockEngine(options: MockEngineOptions = {}): GenerationEngine {
+  const outputKind = options.outputKind ?? "image";
+  const failureRate = options.failureRate ?? 0;
+  return {
+    async generate({ modelId = "mock-model", prompt, onText, signal }) {
+      mockCallCount += 1;
+      const seed = `${modelId}:${prompt}:${mockCallCount}`;
+      await abortableSleep(500 + (hash(seed) % 1200), signal);
+
+      if (failureRate > 0 && (hash(seed) % 100) / 100 < failureRate) {
+        throw new GenerationError("Generation failed", [
+          "The model could not complete this request.",
+          "Try again, or select a different model.",
+        ]);
+      }
+
+      if (outputKind === "text") {
+        const text = mockText(prompt, modelId);
+        if (onText) {
+          // Word by word, so a streaming UI has something real to render.
+          const words = text.split(" ");
+          for (let i = 1; i <= words.length; i++) {
+            onText(words.slice(0, i).join(" "));
+            await abortableSleep(60, signal);
+          }
+        }
+        return { src: text, kind: "text", usage: mockUsage(seed) };
+      }
+      const caption = `${modelId} · ${prompt.slice(0, 48)}${prompt.length > 48 ? "…" : ""}`;
+      return { src: placeholderSvg(`${modelId}:${prompt}`, caption), kind: "image", usage: mockUsage(seed) };
+    },
+  };
+}
+
+export const mockEngine: GenerationEngine = createMockEngine();

package/src/engines/fal.ts

@@ -0,0 +1,271 @@
+/**
+ * A real `GenerationEngine` backed by Fal.ai (fal.ai) — CHAI's default
+ * model marketplace as of 2026-09-24, chosen for the
+ * text/image-to-video and audio-generation coverage OpenRouter lacks.
+ * OpenRouter remains a fully-supported alternative, not deprecated by
+ * this — see the Develop page's "Model providers" section.
+ *
+ * Handles media generation only: produces real image/video media via Fal's
+ * queue API (submit → poll → fetch result). Fal's own vision/LLM access
+ * (`any-llm`, `any-llm/vision`) is itself a proxy in front of OpenRouter,
+ * not an independent catalog — for text/reasoning calls
+ * (e.g. prompt enhancement, media analysis) use `createOpenRouterEngine`
+ * instead of routing through Fal to OpenRouter.
+ *
+ * Security: this engine never sees an API key and never calls
+ * `queue.fal.run` directly. It calls a same-origin `endpoint` (default
+ * `/api/chai/fal`, served by `createChaiHandler`) that a server-side proxy owns and mirrors Fal's own queue
+ * URL shape (`/{model}`, `/{model}/requests/{id}/status`,
+ * `/{model}/requests/{id}`) — the proxy is the only thing that reads
+ * `FAL_KEY` and attaches the `Authorization: Key ...` header. Passing a
+ * key into this file would put it in the browser bundle; don't add one.
+ */
+
+import { abortError, abortableSleep, isAbortError, readEvaluations, type GenerationEngine } from "../engine.js";
+import type { DroppedMedia, MediaKind } from "../types.js";
+
+/** Output kinds this engine can produce — text goes through a reasoning engine instead (see file doc comment). */
+type FalOutputKind = Exclude<MediaKind, "text">;
+
+export interface FalEngineOptions {
+  /** Same-origin proxy path that attaches the real key server-side and mirrors Fal's queue URL shape. */
+  endpoint?: string;
+  /** Fal model id to call when the caller passes no `modelId` and no `modelByKind` entry matches `outputKind`. */
+  model?: string;
+  /** Per-output-kind Fal model id override — e.g. `{ image: "fal-ai/flux/schnell", video: "minimax/h3-max/text-to-video" }`. */
+  modelByKind?: Partial<Record<FalOutputKind, string>>;
+  /** Which kind of media this engine instance produces. Defaults to "image". */
+  outputKind?: FalOutputKind;
+  /** Poll interval while a queued job is in progress. Defaults to 1500ms. */
+  pollIntervalMs?: number;
+  /** Give up waiting after this long. Defaults to 120000ms (2 min) — video/audio jobs run longer than image ones. */
+  timeoutMs?: number;
+  /** Injectable for tests; defaults to the global `fetch`. */
+  fetchImpl?: typeof fetch;
+}
+
+/**
+ * Fal model ids verified live against fal.ai's own docs/catalog
+ * 2026-09-24, not invented. No default for "audio": CHAI has no audio
+ * `GenerationUseCase` yet, so guessing one
+ * here would be ahead of any real use case that needs it.
+ */
+const DEFAULT_MODEL_BY_KIND: Partial<Record<FalOutputKind, string>> = {
+  image: "fal-ai/flux/schnell",
+  video: "minimax/h3-max/text-to-video",
+};
+
+const DEFAULT_POLL_INTERVAL_MS = 1500;
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+interface FalSubmitResponse {
+  request_id?: string;
+  status?: string;
+  error?: unknown;
+  detail?: unknown;
+}
+
+interface FalStatusResponse {
+  status?: "IN_QUEUE" | "IN_PROGRESS" | "COMPLETED" | string;
+  error?: unknown;
+  detail?: unknown;
+}
+
+interface FalResultResponse {
+  images?: { url: string }[];
+  video?: { url: string };
+  audio?: { url: string };
+  audio_url?: string;
+  error?: unknown;
+  detail?: unknown;
+}
+
+
+/** Fal's error shape varies by failure type — validation errors carry `detail`, job failures carry `error`. Prefer whichever is present and stringify a non-string one. */
+export function describeFalError(json: { error?: unknown; detail?: unknown }, fallback: string): string {
+  const raw = json.error ?? json.detail;
+  if (!raw) return fallback;
+  if (typeof raw === "string") return raw;
+  try {
+    return JSON.stringify(raw);
+  } catch {
+    return fallback;
+  }
+}
+
+/** Builds the one Fal request body CHAI sends — a prompt, plus an `image_url` when an attached image is available (for image-to-video / edit-shaped models). */
+export function buildFalRequestBody(args: {
+  prompt: string;
+  media?: DroppedMedia;
+}): Record<string, unknown> {
+  const body: Record<string, unknown> = { prompt: args.prompt };
+  if (args.media?.kind === "image") body.image_url = args.media.src;
+  return body;
+}
+
+/** Pulls the generated media URL out of Fal's result JSON for the given output kind — the response shape differs by modality. */
+export function extractFalResultSrc(json: FalResultResponse, kind: FalOutputKind): string | undefined {
+  if (kind === "image") return json.images?.[0]?.url;
+  if (kind === "video") return json.video?.url;
+  return json.audio?.url ?? json.audio_url;
+}
+
+async function submitFalJob(args: {
+  endpoint: string;
+  model: string;
+  body: Record<string, unknown>;
+  fetchImpl: typeof fetch;
+}): Promise<{ requestId: string; status: string }> {
+  const res = await args.fetchImpl(`${args.endpoint}/${args.model}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(args.body),
+  });
+  const json = (await res.json().catch(() => ({}))) as FalSubmitResponse;
+  if (!res.ok || json.error) throw new Error(describeFalError(json, `${res.status} ${res.statusText}`));
+  if (!json.request_id) throw new Error("submit response had no request_id");
+  return { requestId: json.request_id, status: json.status ?? "IN_QUEUE" };
+}
+
+/** Polls a submitted job's status until `COMPLETED`, then fetches and returns its result. */
+async function awaitFalJob(args: {
+  endpoint: string;
+  model: string;
+  requestId: string;
+  status: string;
+  fetchImpl: typeof fetch;
+  pollIntervalMs: number;
+  timeoutMs: number;
+  signal?: AbortSignal;
+}): Promise<FalResultResponse> {
+  let status = args.status;
+  const deadline = Date.now() + args.timeoutMs;
+  while (status !== "COMPLETED") {
+    if (Date.now() > deadline) {
+      throw new Error(`timed out after ${args.timeoutMs}ms waiting for the job to complete`);
+    }
+    await abortableSleep(args.pollIntervalMs, args.signal);
+    const res = await args.fetchImpl(`${args.endpoint}/${args.model}/requests/${args.requestId}/status`);
+    const json = (await res.json().catch(() => ({}))) as FalStatusResponse;
+    if (!res.ok || json.error) throw new Error(describeFalError(json, `${res.status} ${res.statusText}`));
+    status = json.status ?? status;
+  }
+  const res = await args.fetchImpl(`${args.endpoint}/${args.model}/requests/${args.requestId}`);
+  const json = (await res.json().catch(() => ({}))) as FalResultResponse;
+  if (!res.ok || json.error) throw new Error(describeFalError(json, `${res.status} ${res.statusText}`));
+  return json;
+}
+
+/**
+ * Asks Fal to drop a job (`PUT …/requests/<id>/cancel`). A queued job is
+ * removed and never runs; a running one gets a cancel signal and may still
+ * finish, depending on the model. Best effort: a failed cancel call is
+ * ignored, since the person has already stopped waiting.
+ */
+async function cancelFalJob(args: { endpoint: string; model: string; requestId: string; fetchImpl: typeof fetch }) {
+  await args.fetchImpl(`${args.endpoint}/${args.model}/requests/${args.requestId}/cancel`, { method: "PUT" }).catch(() => {});
+}
+
+/**
+ * A media-generation `GenerationEngine` — submits the prompt (plus the
+ * first attached image, if any) to Fal's queue API and polls until the job
+ * completes, returning the real generated `src` URL. Calls the caller's
+ * `modelId` when given, otherwise `modelByKind`/`model`/the built-in default.
+ */
+export function createFalEngine(options: FalEngineOptions = {}): GenerationEngine {
+  const endpoint = options.endpoint ?? "/api/chai/fal";
+  // Called through a wrapper, never as `args.fetchImpl(...)`: browsers throw
+  // "Illegal invocation" when fetch runs with an object as `this`.
+  const fetchImpl: typeof fetch = (input, init) => (options.fetchImpl ?? fetch)(input, init);
+  const outputKind = options.outputKind ?? "image";
+  const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+
+  return {
+    async generate({ modelId, prompt, attachments, signal }) {
+      const model =
+        modelId ?? options.modelByKind?.[outputKind] ?? options.model ?? DEFAULT_MODEL_BY_KIND[outputKind];
+      if (!model) {
+        throw new Error(
+          `falEngine: no model configured for outputKind "${outputKind}" — pass \`model\` or \`modelByKind.${outputKind}\`.`
+        );
+      }
+
+      const body = buildFalRequestBody({ prompt, media: attachments[0] });
+      if (signal?.aborted) throw abortError();
+
+      try {
+        // The submit itself isn't aborted mid-flight: without its request id
+        // there'd be nothing to cancel at Fal.
+        const { requestId, status } = await submitFalJob({ endpoint, model, body, fetchImpl });
+        if (signal?.aborted) {
+          await cancelFalJob({ endpoint, model, requestId, fetchImpl });
+          throw abortError();
+        }
+        const result = await awaitFalJob({
+          endpoint,
+          model,
+          requestId,
+          status,
+          fetchImpl,
+          pollIntervalMs,
+          timeoutMs,
+          signal,
+        }).catch(async (err) => {
+          if (isAbortError(err)) await cancelFalJob({ endpoint, model, requestId, fetchImpl });
+          throw err;
+        });
+        const src = extractFalResultSrc(result, outputKind);
+        if (!src) throw new Error(`no ${outputKind} output in Fal's response`);
+        // No `usage`: Fal bills per generation, not per token — `Usage`
+        // is token-shaped (promptTokens/completionTokens), and fabricating
+        // token counts to fit it would be a worse guess than reporting
+        // nothing, per the same rule `openrouter.ts`'s
+        // `pricePerMillionTokens` comment documents for cost.
+        return { src, kind: outputKind, evaluations: readEvaluations(result) };
+      } catch (err) {
+        if (isAbortError(err)) throw err;
+        throw new Error(`falEngine: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    },
+  };
+}
+
+/**
+ * A minimal, cheap connectivity check against Fal's fastest image model —
+ * the "use real inference sparingly" path, same role as `pingOpenRouter`.
+ * Deliberately not a `GenerationEngine` and not exercised by any automated
+ * test: meant to be triggered once, by a person, from the Develop page's
+ * "Test connection" button.
+ */
+export async function pingFal(
+  options: { endpoint?: string; model?: string; fetchImpl?: typeof fetch } = {}
+): Promise<{ ok: true; src: string } | { ok: false; error: string }> {
+  const endpoint = options.endpoint ?? "/api/chai/fal";
+  // Called through a wrapper, never as `args.fetchImpl(...)`: browsers throw
+  // "Illegal invocation" when fetch runs with an object as `this`.
+  const fetchImpl: typeof fetch = (input, init) => (options.fetchImpl ?? fetch)(input, init);
+  const model = options.model ?? DEFAULT_MODEL_BY_KIND.image!;
+  try {
+    const { requestId, status } = await submitFalJob({
+      endpoint,
+      model,
+      body: buildFalRequestBody({ prompt: "a single red circle on a white background" }),
+      fetchImpl,
+    });
+    const result = await awaitFalJob({
+      endpoint,
+      model,
+      requestId,
+      status,
+      fetchImpl,
+      pollIntervalMs: 1000,
+      timeoutMs: 30_000,
+    });
+    const src = extractFalResultSrc(result, "image");
+    if (!src) return { ok: false, error: "no image output in Fal's response" };
+    return { ok: true, src };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}