@howells/motif-sdk 1.2.0 → 1.3.1

package/dist/image.d.ts

@@ -1,6 +1,6 @@
-import { generateImage, ImageModel } from 'ai';
-import { Result } from 'neverthrow';
-
+import { ImageModel, generateImage } from "ai";
+import { Result } from "neverthrow";
+//#region src/errors.d.ts
 /**
  * `MotifError` and its coercion helper.
  *
@@ -10,23 +10,15 @@ import { Result } from 'neverthrow';
  * re-exports `MotifError` so the package's public surface is unchanged.
  */
 declare class MotifError extends Error {
-    readonly status: number;
-    readonly code?: string;
-    /** fal's request-correlation id (from the `x-fal-request-id` header or the
-     * error body). Ties a failure back to fal's dashboard/support. */
-    readonly requestId?: string;
-    constructor(message: string, status: number, code?: string, requestId?: string);
+  readonly status: number;
+  readonly code?: string;
+  /** fal's request-correlation id (from the `x-fal-request-id` header or the
+   * error body). Ties a failure back to fal's dashboard/support. */
+  readonly requestId?: string;
+  constructor(message: string, status: number, code?: string, requestId?: string);
 }
-
-/**
- * Public types for the provider-agnostic image generation + editing layer
- * (`@howells/motif-sdk/image`).
- *
- * This layer is additive: it sits alongside the fal-specific `FalClient`
- * surface and reuses the SDK's Result convention (`Result<T, MotifError>` — no
- * thrown exceptions). See docs/design/provider-agnostic-image-layer.md.
- */
-
+//#endregion
+//#region src/image/types.d.ts
 /**
  * Quality/latency tier. Resolves through a provider-aware tier→model map when no
  * explicit `model` id is given. `balanced` is the default when a tier is omitted.
@@ -42,10 +34,10 @@ type ImageProviderId = "google" | "openai" | "replicate" | "fal" | (string & Rec
 type ImageCostSource = "provider-metadata" | "table" | "unknown";
 /** Normalized per-call spend attached to every result. */
 interface ImageCost {
-    /** Total USD for the call (all images), best-effort. */
-    usd: number;
-    /** Where the figure came from: the provider's metadata, the static table, or unknown. */
-    source: ImageCostSource;
+  /** Total USD for the call (all images), best-effort. */
+  usd: number;
+  /** Where the figure came from: the provider's metadata, the static table, or unknown. */
+  source: ImageCostSource;
 }
 /**
  * Client configuration. Every provider key is optional and falls back to that
@@ -54,137 +46,137 @@ interface ImageCost {
  * credential `apiToken`, not `apiKey`.
  */
 interface MotifImageConfig {
-    /** Provider used when a call does not specify one. Defaults to `google`. */
-    defaultProvider?: ImageProviderId;
-    /** Google provider overrides. `apiKey` falls back to `GOOGLE_GENERATIVE_AI_API_KEY`. */
-    google?: {
-        apiKey?: string;
-    };
-    /** OpenAI provider overrides. `apiKey` falls back to `OPENAI_API_KEY`. */
-    openai?: {
-        apiKey?: string;
-    };
-    /**
-     * Replicate provider overrides. Replicate's SDK names the credential
-     * `apiToken` (not `apiKey`); it falls back to `REPLICATE_API_TOKEN`.
-     */
-    replicate?: {
-        apiToken?: string;
-    };
-    /** fal provider overrides. `apiKey` falls back to `FAL_KEY`. */
-    fal?: {
-        apiKey?: string;
-    };
+  /** Provider used when a call does not specify one. Defaults to `google`. */
+  defaultProvider?: ImageProviderId;
+  /** Google provider overrides. `apiKey` falls back to `GOOGLE_GENERATIVE_AI_API_KEY`. */
+  google?: {
+    apiKey?: string;
+  };
+  /** OpenAI provider overrides. `apiKey` falls back to `OPENAI_API_KEY`. */
+  openai?: {
+    apiKey?: string;
+  };
+  /**
+   * Replicate provider overrides. Replicate's SDK names the credential
+   * `apiToken` (not `apiKey`); it falls back to `REPLICATE_API_TOKEN`.
+   */
+  replicate?: {
+    apiToken?: string;
+  };
+  /** fal provider overrides. `apiKey` falls back to `FAL_KEY`. */
+  fal?: {
+    apiKey?: string;
+  };
 }
 /** Options for a text→image generation. */
 interface GenerateImageOptions {
-    /** The text prompt. */
-    prompt: string;
-    /** Quality/latency tier. Ignored when `model` is set. */
-    tier?: ImageTier;
-    /** Explicit provider model id. Overrides `tier`. */
-    model?: string;
-    /** Provider override for this call. */
-    provider?: ImageProviderId;
-    /**
-     * Aspect ratio, e.g. `"1:1"`. An alternative to {@link size}; pass one or the
-     * other. If both are passed the provider decides which to honor and typically
-     * surfaces a warning (see {@link MotifImageResult.warnings}).
-     */
-    aspectRatio?: `${number}:${number}`;
-    /**
-     * Explicit pixel size, e.g. `"1024x1024"`. An alternative to
-     * {@link aspectRatio}; pass one or the other. If both are passed the provider
-     * decides which to honor and typically surfaces a warning (see
-     * {@link MotifImageResult.warnings}).
-     */
-    size?: `${number}x${number}`;
-    /** Number of images to generate. */
-    n?: number;
-    /** Seed for reproducible generation, where the provider supports it. */
-    seed?: number;
-    /** Abort signal to cancel the in-flight request. */
-    signal?: AbortSignal;
-    /**
-     * Extra HTTP headers forwarded to the provider request. Fal's non-retained IO
-     * (paired with FalClient.deletePayloads) is
-     * `headers: { "X-Fal-Store-IO": "0" }`.
-     */
-    headers?: Record<string, string>;
-    /**
-     * Provider-specific options, passed straight through to the underlying model
-     * as body parameters. Outer key = provider name, inner key = option name.
-     * Values must be JSON-representable; a non-JSON value (undefined, function,
-     * bigint, symbol) makes the call fail with a `MotifError`.
-     */
-    providerOptions?: Record<string, Record<string, unknown>>;
+  /** The text prompt. */
+  prompt: string;
+  /** Quality/latency tier. Ignored when `model` is set. */
+  tier?: ImageTier;
+  /** Explicit provider model id. Overrides `tier`. */
+  model?: string;
+  /** Provider override for this call. */
+  provider?: ImageProviderId;
+  /**
+   * Aspect ratio, e.g. `"1:1"`. An alternative to {@link size}; pass one or the
+   * other. If both are passed the provider decides which to honor and typically
+   * surfaces a warning (see {@link MotifImageResult.warnings}).
+   */
+  aspectRatio?: `${number}:${number}`;
+  /**
+   * Explicit pixel size, e.g. `"1024x1024"`. An alternative to
+   * {@link aspectRatio}; pass one or the other. If both are passed the provider
+   * decides which to honor and typically surfaces a warning (see
+   * {@link MotifImageResult.warnings}).
+   */
+  size?: `${number}x${number}`;
+  /** Number of images to generate. */
+  n?: number;
+  /** Seed for reproducible generation, where the provider supports it. */
+  seed?: number;
+  /** Abort signal to cancel the in-flight request. */
+  signal?: AbortSignal;
+  /**
+   * Extra HTTP headers forwarded to the provider request. Fal's non-retained IO
+   * (paired with FalClient.deletePayloads) is
+   * `headers: { "X-Fal-Store-IO": "0" }`.
+   */
+  headers?: Record<string, string>;
+  /**
+   * Provider-specific options, passed straight through to the underlying model
+   * as body parameters. Outer key = provider name, inner key = option name.
+   * Values must be JSON-representable; a non-JSON value (undefined, function,
+   * bigint, symbol) makes the call fail with a `MotifError`.
+   */
+  providerOptions?: Record<string, Record<string, unknown>>;
 }
 /** Options for a multi-image edit (images in → image out), with an optional mask. */
 interface EditImageOptions {
-    /**
-     * Input images. Each entry is raw bytes (`Uint8Array`) or a string. A string
-     * may be base64, a `data:` URL, OR a remote `http(s)://` URL. Remote URLs are
-     * FETCHED by the provider — and on some providers (e.g. OpenAI) that fetch
-     * happens from the local process running this SDK. Callers that accept
-     * untrusted URLs should fetch and validate the bytes themselves before
-     * passing them here (SSRF / local-network exposure otherwise).
-     */
-    images: (Uint8Array | string)[];
-    /** Natural-language edit instruction. */
-    instruction: string;
-    /**
-     * Optional mask constraining the edited region. Same accepted forms as
-     * {@link EditImageOptions.images} (bytes, base64, `data:` URL, or a remote
-     * `http(s)://` URL that the provider fetches — see the images note on
-     * untrusted URLs). When multiple images are passed, the mask applies to
-     * `images[0]`.
-     */
-    mask?: Uint8Array | string;
-    /** Quality/latency tier. Ignored when `model` is set. */
-    tier?: ImageTier;
-    /** Explicit provider model id. Overrides `tier`. */
-    model?: string;
-    /** Provider override for this call. */
-    provider?: ImageProviderId;
-    /** Number of images to generate. */
-    n?: number;
-    /** Seed for reproducible generation, where the provider supports it. */
-    seed?: number;
-    /** Abort signal to cancel the in-flight request. */
-    signal?: AbortSignal;
-    /**
-     * Extra HTTP headers forwarded to the provider request. Fal's non-retained IO
-     * (paired with FalClient.deletePayloads) is
-     * `headers: { "X-Fal-Store-IO": "0" }`.
-     */
-    headers?: Record<string, string>;
-    /** Provider-specific options (see {@link GenerateImageOptions.providerOptions}). */
-    providerOptions?: Record<string, Record<string, unknown>>;
+  /**
+   * Input images. Each entry is raw bytes (`Uint8Array`) or a string. A string
+   * may be base64, a `data:` URL, OR a remote `http(s)://` URL. Remote URLs are
+   * FETCHED by the provider — and on some providers (e.g. OpenAI) that fetch
+   * happens from the local process running this SDK. Callers that accept
+   * untrusted URLs should fetch and validate the bytes themselves before
+   * passing them here (SSRF / local-network exposure otherwise).
+   */
+  images: (Uint8Array | string)[];
+  /** Natural-language edit instruction. */
+  instruction: string;
+  /**
+   * Optional mask constraining the edited region. Same accepted forms as
+   * {@link EditImageOptions.images} (bytes, base64, `data:` URL, or a remote
+   * `http(s)://` URL that the provider fetches — see the images note on
+   * untrusted URLs). When multiple images are passed, the mask applies to
+   * `images[0]`.
+   */
+  mask?: Uint8Array | string;
+  /** Quality/latency tier. Ignored when `model` is set. */
+  tier?: ImageTier;
+  /** Explicit provider model id. Overrides `tier`. */
+  model?: string;
+  /** Provider override for this call. */
+  provider?: ImageProviderId;
+  /** Number of images to generate. */
+  n?: number;
+  /** Seed for reproducible generation, where the provider supports it. */
+  seed?: number;
+  /** Abort signal to cancel the in-flight request. */
+  signal?: AbortSignal;
+  /**
+   * Extra HTTP headers forwarded to the provider request. Fal's non-retained IO
+   * (paired with FalClient.deletePayloads) is
+   * `headers: { "X-Fal-Store-IO": "0" }`.
+   */
+  headers?: Record<string, string>;
+  /** Provider-specific options (see {@link GenerateImageOptions.providerOptions}). */
+  providerOptions?: Record<string, Record<string, unknown>>;
 }
 /** A single generated image, mirroring the AI SDK's `GeneratedFile`. */
 interface MotifImageFile {
-    uint8Array: Uint8Array;
-    base64: string;
-    mediaType: string;
+  uint8Array: Uint8Array;
+  base64: string;
+  mediaType: string;
 }
 /** Normalized result of a generate/edit call. */
 interface MotifImageResult {
-    /** Generated images. */
-    images: MotifImageFile[];
-    /** Normalized per-call cost + provenance. */
-    cost: ImageCost;
-    /** Resolved provider. */
-    provider: ImageProviderId;
-    /** Resolved model id. */
-    model: string;
-    /** Provider correlation id, where the provider surfaces one. */
-    requestId?: string;
-    /**
-     * Degraded-success warnings from the provider (a requested setting was
-     * ignored or adjusted — e.g. passing both `size` and `aspectRatio`). Each is a
-     * readable string. Omitted entirely when the provider returned none.
-     */
-    warnings?: readonly string[];
+  /** Generated images. */
+  images: MotifImageFile[];
+  /** Normalized per-call cost + provenance. */
+  cost: ImageCost;
+  /** Resolved provider. */
+  provider: ImageProviderId;
+  /** Resolved model id. */
+  model: string;
+  /** Provider correlation id, where the provider surfaces one. */
+  requestId?: string;
+  /**
+   * Degraded-success warnings from the provider (a requested setting was
+   * ignored or adjusted — e.g. passing both `size` and `aspectRatio`). Each is a
+   * readable string. Omitted entirely when the provider returned none.
+   */
+  warnings?: readonly string[];
 }
 /**
  * Picks the winning candidate for a {@link MotifImageClient.bestOfN} call.
@@ -197,14 +189,14 @@ interface MotifImageResult {
  * is not required.
  */
 type ImageJudge = (candidates: readonly MotifImageResult[], context: {
-    readonly prompt?: string;
-    readonly instruction?: string;
+  readonly prompt?: string;
+  readonly instruction?: string;
 }) => Promise<{
-    index: number;
-    reason?: string;
+  index: number;
+  reason?: string;
 }> | {
-    index: number;
-    reason?: string;
+  index: number;
+  reason?: string;
 };
 /**
  * Options for a best-of-N generation. Extends either {@link GenerateImageOptions}
@@ -212,120 +204,94 @@ type ImageJudge = (candidates: readonly MotifImageResult[], context: {
  * `images` selects the edit path — with the candidate count and an optional judge.
  */
 type BestOfNOptions = (GenerateImageOptions | EditImageOptions) & {
-    /** How many candidates to generate (>= 1). */
-    n: number;
-    /** Chooses the winner. Omit → candidate 0 wins. */
-    judge?: ImageJudge;
+  /** How many candidates to generate (>= 1). */
+  n: number;
+  /** Chooses the winner. Omit → candidate 0 wins. */
+  judge?: ImageJudge;
 };
 /** Result of a {@link MotifImageClient.bestOfN} call. */
 interface BestOfNResult {
-    /** The winning candidate (its single-image {@link MotifImageResult}). */
-    best: MotifImageResult;
-    /** The index of `best` within `candidates`. */
-    chosenIndex: number;
-    /** Judge's rationale, if it returned one. */
-    reason?: string;
-    /** All successful candidates, in generation order. */
-    candidates: readonly MotifImageResult[];
-    /** Total USD across all candidates that were generated (successes only). */
-    totalCostUsd: number;
+  /** The winning candidate (its single-image {@link MotifImageResult}). */
+  best: MotifImageResult;
+  /** The index of `best` within `candidates`. */
+  chosenIndex: number;
+  /** Judge's rationale, if it returned one. */
+  reason?: string;
+  /** All successful candidates, in generation order. */
+  candidates: readonly MotifImageResult[];
+  /** Total USD across all candidates that were generated (successes only). */
+  totalCostUsd: number;
 }
 /** The provider-agnostic image client. Every method returns a Result — no throws. */
 interface MotifImageClient {
-    /** Text→image generation. */
-    generate: (opts: GenerateImageOptions) => Promise<Result<MotifImageResult, MotifError>>;
-    /** Multi-image edit (with optional mask). */
-    edit: (opts: EditImageOptions) => Promise<Result<MotifImageResult, MotifError>>;
-    /**
-     * Generate N candidates (in parallel) and pick the best via an optional
-     * injectable judge. Discriminates generate vs edit by the presence of
-     * `images`. Returns the winner plus all successful candidates and total spend.
-     */
-    bestOfN: (opts: BestOfNOptions) => Promise<Result<BestOfNResult, MotifError>>;
+  /** Text→image generation. */
+  generate: (opts: GenerateImageOptions) => Promise<Result<MotifImageResult, MotifError>>;
+  /** Multi-image edit (with optional mask). */
+  edit: (opts: EditImageOptions) => Promise<Result<MotifImageResult, MotifError>>;
+  /**
+   * Generate N candidates (in parallel) and pick the best via an optional
+   * injectable judge. Discriminates generate vs edit by the presence of
+   * `images`. Returns the winner plus all successful candidates and total spend.
+   */
+  bestOfN: (opts: BestOfNOptions) => Promise<Result<BestOfNResult, MotifError>>;
 }
