videobook 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -6,6 +6,47 @@ and the package uses [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.2.3] - 2026-10-21
+
+### Added
+
+- Fal FLUX 3 Max text-to-video, image-to-video, and keyframes-to-video,
+  with generated audio and resolution-tiered per-second cost estimates.
+- Bria Fibo 2 text-to-image with structured VGL prompts, and Fibo 2 Edit
+  for one to four reference images, including the image editor.
+- H3 Max Reframe Video, which outpaints a source video to a target aspect
+  ratio at 480p, 768p, or 1080p while keeping its audio and timing.
+  Priced from fal's historical average because the request does not fix
+  the billed duration.
+
+### Changed
+
+- Upgrade all application `@apicity/*` dependencies to 0.16.3.
+- Windows x64 is supported. The release check runs the pack-and-install
+  smoke on Windows and blocks the release when it fails. Stopping
+  `videobook serve` from another process still ends it without a clean
+  shutdown, because Windows has no SIGTERM, and the next start replaces
+  the lock file.
+- Dynamic fal requests are priced from fal's historical average when
+  `FAL_ADMIN_API_KEY` is set. Without the key, and for the two Seedance
+  formula gaps, the estimate stays at the local $0.
+
+## [0.2.2] - 2026-10-21
+
+### Added
+
+- KIE FLUX 3 Klein text-to-image and image editing, with 1K defaults,
+  up to ten edit references, and resolution-aware per-image cost estimates.
+- FLUX 3 Klein Edit in the image editor for whole-image and region edits.
+
+### Changed
+
+- Upgrade all application `@apicity/*` dependencies to 0.16.2.
+
+### Fixed
+
+- Accept npm 12 workspace pack results in the installed-package smoke gate.
+
 ## [0.2.1] - 2026-10-20
 
 ### Changed

package/README.md

@@ -12,8 +12,8 @@ graph, and every change is recorded as a revision. This package installs one
 ## Requirements
 
 - Node.js 22 or newer.
-- macOS (Apple Silicon or Intel) or Linux (x64 or arm64). Windows is not
-  supported yet; see the platform notes.
+- macOS (Apple Silicon or Intel), Linux (x64 or arm64), or Windows x64.
+  See the platform notes.
 - About 800 MB of disk. Installing downloads the ffmpeg and yt-dlp binaries
   from GitHub, and the first video render downloads Chrome Headless Shell
   (about 150 MB) into `~/.cache/videobook/remotion`.
@@ -121,6 +121,7 @@ Caches live in `~/.cache/videobook`. Other settings: `PORT`,
 ## Provider keys
 
 The keys are `OPENAI_API_KEY`, `KIE_API_KEY`, `XAI_API_KEY`, `FAL_API_KEY`,
+`FAL_ADMIN_API_KEY`,
 `DASHSCOPE_API_KEY`, `ELEVENLABS_API_KEY`, `KIMI_CODING_API_KEY`,
 `X_CLIENT_ID` and `X_CLIENT_SECRET`, `DROPBOX_CLIENT_ID` and
 `DROPBOX_CLIENT_SECRET`, and the `B2_*` storage settings. The server starts
@@ -177,12 +178,10 @@ come from 1Password are read-only in Settings.
 - macOS on Intel works, but ONNX Runtime has no Intel Mac build, so semantic
   search is unavailable there.
 - Linux x64 and arm64 are supported.
-- Windows is not supported yet. Every native dependency has a Windows x64
-  build, but the release smoke test has not passed on Windows. Windows has no
-  SIGTERM, so stopping `videobook serve` from another process ends it without
-  a clean shutdown, and the next start replaces the lock file it leaves. The
-  Release check workflow runs the smoke test on Windows for every release tag
-  without blocking the release.
+- Windows x64 is supported. Windows has no SIGTERM, so stopping
+  `videobook serve` from another process ends it without a clean shutdown,
+  and the next start replaces the lock file it leaves. The Release check
+  workflow runs the pack-and-install smoke on Windows for every release tag.
 
 ## Security
 

package/dist/book-manager.js

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { lstat, mkdir, readdir, rename, rm } from "node:fs/promises";
+import { cp, lstat, mkdir, readdir, rename, rm } from "node:fs/promises";
 import { join, relative, resolve, sep } from "node:path";
 import { performance } from "node:perf_hooks";
 import { BOOK_SLUG_ERROR, normalizeBookSlug } from "videobook-engine/book-slug";
