@howells/motif-sdk 7.0.0 → 7.2.0

package/dist/index.d.ts

@@ -1,6 +1,18 @@
+/**
+ * Motif SDK: task-first image work over fal.ai.
+ *
+ * Callers name a task and a tier; Motif picks the model. The per-model registry
+ * and the fal client stay internal.
+ *
+ * @example
+ * ```typescript
+ * import { createMotif } from "@howells/motif-sdk";
+ *
+ * const motif = createMotif();
+ * ```
+ */
 import { Result, Result as Result$1, ResultAsync, err, ok } from "neverthrow";
 import { z } from "zod";
-//#region src/creative.d.ts
 /**
  * Creative direction fields applied to prompts in Motif's canonical order.
  *
@@ -241,8 +253,6 @@ export declare function validateCreativeDirection(creative: CreativeDirection |
  * are joined with `". "` and closed with a period. With no clauses the sanitized prompt is returned unchanged.
  */
 export declare function enrichPrompt(options: EnrichPromptOptions): CreativePromptResult;
-//#endregion
-//#region src/types.d.ts
 /** ─── 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";
@@ -275,8 +285,6 @@ interface JobStatus {
 /** ─── Configuration ──────────────────────────────────────────── */
 /** The network seam: a `fetch`-shaped function. */
 type FalFetch = (url: string, init: RequestInit) => Promise<Response>;
-//#endregion
-//#region src/aspects.d.ts
 /** Ordered by popularity: square first, then common ratios */
 export declare const ASPECT_RATIOS: AspectRatio[];
 export declare const RESOLUTIONS: Resolution[];
@@ -296,8 +304,6 @@ export declare const FORMAT_PRESETS: Record<string, {
   aspect: AspectRatio;
   resolution?: Resolution;
 }>;
-//#endregion
-//#region src/errors.d.ts
 /**
  * `MotifError` and its coercion helper.
  *
@@ -325,8 +331,6 @@ export declare const ACCOUNT_LOCKED = "ACCOUNT_LOCKED";
  * account has run out of credit. Retrying cannot help, and the key is valid.
  */
 export declare function isFalAccountLocked(status: number, body: string): boolean;
-//#endregion
-//#region src/image-benchmarks.d.ts
 /**
  * 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
@@ -340,6 +344,8 @@ interface ArenaScore {
   readonly uncertainty: number;
   /** Exact leaderboard label, including a setting where one was reported. */
   readonly evaluatedModel: string;
+  /** Set when the score was measured on a different version than Motif runs. */
+  readonly note?: string;
   readonly preliminary?: true;
   readonly votes?: number;
 }
@@ -349,8 +355,6 @@ interface ImageModelBenchmark extends ArenaScore {
   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];