-
-/**
- * Internal dependency-injection seam for the image layer.
- *
- * These types are INTERNAL: they are consumed by `createMotifImage`'s `deps`
- * parameter and by the offline tests, but they are deliberately NOT re-exported
- * from the public `@howells/motif-sdk/image` subpath, so they never appear in
- * `dist/image.d.ts`. Import them from `./deps` inside the package (and from
- * `../src/image/deps` in tests).
- */
-
+//#endregion
+//#region src/image/deps.d.ts
 /** A model resolver: builds an AI SDK `ImageModel` for a (provider, model, key). */
 type ResolveImageModel = (provider: ImageProviderId, modelId: string, apiKey?: string) => ImageModel;
 /** Internal dependency-injection seam (default: real `generateImage` + adapters). */
 interface MotifImageDeps {
-    generateImage?: typeof generateImage;
-    resolveModel?: ResolveImageModel;
+  generateImage?: typeof generateImage;
+  resolveModel?: ResolveImageModel;
 }
-
-/**
- * Provider registry for the image layer.
- *
- * Each provider (google, openai, replicate, fal) contributes exactly one
- * {@link ImageProviderAdapter}. The dispatch functions in `index.ts` and the
- * cost lookup in `cost.ts` read the registry by id, so adding a provider is a
- * single registry entry — not new branches spread across generate/edit/cost.
- */
-
+//#endregion
+//#region src/image/provider.d.ts
 /**
  * A single image provider. A thin wrapper over the provider's `@ai-sdk/*` image
  * model, plus the metadata the layer needs to route by tier, resolve keys, and
  * meter spend.
  */
 interface ImageProviderAdapter {
-    /** Provider id, matching the key it is registered under in {@link PROVIDERS}. */
-    readonly id: ImageProviderId;
-    /** Tier → model id map, used when a call does not pass an explicit `model`. */
-    readonly tierModels: Readonly<Record<ImageTier, string>>;
-    /** Env var read for the API key when no key is supplied in config. */
-    readonly apiKeyEnv: string;
-    /**
-     * Build the AI SDK `ImageModel` for a model id. Prefers the passed `apiKey`,
-     * else the adapter's `apiKeyEnv`. Throws `MotifError` when neither is present
-     * (callers translate this into a `Result.err`). Building a model performs no
-     * network I/O.
-     */
-    readonly resolveModel: (modelId: string, apiKey?: string) => ImageModel;
-    /**
-     * Static per-model USD/**image** table (best-effort; cited per adapter). This
-     * is multiplied by the returned image count to form the call total.
-     *
-     * Cost contract: if an adapter instead surfaces a cost on
-     * `result.providerMetadata` (the preferred source; see
-     * {@link costFromProviderMetadata}), that value MUST already be the **call
-     * total** across all `n` images — NOT a per-image figure. `priceUsdByModel`
-     * is per-image; `providerMetadata.cost` is the whole call. These two paths
-     * intentionally differ, so an adapter must not populate a per-image number
-     * into `providerMetadata.cost`.
-     */
-    readonly priceUsdByModel: Readonly<Record<string, number>>;
+  /** Provider id, matching the key it is registered under in {@link PROVIDERS}. */
+  readonly id: ImageProviderId;
+  /** Tier → model id map, used when a call does not pass an explicit `model`. */
+  readonly tierModels: Readonly<Record<ImageTier, string>>;
+  /** Env var read for the API key when no key is supplied in config. */
+  readonly apiKeyEnv: string;
+  /**
+   * Build the AI SDK `ImageModel` for a model id. Prefers the passed `apiKey`,
+   * else the adapter's `apiKeyEnv`. Throws `MotifError` when neither is present
+   * (callers translate this into a `Result.err`). Building a model performs no
+   * network I/O.
+   */
+  readonly resolveModel: (modelId: string, apiKey?: string) => ImageModel;
+  /**
+   * Static per-model USD/**image** table (best-effort; cited per adapter). This
+   * is multiplied by the returned image count to form the call total.
+   *
+   * Cost contract: if an adapter instead surfaces a cost on
+   * `result.providerMetadata` (the preferred source; see
+   * {@link costFromProviderMetadata}), that value MUST already be the **call
+   * total** across all `n` images — NOT a per-image figure. `priceUsdByModel`
+   * is per-image; `providerMetadata.cost` is the whole call. These two paths
+   * intentionally differ, so an adapter must not populate a per-image number
+   * into `providerMetadata.cost`.
+   */
+  readonly priceUsdByModel: Readonly<Record<string, number>>;
 }
 /**
  * The provider registry. Every id in {@link ImageProviderId}'s closed part maps
  * to its adapter; the open union tail means a lookup can still miss, so access
  * goes through {@link getProviderAdapter}.
  */