@@ -8,6 +8,43 @@ import { createEngine, err, isUuidV7, ok, } from "videobook-engine";
 function engineError(code, message) {
     return { code, message };
 }
+const MOVE_ATTEMPTS = 8;
+const RETRYABLE_MOVE_CODES = new Set(["EPERM", "EBUSY", "EACCES", "ENOTEMPTY"]);
+function systemCode(cause) {
+    if (!cause || typeof cause !== "object" || !("code" in cause))
+        return undefined;
+    const code = cause.code;
+    return typeof code === "string" ? code : undefined;
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// Windows denies renaming a directory while Defender, or a Dolt file that just
+// closed, still holds a handle. Retry, then copy and drop the staging tree.
+async function moveDirectory(source, destination) {
+    let last;
+    for (let attempt = 0; attempt < MOVE_ATTEMPTS; attempt += 1) {
+        try {
+            await rename(source, destination);
+            return;
+        }
+        catch (cause) {
+            last = cause;
+            if (!RETRYABLE_MOVE_CODES.has(systemCode(cause) ?? ""))
+                throw cause;
+            if (attempt < MOVE_ATTEMPTS - 1)
+                await delay(50 * 2 ** attempt);
+        }
+    }
+    try {
+        await cp(source, destination, { recursive: true });
+    }
+    catch {
+        await rm(destination, { recursive: true, force: true }).catch(() => undefined);
+        throw last;
+    }
+    await rm(source, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }).catch(() => undefined);
+}
 function isInside(parent, candidate) {
     const path = relative(parent, candidate);
     return path !== "" && !path.startsWith(`..${sep}`) && path !== "..";
@@ -114,8 +151,9 @@ export class BookManager {
             const created = temporaryEngine.book.get();
             temporaryEngine.close();
             temporaryEngine = null;
+            await delay(0);
             const destination = this.bookRoot(created.bookId);
-            await rename(temporaryRoot, destination);
+            await moveDirectory(temporaryRoot, destination);
             finalRoot = destination;
             const engine = this.createEngine(finalRoot);
             finalEngine = engine;

package/dist/chat-router.js

@@ -576,7 +576,7 @@ Parameter guidelines:
 - Preserve every consumed notebook @address in the generation prompt at the semantic position where it belongs. Do not strip, rename, or expand notebook references into prose
 - For generate_video: put the compact generation description in "prompt" and preserve every consumed @ reference
 - For generate_image: put the compact image description in "prompt" and preserve every consumed image @address there; use refs.image ONLY for the corresponding resolved asset tags whose asset context type is "image", in the same order (include @ prefix). Never put a video or audio asset tag in refs.image — if the user wants an image inspired by a video, describe that source without connecting it as an image
-- ByteDance naming: Seedance is video, Seedream is image. Users often say Seedance for both. When the query names seedance, bytedance, or seedream: if the edit/replace target is an image, use generate_image with model kie:seedream/5-lite-image-to-image and put the edit-target image first in refs.image, followed by replacement image refs. If the target is a video, use generate_video with model kie:bytedance/seedance-2-5, that clip in refs.video and replacement stills in refs.image. Never route an image-target Seedance ask to a video model or to Nano Banana Pro
+- ByteDance naming: Seedance is video, Seedream is image. Users often say Seedance for both. When the query names seedance, bytedance, or seedream: if the edit/replace target is an image, use generate_image with model kie:seedream/5-lite-image-to-image and put the edit-target image first in refs.image, followed by replacement image refs. If the target is a video, use generate_video with model kie:bytedance/seedance-2-5, mode v2v, one 4–30 second clip in refs.video and replacement stills in refs.image. Edit mode follows the source aspect ratio and duration. Never route an image-target Seedance ask to a video model or to Nano Banana Pro
 - Treat "Seedance 5.0 edit", "Seedance 5", and "Seedream 5" as Seedream 5. Generic chat uses Seedream 5 Lite image-to-image; Seedream 5 Pro edit lives in the subject/region pipeline. When Seedream is used for an image ask that said Seedance, the status message must note that substitution
 - For create_watermark_card (QR code / watermark card): use this tool for real scannable QR codes — never generate_image. Pass url from the referenced asset's source_url/webpage_url when the user says "from the url in @vid-…" or similar; optional handle is an X or TikTok alias without @; set platform to "tiktok" for TikTok or "x" for X. apply_watermark uses the same platform field for its alias, icon, and default QR destination
 - For create_qart (artistic / picture QR): use when turning an image asset into scan-safe color and monochrome QR mosaics; pass image_ref and value (URL/text). Prefer over create_watermark_card when the user wants a photo integrated into the QR modules

package/dist/env-secrets.js

@@ -35,6 +35,7 @@ export const MANAGED_ENV_KEYS = [
     "DROPBOX_CLIENT_SECRET",
     "KIMI_CODING_API_KEY",
     "FAL_API_KEY",
+    "FAL_ADMIN_API_KEY",
     "DASHSCOPE_API_KEY",
     "ELEVENLABS_API_KEY",
     "B2_ACCESS_KEY_ID",

package/dist/guides/seedance_2_prompting_guide.md

@@ -85,7 +85,7 @@ Use Seedance 2.0 reference-to-video when replacing people in a clip. Pass the so
 Replace the on-screen person matching @Image1 with @Image1 as character reference. Replace the on-screen person matching @Image2 with @Image2 as character reference. Replace the on-screen person matching @Image3 with @Image3 as character reference. Keep camera movement, pacing, and framing of @Video1.
 ```
 
-Notebook wiring: connect the source video plus the identity stills to a Seedance generation cell (model `kie:bytedance/seedance-2-5`, mode `r2v`). The runner fills `refs.video` from connected video cells and `refs.image` from connected image cells. The result is a normal generated video artifact (`original.mp4` / `proxy.mp4`), not an orientation render.
+Notebook wiring: connect the source video plus the identity stills to a Seedance generation cell (model `kie:bytedance/seedance-2-5`, mode `v2v` / Edit video). Use one source video with a known duration of 4–30 seconds; import URL sources into the book first. Edit mode sets `aspect_ratio=adaptive` and `duration=-1` to preserve the source shape and length. Ordinary reference generation remains `r2v` with its chosen output settings. The runner fills `refs.video` from connected video cells and `refs.image` from connected image cells. The result is a normal generated video artifact (`original.mp4` / `proxy.mp4`), not an orientation render.
 
 ## Camera Movement Vocabulary
 

package/dist/image-edit-models.js

@@ -9,6 +9,7 @@ const STANDARD_IMAGE_EDIT_CAPABILITIES = {
 };
 const EDIT_MODELS = [
     { catalogModel: `kie:${DEFAULT_IMAGE_EDIT_MODEL_ID}`, label: "Nano Banana 2.1 Edit" },
+    { catalogModel: "kie:flux-3/klein-edit-image", label: "FLUX 3 Klein Edit" },
     { catalogModel: "kie:seedream/5-pro-image-to-image", label: "Seedream 5 Pro" },
     { catalogModel: "kie:gpt-image-2-5-flare-image-to-image", label: "GPT Image 2.5 Flare" },
     { catalogModel: "kie:gpt-image-2-5-sunburst-image-to-image", label: "GPT Image 2.5 Sunburst" },
@@ -17,6 +18,7 @@ const EDIT_MODELS = [
     { catalogModel: "fal:fal-ai/nano-banana-2/edit", label: "Nano Banana 2" },
     { catalogModel: "fal:alibaba/qwen-image-3/edit", label: "Qwen 3.0 Edit" },
     { catalogModel: "fal:fal-ai/wan/v2.7/edit", label: "Wan 2.7 Edit" },
+    { catalogModel: "fal:bria/fibo-2/edit", label: "Fibo 2 Edit" },
 ];
 function imageSlotMax(model) {
     return model.slots.find((slot) => slot.role === "image")?.max ?? null;

package/dist/jobs/generate-media.js

@@ -1,3 +1,4 @@
+import { isSeedanceEdit } from "../media/seedance-edit.js";
 import { registerJobHandler } from "../queue.js";
 import { assertProviderPayload } from "../provider-prompt-transform.js";
 import { requireApiKey } from "../api-key.js";
@@ -5,7 +6,7 @@ import { referenceVideoDuration } from "../reference-video-duration.js";
 import { resolveModel } from "../media/descriptor.js";
 import { buildWireRequest } from "../media/request.js";
 import { applyPromptDialect } from "../media/prompt-dialects.js";
-import { checkInsertVideoTiming, checkRefDurations, resolveRefInput, uploadRefs } from "../media/refs.js";
+import { checkSeedanceEditSource, checkInsertVideoTiming, checkRefDurations, resolveRefInput, uploadRefs } from "../media/refs.js";
 import { adapterFor } from "../media/adapters/index.js";
 import { completeMediaGeneration } from "../media/complete.js";
 function storedPayload(model, request) {
@@ -17,11 +18,21 @@ async function replaceAudioMeta(engine, ref) {
     const input = await resolveRefInput(engine, "audio", ref);
     return { replaceAudioWith: { assetId: input.assetId, filename: input.filename } };
 }
-async function costHints(engine, refs) {
-    if (refs.sourceVideoIds.length === 0)
+export async function generationSourceCostHints(engine, refs, job) {
+    const videoSeconds = await referenceVideoDuration(engine, refs.sourceVideoIds);
+    if (videoSeconds !== undefined) {
+        return { inputDurationSeconds: videoSeconds, ...(isSeedanceEdit(job.model, job.mode) ? { durationSeconds: videoSeconds } : {}) };
+    }
+    if (resolveModel(job.model).provider !== "fal")
         return {};
-    const seconds = await referenceVideoDuration(engine, refs.sourceVideoIds);
-    return seconds === undefined ? {} : { inputDurationSeconds: seconds };
+    for (const assetId of refs.sourceAudioIds) {
+        const metadata = await engine.metadata.artifacts.read(assetId, "original");
+        const seconds = metadata.ok ? metadata.value.duration : undefined;
+        if (typeof seconds === "number" && Number.isFinite(seconds) && seconds > 0) {
+            return { inputDurationSeconds: seconds };
+        }
+    }
+    return {};
 }
 function generationMeta(job, model, refs) {
     return {
@@ -40,6 +51,7 @@ export async function runGenerateMedia(engine, job, ctx) {
     await engine.metadata.artifacts.write(job.assetId, "generation-request", job);
     const prompt = job.prompt === undefined ? undefined : applyPromptDialect(model.entry.dialect, job.prompt, job.refs);
     const durationError = (await checkInsertVideoTiming(engine, model, job.refs, job.options))
+        ?? (await checkSeedanceEditSource(engine, model, job.refs, job.mode))
         ?? await checkRefDurations(engine, model, job.refs);
     if (durationError)
         throw new Error(durationError);
@@ -58,7 +70,7 @@ export async function runGenerateMedia(engine, job, ctx) {
         assetId: job.assetId,
         assetDir: job.assetDir,
         meta,
-        costHints: await costHints(engine, refs),
+        costHints: await generationSourceCostHints(engine, refs, job),
     });
     if (result.kind === "done") {
         await completeMediaGeneration({ engine, assetId: job.assetId, assetDir: job.assetDir, bookId: job.bookId, meta, outputs: result.outputs });

package/dist/jobs/run-notebook.js

@@ -14,7 +14,7 @@ import { smoothSceneConcatDef } from "../tools/smooth-scene-concat.js";
 import { spliceVideoDef } from "../tools/splice-video.js";
 import { tryResolveModel } from "../media/descriptor.js";
 import { previewGeneration } from "../media/preview.js";
-import { checkInsertVideoTiming, normalizeRefs } from "../media/refs.js";
+import { checkSeedanceEditSource, checkInsertVideoTiming, normalizeRefs } from "../media/refs.js";
 import { REF_ROLES } from "../media/types.js";
 import { captureFrame, concatSourceRanges, exportSequenceMaster, extractSourceAudio, MINIMUM_SPLIT_PIECE_SECONDS, normalizeSceneVideo, splitSourceRange, splitSourceRanges, } from "../notebook-media-ops.js";
 import { analyzeNotebookSource } from "../notebook-live-analysis.js";
@@ -830,6 +830,9 @@ async function prepareMediaGeneration(model, document, cell, bookId, engine, opt
         const timingError = await checkInsertVideoTiming(engine, model, normalizeRefs(prepared.input.refs), preview.preview.payload.input ?? {});
         if (timingError)
             throw new Error(timingError);
+        const sourceError = await checkSeedanceEditSource(engine, model, normalizeRefs(prepared.input.refs), prepared.input.mode);
+        if (sourceError)
+            throw new Error(sourceError);
     }
     return {
         tool: `generate_${model.media}`,
@@ -2357,7 +2360,7 @@ export async function failQueuedNotebookCells(engine, notebookId, options) {
 function notebookRunPlanRecords(document) {
     return document.notebookRunPlans ?? [];
 }
-async function updateNotebookRunPlanState(engine, notebookId, planId, status, details = {}) {
+async function updateNotebookRunPlanState(engine, notebookId, planId, status, details = {}, recordedRun) {
     const result = await mutateNotebook(engine, notebookId, "update_notebook_run_plan", (document) => ({
         ...document,
         notebookRunPlans: notebookRunPlanRecords(document).map((record) => record.planId === planId
@@ -2367,6 +2370,17 @@ async function updateNotebookRunPlanState(engine, notebookId, planId, status, de
                 ...record,
                 status,
                 ...details,
+                ...(recordedRun ? {
+                    plan: {
+                        ...record.plan,
+                        recordedRunId: recordedRun.recordedRunId,
+                        recordedRuns: [
+                            ...(record.plan.recordedRuns ?? []),
+                            recordedRun,
+                        ],
+                    },
+                    error: recordedRun.error,
+                } : {}),
                 updatedAt: new Date().toISOString(),
             }
             : record),
@@ -2922,7 +2936,7 @@ export function registerRunNotebookJob(engine) {
         }
         const now = new Date().toISOString();
         const run = {
-            id: runId,
+            id: uuidv7(),
             notebookId: input.notebookId,
             status: errors.length === 0 ? "completed" : "failed",
             startedAt: now,
@@ -2939,11 +2953,16 @@ export function registerRunNotebookJob(engine) {
                 runId,
                 outputs,
                 ...(errors.length > 0 ? { error: errors.join("\n") } : {}),
+            }, {
+                recordedRunId: run.id,
+                status: run.status,
+                completedAt: now,
+                ...(run.error ? { error: run.error } : {}),
             });
         }
         if (errors.length > 0)
             throw new Error(errors.join("\n"));
-        return run;
+        return { ...run, id: runId, runId, recordedRunId: run.id };
     };
     registerJobHandler("run_notebook", async (payload) => {
         const input = payload;

package/dist/media/adapters/fal.js

@@ -3,6 +3,7 @@ import { requireApiKey } from "../../api-key.js";
 import { uploadAssetToFal } from "../../jobs/_fal-upload.js";
 import { describeFalError } from "../../jobs/_fal-shared.js";
 import { withProviderHandoff } from "../../jobs/_lease.js";
+import { generationCostHints } from "../cost.js";
 import { providerEndpoints } from "../endpoints.js";
 import { writePendingTask } from "./pending.js";
 import { MEDIA_TASK_TYPES } from "./types.js";
@@ -30,6 +31,12 @@ async function submitQueued(request, context, ownerId) {
     return submitted.request_id;
 }
 async function submit(request, context) {
+    const hints = generationCostHints(request, context.costHints);
+    if (Object.keys(hints).length > 0) {
+        const written = await context.engine.metadata.artifacts.write(context.assetId, "generation-cost-hints", hints);
+        if (!written.ok)
+            throw new Error(written.error.message);
+    }
     const taskId = await withProviderHandoff(context.engine, context.assetId, context.ctx, "generate", async (ownerId) => {
         const id = await submitQueued(request, context, ownerId);
         return { taskId: id, result: id };

package/dist/media/catalog.js

@@ -8,6 +8,13 @@ const SEEDANCE_MODES = [
 const FRAME_MODES = [
     { id: "i2v", label: "Frames", roles: ["first_frame", "last_frame"] },
 ];
+const FLUX_3_MAX_DEFAULTS = {
+    aspect_ratio: "auto",
+    duration: 5,
+    generate_audio: true,
+    resolution: "720p",
+    reasoning_level: "high",
+};
 const SEEDANCE_US_REFERENCE_MODES = [
     { id: "r2v", label: "References", roles: ["image", "video", "audio"], requireAny: ["image", "video", "audio"] },
     { id: "v2v", label: "Edit video", roles: ["video", "image", "audio"], requireAny: ["video"], defaults: { task: "editing" } },
@@ -60,6 +67,8 @@ function h3MaxStyle(style) {
 }
 export const MODEL_ENTRIES = [
     { id: "kie:nano-banana-2-1", media: "image", operations: ["text_to_image", "edit_image"], dialect: "natural_numbered", defaults: { ...LIGHTNING_SCENE_OPTIONS } },
+    { id: "kie:flux-3/klein-text-to-image", media: "image", operations: ["text_to_image"], dialect: "natural", defaults: { resolution: "1K" } },
+    { id: "kie:flux-3/klein-edit-image", media: "image", operations: ["edit_image"], dialect: "natural", defaults: { resolution: "1K" } },
     { id: "kie:nano-banana-pro", media: "image", operations: ["text_to_image", "edit_image"], guide: "nano_banana", dialect: "natural" },
     { id: "kie:gpt-image-2-5-flare-text-to-image", media: "image", operations: ["text_to_image"], guide: "gpt_image", dialect: "natural", defaults: { resolution: "2K" } },
     { id: "kie:gpt-image-2-5-flare-image-to-image", media: "image", operations: ["edit_image"], guide: "gpt_image", dialect: "natural", defaults: { resolution: "2K" } },
@@ -108,6 +117,8 @@ export const MODEL_ENTRIES = [
     { id: "fal:ideogram/v4.5/edit", media: "image", operations: ["edit_image"], refs: { image: ["image_url", "reference_image_urls"] } },
     { id: "fal:blackforestlabs/flux-3/text-to-image", media: "image", operations: ["text_to_image"] },
     { id: "fal:blackforestlabs/flux-3/edit-image", media: "image", operations: ["edit_image"] },
+    { id: "fal:bria/fibo-2/generate", media: "image", operations: ["text_to_image"] },
+    { id: "fal:bria/fibo-2/edit", media: "image", operations: ["edit_image"], prompt: "instruction" },
     { id: "fal:fal-ai/flux-2-flex", media: "image", operations: ["text_to_image"] },
     { id: "fal:bria/guided-remove-background", media: "image", operations: ["edit_image"] },
     { id: "fal:bria/fibo-edit-1.5/expand", media: "image", operations: ["edit_image"] },
@@ -115,10 +126,10 @@ export const MODEL_ENTRIES = [
     {
         id: "kie:bytedance/seedance-2-5",
         media: "video",
-        operations: ["text_to_video", "image_to_video", "reference_to_video"],
+        operations: ["text_to_video", "image_to_video", "reference_to_video", "edit_video"],
         guide: "seedance25",
         dialect: "seedance",
-        modes: SEEDANCE_MODES,
+        modes: [...SEEDANCE_MODES, { id: "v2v", label: "Edit video", roles: ["video", "image", "audio"], requireAny: ["video"] }],
         defaults: { ...LIGHTNING_VIDEO_OPTIONS },
         frameOptions: { aspect_ratio: "adaptive" },
     },
@@ -170,6 +181,10 @@ export const MODEL_ENTRIES = [
     { id: "fal:alibaba/wan-3.0-prime/text-to-video", media: "video", operations: ["text_to_video"], hidden: true },
     { id: "fal:alibaba/wan-3.0-prime/image-to-video", media: "video", operations: ["image_to_video"], hidden: true },
     { id: "fal:alibaba/wan-3.0-prime/reference-to-video", media: "video", operations: ["reference_to_video"], hidden: true },
+    { id: "fal:blackforestlabs/flux-3-max/text-to-video", media: "video", operations: ["text_to_video"], title: "FLUX 3 Max", defaults: FLUX_3_MAX_DEFAULTS },
+    { id: "fal:blackforestlabs/flux-3-max/image-to-video", media: "video", operations: ["image_to_video"], title: "FLUX 3 Max Image", refs: { first_frame: "image_url" }, modes: FRAME_MODES, defaults: FLUX_3_MAX_DEFAULTS },
+    { id: "fal:blackforestlabs/flux-3-max/keyframes-to-video", media: "video", operations: ["image_to_video"], title: "FLUX 3 Max Keyframes", refs: { image: "keyframes" }, keyframeFps: 24, defaults: FLUX_3_MAX_DEFAULTS },
+    { id: "fal:minimax/h3-max/reframe-video", media: "video", operations: ["edit_video"] },
     { id: "fal:minimax/h3-max/insert-video", media: "video", operations: ["edit_video"], refs: { video: ["video_url", "reference_video_urls"] } },
     { id: "fal:minimax/h3-max/recast", media: "video", operations: ["edit_video"] },
     { id: "fal:minimax/h3-max-turbo/extend-video", media: "video", operations: ["extend_video"] },

package/dist/media/cost.js

@@ -1,5 +1,70 @@
-import { computeEstimate } from "@apicity/cost";
+import { createFal } from "@apicity/fal";
+import { computeEstimate, createFalEstimateCache, resolveFalDynamicEstimate, } from "@apicity/cost";
 import { buildWireRequest } from "./request.js";
+const FAL_ESTIMATE_TTL_MS = 5 * 60 * 1000;
+let falEstimateCache = createFalEstimateCache({
+    ttlMs: FAL_ESTIMATE_TTL_MS,
+    maxEntries: 128,
+});
+let estimatorOverrideActive = false;
+let estimatorOverride = null;
+let liveEstimatorKey;
+let liveEstimator;
+function freshFalEstimateCache() {
+    return createFalEstimateCache({ ttlMs: FAL_ESTIMATE_TTL_MS, maxEntries: 128 });
+}
+export function installFalDynamicEstimator(estimator) {
+    const previous = {
+        active: estimatorOverrideActive,
+        estimator: estimatorOverride,
+        cache: falEstimateCache,
+    };
+    estimatorOverrideActive = true;
+    estimatorOverride = estimator;
+    falEstimateCache = freshFalEstimateCache();
+    return () => {
+        estimatorOverrideActive = previous.active;
+        estimatorOverride = previous.estimator;
+        falEstimateCache = previous.cache;
+    };
+}
+function falAdminKey() {
+    const value = process.env.FAL_ADMIN_API_KEY?.trim();
+    return value ? value : undefined;
+}
+function falPricingEstimator(apiKey) {
+    const estimate = createFal({ apiKey }).v1.models.pricing.estimate;
+    return (request) => estimate(request);
+}
+function currentFalEstimator() {
+    if (estimatorOverrideActive)
+        return estimatorOverride;
+    const apiKey = falAdminKey();
+    if (!apiKey)
+        return null;
+    if (liveEstimator && liveEstimatorKey === apiKey)
+        return liveEstimator;
+    liveEstimatorKey = apiKey;
+    liveEstimator = falPricingEstimator(apiKey);
+    return liveEstimator;
+}
+export async function estimateFalRequest(endpoint, payload, hints) {
+    const estimator = currentFalEstimator();
+    if (!estimator) {
+        return computeEstimate({
+            provider: "fal",
+            payload,
+            endpoint,
+            ...(hints ? { costHints: hints } : {}),
+        });
+    }
+    return resolveFalDynamicEstimate(endpoint, payload, estimator, {
+        ...(hints ? { hints } : {}),
+        // Queue polls omit x-fal-billable-units, so this is one historical call.
+        callQuantity: 1,
+        cache: falEstimateCache,
+    });
+}
 function costProvider(model) {
     return model.provider;
 }
@@ -18,26 +83,34 @@ function durationHint(input) {
         ?? (numeric(input.music_length_ms) !== undefined ? numeric(input.music_length_ms) / 1000 : undefined);
     return seconds !== undefined && seconds > 0 ? { durationSeconds: seconds } : {};
 }
-function combinedHints(input, hints) {
+export function generationCostHints(input, hints) {
     const combined = { ...durationHint(input), ...hints };
     return combined.durationSeconds === undefined && combined.inputDurationSeconds !== undefined
         ? { ...combined, durationSeconds: combined.inputDurationSeconds }
         : combined;
 }
-function estimateWireRequest(model, request, input, hints = {}) {
+async function estimateWireRequest(model, request, input, hints = {}) {
+    const payload = costPayload(model, request, input);
+    const costHints = generationCostHints(input, hints);
+    if (model.provider === "fal")
+        return estimateFalRequest(model.apiId, payload, costHints);
     return computeEstimate({
         provider: costProvider(model),
-        payload: costPayload(model, request, input),
+        payload,
         endpoint: model.apiId,
-        costHints: combinedHints(input, hints),
+        costHints,
     });
 }
-export function estimateGeneration(model, call, hints = {}) {
+export async function estimateGeneration(model, call, hints = {}) {
     const built = buildWireRequest(model, call);
     if (!built.ok)
         return built;
     try {
-        return { ok: true, estimate: estimateWireRequest(model, built.request, built.input, hints), request: built.request };
+        return {
+            ok: true,
+            estimate: await estimateWireRequest(model, built.request, built.input, hints),
+            request: built.request,
+        };
     }
     catch (error) {
         return { ok: false, error: error instanceof Error ? error.message : String(error) };

package/dist/media/json-schema.js

@@ -36,6 +36,13 @@ export function isUrlObject(schema) {
         return false;
     return branches(schema).some((branch) => branch.type === "object" && branch.properties?.url !== undefined);
 }
+export function isKeyframeItem(schema) {
+    if (!schema)
+        return false;
+    return branches(schema).some((branch) => branch.type === "object"
+        && branch.properties?.image_url !== undefined
+        && branch.properties?.frame_index !== undefined);
+}
 export function isArraySchema(schema) {
     return branches(schema).some((branch) => branch.type === "array");
 }

package/dist/media/ref-fields.js

@@ -1,4 +1,4 @@
-import { arrayBounds, arrayItems, isArraySchema, isUrlObject, propertyAt } from "./json-schema.js";
+import { arrayBounds, arrayItems, isArraySchema, isKeyframeItem, isUrlObject, propertyAt } from "./json-schema.js";
 const CANDIDATES = {
     first_frame: [
         "first_frame_url",
@@ -55,12 +55,14 @@ function expandField(input, field) {
     const required = isRequired(input, field);
     if (isArraySchema(schema)) {
         const bounds = arrayBounds(schema);
+        const items = arrayItems(schema);
         return [{
                 path: field,
                 multi: true,
                 max: bounds.max,
                 min: required ? Math.max(1, bounds.min) : 0,
-                urlObject: isUrlObject(arrayItems(schema)),
+                urlObject: isUrlObject(items),
+                ...(isKeyframeItem(items) ? { keyframe: true } : {}),
             }];
     }
     return [{ path: field, multi: false, max: 1, min: required ? 1 : 0, urlObject: isUrlObject(schema) }];
@@ -83,7 +85,13 @@ export function resolveSlot(role, input, entry) {
             throw new Error(`${entry.id}: ref field ${name} for ${role} is not in the apicity schema`);
     }
     const expanded = names.flatMap((name) => expandField(input, name));
-    const fields = expanded.map(({ path, multi, max, urlObject }) => ({ path, multi, max, urlObject }));
+    const fields = expanded.map(({ path, multi, max, urlObject, keyframe }) => ({
+        path,
+        multi,
+        max,
+        urlObject,
+        ...(keyframe ? { keyframe: true } : {}),
+    }));
     const max = expanded.some((field) => field.max === null)
         ? null
         : expanded.reduce((sum, field) => sum + (field.max ?? 0), 0);

package/dist/media/refs.js

@@ -1,3 +1,4 @@
+import { isSeedanceEdit } from "./seedance-edit.js";
 import { referenceVideoDuration } from "../reference-video-duration.js";
 import { insertVideoTimingError, isInsertVideoModel } from "./insert-video-timing.js";
 import { resolveAudioRef, resolveImageRef, resolveVideoRef } from "../tools/_media-refs.js";
@@ -129,3 +130,15 @@ export async function checkInsertVideoTiming(engine, model, refs, options) {
     const duration = source ? await referenceVideoDuration(engine, [source]) : undefined;
     return insertVideoTimingError(options, duration);
 }
+export async function checkSeedanceEditSource(engine, model, refs, mode) {
+    if (!isSeedanceEdit(model.id, mode))
+        return null;
+    if (refs.video?.length !== 1)
+        return "Seedance Edit video requires exactly one source video (4–30 seconds).";
+    const duration = await referenceVideoDuration(engine, refs.video);
+    if (duration === undefined)
+        return "Seedance Edit video requires a source with known duration. Import the video into the book and use its artifact reference (4–30 seconds).";
+    return duration < 4 || duration > 30
+        ? `Seedance Edit video source is ${duration} seconds; use a source between 4 and 30 seconds.`
+        : null;
+}