@howells/motif-sdk 4.0.0 → 5.0.1

package/dist/index.cjs

@@ -4,7 +4,6 @@ let _howells_envy = require("@howells/envy");
 let zod = require("zod");
 let ai = require("ai");
 let _ai_sdk_fal = require("@ai-sdk/fal");
-let _ai_sdk_google = require("@ai-sdk/google");
 let _ai_sdk_openai = require("@ai-sdk/openai");
 let _ai_sdk_replicate = require("@ai-sdk/replicate");
 //#region src/aspects.ts
@@ -268,10 +267,11 @@ var CreativeOptionError = class extends Error {
 /** Canonical creative field order used for prompt enrichment and schema output. */
 const CREATIVE_FIELDS = ["look", "mood"];
 /**
-* Built-in creative direction catalogue: twelve house looks and six light moods.
+* Built-in creative direction catalogue: nine house looks and six light moods.
 *
 * Each option carries the exact prompt sentence appended when it is selected.
-* Looks also carry the aspect ratio and model they were tuned for.
+* Looks also carry the aspect ratio and model they were tuned for. The five
+* photographic looks come first, then the four flat ones.
 */
 const CREATIVE_TAXONOMY = {
 	look: [
@@ -287,102 +287,75 @@ const CREATIVE_TAXONOMY = {
 		{
 			acceptsMood: true,
 			aspect: "1:1",
-			clause: "Editorial still life on a warm bone plaster ground, chalky unglazed surfaces, a long soft shadow, generous empty space, shot on film with fine grain. No text, no logos, no people",
-			description: "Objects and material samples on a plaster ground, for product and swatch shots.",
+			clause: "Editorial still life in the register of Aesop and Kinfolk, on a warm bone plaster ground, chalky unglazed surfaces in muted mineral colour, a long soft shadow, generous empty space, shot on film with fine grain, restrained and materially rich. No text, no logos, no people",
+			description: "Objects and products on a plaster ground, for product and editorial still life.",
 			id: "still-life",
-			label: "Material still life",
+			label: "Editorial still life",
 			model: "flux2-pro"
 		},
 		{
 			acceptsMood: true,
 			aspect: "3:2",
-			clause: "Interior photograph shot square-on at eye level on a 35mm lens, warm off-white plaster, wide oak floorboards, linen, brass and a little pattern, light, bright and layered, collected rather than styled, slightly imperfect and lived-in rather than showroom-perfect, photographic realism. No text, no logos, no people",
+			clause: "Interior photograph in the register of House & Garden and Kinfolk, shot square-on at eye level on a 35mm lens, warm off-white plaster, wide oak floorboards, linen, brass and a little pattern, light, bright and layered, collected rather than styled, lived-in rather than showroom-perfect, soft natural daylight, shot on film with fine grain. No text, no logos, no people",
 			description: "Bright, collected rooms that feel lived in, for interior scenes.",
-			id: "lived-in",
-			label: "Lived-in interior",
+			id: "interior",
+			label: "Interior",
 			model: "flux2-pro"
 		},
 		{
 			acceptsMood: true,
 			aspect: "4:5",
-			clause: "Architectural editorial photograph at full room scale, honest materials meeting precise detailing, one hero element genuinely installed, plausible light and shadow, generous negative space, empty of people. No text, no logos",
-			description: "Whole rooms with one product installed, for showing a material at scale.",
+			clause: "Architectural photograph in the register of House & Garden and Kinfolk, a considered house seen from outside at editorial distance with its garden and setting, pale render, stone or timber meeting precise detailing, clipped planting, soft warm daylight and long shadow, generous negative space, immaculate and calm, shot on film with fine grain. No text, no logos, no people",
+			description: "Buildings and their settings from outside, for architecture, property and place.",
 			id: "architectural",
-			label: "Architectural scale",
+			label: "Architectural exterior",
 			model: "banana"
 		},
-		{
-			acceptsMood: true,
-			aspect: "4:3",
-			clause: "Amateur phone photo of a real home taken by the homeowner, slightly wonky framing, unstyled domestic photography, ordinary exposure. No text, no people",
-			description: "Unstyled phone snapshots of real homes, for believable before and after shots.",
-			id: "homeowner",
-			label: "Homeowner snapshot",
-			model: "seedream45"
-		},
 		{
 			acceptsMood: true,
 			aspect: "1:1",
-			clause: "Stylised architectural illustration of the room, colour laid as flat planes on walls, joinery and trim, fine hand-drawn line with a gentle gouache wash, clearly a drawing of a design decision rather than a photograph. No text, no people",
-			description: "Line and gouache room drawings, for showing a colour scheme as a design idea.",
-			experimental: true,
-			id: "drawing",
-			label: "Palette drawing",
-			model: "gpt2"
+			clause: "Editorial documentary portrait in the register of Kinfolk, muted warm palette, waist-up and unposed against a plain plaster or linen ground, plain clothing with no logos, soft natural light, shot on film with fine grain. No text",
+			description: "Natural, unposed documentary portraits of people. Pair with a mood for the light.",
+			id: "portrait",
+			label: "Documentary portrait",
+			model: "seedream45"
 		},
 		{
 			acceptsMood: false,
 			aspect: "1:1",
-			clause: "Straight-on orthographic photograph of the surface filling the entire frame edge to edge, even shadowless studio light, crisp macro texture, colour-accurate. No text, no logos",
-			description: "Flat, edge-to-edge surface photographs, for textures and material swatches.",
-			id: "plate",
-			label: "Flat plate",
+			clause: "A single matte object centred with generous empty space, soft diffused studio light, minimal and quiet in the register of Aesop, one committed muted mineral colour on a plain ground. No text, no logos, no people",
+			description: "One object in one colour on a clean ground, for icons and simple product shots.",
+			id: "object",
+			label: "Studio object",
 			model: "flux2-pro"
 		},
 		{
 			acceptsMood: false,
 			aspect: "1:1",
-			clause: "Fine hand-engraved botanical plate with delicate hatching and dry brush, grey ink only, reaching near-black at its densest, on matte uncoated stock under flat even light, cropped mid-motif and running past all four edges, never simplified or cartoonish. No text",
-			description: "Grey-ink botanical engravings that run off the edges, for patterns and backgrounds.",
-			id: "engraved",
-			label: "Engraved grey ink",
-			model: "gpt2"
-		},
-		{
-			acceptsMood: false,
-			aspect: "2:3",
-			clause: "Tightly cropped photograph of a single piece of late-1940s American printed matter, flat and square-on in even light, every pixel paper, letterpress and wood type, sun-faded ink, foxing, soft creases and thumbtack holes, era-correct typography, nothing that looks like a digital photo run through a filter",
-			description: "Aged mid-century printed matter such as posters and cards, where the lettering matters.",
-			id: "ephemera",
-			label: "Period ephemera",
-			model: "ideogram4"
+			clause: "Straight-on orthographic photograph of the surface filling the entire frame edge to edge, even shadowless studio light, crisp macro texture, colour-accurate and quietly material. No text, no logos",
+			description: "Flat, edge-to-edge surface photographs, for textures, backgrounds and material swatches.",
+			id: "surface",
+			label: "Flat surface",
+			model: "flux2-pro"
 		},
 		{
 			acceptsMood: false,
-			aspect: "3:4",
-			clause: "Physical mineral pigment and chalk gesso on coarse natural linen, two or three confident gestures, warm ivory, oatmeal, putty and soft charcoal, flat diffuse museum reproduction lighting, shown unframed. No text",
-			description: "Loose abstract paintings on linen, for wall art and calm backgrounds.",
-			id: "canvas",
-			label: "Linen abstract",
+			aspect: "3:2",
+			clause: "Painted abstraction filling the frame edge to edge, mineral pigment and chalk gesso on coarse natural linen, two or three confident gestures, warm ivory, oatmeal, putty and soft charcoal, flat diffuse reproduction light. No text",
+			description: "Painted abstraction edge to edge, for wall art, heroes and calm backgrounds.",
+			id: "abstract",
+			label: "Painted abstract",
 			model: "banana"
 		},
-		{
-			acceptsMood: true,
-			aspect: "1:1",
-			clause: "Editorial documentary portrait, muted warm palette, waist-up, unposed, plain clothing with no logos. No text",
-			description: "Natural, unposed documentary portraits of people. Pair with a mood for the light.",
-			id: "portrait",
-			label: "Documentary portrait",
-			model: "seedream45"
-		},
 		{
 			acceptsMood: false,
 			aspect: "1:1",
-			clause: "A single matte object centred with generous empty space, soft diffused studio light, minimal and quiet, one committed colour. No text, no logos, no people",
-			description: "One object in one colour on a clean ground, for icons and simple product shots.",
-			id: "object",
-			label: "Studio object",
-			model: "flux2-pro"
+			clause: "Stylised editorial illustration in the register of Kinfolk, colour laid as flat planes in a warm muted palette of ivory, putty, sage and charcoal, fine hand-drawn line with a gentle gouache wash, generous empty space, clearly a drawing rather than a photograph. No text, no logos",
+			description: "Line and gouache illustration of any subject, for drawn editorial imagery.",
+			experimental: true,
+			id: "illustration",
+			label: "Editorial illustration",
+			model: "gpt2"
 		}
 	],
 	mood: [
@@ -857,12 +830,16 @@ const MODELS = {
 			unit: "units",
 			unitPrice: 1
 		},
-		maxReferenceImages: 4,
+		maxReferenceImages: 16,
 		name: "GPT Image 2",
 		pricePerImageUsd: .211,
 		pricing: "$0.211",
 		sizeMode: "image_size_enum",
 		supportsAspect: true,
+		streaming: {
+			generation: true,
+			edit: true
+		},
 		supportsEdit: true,
 		supportsMaskImage: true,
 		maskImageField: "mask_url",
@@ -924,6 +901,10 @@ const MODELS = {
 		sizeMode: "gpt_size",
 		supportsAspect: false,
 		supportsBackground: true,
+		streaming: {
+			generation: true,
+			edit: true
+		},
 		supportsEdit: true,
 		supportsMaskImage: true,
 		supportsNumImages: true,
@@ -1558,12 +1539,16 @@ const MODELS = {
 			unit: "compute seconds",
 			unitPrice: .00167
 		},
-		maxReferenceImages: 10,
+		maxReferenceImages: 4,
 		name: "FLUX.2 [dev]",
 		pricePerImageUsd: .012,
 		pricing: "$0.00167/sec",
 		sizeMode: "image_size_enum",
 		supportsAspect: true,
+		streaming: {
+			generation: true,
+			edit: true
+		},
 		supportsEdit: true,
 		supportsGuidanceScale: true,
 		supportsInferenceSteps: true,
@@ -2315,7 +2300,7 @@ function estimateVideoCost(durationSeconds = 5, generateAudio = true, model = "k
 * `Response.json()` yields `any`; these helpers narrow that untyped payload into
 * the SDK's response types with runtime guards instead of unchecked assertions.
 */
-function isRecord$3(value) {
+function isRecord$4(value) {
 	return typeof value === "object" && value !== null;
 }
 function asString(value) {
@@ -2325,7 +2310,7 @@ function asNumber(value) {
 	return typeof value === "number" ? value : void 0;
 }
 function toMotifImage(value) {
-	if (isRecord$3(value)) return {
+	if (isRecord$4(value)) return {
 		content_type: asString(value.content_type),
 		height: asNumber(value.height),
 		url: asString(value.url) ?? "",
@@ -2340,7 +2325,7 @@ function parseImages(value) {
 function parseLogs(value) {
 	if (!Array.isArray(value)) return;
 	const entries = [];
-	for (const entry of value) if (isRecord$3(entry)) entries.push({
+	for (const entry of value) if (isRecord$4(entry)) entries.push({
 		message: asString(entry.message) ?? "",
 		timestamp: asString(entry.timestamp) ?? ""
 	});
@@ -2360,7 +2345,7 @@ function endpointFromQueueUrl(url, fallback) {
 	}
 }
 function parseQueueSubmission(data) {
-	if (!isRecord$3(data)) return { requestId: "" };
+	if (!isRecord$4(data)) return { requestId: "" };
 	return {
 		requestId: asString(data.request_id) ?? "",
 		responseUrl: asString(data.response_url)
@@ -2400,7 +2385,7 @@ function requestIdFromBody(text) {
 	} catch {
 		return;
 	}
-	if (!isRecord$3(parsed)) return;
+	if (!isRecord$4(parsed)) return;
 	return asString(parsed.request_id) ?? asString(parsed.requestId) ?? asString(parsed.trace_id);
 }
 //#endregion
@@ -4248,7 +4233,7 @@ async function runRequest(exec, prepared) {
 	const response = await exec.request(`${FAL_BASE_URL$1}/${prepared.endpoint}`, requestInit(prepared));
 	if (response.isErr()) return (0, neverthrow.err)(response.error);
 	const data = await response.value.json();
-	const record = isRecord$3(data) ? data : {};
+	const record = isRecord$4(data) ? data : {};
 	const requestId = response.value.headers.get("x-fal-request-id") ?? asString(record.request_id);
 	return (0, neverthrow.ok)({
 		data: record,
@@ -4275,7 +4260,7 @@ async function getToolResult(exec, job) {
 	const response = await exec.request(url);
 	if (response.isErr()) return (0, neverthrow.err)(response.error);
 	const data = await response.value.json();
-	return (0, neverthrow.ok)(isRecord$3(data) ? data : {});
+	return (0, neverthrow.ok)(isRecord$4(data) ? data : {});
 }
 /** Submit a prepared request, poll it to completion and fetch the result. */
 async function runRequestQueued(exec, prepared, onProgress) {
@@ -4430,7 +4415,7 @@ var FalClient = class {
 		const response = await this.request(url);
 		if (response.isErr()) return (0, neverthrow.err)(response.error);
 		const data = await response.value.json();
-		const record = isRecord$3(data) ? data : {};
+		const record = isRecord$4(data) ? data : {};
 		const rawStatus = asString(record.status);
 		let status;
 		if (rawStatus === "IN_QUEUE") status = "queued";
@@ -4538,7 +4523,7 @@ var FalClient = class {
 		const response = await this.request(url);
 		if (response.isErr()) return (0, neverthrow.err)(response.error);
 		const data = await response.value.json();
-		const video = isRecord$3(data) && isRecord$3(data.video) ? data.video : void 0;
+		const video = isRecord$4(data) && isRecord$4(data.video) ? data.video : void 0;
 		if (video === void 0) return (0, neverthrow.err)(new MotifError("No video in response", 0));
 		return (0, neverthrow.ok)({
 			contentType: asString(video.content_type) ?? "",
@@ -4562,8 +4547,8 @@ var FalClient = class {
 		});
 		if (initiateResponse.isErr()) return (0, neverthrow.err)(initiateResponse.error);
 		const initiateData = await initiateResponse.value.json();
-		const fileUrl = isRecord$3(initiateData) ? asString(initiateData.file_url) ?? "" : "";
-		const uploadUrl = isRecord$3(initiateData) ? asString(initiateData.upload_url) : void 0;
+		const fileUrl = isRecord$4(initiateData) ? asString(initiateData.file_url) ?? "" : "";
+		const uploadUrl = isRecord$4(initiateData) ? asString(initiateData.upload_url) : void 0;
 		if (uploadUrl === void 0 || uploadUrl === "") return (0, neverthrow.err)(new MotifError("Upload initiate response missing upload_url", 0));
 		let putResponse;
 		try {
@@ -4715,7 +4700,7 @@ var FalClient = class {
 	* Some APIs return `{ image: {...} }` instead of `{ images: [...] }`.
 	*/
 	normalizeResponse(data, fallbackRequestId) {
-		if (!isRecord$3(data)) return (0, neverthrow.err)(new MotifError("Unexpected fal response shape", 0, "FAL_ERROR"));
+		if (!isRecord$4(data)) return (0, neverthrow.err)(new MotifError("Unexpected fal response shape", 0, "FAL_ERROR"));
 		const obj = data;
 		const requestId = asString(obj.request_id) ?? asString(obj.requestId) ?? fallbackRequestId;
 		if ("detail" in obj) return (0, neverthrow.err)(new MotifError(asString(obj.detail) ?? "", 0, "FAL_ERROR"));
@@ -8414,6 +8399,17 @@ function resolveModel$3(modelId, apiKey, fetch) {
 		...toProviderFetch(fetch)
 	}).image(modelId);
 }
+/**
+* How a registered fal edit endpoint takes its input images, from the
+* registry's `editImagesField` (default `image_urls`). `@ai-sdk/fal` sends only
+* the first image as `image_url` unless told otherwise, which list-only
+* endpoints reject and which silently drops every reference after the first.
+* Undefined for an endpoint the registry does not list as an edit route.
+*/
+function falEditImagesField(modelId) {
+	const config = Object.values(MODELS).find((entry) => entry.editEndpoint === modelId);
+	return config === void 0 ? void 0 : config.editImagesField ?? "image_urls";
+}
 /** The fal provider adapter registered in the provider registry. */
 const falAdapter = {
 	id: "fal",
@@ -8422,61 +8418,6 @@ const falAdapter = {
 	priceUsdByModel: FAL_IMAGE_PRICE_USD
 };
 //#endregion
-//#region src/image/google.ts
-/**
-* Google (Gemini) provider adapter.
-*
-* Builds a Vercel AI SDK `ImageModel` from `@ai-sdk/google`. Building a model
-* performs no network I/O — the request only happens when `generateImage`
-* invokes `model.doGenerate`. Gemini supports both text→image generation and
-* multi-image-in → image-out editing (with an optional mask), which is the core
-* operation this layer normalizes.
-*/
-/** Env var read for the Google API key when `apiKey` is not supplied in config. */
-const GOOGLE_API_KEY_ENV = "GOOGLE_GENERATIVE_AI_API_KEY";
-/**
-* Static Google-direct USD/image, keyed by model id.
-*
-* Sources (Google direct, not fal-hosted):
-*   - `gemini-2.5-flash-image` ("nano banana"): image output billed at 1290
-*     output tokens/image at $30 / 1M output tokens ≈ $0.039/image.
-*     Source: https://ai.google.dev/gemini-api/docs/pricing
-*     Sanity anchor: fal-hosted `fal-ai/gemini-25-flash-image` is $0.0398
-*     (`MODELS.gemini.pricePerImageUsd` in ../models) — same ballpark.
-*   - `gemini-3-pro-image-preview` ("nano banana pro"): standard 1K/2K image
-*     output ≈ $0.134/image (higher tiers/4K cost more).
-*     Source: https://ai.google.dev/gemini-api/docs/pricing
-*     Sanity anchor: fal-hosted `fal-ai/gemini-3-pro-image-preview` is $0.15
-*     (`MODELS.gemini3`/`MODELS.banana` in ../models) — fal adds overhead.
-*   - `gemini-3.1-flash-image-preview`: flash-tier image output; priced with the
-*     2.5 flash-image line (≈ $0.039/image) pending a distinct published rate.
-*/
-const GOOGLE_IMAGE_PRICE_USD = {
-	"gemini-2.5-flash-image": .039,
-	"gemini-3.1-flash-image-preview": .039,
-	"gemini-3-pro-image-preview": .134
-};
-/**
-* Build a Google Gemini `ImageModel`. Prefers the passed `apiKey`, else the
-* `GOOGLE_GENERATIVE_AI_API_KEY` env var. Throws `MotifError` when neither is
-* present (callers translate this into a `Result.err`).
-*/
-function resolveModel$2(modelId, apiKey, fetch) {
-	const key = apiKey ?? process.env["GOOGLE_GENERATIVE_AI_API_KEY"];
-	if (key === void 0 || key === "") throw new MotifError(`Google image generation requires an API key (config.google.apiKey or ${GOOGLE_API_KEY_ENV})`, 0);
-	return (0, _ai_sdk_google.createGoogleGenerativeAI)({
-		apiKey: key,
-		...toProviderFetch(fetch)
-	}).image(modelId);
-}
-/** The Google (Gemini) provider adapter registered in the provider registry. */
-const googleAdapter = {
-	id: "google",
-	apiKeyEnv: GOOGLE_API_KEY_ENV,
-	resolveModel: resolveModel$2,
-	priceUsdByModel: GOOGLE_IMAGE_PRICE_USD
-};
-//#endregion
 //#region src/image/openai.ts
 /**
 * OpenAI (gpt-image) provider adapter.
@@ -8495,7 +8436,7 @@ const OPENAI_API_KEY_ENV = "OPENAI_API_KEY";
 * and size — this is a documented approximation for the common case.
 * Source: https://platform.openai.com/docs/pricing (image generation)
 * Sanity anchor: the Phase 0 benchmark measured gpt-image direct at $0.042
-* (vs $0.133 via fal — see docs/design/provider-agnostic-image-layer.md §10).
+* (vs $0.133 via fal — full data and methodology on Linear MOT-23).
 *
 * GPT Image 2.5 is token-priced, with no published per-image estimate. Leave
 * these models absent so cost remains unknown unless supplied by the provider.
@@ -8508,7 +8449,7 @@ const OPENAI_IMAGE_PRICE_USD = { "gpt-image-1": .042 };
 * `OPENAI_API_KEY` env var. Throws `MotifError` when neither is present
 * (callers translate this into a `Result.err`).
 */
-function resolveModel$1(modelId, apiKey, fetch) {
+function resolveModel$2(modelId, apiKey, fetch) {
 	const key = apiKey ?? process.env["OPENAI_API_KEY"];
 	if (key === void 0 || key === "") throw new MotifError(`OpenAI image generation requires an API key (config.openai.apiKey or ${OPENAI_API_KEY_ENV})`, 0);
 	return (0, _ai_sdk_openai.createOpenAI)({
@@ -8520,10 +8461,174 @@ function resolveModel$1(modelId, apiKey, fetch) {
 const openaiAdapter = {
 	id: "openai",
 	apiKeyEnv: OPENAI_API_KEY_ENV,
-	resolveModel: resolveModel$1,
+	resolveModel: resolveModel$2,
 	priceUsdByModel: OPENAI_IMAGE_PRICE_USD
 };
 //#endregion
+//#region src/image/openrouter.ts
+/** Env var read for the OpenRouter API key when `apiKey` is not supplied in config. */
+const OPENROUTER_API_KEY_ENV = "OPENROUTER_API_KEY";
+const OPENROUTER_IMAGES_URL = "https://openrouter.ai/api/v1/images";
+/** Key under which this adapter's metadata sits on `providerMetadata`. */
+const METADATA_KEY = "openrouter";
+/**
+* The Gemini image models Motif exposes, by their bare Google names, mapped to
+* the OpenRouter slug that serves them. All six are listed by
+* `GET https://openrouter.ai/api/v1/images/models`.
+*/
+const OPENROUTER_GEMINI_IMAGE_MODELS = {
+	"gemini-2.5-flash-image": "google/gemini-2.5-flash-image",
+	"gemini-3.1-flash-image-preview": "google/gemini-3.1-flash-image-preview",
+	"gemini-3-pro-image-preview": "google/gemini-3-pro-image-preview",
+	"gemini-3.1-flash-image": "google/gemini-3.1-flash-image",
+	"gemini-3-pro-image": "google/gemini-3-pro-image",
+	"gemini-3.1-flash-lite-image": "google/gemini-3.1-flash-lite-image"
+};
+/**
+* Static USD/image estimate, keyed by the bare model name. Used only when a
+* response carries no `usage.cost`; OpenRouter normally reports the real figure.
+*
+*   - `gemini-2.5-flash-image`: 1290 output tokens at $30 / 1M ≈ $0.039.
+*   - `gemini-3-pro-image-preview`, `gemini-3-pro-image`: ≈ $0.134 at 1K/2K.
+*   - `gemini-3.1-flash-image-preview`: priced with the 2.5 flash-image line
+*     pending a distinct published rate.
+*   - `gemini-3.1-flash-image`: $0.067 at 1K.
+*   - `gemini-3.1-flash-lite-image`: ≈ $0.0336 at 1K.
+* Source: https://ai.google.dev/gemini-api/docs/pricing
+*/
+const OPENROUTER_IMAGE_PRICE_USD = {
+	"gemini-2.5-flash-image": .039,
+	"gemini-3.1-flash-image-preview": .039,
+	"gemini-3-pro-image-preview": .134,
+	"gemini-3.1-flash-image": .067,
+	"gemini-3-pro-image": .134,
+	"gemini-3.1-flash-lite-image": .0336
+};
+/**
+* Resolve a Motif model name to an OpenRouter slug. A bare Gemini name maps to
+* its `google/<id>` slug; a name already containing `/` is an OpenRouter slug
+* and passes through. Anything else is unknown and throws.
+*/
+function openRouterModelSlug(modelId) {
+	if (modelId.includes("/")) return modelId;
+	const slug = OPENROUTER_GEMINI_IMAGE_MODELS[modelId];
+	if (slug === void 0) throw new MotifError(`No OpenRouter image model for "${modelId}". Known: ${Object.keys(OPENROUTER_GEMINI_IMAGE_MODELS).join(", ")}; or pass an OpenRouter slug such as google/gemini-3.1-flash-image.`, 0);
+	return slug;
+}
+function isRecord$3(value) {
+	return typeof value === "object" && value !== null;
+}
+function toDataUrl(mediaType, data) {
+	return `data:${mediaType};base64,${typeof data === "string" ? data : Buffer.from(data).toString("base64")}`;
+}
+/** One `input_references` entry for an input file: a URL as-is, bytes as a data URL. */
+function toInputReference(file) {
+	return {
+		type: "image_url",
+		image_url: { url: file.type === "url" ? file.url : toDataUrl(file.mediaType, file.data) }
+	};
+}
+function buildBody(slug, options) {
+	if (options.mask !== void 0) throw new MotifError("OpenRouter's Image API takes no mask; describe the region in the instruction instead.", 0);
+	return {
+		...options.providerOptions[METADATA_KEY] ?? {},
+		model: slug,
+		prompt: options.prompt,
+		n: options.n,
+		...options.aspectRatio === void 0 ? {} : { aspect_ratio: options.aspectRatio },
+		...options.files === void 0 || options.files.length === 0 ? {} : { input_references: options.files.map(toInputReference) }
+	};
+}
+function errorMessage(body, fallback) {
+	if (isRecord$3(body) && isRecord$3(body.error)) {
+		const { message } = body.error;
+		if (typeof message === "string" && message !== "") return message;
+	}
+	return fallback;
+}
+function parseResponse(body) {
+	if (!isRecord$3(body) || !Array.isArray(body.data)) throw new MotifError("OpenRouter image response had no data array", 502);
+	const images = [];
+	for (const entry of body.data) if (isRecord$3(entry) && typeof entry.b64_json === "string") images.push(entry.b64_json);
+	if (images.length === 0) throw new MotifError("OpenRouter returned no images", 502);
+	return {
+		images,
+		cost: isRecord$3(body.usage) && typeof body.usage.cost === "number" ? body.usage.cost : void 0
+	};
+}
+function buildModel(modelId, apiKey, doFetch) {
+	const slug = openRouterModelSlug(modelId);
+	return {
+		specificationVersion: "v4",
+		provider: METADATA_KEY,
+		modelId: slug,
+		maxImagesPerCall: 10,
+		async doGenerate(options) {
+			const warnings = [];
+			if (options.seed !== void 0) warnings.push({
+				type: "unsupported",
+				feature: "seed"
+			});
+			if (options.size !== void 0) warnings.push({
+				type: "unsupported",
+				feature: "size",
+				details: "Gemini on OpenRouter takes aspectRatio, not pixel sizes."
+			});
+			const timestamp = /* @__PURE__ */ new Date();
+			const response = await doFetch(OPENROUTER_IMAGES_URL, {
+				method: "POST",
+				headers: {
+					...options.headers,
+					Authorization: `Bearer ${apiKey}`,
+					"Content-Type": "application/json"
+				},
+				body: JSON.stringify(buildBody(slug, options)),
+				...options.abortSignal === void 0 ? {} : { signal: options.abortSignal }
+			});
+			const text = await response.text();
+			let body;
+			try {
+				body = JSON.parse(text);
+			} catch {
+				body = void 0;
+			}
+			if (!response.ok) throw new MotifError(errorMessage(body, `OpenRouter ${response.status}: ${text}`), response.status);
+			const { images, cost } = parseResponse(body);
+			return {
+				images,
+				warnings,
+				providerMetadata: { [METADATA_KEY]: {
+					images: images.map(() => ({})),
+					...cost === void 0 ? {} : { cost }
+				} },
+				response: {
+					timestamp,
+					modelId: slug,
+					headers: Object.fromEntries(response.headers.entries())
+				}
+			};
+		}
+	};
+}
+/**
+* Build an OpenRouter `ImageModel`. Prefers the passed `apiKey`, else the
+* `OPENROUTER_API_KEY` env var. Throws `MotifError` when neither is present or
+* the model name is unknown (callers translate this into a `Result.err`).
+*/
+function resolveModel$1(modelId, apiKey, fetch) {
+	const key = apiKey ?? process.env["OPENROUTER_API_KEY"];
+	if (key === void 0 || key === "") throw new MotifError(`OpenRouter image generation requires an API key (config.openrouter.apiKey or ${OPENROUTER_API_KEY_ENV})`, 0);
+	const configured = toProviderFetch(fetch);
+	return buildModel(modelId, key, "fetch" in configured ? configured.fetch : globalThis.fetch);
+}
+/** The OpenRouter provider adapter registered in the provider registry. */
+const openrouterAdapter = {
+	id: "openrouter",
+	apiKeyEnv: OPENROUTER_API_KEY_ENV,
+	resolveModel: resolveModel$1,
+	priceUsdByModel: OPENROUTER_IMAGE_PRICE_USD
+};
+//#endregion
 //#region src/image/replicate.ts
 /**
 * Replicate provider adapter.
@@ -8567,7 +8672,7 @@ function resolveModel(modelId, apiKey, fetch) {
 * goes through {@link getProviderAdapter}.
 */
 const PROVIDERS = {
-	google: googleAdapter,
+	openrouter: openrouterAdapter,
 	openai: openaiAdapter,
 	replicate: {
 		id: "replicate",
@@ -8622,11 +8727,16 @@ function roundUsd(value) {
 	return Number(value.toFixed(6));
 }
 /**
-* Normalized per-call cost for a generation. Prefers a provider-metadata cost,
-* then the static table (× image count), then unknown.
+* Cost across every underlying model call of one generation. Provider-metadata
+* costs from the calls that report one are summed; otherwise the static table
+* (× image count), then unknown.
 */
-function costForImages(provider, modelId, providerMetadata, imageCount) {
-	const metaCost = costFromProviderMetadata(providerMetadata);
+function costForCalls(provider, modelId, callMetadata, imageCount) {
+	let metaCost;
+	for (const providerMetadata of callMetadata) {
+		const callCost = costFromProviderMetadata(providerMetadata);
+		if (callCost !== void 0) metaCost = (metaCost ?? 0) + callCost;
+	}
 	if (metaCost !== void 0) return {
 		usd: roundUsd(metaCost),
 		source: "provider-metadata"
@@ -8649,18 +8759,18 @@ function costForImages(provider, modelId, providerMetadata, imageCount) {
 * ESM-only subpath export, built on the Vercel AI SDK image interface
 * (`generateImage`, `@ai-sdk/*`). The caller names the provider and model;
 * reuses the SDK's Result convention (`Result<T, MotifError>` — no
-* thrown exceptions). Google (Gemini) is the only provider in Phase 1a.
+* thrown exceptions). Gemini is reached through OpenRouter.
 *
 * @example
 * ```ts
 * import { createMotifImage } from "@howells/motif-sdk/image";
 *
-* const img = createMotifImage({ defaultProvider: "google" });
-* const r = await img.generate({ model: "gemini-2.5-flash-image", prompt: "a bare concrete wall" });
+* const img = createMotifImage({ defaultProvider: "openrouter" });
+* const r = await img.generate({ model: "gemini-3.1-flash-image", prompt: "a bare concrete wall" });
 * if (r.isOk()) console.log(r.value.images[0].mediaType, r.value.cost);
 * ```
 */
-const DEFAULT_PROVIDER = "google";
+const DEFAULT_PROVIDER = "openrouter";
 /**
 * Create a provider-agnostic image client.
 *
@@ -8676,7 +8786,7 @@ function createMotifImage(config = {}, deps = {}) {
 	}
 	function apiKeyFor(provider) {
 		switch (provider) {
-			case "google": return config.google?.apiKey;
+			case "openrouter": return config.openrouter?.apiKey;
 			case "openai": return config.openai?.apiKey;
 			case "replicate": return config.replicate?.apiToken;
 			case "fal": return config.fal?.apiKey;
@@ -8707,6 +8817,15 @@ function createMotifImage(config = {}, deps = {}) {
 	}
 	async function edit(opts) {
 		const provider = resolveProvider(opts.provider);
+		const imagesField = provider === "fal" ? falEditImagesField(opts.model) : void 0;
+		if (imagesField === "image_url" && opts.images.length > 1) return (0, neverthrow.err)(new MotifError(`${opts.model} takes one input image; ${opts.images.length} were given`, 0));
+		const providerOptions = imagesField === "image_urls" && opts.providerOptions?.fal?.useMultipleImages === void 0 ? {
+			...opts.providerOptions,
+			fal: {
+				...opts.providerOptions?.fal,
+				useMultipleImages: true
+			}
+		} : opts.providerOptions;
 		try {
 			const modelId = opts.model;
 			const model = resolveModelFn(provider, modelId, apiKeyFor(provider), config.fetch);
@@ -8722,7 +8841,7 @@ function createMotifImage(config = {}, deps = {}) {
 				...config.maxRetries === void 0 ? {} : { maxRetries: config.maxRetries },
 				...opts.signal === void 0 ? {} : { abortSignal: opts.signal },
 				...opts.headers === void 0 ? {} : { headers: opts.headers },
-				...opts.providerOptions === void 0 ? {} : { providerOptions: toProviderOptions(opts.providerOptions) }
+				...providerOptions === void 0 ? {} : { providerOptions: toProviderOptions(providerOptions) }
 			});
 			return (0, neverthrow.ok)(toMotifImageResult(result, provider, modelId));
 		} catch (error) {
@@ -8815,7 +8934,7 @@ function toMotifImageResult(result, provider, model) {
 		base64: file.base64,
 		mediaType: file.mediaType
 	}));
-	const cost = costForImages(provider, model, result.providerMetadata, images.length);
+	const cost = costForCalls(provider, model, result.calls.map((call) => call.providerMetadata), images.length);
 	const requestId = extractRequestId(result);
 	const warnings = result.warnings.map(renderWarning);
 	return {
@@ -8841,9 +8960,11 @@ function isRecord$1(value) {
 }
 /** Look for a provider correlation id in providerMetadata, then response headers. */
 function extractRequestId(result) {
-	const fromMetadata = requestIdFromMetadata(result.providerMetadata);
-	if (fromMetadata !== void 0) return fromMetadata;
-	for (const response of result.responses) {
+	for (const call of result.calls) {
+		const fromMetadata = requestIdFromMetadata(call.providerMetadata);
+		if (fromMetadata !== void 0) return fromMetadata;
+	}
+	for (const { response } of result.calls) {
 		const { headers } = response;
 		if (headers) {
 			const id = headers["x-request-id"] ?? headers["x-goog-request-id"] ?? headers["x-fal-request-id"];
@@ -9777,7 +9898,7 @@ function generationPlan(task, model, config, input) {
 		endpoint: built.endpoint,
 		prompt: typeof built.body.prompt === "string" ? built.body.prompt : void 0,
 		provider: "fal",
-		queued: config.useQueue === true
+		queued: config.useQueue === true || input.onProgress !== void 0
 	});
 }
 /**
@@ -9869,6 +9990,286 @@ function upscalerPlan(task, model, input) {
 	});
 }
 //#endregion
+//#region src/task-stream.ts
+const MAX_EVENT_CHARACTERS = 16777216;
+const JSON_START = /^[[{]/;
+function parsePayload(text) {
+	let raw;
+	try {
+		raw = zod.z.json().parse(JSON.parse(text));
+	} catch (error) {
+		if (JSON_START.test(text.trim())) throw error;
+		raw = text;
+	}
+	if (!isRecord$4(raw) || Array.isArray(raw)) return {
+		raw,
+		files: []
+	};
+	const images = Object.fromEntries(["images", "image"].map((key) => {
+		const value = raw[key];
+		const parsed = zod.z.array(zod.z.json()).safeParse(value);
+		return [key, (parsed.success ? parsed.data : [value]).map((item) => {
+			const url = asString(item);
+			return url?.startsWith("data:image/") === true ? { url } : item;
+		})];
+	}));
+	const number = asNumber(raw.progress);
+	const progress = number !== void 0 && Number.isFinite(number) && number >= 0 && number <= 1 ? number : void 0;
+	const message = asString(raw.message);
+	const error = raw.error !== void 0 && raw.error !== null ? asString(raw.detail) ?? message ?? "Provider reported a streaming error." : void 0;
+	return {
+		raw,
+		files: collectUrls(images, ["images", "image"]),
+		progress,
+		message,
+		error
+	};
+}
+function normalise(payload, metadata) {
+	const { raw, files, progress, message } = payload;
+	if (files.length > 0) return {
+		...metadata,
+		type: "images",
+		files,
+		raw
+	};
+	if (progress !== void 0 || message !== void 0) return {
+		...metadata,
+		type: "progress",
+		...progress !== void 0 && { progress },
+		...message !== void 0 && { message },
+		raw
+	};
+	return {
+		...metadata,
+		type: "provider",
+		data: raw
+	};
+}
+function validateStream(plan, key, options) {
+	const model = MODELS[plan.model];
+	const supported = model !== void 0 && (plan.endpoint === model.endpoint && model.streaming?.generation === true || plan.endpoint === model.editEndpoint && model.streaming?.edit === true);
+	if (plan.provider !== "fal" || !supported) return new MotifError("The resolved route does not support streaming.", 0, "STREAMING_UNSUPPORTED", void 0, {
+		model: plan.model,
+		endpoint: plan.endpoint
+	});
+	if (key === void 0) return new MotifError("FAL_KEY is not set.", 0, "MISSING_API_KEY", void 0, { envVar: "FAL_KEY" });
+	if (options.timeout !== void 0 && (!Number.isFinite(options.timeout) || options.timeout <= 0)) return new MotifError("Stream timeout must be a positive finite number.", 0, "INVALID_OPTION");
+}
+function createSession(options) {
+	const controller = new AbortController();
+	let timedOut = false;
+	let requestId;
+	let reader;
+	const abort = () => {
+		controller.abort();
+	};
+	options.signal?.addEventListener("abort", abort, { once: true });
+	if (options.signal?.aborted === true) abort();
+	const timer = setTimeout(() => {
+		timedOut = true;
+		abort();
+		cleanup();
+	}, options.timeout ?? 12e4);
+	const cleanup = async () => {
+		clearTimeout(timer);
+		options.signal?.removeEventListener("abort", abort);
+		controller.abort();
+		try {
+			await reader?.cancel();
+		} catch {}
+	};
+	const failure = (cause) => {
+		if (controller.signal.aborted) return new MotifError(timedOut ? "Stream deadline exceeded." : "Stream aborted.", 0, timedOut ? "TIMEOUT" : "ABORTED", requestId);
+		return cause instanceof MotifError ? cause : new MotifError(cause instanceof Error ? cause.message : String(cause), 0, "STREAM_ERROR", requestId);
+	};
+	const cancellable = async (operation) => {
+		if (controller.signal.aborted) throw failure();
+		let rejectAbort;
+		const interrupted = new Promise((_, reject) => {
+			rejectAbort = () => {
+				reject(failure());
+			};
+			controller.signal.addEventListener("abort", rejectAbort, { once: true });
+		});
+		try {
+			return await Promise.race([operation, interrupted]);
+		} finally {
+			if (rejectAbort !== void 0) controller.signal.removeEventListener("abort", rejectAbort);
+		}
+	};
+	return {
+		controller,
+		failure,
+		cleanup,
+		cancellable,
+		setRequestId(value) {
+			requestId = value;
+		},
+		setReader(value) {
+			reader = value;
+		}
+	};
+}
+/** Direct inference streaming. Never submits to the queue or retries. */
+async function streamTask(plan, key, fetch, ephemeral, options) {
+	const invalid = validateStream(plan, key, options);
+	if (invalid !== void 0) return (0, neverthrow.err)(invalid);
+	if (key === void 0) return (0, neverthrow.err)(new MotifError("FAL_KEY is not set.", 0, "MISSING_API_KEY"));
+	const session = createSession(options);
+	const { controller, failure, cleanup, cancellable } = session;
+	let requestId;
+	let reader;
+	try {
+		if (controller.signal.aborted) throw failure();
+		const response = await cancellable(fetch(`https://fal.run/${plan.endpoint}/stream`, {
+			method: "POST",
+			signal: controller.signal,
+			headers: {
+				Authorization: `Key ${key}`,
+				"Content-Type": "application/json",
+				Accept: "text/event-stream",
+				...ephemeral && { "X-Fal-Store-IO": "0" }
+			},
+			body: JSON.stringify(plan.body)
+		}));
+		requestId = response.headers.get("x-fal-request-id") ?? void 0;
+		session.setRequestId(requestId);
+		if (!response.ok) {
+			const body = await cancellable(response.text());
+			const error = falHttpError(response.status, body, requestId ?? requestIdFromBody(body));
+			await cleanup();
+			return (0, neverthrow.err)(error);
+		}
+		if (response.headers.get("content-type")?.toLowerCase().includes("text/event-stream") !== true || response.body === null) {
+			await response.body?.cancel();
+			await cleanup();
+			return (0, neverthrow.err)(new MotifError("Expected an SSE response body.", response.status, "INVALID_STREAM_RESPONSE", requestId));
+		}
+		reader = response.body.getReader();
+		session.setReader(reader);
+	} catch (error) {
+		const failed = failure(error);
+		await cleanup();
+		return (0, neverthrow.err)(failed);
+	}
+	const iterator = consume(reader, session, requestId);
+	let claimed = false;
+	const events = { [Symbol.asyncIterator]() {
+		if (claimed) throw new Error("Stream events can only be consumed once.");
+		claimed = true;
+		return {
+			next: async () => await iterator.next(),
+			async return() {
+				await cleanup();
+				return await iterator.return(void 0);
+			}
+		};
+	} };
+	return (0, neverthrow.ok)({
+		plan,
+		...requestId !== void 0 && { requestId },
+		events,
+		abort() {
+			controller.abort();
+			cleanup();
+		}
+	});
+}
+async function* consume(reader, session, requestId) {
+	const { cancellable, failure, cleanup } = session;
+	const decoder = new TextDecoder();
+	const frames = createFrames(requestId);
+	try {
+		if (reader === void 0) throw new Error("Missing stream reader.");
+		let finished = false;
+		while (!finished) {
+			const chunk = await cancellable(reader.read());
+			finished = chunk.done;
+			frames.append(chunk.done ? decoder.decode() : decoder.decode(chunk.value, { stream: true }), finished);
+			let frame = frames.next();
+			while (frame !== void 0) {
+				if (frame === "done") return;
+				yield frame;
+				if (frame.isErr()) return;
+				frame = frames.next();
+			}
+		}
+	} catch (error) {
+		yield (0, neverthrow.err)(failure(error));
+	} finally {
+		await cleanup();
+	}
+}
+function createFrames(requestId) {
+	let buffer = "";
+	let finished = false;
+	let data = [];
+	let event;
+	let id;
+	let length = 0;
+	const parse = () => {
+		if (data.length === 0) {
+			event = void 0;
+			length = 0;
+			return;
+		}
+		const text = data.join("\n");
+		const metadata = {
+			...event !== void 0 && { event },
+			...id !== void 0 && { id }
+		};
+		data = [];
+		event = void 0;
+		length = 0;
+		if (text.trim() === "[DONE]") return "done";
+		let payload;
+		try {
+			payload = parsePayload(text);
+		} catch {
+			return (0, neverthrow.err)(new MotifError("Malformed JSON in stream event.", 0, "INVALID_STREAM_DATA", requestId));
+		}
+		if (metadata.event === "error" || payload.error !== void 0) return (0, neverthrow.err)(new MotifError(payload.error ?? payload.message ?? "Provider reported a streaming error.", 0, "STREAM_ERROR", requestId, { data: payload.raw }));
+		return (0, neverthrow.ok)(normalise(payload, metadata));
+	};
+	function acceptField(line) {
+		if (line.startsWith(":")) return;
+		const colon = line.indexOf(":");
+		const field = colon === -1 ? line : line.slice(0, colon);
+		const value = colon === -1 ? "" : line.slice(colon + 1).replace(/^ /, "");
+		if (field === "data") data.push(value);
+		else if (field === "event") event = value;
+		else if (field === "id" && !value.includes("\0")) id = value;
+	}
+	function next() {
+		while (buffer.length > 0) {
+			const lf = buffer.search(/[\r\n]/);
+			if (lf < 0 || !finished && lf === buffer.length - 1 && buffer[lf] === "\r") break;
+			const line = buffer.slice(0, lf);
+			const width = buffer[lf] === "\r" && buffer[lf + 1] === "\n" ? 2 : 1;
+			buffer = buffer.slice(lf + width);
+			length += line.length;
+			enforceBufferLimit(length, requestId);
+			if (line === "") {
+				const parsed = parse();
+				if (parsed === "done") return "done";
+				if (parsed !== void 0) return parsed;
+			} else acceptField(line);
+		}
+		enforceBufferLimit(length + buffer.length, requestId);
+	}
+	return {
+		next,
+		append(text, done) {
+			buffer += text;
+			finished = done;
+		}
+	};
+}
+function enforceBufferLimit(length, requestId) {
+	if (length > MAX_EVENT_CHARACTERS) throw new MotifError("Stream event exceeds the buffer limit.", 0, "STREAM_EVENT_TOO_LARGE", requestId);
+}
+//#endregion
 //#region src/task-client.ts
 /**
 * The Task client: one function per Task. `createMotif()` returns a client
@@ -10055,6 +10456,16 @@ async function openAiOutput(plan, openAiKey, config) {
 		tier: plan.tier
 	});
 }
+function taskStreamer(config, plan, context) {
+	return async (task, input, options = {}) => {
+		const planned = plan(task, input);
+		if (planned.isErr()) return (0, neverthrow.err)(planned.error);
+		return await streamTask(planned.value, context().falKey, config.fetch ?? (async (url, init) => await globalThis.fetch(url, init)), input.ephemeral === true, {
+			timeout: config.timeout,
+			...options
+		});
+	};
+}
 /** Create the Task client. Keys fall back to FAL_KEY and OPENAI_API_KEY. */
 function createMotif(config = {}) {
 	function context() {
@@ -10123,6 +10534,7 @@ function createMotif(config = {}) {
 		},
 		plan,
 		run,
+		stream: taskStreamer(config, plan, context),
 		async upload(bytes, contentType, fileName) {
 			const client = falClient();
 			return client.isErr() ? (0, neverthrow.err)(client.error) : await client.value.uploadToFalCdn(bytes, {