-declare const PROVIDERS: Record<ImageProviderId, ImageProviderAdapter>;
+export declare const PROVIDERS: Record<ImageProviderId, ImageProviderAdapter>;
 /**
  * Look up an adapter by provider id, throwing a `MotifError` for an unknown
  * provider (callers catch this into a `Result.err`).
  */
-declare function getProviderAdapter(provider: ImageProviderId): ImageProviderAdapter;
-
-/**
- * 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.
- */
-
+export declare function getProviderAdapter(provider: ImageProviderId): ImageProviderAdapter;
+//#endregion
+//#region src/image/google.d.ts
 /**
  * Tier → Gemini image model id.
  *
@@ -333,111 +299,46 @@ declare function getProviderAdapter(provider: ImageProviderId): ImageProviderAda
  * consumer, see the design doc). `gemini-2.5-flash-image` is the proven-reachable
  * floor; the preview ids may require allowlist/tier access.
  */
-declare const GOOGLE_TIER_MODELS: Readonly<Record<ImageTier, string>>;
+export declare const GOOGLE_TIER_MODELS: Readonly<Record<ImageTier, string>>;
 /** Env var read for the Google API key when `apiKey` is not supplied in config. */
-declare const GOOGLE_API_KEY_ENV = "GOOGLE_GENERATIVE_AI_API_KEY";
-
-/**
- * OpenAI (gpt-image) provider adapter.
- *
- * Builds a Vercel AI SDK `ImageModel` from `@ai-sdk/openai`. Building a model
- * performs no network I/O — the request only happens when `generateImage`
- * invokes `model.doGenerate`.
- */
-
+export declare const GOOGLE_API_KEY_ENV = "GOOGLE_GENERATIVE_AI_API_KEY";
+//#endregion
+//#region src/image/openai.d.ts
 /** Tier → OpenAI image model id (all tiers → the single gpt-image model). */
