@howells/motif-sdk 5.2.0 → 5.4.0

package/dist/index.d.cts

@@ -246,7 +246,8 @@ export declare function enrichPrompt(options: EnrichPromptOptions): CreativeProm
 /** ─── Model Types ─────────────────────────────────────────────── */
 type AspectRatio = "auto" | "8:1" | "4:1" | "21:9" | "16:9" | "3:2" | "4:3" | "5:4" | "1:1" | "4:5" | "3:4" | "2:3" | "9:16" | "1:4" | "1:8";
 type Resolution = "0.5K" | "1K" | "2K" | "4K";
-type ImageOutputFormat = "jpeg" | "png" | "webp";
+/** `gif` is an animation and `svg` a vector image, on the Models that make them. */
+type ImageOutputFormat = "jpeg" | "png" | "webp" | "gif" | "svg";
 interface CustomImageSize {
   height: number;
   width: number;
@@ -325,25 +326,31 @@ export declare const ACCOUNT_LOCKED = "ACCOUNT_LOCKED";
  */
 export declare function isFalAccountLocked(status: number, body: string): boolean;
 //#endregion
-//#region src/tasks.d.ts
+//#region src/image-benchmarks.d.ts
 /**
- * The Task registry: every job Motif does, with the Models that can do it
- * ranked best-first and tagged with the Tier each belongs to.
- *
- * Rankings are data so a default change is visible in a pull request. A Task
- * ranked from the bench's human comparisons says `rankedFrom: "bench"`; every
- * other Task is hand-ranked from published quality numbers and fal price, and
- * says so. Today no Task is bench-ranked: the bench holds two human ratings,
- * both on one model, which is not an order.
- *
- * Model ids are the short aliases `-m` and `TaskInput.model` accept. `resolveTask` in `./resolve` is the only place a Model is
- * chosen from these lists.
- *
- * A Task can have modes: a variant of the job a caller names explicitly, such
- * as erasing text rather than an object. A ranked entry with a `mode` is only
- * chosen when the request names that mode; an entry without one only when it
- * names none. A Model can appear once per mode.
+ * Arena image scores captured for MOT-72 on October 29, 2026. Flare and
+ * Sunburst route to GPT Image 2.6 but keep 2.5's scores until 2.6 is
+ * benchmarked; `evaluatedModel` names what was measured.
  */
+type ImageBenchmarkTask = "text-to-image" | "image-edit-single-image";
+interface ArenaScore {
+  readonly elo: number;
+  readonly rank: number;
+  /** The reported plus-or-minus interval, in Elo points. */
+  readonly uncertainty: number;
+  /** Exact leaderboard label, including a setting where one was reported. */
+  readonly evaluatedModel: string;
+  readonly preliminary?: true;
+  readonly votes?: number;
+}
+/** Scores are comparable only on the same board and snapshot. */
+interface ImageModelBenchmark extends ArenaScore {
+  readonly source: string;
+  readonly snapshotDate: string;
+  readonly task: ImageBenchmarkTask;
+}
+//#endregion
+//#region src/tasks.d.ts
 export declare const TIERS: readonly ["fast", "balanced", "quality"];
 /** How far a Task trades cost and speed for quality. */
 type Tier = (typeof TIERS)[number];
@@ -351,12 +358,14 @@ export declare const DEFAULT_TIER: Tier;
 /** Where a Task's order came from. */
 type RankedFrom = "bench" | "hand";
 /** Something a request needs that not every Model can honour. */
-type Capability = "aspect" | "count" | "image" | "mask" | "negativePrompt" | "outputFormat" | "references" | "resolution" | "rig" | "seed" | "transparency" | "video";
+type Capability = "aspect" | "count" | "image" | "markup" | "mask" | "negativePrompt" | "outputFormat" | "references" | "resolution" | "rig" | "seed" | "transparency" | "video";
 interface RankedModel {
   /** A Model id, as accepted by `-m` or `TaskInput.model`. */
   readonly model: string;
   /** The Tier this Model is offered at. */
   readonly tier: Tier;
+  /** Published evidence for this Task; null means this route is unscored. */
+  readonly benchmark?: ImageModelBenchmark | null;
   /** The mode this entry serves. Absent for the Task's plain job. */
   readonly mode?: string;
   /** Capabilities this Model has for this Task beyond its registry profile. */
@@ -524,10 +533,10 @@ export declare const TASKS: {
     readonly summary: "Remove an object, person, text or clutter from an image and fill the gap.";
   };
   readonly generate: {
-    readonly basis: "Curated from Artificial Analysis v2, captured 2026-10-07, and Arena 2026-10-06. Sunburst and Flare lead quality at the benchmarked max setting. Nano Banana 2.1 leads balanced on preliminary Arena evidence and lower representative cost; Grok Image 2 and MAI 2.5 are established alternatives. Fast keeps Nano Banana 2 Lite, budget Grok and Seedream 5 Lite, and FLUX.2 Turbo. Design, transparency and tuned Look routes are capability exceptions. Generation with References uses the separate editing ranking. Older routes are explicit/pin/Look-only.";
+    readonly basis: "Order follows Arena text-to-image (https://arena.ai/leaderboard/image/text-to-image), read 2026-10-29 (MOT-72). Sunburst and Flare lead quality at the benchmarked max setting. Balanced starts with Nano Banana 2.1 on preliminary Arena evidence, then Grok Image 2 and Muse Image. Models not yet on the board follow the ranked ones in their Tier, in their previous order. The Artificial Analysis v2 snapshot of 2026-10-07 stays as recorded benchmark data. Fast keeps Nano Banana 2 Lite, budget Grok and Seedream 5 Lite, and FLUX.2 Turbo. Design, transparency and tuned Look routes are capability exceptions. Generation with References uses the separate editing ranking. Older routes are explicit/pin/Look-only.";
     readonly models: readonly RankedModel[];
     readonly notFor: "Variations of an image you already have (vary), or a consistent set of images (series run).";
-    readonly rankedAt: "2026-10-07";
+    readonly rankedAt: "2026-10-29";
     readonly rankedFrom: "hand";
     readonly summary: "Make an image from a prompt, or change an image you pass as a reference.";
   };
@@ -937,10 +946,10 @@ export declare const TASKS: {
     readonly summary: "Trace a raster image to a clean SVG.";
   };
   readonly vary: {
-    readonly basis: "Curated from Artificial Analysis v2 editing, captured 2026-10-07, and preliminary Arena 2026-10-06 evidence for Nano Banana 2.1. Editing order differs from generation: MAI 2.5 outranks Grok Image 2, and Seedream 5 Pro outranks GPT Image 1.5. Sunburst and Flare use max quality. vary reuses a previously chosen Model when explicitly supplied, including retained legacy routes.";
+    readonly basis: "Order follows Arena image edit, single image (https://arena.ai/leaderboard/image/image-edit/single-image), read 2026-10-29 (MOT-72). Editing order differs from generation: Grok Image 2 leads balanced, ahead of Nano Banana 2.1, and Seedream 5 Pro outranks GPT Image 1.5. Arena scores Krea 3 only at its Ultra setting, which costs $0.27 to $0.35 an edit and ignores the requested size, so krea3, which runs fal's default setting, is ranked as unscored. Models not yet on the board follow the ranked ones in their Tier, in their previous order. The Artificial Analysis v2 snapshot of 2026-10-07 stays as recorded benchmark data. Sunburst and Flare use max quality. vary reuses a previously chosen Model when explicitly supplied, including retained legacy routes.";
     readonly models: readonly RankedModel[];
     readonly notFor: "A specific change to an image described in words (generate with a reference), or a set of different scenes in one style (series run).";
-    readonly rankedAt: "2026-10-07";
+    readonly rankedAt: "2026-10-29";
     readonly rankedFrom: "hand";
     readonly summary: "Make variations of an image you already have.";
   };
@@ -964,6 +973,8 @@ interface TaskRequest {
   readonly references?: number;
   /** A mask image is passed in. */
   readonly mask?: boolean;
+  /** A markup image is passed in. */
+  readonly markup?: boolean;
   /** An aspect ratio is asked for, e.g. `"3:2"`. */
   readonly aspect?: string;
   /** A resolution tier is asked for, e.g. `"1K"`. */
@@ -972,7 +983,8 @@ interface TaskRequest {
   readonly count?: number;
   readonly seed?: boolean;
   readonly negativePrompt?: boolean;
-  readonly outputFormat?: boolean;
+  /** An output format is asked for, e.g. `"gif"`. */
+  readonly outputFormat?: string;
   /** A rigged mesh wanted. */
   readonly rig?: boolean;
   /** The kind of Source passed in. Absent for a text-only request. */
@@ -1027,6 +1039,12 @@ interface ModelProfile {
   readonly aspects?: readonly string[];
   /** Resolutions the Model accepts. Absent means any. */
   readonly resolutions?: readonly string[];
+  /** Output formats the Model returns, for a text request and an edit.
+   * Absent means any. */
+  readonly outputFormats?: {
+    readonly edit: readonly string[];
+    readonly text: readonly string[];
+  };
 }
 /** The profile for a Model id, or undefined when no registry knows it. */
 export declare function modelProfile(model: string): ModelProfile | undefined;
@@ -1170,6 +1188,12 @@ interface TaskInput {
   prompt?: string;
   /** Mask image: https URL or data URL. */
   mask?: string;
+  /**
+   * Markup image: https URL or data URL. A transparent PNG of annotations
+   * (circles, arrows, notes) the size of the image being edited, guiding its
+   * edit. generate with references and vary take it; it can't join a mask.
+   */
+  markup?: string;
   /** Reference images: https URLs or data URLs. restyle and try-on take exactly one. */
   references?: readonly string[];
   aspect?: AspectRatio;
@@ -1198,10 +1222,15 @@ interface TaskInput {
   ephemeral?: boolean;
   /**
    * Called on each poll of fal's queue with its status ("queued",
-   * "processing", "completed", "failed") and, while queued, the place in line. Passing
-   * it runs a fal generation through the queue, since only the queue reports.
+   * "processing", "completed", "failed") and, while queued, the place in line. When fal has
+   * written new log lines since the last poll, they come as the third argument
+   * (new lines only). Passing it runs a fal generation through the queue, since
+   * only the queue reports.
    */
-  onProgress?: (status: JobStatus["status"], queuePosition?: number) => void;
+  onProgress?: (status: JobStatus["status"], queuePosition?: number, logs?: readonly {
+    message: string;
+    timestamp: string;
+  }[]) => void;
   /**
    * Called once, as soon as fal's queue accepts the run, with its request id
    * and before any wait. Keep it to `resume` the same job after a restart

package/dist/index.d.ts

@@ -246,7 +246,8 @@ export declare function enrichPrompt(options: EnrichPromptOptions): CreativeProm
 /** ─── Model Types ─────────────────────────────────────────────── */
 type AspectRatio = "auto" | "8:1" | "4:1" | "21:9" | "16:9" | "3:2" | "4:3" | "5:4" | "1:1" | "4:5" | "3:4" | "2:3" | "9:16" | "1:4" | "1:8";
 type Resolution = "0.5K" | "1K" | "2K" | "4K";
-type ImageOutputFormat = "jpeg" | "png" | "webp";
+/** `gif` is an animation and `svg` a vector image, on the Models that make them. */
+type ImageOutputFormat = "jpeg" | "png" | "webp" | "gif" | "svg";
 interface CustomImageSize {
   height: number;
   width: number;
@@ -325,25 +326,31 @@ export declare const ACCOUNT_LOCKED = "ACCOUNT_LOCKED";
  */
 export declare function isFalAccountLocked(status: number, body: string): boolean;
 //#endregion
-//#region src/tasks.d.ts
+//#region src/image-benchmarks.d.ts
 /**
- * The Task registry: every job Motif does, with the Models that can do it
- * ranked best-first and tagged with the Tier each belongs to.
- *
- * Rankings are data so a default change is visible in a pull request. A Task
- * ranked from the bench's human comparisons says `rankedFrom: "bench"`; every
- * other Task is hand-ranked from published quality numbers and fal price, and
- * says so. Today no Task is bench-ranked: the bench holds two human ratings,
- * both on one model, which is not an order.
- *
- * Model ids are the short aliases `-m` and `TaskInput.model` accept. `resolveTask` in `./resolve` is the only place a Model is
- * chosen from these lists.
- *
- * A Task can have modes: a variant of the job a caller names explicitly, such
- * as erasing text rather than an object. A ranked entry with a `mode` is only
- * chosen when the request names that mode; an entry without one only when it
- * names none. A Model can appear once per mode.
+ * Arena image scores captured for MOT-72 on October 29, 2026. Flare and
+ * Sunburst route to GPT Image 2.6 but keep 2.5's scores until 2.6 is
+ * benchmarked; `evaluatedModel` names what was measured.
  */
+type ImageBenchmarkTask = "text-to-image" | "image-edit-single-image";
+interface ArenaScore {
+  readonly elo: number;
+  readonly rank: number;
+  /** The reported plus-or-minus interval, in Elo points. */
+  readonly uncertainty: number;
+  /** Exact leaderboard label, including a setting where one was reported. */
+  readonly evaluatedModel: string;
+  readonly preliminary?: true;
+  readonly votes?: number;
+}
+/** Scores are comparable only on the same board and snapshot. */
+interface ImageModelBenchmark extends ArenaScore {
+  readonly source: string;
+  readonly snapshotDate: string;
+  readonly task: ImageBenchmarkTask;
+}
+//#endregion
+//#region src/tasks.d.ts
 export declare const TIERS: readonly ["fast", "balanced", "quality"];
 /** How far a Task trades cost and speed for quality. */
 type Tier = (typeof TIERS)[number];
@@ -351,12 +358,14 @@ export declare const DEFAULT_TIER: Tier;
 /** Where a Task's order came from. */
 type RankedFrom = "bench" | "hand";
 /** Something a request needs that not every Model can honour. */
-type Capability = "aspect" | "count" | "image" | "mask" | "negativePrompt" | "outputFormat" | "references" | "resolution" | "rig" | "seed" | "transparency" | "video";
+type Capability = "aspect" | "count" | "image" | "markup" | "mask" | "negativePrompt" | "outputFormat" | "references" | "resolution" | "rig" | "seed" | "transparency" | "video";
 interface RankedModel {
   /** A Model id, as accepted by `-m` or `TaskInput.model`. */
   readonly model: string;
   /** The Tier this Model is offered at. */
   readonly tier: Tier;
+  /** Published evidence for this Task; null means this route is unscored. */
+  readonly benchmark?: ImageModelBenchmark | null;
   /** The mode this entry serves. Absent for the Task's plain job. */
   readonly mode?: string;
   /** Capabilities this Model has for this Task beyond its registry profile. */
@@ -524,10 +533,10 @@ export declare const TASKS: {
     readonly summary: "Remove an object, person, text or clutter from an image and fill the gap.";
   };
   readonly generate: {
-    readonly basis: "Curated from Artificial Analysis v2, captured 2026-10-07, and Arena 2026-10-06. Sunburst and Flare lead quality at the benchmarked max setting. Nano Banana 2.1 leads balanced on preliminary Arena evidence and lower representative cost; Grok Image 2 and MAI 2.5 are established alternatives. Fast keeps Nano Banana 2 Lite, budget Grok and Seedream 5 Lite, and FLUX.2 Turbo. Design, transparency and tuned Look routes are capability exceptions. Generation with References uses the separate editing ranking. Older routes are explicit/pin/Look-only.";
+    readonly basis: "Order follows Arena text-to-image (https://arena.ai/leaderboard/image/text-to-image), read 2026-10-29 (MOT-72). Sunburst and Flare lead quality at the benchmarked max setting. Balanced starts with Nano Banana 2.1 on preliminary Arena evidence, then Grok Image 2 and Muse Image. Models not yet on the board follow the ranked ones in their Tier, in their previous order. The Artificial Analysis v2 snapshot of 2026-10-07 stays as recorded benchmark data. Fast keeps Nano Banana 2 Lite, budget Grok and Seedream 5 Lite, and FLUX.2 Turbo. Design, transparency and tuned Look routes are capability exceptions. Generation with References uses the separate editing ranking. Older routes are explicit/pin/Look-only.";
     readonly models: readonly RankedModel[];
     readonly notFor: "Variations of an image you already have (vary), or a consistent set of images (series run).";
-    readonly rankedAt: "2026-10-07";
+    readonly rankedAt: "2026-10-29";
     readonly rankedFrom: "hand";
     readonly summary: "Make an image from a prompt, or change an image you pass as a reference.";
   };
@@ -937,10 +946,10 @@ export declare const TASKS: {
     readonly summary: "Trace a raster image to a clean SVG.";
   };
   readonly vary: {
-    readonly basis: "Curated from Artificial Analysis v2 editing, captured 2026-10-07, and preliminary Arena 2026-10-06 evidence for Nano Banana 2.1. Editing order differs from generation: MAI 2.5 outranks Grok Image 2, and Seedream 5 Pro outranks GPT Image 1.5. Sunburst and Flare use max quality. vary reuses a previously chosen Model when explicitly supplied, including retained legacy routes.";
+    readonly basis: "Order follows Arena image edit, single image (https://arena.ai/leaderboard/image/image-edit/single-image), read 2026-10-29 (MOT-72). Editing order differs from generation: Grok Image 2 leads balanced, ahead of Nano Banana 2.1, and Seedream 5 Pro outranks GPT Image 1.5. Arena scores Krea 3 only at its Ultra setting, which costs $0.27 to $0.35 an edit and ignores the requested size, so krea3, which runs fal's default setting, is ranked as unscored. Models not yet on the board follow the ranked ones in their Tier, in their previous order. The Artificial Analysis v2 snapshot of 2026-10-07 stays as recorded benchmark data. Sunburst and Flare use max quality. vary reuses a previously chosen Model when explicitly supplied, including retained legacy routes.";
     readonly models: readonly RankedModel[];
     readonly notFor: "A specific change to an image described in words (generate with a reference), or a set of different scenes in one style (series run).";
-    readonly rankedAt: "2026-10-07";
+    readonly rankedAt: "2026-10-29";
     readonly rankedFrom: "hand";
     readonly summary: "Make variations of an image you already have.";
   };
@@ -964,6 +973,8 @@ interface TaskRequest {
   readonly references?: number;
   /** A mask image is passed in. */
   readonly mask?: boolean;
+  /** A markup image is passed in. */
+  readonly markup?: boolean;
   /** An aspect ratio is asked for, e.g. `"3:2"`. */
   readonly aspect?: string;
   /** A resolution tier is asked for, e.g. `"1K"`. */
@@ -972,7 +983,8 @@ interface TaskRequest {
   readonly count?: number;
   readonly seed?: boolean;
   readonly negativePrompt?: boolean;
-  readonly outputFormat?: boolean;
+  /** An output format is asked for, e.g. `"gif"`. */
+  readonly outputFormat?: string;
   /** A rigged mesh wanted. */
   readonly rig?: boolean;
   /** The kind of Source passed in. Absent for a text-only request. */
@@ -1027,6 +1039,12 @@ interface ModelProfile {
   readonly aspects?: readonly string[];
   /** Resolutions the Model accepts. Absent means any. */
   readonly resolutions?: readonly string[];
+  /** Output formats the Model returns, for a text request and an edit.
+   * Absent means any. */
+  readonly outputFormats?: {
+    readonly edit: readonly string[];
+    readonly text: readonly string[];
+  };
 }
 /** The profile for a Model id, or undefined when no registry knows it. */
 export declare function modelProfile(model: string): ModelProfile | undefined;
@@ -1170,6 +1188,12 @@ interface TaskInput {
   prompt?: string;
   /** Mask image: https URL or data URL. */
   mask?: string;
+  /**
+   * Markup image: https URL or data URL. A transparent PNG of annotations
+   * (circles, arrows, notes) the size of the image being edited, guiding its
+   * edit. generate with references and vary take it; it can't join a mask.
+   */
+  markup?: string;
   /** Reference images: https URLs or data URLs. restyle and try-on take exactly one. */
   references?: readonly string[];
   aspect?: AspectRatio;
@@ -1198,10 +1222,15 @@ interface TaskInput {
   ephemeral?: boolean;
   /**
    * Called on each poll of fal's queue with its status ("queued",
-   * "processing", "completed", "failed") and, while queued, the place in line. Passing
-   * it runs a fal generation through the queue, since only the queue reports.
+   * "processing", "completed", "failed") and, while queued, the place in line. When fal has
+   * written new log lines since the last poll, they come as the third argument
+   * (new lines only). Passing it runs a fal generation through the queue, since
+   * only the queue reports.
    */
-  onProgress?: (status: JobStatus["status"], queuePosition?: number) => void;
+  onProgress?: (status: JobStatus["status"], queuePosition?: number, logs?: readonly {
+    message: string;
+    timestamp: string;
+  }[]) => void;
   /**
    * Called once, as soon as fal's queue accepts the run, with its request id
    * and before any wait. Keep it to `resume` the same job after a restart