@chai-ui/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kazarazat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# @chai-ui/core
+
+The headless core behind CHAI's components: the data types, the
+Request → Run → Result model a submitted prompt flows through, and the
+pluggable generation engines that actually call models. No framework, no
+rendering — `@chai-ui/react` is one binding of this; a future non-React
+binding would depend on this package the same way.
+
+## Layout
+
+- `types.ts` — shared types: `MediaKind`, `DroppedMedia`, `ModelOption`, `Usage`, `GenerationUseCase`.
+- `run.ts` — `Request`/`Run`/`Result` plus pure transitions over them (`createRun`, `startResult`, `resolveResult`, `failResult`, `deriveGenerationUseCase`).
+- `engine.ts` — the `GenerationEngine` interface every provider implements, `GenerationError`, and `mockEngine`/`createMockEngine` (placeholder output, no network call, no API key).
+- `engines/fal.ts` — `createFalEngine`, media generation through Fal.ai (the default).
+- `engines/openrouter.ts` — `createOpenRouterEngine`, text/reasoning through OpenRouter (prompt enhancement, media analysis).
+- `media-analysis-prompts.ts` — the instruction text `MediaAnalyzer` sends, per media kind × prompt length.
+- `model-routing.ts` — auto-select: `buildModelRoutingPrompt`, `parseModelRoutingReply`, and `routeModel`, which falls back to the first listed model instead of throwing.
+- `server/` — `createChaiHandler` and `toNodeHandler`, exported from `@chai-ui/core/server` (server-only).
+
+## The server route: `@chai-ui/core/server`
+
+The built-in engines never hold an API key. They call one route on your
+server, `/api/chai/*`, and `createChaiHandler` serves it: it adds the key
+and forwards the request to Fal.ai or OpenRouter, streaming replies
+through.
+
+```ts
+// Next.js: app/api/chai/[...path]/route.ts
+import { createChaiHandler } from "@chai-ui/core/server";
+
+export const { GET, POST, PUT } = createChaiHandler();
+```
+
+Set `FAL_KEY` and `OPENROUTER_API_KEY` in the server's environment (never
+with a `VITE_` or `NEXT_PUBLIC_` prefix). A missing key comes back as a
+clear error, e.g. "FAL_KEY isn't set on the server."
+
+**Where it runs.** Chai's components are React-only, so the route lives in
+your React app's framework or on the API server behind it. Mount it at
+`/api/chai`, where the components send their requests. `handle(request)`
+takes a standard web `Request` and returns a `Response`; `GET`, `POST` and
+`PUT` (Fal's cancel call) are the same function. When the browser
+disconnects, the provider call is aborted too.
+
+| Your setup | Add this |
+|---|---|
+| Next.js (App Router) | `export const { GET, POST, PUT } = createChaiHandler();` in `app/api/chai/[...path]/route.ts` |
+| Remix / React Router | `export const loader = ({ request }) => chai.handle(request); export const action = loader;` in `app/routes/api.chai.$.ts` |
+| Hono | `app.all("/api/chai/*", (c) => chai.handle(c.req.raw))` |
+| Bun, Deno | route `/api/chai/*` to `chai.handle` in `Bun.serve` / `Deno.serve` |
+| Cloudflare Workers | `createChaiHandler({ falKey: env.FAL_KEY, openRouterKey: env.OPENROUTER_API_KEY }).handle(request)` |
+| Express, plain Node | `app.use("/api/chai", toNodeHandler(createChaiHandler()))` |
+
+**Before going live**, limit who can use the route and what it runs.
+Without these, anyone who reaches your site can spend your API credit:
+
+```ts
+createChaiHandler({
+  authorize: async (request) => Boolean(await getSession(request)), // false → 403
+  allowedModels: ["fal-ai/flux/schnell", "anthropic/claude-opus-5"], // anything else → 403
+});
+```
+
+Never import `@chai-ui/core/server` from browser code.
+
+## Writing an engine
+
+One method: a prompt plus any attached media in, one piece of output back.
+
+```ts
+import type { GenerationEngine } from "@chai-ui/core";
+
+const myEngine: GenerationEngine = {
+  async generate({ modelId, prompt, attachments }) {
+    // call your provider…
+    return { src: "https://…/output.png", kind: "image" };
+  },
+};
+```
+
+Throw a `GenerationError(message, reasons?)` to fail a call with
+user-facing content rather than a bare network error. API keys never
+belong in an engine: call a server route that adds the key, like
+`createChaiHandler` above.

package/dist/engine.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 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 declare function abortError(): Error;
+/** True for an `AbortError`, the way an engine reports a cancelled call. */
+export declare function isAbortError(err: unknown): boolean;
+/** Resolves after `ms`, or rejects with an `AbortError` as soon as `signal` aborts. */
+export declare function abortableSleep(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * 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 declare class GenerationError extends Error {
+    reasons?: string[];
+    constructor(message: string, reasons?: string[]);
+}
+/**
+ * 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 declare function readEvaluations(json: unknown): Evaluation[] | undefined;
+/** Turns anything an engine threw into the `{ message, reasons }` shape a `Result`'s `error` holds. */
+export declare function normalizeGenerationError(err: unknown): {
+    message: string;
+    reasons?: string[];
+};
+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;
+}
+export declare function createMockEngine(options?: MockEngineOptions): GenerationEngine;
+export declare const mockEngine: GenerationEngine;
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAE7E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE;QACb;;;WAGG;QACH,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,EAAE,YAAY,EAAE,CAAC;QAC5B;;;;;WAKG;QACH,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;QACrC;;;;;WAKG;QACH,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,SAAS,CAAC;QAAC,KAAK,CAAC,EAAE,KAAK,CAAC;QAAC,WAAW,CAAC,EAAE,UAAU,EAAE,CAAA;KAAE,CAAC,CAAC;CAC1F;AAED,sEAAsE;AACtE,wBAAgB,UAAU,IAAI,KAAK,CAElC;AAED,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAElD;AAED,uFAAuF;AACvF,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAa9E;AAED;;;;;;GAMG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;gBACP,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE;CAKhD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,EAAE,GAAG,SAAS,CAQvE;AAED,uGAAuG;AACvG,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,OAAO,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAM9F;AAoFD,MAAM,WAAW,iBAAiB;IAChC,8HAA8H;IAC9H,UAAU,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC9B;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAID,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,iBAAsB,GAAG,gBAAgB,CAgClF;AAED,eAAO,MAAM,UAAU,EAAE,gBAAqC,CAAC"}

package/dist/engine.js

@@ -0,0 +1,173 @@
+/**
+ * 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.
+ */
+/** The error an engine rejects with when its `signal` was aborted. */
+export function abortError() {
+    return new DOMException("The request was cancelled.", "AbortError");
+}
+/** True for an `AbortError`, the way an engine reports a cancelled call. */
+export function isAbortError(err) {
+    return typeof err === "object" && err !== null && err.name === "AbortError";
+}
+/** Resolves after `ms`, or rejects with an `AbortError` as soon as `signal` aborts. */
+export function abortableSleep(ms, signal) {
+    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 {
+    constructor(message, reasons) {
+        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) {
+    const raw = json?.evaluations;
+    if (!Array.isArray(raw))
+        return undefined;
+    const valid = raw.filter((e) => !!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) {
+    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) {
+    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, caption) {
+    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) {
+    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, modelId) {
+    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) {
+    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 };
+}
+let mockCallCount = 0;
+export function createMockEngine(options = {}) {
+    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 = createMockEngine();
+//# sourceMappingURL=engine.js.map

package/dist/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"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"}

package/dist/engines/fal.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 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 { 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;
+}
+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 declare function describeFalError(json: {
+    error?: unknown;
+    detail?: unknown;
+}, fallback: string): string;
+/** 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 declare function buildFalRequestBody(args: {
+    prompt: string;
+    media?: DroppedMedia;
+}): Record<string, unknown>;
+/** Pulls the generated media URL out of Fal's result JSON for the given output kind — the response shape differs by modality. */
+export declare function extractFalResultSrc(json: FalResultResponse, kind: FalOutputKind): string | undefined;
+/**
+ * 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 declare function createFalEngine(options?: FalEngineOptions): GenerationEngine;
+/**
+ * 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 declare function pingFal(options?: {
+    endpoint?: string;
+    model?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<{
+    ok: true;
+    src: string;
+} | {
+    ok: false;
+    error: string;
+}>;
+export {};
+//# sourceMappingURL=fal.d.ts.map

package/dist/engines/fal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fal.d.ts","sourceRoot":"","sources":["../../src/engines/fal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAA6D,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChH,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE3D,kHAAkH;AAClH,KAAK,aAAa,GAAG,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;AAEhD,MAAM,WAAW,gBAAgB;IAC/B,uGAAuG;IACvG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gHAAgH;IAChH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8HAA8H;IAC9H,WAAW,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC,CAAC;IACrD,8EAA8E;IAC9E,UAAU,CAAC,EAAE,aAAa,CAAC;IAC3B,2EAA2E;IAC3E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mHAAmH;IACnH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AA6BD,UAAU,iBAAiB;IACzB,MAAM,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC3B,KAAK,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACxB,KAAK,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAGD,2KAA2K;AAC3K,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAStG;AAED,gKAAgK;AAChK,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAI1B;AAED,iIAAiI;AACjI,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CAIpG;AA0DD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,gBAAqB,GAAG,gBAAgB,CAyDhF;AAED;;;;;;GAMG;AACH,wBAAsB,OAAO,CAC3B,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CAAO,GAC5E,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CA4BnE"}