-declare const OPENAI_TIER_MODELS: Readonly<Record<ImageTier, string>>;
+export declare const OPENAI_TIER_MODELS: Readonly<Record<ImageTier, string>>;
 /** Env var read for the OpenAI API key when `apiKey` is not supplied in config. */
-declare const OPENAI_API_KEY_ENV = "OPENAI_API_KEY";
-
-/**
- * Replicate provider adapter.
- *
- * Builds a Vercel AI SDK `ImageModel` from `@ai-sdk/replicate`. Building a model
- * performs no network I/O — the request only happens when `generateImage`
- * invokes `model.doGenerate`.
- *
- * NOTE: Replicate's SDK names the credential option `apiToken` (not `apiKey`),
- * and reads `REPLICATE_API_TOKEN` from the environment.
- */
-
+export declare const OPENAI_API_KEY_ENV = "OPENAI_API_KEY";
+//#endregion
+//#region src/image/replicate.d.ts
 /** Tier → Replicate model id (all tiers → FLUX 1.1 Pro Ultra for now). */
-declare const REPLICATE_TIER_MODELS: Readonly<Record<ImageTier, string>>;
+export declare const REPLICATE_TIER_MODELS: Readonly<Record<ImageTier, string>>;
 /** Env var read for the Replicate API token when `apiToken` is not in config. */