@@ -958,8 +962,6 @@ export declare const TASKS: {
 type TaskId = keyof typeof TASKS;
 export declare const TASK_IDS: readonly TaskId[];
 export declare function isTaskId(value: string): value is TaskId;
-//#endregion
-//#region src/resolve.d.ts
 /** What the request needs. Only the fields that narrow the choice. */
 interface TaskRequest {
   /** Explicit Model id, e.g. from `--model`. Overrides everything. */
@@ -1029,6 +1031,8 @@ interface TaskUnresolved {
 }
 type TaskResolution = TaskResolved | TaskUnresolved;
 interface ModelProfile {
+  /** The Model's display name, e.g. "GPT Image 2.6 Sunburst". */
+  readonly name: string;
   readonly capabilities: ReadonlySet<Capability>;
   /** Key variables the Model needs for any request. */
   readonly keys: readonly string[];
@@ -1059,8 +1063,6 @@ export declare function resolveTask(task: TaskId, request: TaskRequest, environm
  * nothing there.
  */
 export declare function tierChangesChoice(task: TaskId, request: Omit<TaskRequest, "tier">, environment: TaskEnvironment): boolean;
-//#endregion
-//#region src/task-stream.d.ts
 interface TaskStreamOptions {
   signal?: AbortSignal;
   /** Overall deadline covering connection and consumption, in milliseconds. */
@@ -1091,8 +1093,6 @@ interface TaskStream {
   /** Stops local consumption; does not guarantee provider cancellation or refund. */
   abort: () => void;
 }
-//#endregion
-//#region src/tool-cost.d.ts
 /** Pixel dimensions of one file an endpoint returned. */
 interface OutputDimensions {
   height?: number;
@@ -1133,8 +1133,6 @@ export declare function sumCosts(costs: readonly (number | null)[]): {
   known: number;
   unknown: number;
 };
-//#endregion
-//#region src/task-client.d.ts
 interface MotifClientConfig {
   /** Falls back to FAL_KEY. */
   falKey?: string;
@@ -1309,11 +1307,7 @@ interface MotifClient {
 }
 /** Create the Task client. The key falls back to FAL_KEY. */
 export declare function createMotif(config?: MotifClientConfig): MotifClient;
-//#endregion
-//#region src/task-plan-shared.d.ts
 export declare const INVALID_OPTION = "INVALID_OPTION";
-//#endregion
-//#region src/prompt-warnings.d.ts
 /**
  * Advisory checks on a user-written prompt.
  *
@@ -1348,8 +1342,6 @@ interface PromptWarning {
 export declare function promptWarnings(prompt: string, context?: {
   editing?: boolean;
 }): PromptWarning[];
-//#endregion
-//#region src/env.d.ts
 export declare const motifEnvSchema: import("@howells/envy").EnvSchema<{
   readonly optional: {
     FAL_KEY: z.ZodString;
@@ -1358,5 +1350,4 @@ export declare const motifEnvSchema: import("@howells/envy").EnvSchema<{
 type MotifEnv = ReturnType<typeof motifEnvSchema.parse>;
 export declare function parseMotifEnv(input?: Record<string, unknown>): MotifEnv;
 export declare function getFalKeyFromEnv(input?: Record<string, unknown>): string | undefined;
-//#endregion
 export { type AspectRatio, type Blocker, type Capability, type ChosenBy, type CreativeDirection, type CreativeField, type CreativeOption, type CreativeOptionErrorDetails, type CreativePromptResult, type CustomImageSize, type EnrichPromptOptions, type FalFetch, type ImageSizeBounds, type LookId, type LookOption, type ModelProfile, type MoodId, type MotifClient, type MotifClientConfig, type MotifEnv, type OutputDimensions, type PlanOptions, type PromptWarning, type PromptWarningRule, type RankedFrom, type RankedModel, type Resolution, type ResolvedCost, type Result, type ResultAsync, type TaskDefinition, type TaskEnvironment, type TaskFile, type TaskFunction, type TaskId, type TaskInput, type TaskMode, type TaskOutput, type TaskPlan, type TaskRequest, type TaskResolution, type TaskResolved, type TaskStream, type TaskStreamEvent, type TaskStreamOptions, type TaskUnresolved, type Tier, type Unblocker, err, ok };

package/dist/index.js

@@ -1,7 +1,7 @@
 import { err, err as err$1, ok, ok as ok$1 } from "neverthrow";
 import { defineEnv } from "@howells/envy";
 import { z } from "zod";
-//#region src/aspects.ts
+// src/aspects.ts
 /** Ordered by popularity: square first, then common ratios */
 const ASPECT_RATIOS = [
 	"auto",
@@ -141,6 +141,9 @@ function scaleWithin(longEdge, longTerm, unit) {
 function roundUpTo(value, unit) {
 	return unit * Math.ceil(value / unit);
 }
+function roundDownTo(value, unit) {
+	return unit * Math.floor(value / unit);
+}
 /**
 * Exact pixel dimensions for an aspect ratio at a resolution tier, or null for
 * `"auto"`.
@@ -170,8 +173,9 @@ function withinImageSizeBounds(size, bounds) {
 }
 /**
 * The exact size for an aspect on an endpoint with limits: the long edge as
-* close to `longEdge` as the ratio allows without passing it, then scaled up
-* only as far as a minimum edge or pixel count demands. Null for `"auto"`.
+* close to `longEdge` as the ratio allows without passing it or the endpoint's
+* maximum edge or pixel count, then scaled up only as far as a minimum edge or
+* pixel count demands. Null for `"auto"`.
 * Undefined when no size in that ratio fits the limits: the caller refuses,
 * because rounding to another ratio is the defect this exists to remove.
 */
@@ -181,6 +185,8 @@ function boundedImageSize(aspect, longEdge, bounds) {
 	const [width, height] = terms;
 	const unit = bounds.multipleOf ?? EDGE_MULTIPLE;
 	let scale = scaleWithin(longEdge, Math.max(width, height), unit);
+	if (bounds.maxEdge !== void 0) scale = Math.min(scale, roundDownTo(bounds.maxEdge / Math.max(width, height), unit));
+	if (bounds.maxPixels !== void 0) scale = Math.min(scale, roundDownTo(Math.sqrt(bounds.maxPixels / (width * height)), unit));
 	if (bounds.minEdge !== void 0) scale = Math.max(scale, roundUpTo(bounds.minEdge / Math.min(width, height), unit));
 	if (bounds.minPixels !== void 0) scale = Math.max(scale, roundUpTo(Math.sqrt(bounds.minPixels / (width * height)), unit));
 	const size = {
@@ -236,8 +242,7 @@ const FORMAT_PRESETS = {
 		label: "Wide"
 	}
 };
-//#endregion
-//#region src/creative.ts
+// src/creative.ts
 const CONTROL_CHAR_REGEX = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g;
 const TRAILING_PERIODS_REGEX = /\.+$/;
 /**
@@ -479,8 +484,7 @@ function enrichPrompt(options) {
 		prompt: clauses.length ? joinSentences([basePrompt, ...clauses].filter((part) => part !== "")) : basePrompt
 	};
 }
-//#endregion
-//#region src/errors.ts
+// src/errors.ts
 /**
 * `MotifError` and its coercion helper.
 *
@@ -537,8 +541,7 @@ function toMotifError(error) {
 	if (error instanceof MotifError) return error;
 	return new MotifError(error instanceof Error ? error.message : String(error), 0, error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : void 0);
 }
-//#endregion
-//#region src/task-plan-shared.ts
+// src/task-plan-shared.ts
 /**
 * Helpers every request builder in the Task planner shares: refusing fields a
 * Model can't carry, and merging `params` without letting them replace what
@@ -618,8 +621,7 @@ function mergeParams(body, params, owned) {
 		...params
 	});
 }
-//#endregion
-//#region src/prompt-warnings.ts
+// src/prompt-warnings.ts
 const EDIT_VERB_REGEX = /^\s*(remove|erase|extend|outpaint)\b/i;
 /** The CLI verb that does each edit directly, keyed by the prompt's first word. */
 const EDIT_VERBS = {
@@ -685,8 +687,7 @@ function promptWarnings(prompt, context = {}) {
 	});
 	return warnings;
 }
-//#endregion
-//#region src/env.ts
+// src/env.ts
 const motifEnvSchema = defineEnv({ optional: { FAL_KEY: z.string().min(1) } });
 function parseMotifEnv(input = process.env) {
 	return motifEnvSchema.parse(input);
@@ -694,8 +695,7 @@ function parseMotifEnv(input = process.env) {
 function getFalKeyFromEnv(input = process.env) {
 	return parseMotifEnv(input).FAL_KEY;
 }
-//#endregion
-//#region src/models.ts
+// src/models.ts
 const AA_IMAGE_LEADERBOARD_SNAPSHOT = "2026-10-07";
 const AA_IMAGE_SOURCES = ["https://artificialanalysis.ai/image/leaderboard/text-to-image", "https://artificialanalysis.ai/image/leaderboard/editing"];
 const FAL_PRICING_CHECKED_AT = "2026-05-12";
@@ -765,7 +765,7 @@ const MODELS = {
 			"xhigh",
 			"max"
 		],
-		supportsResolution: false,
+		supportsResolution: true,
 		supportsSyncMode: true,
 		type: "generation",
 		useQueue: true
@@ -832,7 +832,7 @@ const MODELS = {
 			"xhigh",
 			"max"
 		],
-		supportsResolution: false,
+		supportsResolution: true,
 		supportsSyncMode: true,
 		type: "generation",
 		useQueue: true
@@ -1866,8 +1866,7 @@ const GENERATION_MODELS = [
 	"recraft41"
 ];
 GENERATION_MODELS.filter((id) => MODELS[id]?.supportsEdit === true);
-//#endregion
-//#region src/cost.ts
+// src/cost.ts
 /**
 * Estimate cost based on model and settings. `editImages` is the number of
 * input images on an edit, for Models whose edits cost more than generation.
@@ -1897,8 +1896,7 @@ function estimateVideoCost(durationSeconds = 5, generateAudio = true, model = "k
 	if (model === "kling-turbo") return .14 * durationSeconds;
 	return (generateAudio ? .168 : .112) * durationSeconds;
 }
-//#endregion
-//#region src/fal-parse.ts
+// src/fal-parse.ts
 /**
 * Boundary parsing for fal.ai HTTP responses.
 *
@@ -2003,8 +2001,7 @@ function requestIdFromBody(text) {
 	if (!isRecord$1(parsed)) return;
 	return asString(parsed.request_id) ?? asString(parsed.requestId) ?? asString(parsed.trace_id);
 }
-//#endregion
-//#region src/capabilities.ts
+// src/capabilities.ts
 /**
 * Which generation options each model accepts, derived from the registry.
 *
@@ -2094,8 +2091,7 @@ var UnsupportedOptionError = class extends Error {
 		this.supportedOptions = supported;
 	}
 };
-//#endregion
-//#region src/generate.ts
+// src/generate.ts
 const GPT_IMAGE_SIZES = [
 	"auto",
 	"1024x1024",
@@ -2133,15 +2129,16 @@ function normalizeImageSize(imageSize, sizeMode) {
 	throw new Error(`fal image_size must be one of ${FAL_IMAGE_SIZE_PRESETS.join(", ")} or WIDTHxHEIGHT`);
 }
 /**
-* `image_size` for an aspect: fal's named preset where one holds the ratio
-* exactly, else exact dimensions where the endpoint takes them, else the
-* nearest preset. A Model without a resolution setting is sized to the preset
+* `image_size` for an aspect: exact dimensions at the requested resolution
+* where the endpoint takes them and has a resolution setting; otherwise fal's
+* named preset where one holds the ratio exactly, else exact dimensions where
+* the endpoint takes them, else the nearest preset. A Model without a resolution setting is sized to the preset
 * long edge, so an exact size costs what a preset would. Out of the Model's
 * limits it throws rather than rounding to another ratio.
 */
 function falImageSizeFor(config, aspect, resolution) {
 	const bounds = config.customImageSize;
-	if (bounds === void 0 || FAL_PRESET_ASPECTS.includes(aspect)) return aspectToFalImageSize(aspect);
+	if (bounds === void 0 || !config.supportsResolution && FAL_PRESET_ASPECTS.includes(aspect)) return aspectToFalImageSize(aspect);
 	const size = boundedImageSize(aspect, config.supportsResolution ? RESOLUTION_LONG_EDGE[resolution] : FAL_PRESET_LONG_EDGE, bounds);
 	if (size === void 0) throw new ImageSizeBoundsError(config.name, aspect, bounds);
 	return size ?? aspectToFalImageSize(aspect);
@@ -2154,6 +2151,7 @@ function validateGenerateOptions(options, config, sizeMode, hasEditImages) {
 	if (options.editImageUrls !== void 0 && options.editImageUrls.length > 0 && !config.supportsEdit) unsupported(config, "image editing");
 	if (options.aspect !== void 0 && sizeMode === "none") unsupported(config, "aspect");
 	if (options.resolution !== void 0 && options.resolution !== "2K" && !config.supportsResolution) unsupported(config, "resolution");
+	if (config.autoEditSize === true && hasEditImages && options.aspect === void 0 && options.imageSize === void 0 && options.resolution !== void 0) throw new Error(`${config.name} sizes an edit from its source image; pass an aspect with resolution`);
 	if (options.aspect !== void 0 && config.supportedAspects !== void 0 && !config.supportedAspects.includes(options.aspect)) throw new Error(`${config.name} aspect must be one of ${config.supportedAspects.join(", ")}`);
 	if (options.resolution !== void 0 && config.supportedResolutions !== void 0 && !config.supportedResolutions.includes(options.resolution)) throw new Error(`${config.name} resolution must be one of ${config.supportedResolutions.join(", ")}`);
 	if (options.numImages !== void 0 && options.numImages !== 1 && !config.supportsNumImages) unsupported(config, "numImages");
@@ -2290,8 +2288,7 @@ function buildGenerateBody(options) {
 		endpoint
 	};
 }
-//#endregion
-//#region src/tool-registry/analysis.ts
+// src/tool-registry/analysis.ts
 const ANALYSIS_TOOLS = {
 	"got-ocr": {
 		category: "analysis",
@@ -2405,8 +2402,7 @@ const ANALYSIS_TOOLS = {
 		task: "vision moderation"
 	}
 };
-//#endregion
-//#region src/tool-registry/assets.ts
+// src/tool-registry/assets.ts
 const ASSET_TOOLS = {
 	"hunyuan3d-v3": {
 		category: "3d",
@@ -2724,8 +2720,7 @@ const ASSET_TOOLS = {
 		task: "single-image 3D reconstruction"
 	}
 };
-//#endregion
-//#region src/tool-registry/background.ts
+// src/tool-registry/background.ts
 const BACKGROUND_TOOLS = {
 	"ben-v2": {
 		category: "background",
@@ -3100,8 +3095,7 @@ const BACKGROUND_TOOLS = {
 		task: "video enhancement"
 	}
 };
-//#endregion
-//#region src/tool-registry/editing.ts
+// src/tool-registry/editing.ts
 const EDITING_TOOLS = {
 	"bria-eraser": {
 		category: "erase",
@@ -3372,8 +3366,7 @@ const EDITING_TOOLS = {
 		task: "virtual garment try-on"
 	}
 };
-//#endregion
-//#region src/tool-registry/structure.ts
+// src/tool-registry/structure.ts
 const STRUCTURE_TOOLS = {
 	"depth-anything": {
 		category: "preprocess",
@@ -3765,8 +3758,7 @@ const STRUCTURE_TOOLS = {
 		task: "depth preprocessing"
 	}
 };
-//#endregion
-//#region src/tools.ts
+// src/tools.ts
 const FAL_TOOLS = {
 	...ANALYSIS_TOOLS,
 	...ASSET_TOOLS,
@@ -3794,8 +3786,7 @@ function buildFalToolRequest(options) {
 		tool
 	};
 }
-//#endregion
-//#region src/server-tools.ts
+// src/server-tools.ts
 /**
 * Tool execution bodies for `FalClient`, both synchronous and queued.
 *
@@ -3925,8 +3916,7 @@ async function runToolQueued(exec, options, onProgress) {
 	if (request.isErr()) return err$1(request.error);
 	return (await runRequestQueued(exec, request.value, onProgress)).map(({ data }) => data);
 }
-//#endregion
-//#region src/server.ts
+// src/server.ts
 const FAL_BASE_URL = "https://fal.run";
 const FAL_QUEUE_URL = "https://queue.fal.run";
 const FAL_API_URL = "https://api.fal.ai";
@@ -4243,8 +4233,7 @@ var FalClient = class {
 		});
 	}
 };
-//#endregion
-//#region src/source-size.ts
+// src/source-size.ts
 const DATA_URL_REGEX = /^data:[^;,]*;base64,(.*)$/s;
 function decodeBase64(data) {
 	try {
@@ -4342,8 +4331,7 @@ function dataUrlImageSize(url) {
 	const size = pngSize(bytes) ?? jpegSize(bytes) ?? webpSize(bytes);
 	return size !== void 0 && size.width > 0 && size.height > 0 ? size : void 0;
 }
-//#endregion
-//#region src/tool-cost.ts
+// src/tool-cost.ts
 /**
 * What a tool run costs, before it happens and after.
 *
@@ -4527,8 +4515,8 @@ function sumCosts(costs) {
 		unknown
 	};
 }
-//#endregion
-//#region src/image-benchmarks.ts
+// src/image-benchmarks.ts
+const MEASURED_ON_2_5 = "Measured on GPT Image 2.5. Motif runs GPT Image 2.6, which Arena has not scored yet.";
 const BOARDS = {
 	"text-to-image": {
 		sunburst: {
@@ -4536,6 +4524,7 @@ const BOARDS = {
 			rank: 1,
 			uncertainty: 5,
 			evaluatedModel: "GPT-Image-2.5 Sunburst",
+			note: MEASURED_ON_2_5,
 			preliminary: true,
 			votes: 40323
 		},
@@ -4544,6 +4533,7 @@ const BOARDS = {
 			rank: 2,
 			uncertainty: 5,
 			evaluatedModel: "GPT-Image-2.5 Flare",
+			note: MEASURED_ON_2_5,
 			preliminary: true,
 			votes: 39218
 		},
@@ -4633,6 +4623,7 @@ const BOARDS = {
 			rank: 1,
 			uncertainty: 5,
 			evaluatedModel: "GPT-Image-2.5 Sunburst",
+			note: MEASURED_ON_2_5,
 			preliminary: true
 		},
 		flare: {
@@ -4640,6 +4631,7 @@ const BOARDS = {
 			rank: 2,
 			uncertainty: 5,
 			evaluatedModel: "GPT-Image-2.5 Flare",
+			note: MEASURED_ON_2_5,
 			preliminary: true
 		},
 		"grok-image-2": {
@@ -4709,8 +4701,7 @@ function imageModelBenchmark(model, task) {
 		task
 	};
 }
-//#endregion
-//#region src/tasks.ts
+// src/tasks.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.
@@ -5587,8 +5578,7 @@ const TASK_IDS = Object.keys(TASKS).filter(isTaskId);
 function isTaskId(value) {
 	return Object.hasOwn(TASKS, value);
 }
-//#endregion
-//#region src/tool-parameters.generated.ts
+// src/tool-parameters.generated.ts
 const FAL_TOOL_PARAMETERS = {
 	"ben-v2": [{
 		key: "seed",
@@ -7745,8 +7735,7 @@ const FAL_TOOL_PARAMETERS = {
 function falToolParameters(tool) {
 	return FAL_TOOL_PARAMETERS[tool] ?? [];
 }
-//#endregion
-//#region src/resolve.ts
+// src/resolve.ts
 /**
 * Model choice: the one place a Model is chosen, for the CLI and the SDK.
 *
@@ -7781,6 +7770,7 @@ function generationProfile(config) {
 	if (config.supportsNegativePrompt === true) capabilities.add("negativePrompt");
 	if (config.supportsOutputFormat === true) capabilities.add("outputFormat");
 	return {
+		name: config.name,
 		aspects: config.supportedAspects,
 		capabilities,
 		keys: [FAL_KEY],
@@ -7814,6 +7804,7 @@ function toolProfile(tool) {
 	const takesReference = "referenceField" in config;
 	if (takesReference) capabilities.add("references");
 	return {
+		name: config.name,
 		capabilities,
 		keys: [FAL_KEY],
 		maxReferences: takesReference ? 1 : 0
@@ -8054,8 +8045,7 @@ function tierChangesChoice(task, request, environment) {
 	}
 	return chosen.size > 1;
 }
-//#endregion
-//#region src/task-output.ts
+// src/task-output.ts
 function isPlainRecord(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -8180,8 +8170,7 @@ function labelUrls(urls, labels) {
 		return names !== void 0 && names.length === totals.get(key) ? names[occurrence] : void 0;
 	});
 }
-//#endregion
-//#region src/task-plan-pricing.ts
+// src/task-plan-pricing.ts
 /**
 * What a generation request bills and which body keys the caller owns. Both
 * read the body as sent, `params` included, because fal bills that body.
@@ -8260,8 +8249,7 @@ function checkParamsImageSize(config, model, task, params) {
 		task
 	});
 }
-//#endregion
-//#region src/task-plan-tools.ts
+// src/task-plan-tools.ts
 /**
 * Request bodies for fal tool Models: map each TaskInput field onto the key
 * the tool's generated parameter list names, refuse what it doesn't list, and
@@ -8610,8 +8598,7 @@ function toolPlan(task, model, input) {
 		queued: "queued" in tool
 	});
 }
-//#endregion
-//#region src/task-plan-video.ts
+// src/task-plan-video.ts
 /**
 * Request bodies for video Models: Kling v3 Pro and Kling v3 Turbo Pro, which
 * take the start frame under different keys and bill by the second.
@@ -8692,8 +8679,7 @@ function turboVideoPlan(task, endpoint, input) {
 		queued: true
 	});
 }
-//#endregion
-//#region src/task-plan.ts
+// src/task-plan.ts
 /**
 * `plan()` for the Task client: resolve the Model, build the request body the
 * Model's kind needs, and price it. Pure: no I/O.
@@ -8994,8 +8980,7 @@ function upscalerPlan(task, model, input) {
 		queued: false
 	});
 }
-//#endregion
-//#region src/task-stream.ts
+// src/task-stream.ts
 const MAX_EVENT_CHARACTERS = 16777216;
 const JSON_START = /^[[{]/;
 function parsePayload(text) {
@@ -9274,8 +9259,7 @@ function createFrames(requestId) {
 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
+// src/task-client.ts
 /**
 * The Task client: one function per Task. `createMotif()` returns a client
 * whose `generate`, `erase`, `upscale` and the rest resolve the Model through
@@ -9451,5 +9435,4 @@ function createMotif(config = {}) {
 		}
 	};
 }
-//#endregion
 export { ACCOUNT_LOCKED, ASPECT_RATIOS, CREATIVE_FIELDS, CREATIVE_TAXONOMY, CreativeOptionError, DEFAULT_TIER, FORMAT_PRESETS, INVALID_OPTION, ImageSizeBoundsError, LOOKS, MotifError, NO_MODEL_AVAILABLE, RESOLUTIONS, TASKS, TASK_IDS, TIERS, createMotif, enrichPrompt, err, formatCost, getFalKeyFromEnv, getLook, isFalAccountLocked, isTaskId, modelProfile, motifEnvSchema, ok, parseMotifEnv, promptWarnings, resolveTask, sanitizePrompt, sumCosts, tierChangesChoice, validateCreativeDirection };

package/dist/registry.d.ts

@@ -1,4 +1,8 @@
-//#region src/types.d.ts
+/**
+ * `@howells/motif-sdk/registry` — the Model and tool tables behind Task
+ * resolution, for callers that show or price Models themselves. Most callers
+ * want the Task client from the package root instead.
+ */
 /** ─── 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";
@@ -139,22 +143,14 @@ interface ModelConfig {
   /** Use fal queue submit/status/result even for generate() calls. */
   useQueue?: boolean;
 }
-//#endregion
-//#region src/aspects.d.ts
 /** Pixel sizes of fal's named `image_size` presets. `auto` has none. */
 export declare const FAL_PRESET_SIZES: Readonly<Record<string, CustomImageSize>>;
-//#endregion
-//#region src/cost.d.ts
 /**
  * Estimate cost based on model and settings. `editImages` is the number of
  * input images on an edit, for Models whose edits cost more than generation.
  */
 export declare function estimateCost(model: string, resolution?: Resolution, numImages?: number, editImages?: number): number | null;
-//#endregion
-//#region src/models.d.ts
 export declare const MODELS: Record<string, ModelConfig>;
-//#endregion
-//#region src/tool-types.d.ts
 type FalToolInputKind = "image" | "images" | "video";
 /**
  * Machine-readable cost, so `--dry-run` can emit a number rather than the
@@ -313,8 +309,6 @@ interface FalToolConfig {
   sourceUrl: string;
   task: string;
 }
-//#endregion
-//#region src/tools.d.ts
 export declare const FAL_TOOLS: {
   readonly "got-ocr": {
     readonly category: "analysis";
@@ -1753,5 +1747,4 @@ export declare const FAL_TOOLS: {
 declare const FAL_TOOL_IDS: (keyof typeof FAL_TOOLS)[];
 type FalToolId = (typeof FAL_TOOL_IDS)[number];
 export declare function isFalToolId(tool: string): tool is FalToolId;
-//#endregion
 export type { FalToolConfig, FalToolPrice, ModelConfig };