-declare const REPLICATE_API_KEY_ENV = "REPLICATE_API_TOKEN";
-
-/**
- * fal provider adapter.
- *
- * Builds a Vercel AI SDK `ImageModel` from `@ai-sdk/fal`. Building a model
- * performs no network I/O — the request only happens when `generateImage`
- * invokes `model.doGenerate`. This is the lightweight fal *image* adapter; the
- * richer `FalClient` fal client (queue, upload, upscale, rmbg, video, tools)
- * is a separate, later fold (design doc §8, phase 1d).
- *
- * ENDPOINT QUIRK (Phase 0): fal's gpt-image endpoint wants `image_size` as a
- * STRING enum (e.g. "1024x1024"), passed at generate time via
- * `providerOptions.fal.image_size` — NOT the AI SDK's generic `size` object.
- * This adapter does NOT auto-inject it; callers pass `providerOptions` when they
- * need a specific size. Example:
- *   img.generate({
- *     provider: "fal",
- *     tier: "balanced",
- *     prompt: "...",
- *     providerOptions: { fal: { image_size: "1024x1024" } },
- *   });
- */
-
+export declare const REPLICATE_API_KEY_ENV = "REPLICATE_API_TOKEN";
+//#endregion
+//#region src/image/fal.d.ts
 /**
  * Tier → fal model id. For fal, explicit `model:` endpoint ids are the primary
  * path (any fal endpoint resolves via passthrough); this tier map is a
  * convenience covering the two most common (FLUX Pro Ultra + gpt-image).
  */
-declare const FAL_TIER_MODELS: Readonly<Record<ImageTier, string>>;
+export declare const FAL_TIER_MODELS: Readonly<Record<ImageTier, string>>;
 /** Env var read for the fal key when `apiKey` is not supplied in config. */
-declare const FAL_API_KEY_ENV = "FAL_KEY";
-
-/**
- * Per-call cost tracking for the image layer.
- *
- * Preference order:
- *   1. A cost surfaced by the provider on `result.providerMetadata` (most image
- *      providers do NOT surface one today, so this is usually absent).
- *   2. A static per-model table, owned per-adapter (`priceUsdByModel`) and read
- *      from the provider registry (see sources in each adapter).
- *   3. Unknown → `{ usd: 0, source: "unknown" }`.
- */
-
+export declare const FAL_API_KEY_ENV = "FAL_KEY";
+//#endregion
+//#region src/image/cost.d.ts
 /**
  * Extract a provider-reported total cost from a `generateImage` result's
  * `providerMetadata`, if the provider surfaces a numeric `cost`. The shape is
  * `{ [provider]: { ...; cost?: number } }`. Returns undefined otherwise.
  */
-declare function costFromProviderMetadata(providerMetadata: unknown): number | undefined;
+export declare function costFromProviderMetadata(providerMetadata: unknown): number | undefined;
 /**
  * Normalized per-call cost for a generation. Prefers a provider-metadata cost,
  * then the static table (× image count), then unknown.
  */
-declare function costForImages(provider: ImageProviderId, modelId: string, providerMetadata: unknown, imageCount: number): ImageCost;
-
-/**
- * `@howells/motif-sdk/image` — provider-agnostic image generation + editing.
- *
- * ESM-only subpath export, built on the Vercel AI SDK image interface
- * (`generateImage`, `@ai-sdk/*`). Additive to the fal-specific `FalClient`
- * surface; reuses the SDK's Result convention (`Result<T, MotifError>` — no
- * thrown exceptions). Google (Gemini) is the only provider in Phase 1a.
- *
- * @example
- * ```ts
- * import { createMotifImage } from "@howells/motif-sdk/image";
- *
- * const img = createMotifImage({ defaultProvider: "google" });
- * const r = await img.generate({ tier: "fast", prompt: "a bare concrete wall" });
- * if (r.isOk()) console.log(r.value.images[0].mediaType, r.value.cost);
- * ```
- */
-
+export declare function costForImages(provider: ImageProviderId, modelId: string, providerMetadata: unknown, imageCount: number): ImageCost;
+//#endregion
+//#region src/image/index.d.ts
 /**
  * Create a provider-agnostic image client.
  *
@@ -445,6 +346,6 @@ declare function costForImages(provider: ImageProviderId, modelId: string, provi
  * @param deps - INTERNAL testing seam. Defaults to the real AI SDK `generateImage`
  *   and the built-in provider adapters; tests inject fakes here to run offline.
  */
-declare function createMotifImage(config?: MotifImageConfig, deps?: MotifImageDeps): MotifImageClient;
-
-export { type BestOfNOptions, type BestOfNResult, type EditImageOptions, FAL_API_KEY_ENV, FAL_TIER_MODELS, GOOGLE_API_KEY_ENV, GOOGLE_TIER_MODELS, type GenerateImageOptions, type ImageCost, type ImageCostSource, type ImageJudge, type ImageProviderAdapter, type ImageProviderId, type ImageTier, type MotifImageClient, type MotifImageConfig, type MotifImageFile, type MotifImageResult, OPENAI_API_KEY_ENV, OPENAI_TIER_MODELS, PROVIDERS, REPLICATE_API_KEY_ENV, REPLICATE_TIER_MODELS, costForImages, costFromProviderMetadata, createMotifImage, getProviderAdapter };
+export declare function createMotifImage(config?: MotifImageConfig, deps?: MotifImageDeps): MotifImageClient;
+//#endregion
+export type { BestOfNOptions, BestOfNResult, EditImageOptions, GenerateImageOptions, ImageCost, ImageCostSource, ImageJudge, ImageProviderAdapter, ImageProviderId, ImageTier, MotifImageClient, MotifImageConfig, MotifImageFile, MotifImageResult };