videobook 0.0.0-stage → 0.2.0

package/dist/guides/kling_3_0_prompting_guide.md

@@ -0,0 +1,136 @@
+---
+source: "https://blog.fal.ai/kling-3-0-prompting-guide/ , https://www.ambienceai.com/tutorials/kling-prompting-guide , https://filmora.wondershare.com/ai-prompt/kling-ai-negative-prompt.html"
+type: reference
+date_added: 2026-02-13
+---
+
+# Kling 3.0 Prompting Guide
+
+Compiled from multiple sources covering Kling 3.0 prompting techniques, camera controls, negative prompts, and multi-shot capabilities.
+
+## Summary
+
+Kling 3.0 is a major update to the Kling AI video generation model. Its biggest advancement is understanding **cinematic intent** — it processes prompts more like a director's notes than a list of objects. Key new features include 15-second generation, multi-shot sequences (up to 6 shots), native audio with dialogue, and improved character consistency.
+
+## Prompt Structure
+
+The recommended prompt template follows this order:
+
+**Scene > Characters > Action > Camera > Audio & Style**
+
+Full template: `[Shot type] of [subject] [action/movement], [environment/setting], [camera movement], [lighting/mood], [style/aesthetic]`
+
+Example: "Medium shot of a professional chef expertly flipping vegetables in a wok with flames rising, modern restaurant kitchen with stainless steel surfaces, camera slowly dollies forward, dramatic side lighting creating strong shadows, cinematic food photography style, shallow depth of field"
+
+## Cinematic Intent
+
+Prompts that reference filmmaking concepts (scene coverage, composition, pacing, continuity) consistently outperform prompts that focus only on visual attributes. The model excels when prompts read like directions to a scene rather than a list of objects.
+
+## Multi-Shot Sequences
+
+- Supports up to 6 shots in a single output
+- Clearly label each shot with framing, subject, and motion
+- Don't compress multi-shot narratives into one paragraph
+- Use explicit shot names: profile shots, macro close-ups, tracking shots, POV
+
+Example structure:
+```
+[Scene Setup with atmosphere]
+[Shot 1 description with framing and motion]
+[Character A, tone]: "Dialogue"
+[Immediate action]
+[Character B, tone]: "Response"
+```
+
+## Camera Movement Types
+
+- **Dolly** — forward/backward for reveal shots
+- **Tracking** — following subjects laterally for action
+- **Crane/Jib** — vertical movement with arc for establishing shots
+- **Pan** — horizontal rotation across landscapes
+- **Tilt** — vertical rotation for height emphasis
+- **Orbit** — 360-degree rotation around subjects
+- **Handheld** — natural shake for documentary feel
+- **Steadicam** — smooth floating movement
+
+Advanced: dolly zoom (perspective shift), arc tracking (dynamic orbits), crane pans (vertical reveals)
+
+Tips: Specify speed ("slow dolly," "rapid pan"), define start/end points, layer movements, match movement to mood, use focal length terms.
+
+## Motion and Temporal Control
+
+- Use temporal markers: "initially... then... finally" for progression
+- Specify motion paths: "arc from left to right," "spiral upward"
+- Add motion endpoints: "then settles back into place" to prevent drift
+- Describe camera behavior precisely: stays, freezes, resumes
+
+Motion descriptors: gracefully, swiftly, gradually, explosively, smoothly, rhythmically, dynamically
+
+## Native Audio and Dialogue
+
+- Specify who speaks and when, especially in multi-character scenes
+- Use consistent character labels: `[Character A: Description]`
+- Bind dialogue to actions: describe the action first, then dialogue
+- Add tone descriptors: "raspy deep voice," "fearful voice"
+- Use temporal markers: "Immediately," "Pause," "Softly speaking"
+- Supports multiple languages, accents, and code-switching
+
+## Elements (Visual Reference Binding)
+
+- Elements inject reference images for specific characters, objects, or styles
+- Each element has: `name` (label), `description` (what it is), `element_input_urls` (2-4 reference images)
+- Reference in prompts with `@element_name` syntax — e.g., `@element_dog`
+- The `name` must match the `@` reference in the prompt exactly (without the `@`)
+- Naming convention: lowercase with underscores (`element_dog`, `element_cat`)
+- Minimum 2 reference images per element, maximum 4 (JPG/PNG, max 10MB each)
+- Video elements also supported: MP4/MOV, max 50MB
+- Tracks up to 3 people independently in one scene
+- `@element_name` binds visual identity; `[Character, tone]:` binds dialogue — use both together
+- API field: `kling_elements` array in the request body
+
+## Negative Prompts
+
+### Best Practices
+- Limit to 3-7 items — don't overload
+- Keep language simple and direct
+- Match prompts to the specific scene type
+- Type what you want to avoid directly (e.g., "robots" not "no robots")
+- Be specific rather than vague
+
+### By Scene Type
+- **Cinematic**: grain, lens distortion, flicker, low resolution
+- **Character animation**: extra fingers, deformed limbs, face blur, glitching
+- **Product marketing**: shadows, reflections, motion blur, unnecessary objects
+- **Fashion/runway**: awkward arm movement, double limbs, stutter, poor lighting
+- **Fantasy**: clutter, pixelation, overlapping structures, unnatural lighting
+- **Nature**: blurry motion, incorrect animal anatomy, unnatural colors
+- **Action**: camera shake, motion blur, vehicle clipping, unrealistic physics
+
+### Common Mistakes
+- Using vague terminology instead of specific technical terms
+- Applying generic prompts without considering scene type
+- Including excessive negative prompts that confuse the AI
+- Forgetting to balance positive and negative instructions
+
+## Style Keywords
+
+Quality enhancers: cinematic, professional, ultra-detailed, photorealistic, studio-quality, broadcast-ready
+
+Atmosphere terms: ethereal, dramatic, moody, vibrant, serene, intense, mysterious, energetic
+
+## Technical Settings
+
+- Resolution: 1080p (1920x1080) for professional output
+- Frame rate: 30fps industry standard
+- Duration: 5 seconds (clips) or 10-15 seconds (extended)
+- Quality modes: Standard (faster) vs Cinematic (highest quality)
+
+## Key Takeaways
+
+- Write prompts like a director, not a describer
+- Structure: Scene > Characters > Action > Camera > Style
+- Use film terminology for camera and framing
+- Multi-shot: label each shot explicitly, don't compress
+- Negative prompts: targeted and limited (3-7 items)
+- Specify motion endpoints to prevent generation drift
+- Iterate by changing one variable at a time

package/dist/guides/nano_banana_pro_prompting_guide.md

@@ -0,0 +1,28 @@
+---
+source: "blog.google/products/gemini/prompting-tips-nano-banana-pro/, wavespeed.ai, minimaxir.com, imagine.art, github.com/ZeroLu/awesome-nanobanana-pro"
+type: reference
+date_added: 2026-02-13
+---
+
+# Nano Banana Pro Prompting Guide
+
+## Summary
+
+Nano Banana Pro is Google DeepMind's image generation model built on Gemini 3 Pro, launched November 2025. It introduces thinking mode (the model reasons through prompts before generating), search grounding (real-time Google Search integration for factual accuracy), text rendering (legible multi-language text directly in images), multi-image input (up to 14 reference images), and high-resolution output (up to 4K).
+
+## Key Takeaways
+
+- Prompts should follow the structure: Subject/Action + Style/Medium + Setting/Atmosphere + Technical Specs + Mood/Emotion
+- Six essential prompt components: subject, composition, action, setting/location, style, and editing instructions
+- Text rendering excels with specific placement, font, and size instructions — keep to 1-3 text elements per image
+- Thinking mode reasons through the prompt and generates interim "thought images" before the final output
+- Search grounding connects to Google Search for real-time data — trigger with keywords like "search for," "latest," "today," "current"
+- Up to 14 reference images can be provided for character/brand consistency, style direction, and composition guidance
+- Supports 1K, 2K, and 4K resolution output
+- The model pushes toward realism due to RLHF training — surreal or absurd prompts get normalized
+- Explicit negations work reliably: "NEVER include any text, watermarks, or line overlays"
+- Photographic specifications (camera model, lens, lighting) significantly improve professional output quality
+- JSON-structured prompts can help organize complex multi-element compositions
+- Era/aesthetic anchoring through film stocks ("Kodak Portra 400") and time periods triggers consistent visual language
+- Grid generations (2x2, 4x4) work well because autoregressive generation understands previously-rendered sections
+- Cost: base ~$0.039/image, Pro 2K ~$0.134/image; generation time 20s to 1min+

package/dist/guides/seedance_2_prompting_guide.md

@@ -0,0 +1,172 @@
+---
+source: "fal.ai/models/bytedance/seedance-2.0/reference-to-video, seedance2api.app/blog/seedance-2-prompt-guide, seed.bytedance.com/en/blog/official-launch-of-seedance-2-0"
+type: reference
+date_added: 2026-05-03
+---
+
+# Seedance 2.0 Prompting Guide
+
+## Summary
+
+Seedance 2.0 is ByteDance's multimodal video generation model. It uses a dual-branch Diffusion Transformer — one branch for spatial information (what things look like), one for temporal (how they move). Well-structured prompts feed both branches cleanly. The model exposes director-level camera control via prompt (dolly, tracking, POV switches, handheld) and generates synchronized native audio by default.
+
+Three task variants share the same prompt grammar:
+- **t2v** (text-to-video) — prompt only
+- **i2v** (image-to-video) — prompt + a single first-frame image (and optional `end_image_url` last frame)
+- **r2v** (reference-to-video) — prompt + up to 9 images, 3 videos, 3 audio clips (12 files max), referenced by @-tag in the prompt
+
+A "fast" mode exists for each variant — same schema, lower quality/latency tradeoff.
+
+## Prompt Structure
+
+Five-component formula:
+
+**Subject + Action + Camera + Style + Constraints**
+
+- **Subject** — who/what appears
+- **Action** — movement and events
+- **Camera** — angle, movement, lens
+- **Style** — aesthetic anchor (specific film/director, not "cinematic")
+- **Constraints** — duration, resolution, physics requirements
+
+Keep prompts under ~150 words. Place subject and action first.
+
+## @ Tag Reference Syntax (r2v)
+
+Reference uploaded files inline using `@Image1`, `@Video1`, `@Audio1`. Numbers correspond to upload order. `generate_video` in `r2v` mode accepts `refs.image` / `refs.video` / `refs.audio` arrays of artifact ids — index 0 is `@Image1`, index 1 is `@Image2`, etc.
+
+Limits per request:
+- Images: `@Image1` … `@Image9` (max 9)
+- Videos: `@Video1` … `@Video3` (max 3, combined 2–15s)
+- Audio: `@Audio1` … `@Audio3` (max 3, combined ≤15s)
+- Total files across modalities: 12
+
+### Image reference roles
+
+State the role explicitly so the model knows what to do with each image:
+
+- `@Image1 as the first frame` — start the video from this image
+- `@Image1 as the last frame` — end the video at this image
+- `@Image1 as character reference` — preserve appearance throughout
+- `@Image1 as background environment` — use as scene setting
+- `@Image1 as style reference` — match color/texture/mood
+
+### Video reference roles
+
+- `Refer to the camera movement of @Video1`
+- `Character moves like @Video1` — transfer choreography
+- `Apply the transition effects from @Video1`
+- `Match the pacing and cuts of @Video1`
+
+### Audio reference roles
+
+- `@Audio1 as background soundtrack`
+- `@Audio1 as ambient sound`
+- `@Audio1 as voice style reference`
+
+### Worked example (multi-modal r2v)
+
+```
+Replace the character in @Video1 with @Image1, with @Image1 as the first frame.
+The character should wear virtual sci-fi glasses. Refer to the camera movement
+and close-up surround shots of @Video1, changing from a third-person perspective
+to the character's subjective perspective. Travel through AI virtual glasses and
+arrive at the deep blue universe of @Image2 where several spaceships are seen
+traveling into distance.
+```
+
+This prompt works because every @-tag has an explicit role (`replace … with`, `as the first frame`, `Refer to … of`, `arrive at … of`), the perspective shift is named (third-person → subjective), and the destination scene is anchored visually (`deep blue universe … spaceships`).
+
+### Actor replacement (video source + still identity refs)
+
+Use Seedance 2.0 reference-to-video when replacing people in a clip. Pass the source clip in `refs.video` (`@Video1`) and one still per actor in `refs.image` (`@Image1`…), then map each still onto an on-screen person:
+
+```
+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.
+
+## Camera Movement Vocabulary
+
+Explicit camera direction is the single highest-leverage prompt component.
+
+- Dolly: "slow dolly-in," "push forward"
+- Pan / tilt: "pan right," "tilt upward"
+- Zoom: "slow zoom to close-up," "dolly zoom"
+- Tracking: "tracking shot," "follow from behind," "close-up surround shots"
+- Static: "static wide shot," "camera holds steady"
+- Angle: "extreme wide shot," "low angle," "overhead"
+- Lens: "anamorphic lens flare," "bokeh background"
+- Perspective: "third-person to subjective POV," "first-person handheld"
+
+## Multi-Shot, Scene Cuts, Timestamps
+
+A single generation can contain natural cuts (up to 15s). Use scene-cut and timecode language to control pacing:
+
+- `Cut scene to …`
+- `At 5 seconds, …`
+- `[00:00-00:04] Shot 1: …`
+
+Shot-script template for multi-shot output:
+
+```
+【Style】Denis Villeneuve sci-fi epic
+【Duration】10s
+[00:00-00:04] Shot 1: Establishing wide (low-angle dolly-in). Description with physical details.
+[00:04-00:07] Shot 2: Close-up surround (tracking arc). Description.
+[00:07-00:10] Shot 3: POV (handheld). Description.
+Consistency: same wardrobe and lighting across all shots.
+```
+
+## Variants and Parameters
+
+All variants share these output parameters:
+
+| Parameter | Values |
+|---|---|
+| `resolution` | `480p`, `720p` (fal.ai also lists `1080p` for r2v) — default `720p` |
+| `duration` | `auto`, `4`–`15` seconds (integer) — default `auto` |
+| `aspect_ratio` | `auto`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` |
+| `generate_audio` | bool, default `true` — synchronized music/SFX/dialogue |
+| `seed` | int, optional |
+
+Variant-specific inputs:
+
+- **t2v** — `prompt` only
+- **i2v** — `prompt` + `image_url` (first frame) + optional `end_image_url` (last frame)
+- **r2v** — `prompt` + `image_urls[≤9]` + `video_urls[≤3]` + `audio_urls[≤3]`, total ≤12
+
+## Style Anchoring
+
+Generic terms ("cinematic," "epic") underperform specific anchors. Reference an actual director, film, or art movement: "Denis Villeneuve sci-fi epic," "Wong Kar-wai neon street photography," "Studio Ghibli watercolor backgrounds." Anchor early in the prompt.
+
+## Physics and Body Language
+
+Seedance 2.0 simulates fluid dynamics, cloth, and character motion. Prompts that describe physical reactions ("hair lifts in the wind," "fabric ripples as she turns") consistently outperform prompts that describe abstract emotion ("she feels free"). Describe the body, not the feeling.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---|---|
+| Vague subject ("a cool car video") | Add specific descriptors and camera direction |
+| @-tag references a non-existent file (e.g., `@Image3` with 2 uploaded) | Verify upload order; tags start at 1 |
+| @-tag with no role | State what the file is for: "as first frame," "as background" |
+| No camera direction | Add explicit movement (dolly, tracking, POV) |
+| Generic style ("cinematic") | Anchor to a specific director/film/movement |
+| Conflicting text vs. reference | Align prompt with the actual content of @-tagged files |
+| >150 words | Trim — long prompts dilute the load-bearing instructions |
+| No duration in prompt OR API | Set both — prompt language plus the `duration` parameter |
+| Multiple actions, no timecodes | Use `[00:00-00:05]` format to bind events to time |
+
+## Key Takeaways
+
+- Five-part formula: Subject + Action + Camera + Style + Constraints
+- Every @-tag needs an explicit role ("as first frame," "as character reference," "Refer to camera movement of")
+- Camera direction is mandatory — the model defaults to bland motion without it
+- Style anchors should name a director or film, not a genre
+- For multi-shot output, use timecodes (`[00:00-00:04]`) and named shots
+- Describe physics and body language, not abstract emotion
+- Keep prompts under ~150 words
+- `generate_audio: true` (default) — say "no audio" in the prompt isn't enough, set the flag
+- Match reference files to prompt text; conflicting signals degrade the output

package/dist/http-access.js

@@ -0,0 +1,49 @@
+export const EXTENSION_ORIGIN = "chrome-extension://cebmihgcglhadjckbebmfahaiiljhgdj";
+function localHost(host) {
+    const match = /^(localhost|127\.0\.0\.1|\[::1\])(?::([0-9]{1,5}))?$/i.exec(host);
+    return match !== null && (match[2] === undefined || Number(match[2]) <= 65535);
+}
+function localOrigin(origin) {
+    if (origin === EXTENSION_ORIGIN)
+        return true;
+    const match = /^https?:\/\/(.+)$/.exec(origin);
+    return match !== null && localHost(match[1]);
+}
+export function allowsHttpRequest(host, origin, fetchSite) {
+    if (!localHost(host))
+        return false;
+    if (origin !== null)
+        return localOrigin(origin);
+    return fetchSite !== "cross-site";
+}
+export const restrictHttpAccess = (req, res, next) => {
+    if (!allowsHttpRequest(req.get("host") ?? "", req.get("origin") ?? null, req.get("sec-fetch-site") ?? null)) {
+        res.status(403).json({ error: "HTTP request origin or host is not allowed" });
+        return;
+    }
+    next();
+};
+function isNativeMediaPath(path) {
+    let decodedPath;
+    try {
+        decodedPath = decodeURIComponent(path);
+    }
+    catch {
+        return false;
+    }
+    return /\.(?:mp4|m4v|mov|webm|ogv|mp3|m4a|aac|wav|flac|ogg|oga|opus|weba)$/iu.test(decodedPath);
+}
+export const restrictMediaContent = (req, res, next) => {
+    const nativeMedia = isNativeMediaPath(req.path);
+    res.setHeader("Content-Security-Policy", [
+        nativeMedia ? "sandbox allow-same-origin" : "sandbox",
+        "default-src 'none'",
+        "img-src 'self' data: blob:",
+        "media-src 'self' data: blob:",
+        "style-src 'unsafe-inline'",
+        "base-uri 'none'",
+        "form-action 'none'",
+    ].join("; "));
+    res.setHeader("X-Content-Type-Options", "nosniff");
+    next();
+};

package/dist/http-byte-range.js

@@ -0,0 +1,31 @@
+export function parseHttpByteRange(value, size) {
+    if (!Number.isSafeInteger(size) || size < 1)
+        return { ok: false };
+    const match = value.trim().match(/^bytes=(\d*)-(\d*)$/u);
+    if (!match || (!match[1] && !match[2]))
+        return { ok: false };
+    if (!match[1]) {
+        const suffixLength = Number(match[2]);
+        if (!Number.isSafeInteger(suffixLength) || suffixLength < 1) {
+            return { ok: false };
+        }
+        return {
+            ok: true,
+            end: size - 1,
+            start: Math.max(0, size - suffixLength),
+        };
+    }
+    const start = Number(match[1]);
+    const requestedEnd = match[2] ? Number(match[2]) : size - 1;
+    if (!Number.isSafeInteger(start)
+        || !Number.isSafeInteger(requestedEnd)
+        || start >= size
+        || requestedEnd < start) {
+        return { ok: false };
+    }
+    return {
+        ok: true,
+        end: Math.min(requestedEnd, size - 1),
+        start,
+    };
+}

package/dist/hydration.js

@@ -0,0 +1,56 @@
+import { startPostMetricsScheduler } from "./posts/post-metrics.js";
+import { queue } from "./queue.js";
+import { loadAndArmAll } from "./scheduled-posts.js";
+const runDirectly = async (step) => await step.run();
+function openBooks(books) {
+    return books.list().flatMap((book) => {
+        const selected = books.get(book.bookId);
+        return selected.ok ? [selected.value] : [];
+    });
+}
+function bookTag(book) {
+    return `${book.name} [${book.bookId.slice(0, 8)}]`;
+}
+async function loadReconcilers(run) {
+    const imageSubjects = await run({ phase: "import", label: "jobs/image-subjects (hydrate)", run: () => import("./jobs/image-subjects.js") });
+    const runNotebook = await run({ phase: "import", label: "jobs/run-notebook (hydrate)", run: () => import("./jobs/run-notebook.js") });
+    return { imageSubjects, runNotebook };
+}
+async function ensureDevFixtures(books, run) {
+    const dancing = await run({ phase: "import", label: "dancing-workflow (fixtures)", run: () => import("./dancing-workflow.js") });
+    await run({ phase: "reconcile", label: "ensureDancingWorkflow()", run: () => dancing.ensureDancingWorkflow(books) });
+}
+async function reconcileBeforeQueue(books, run, reconcilers) {
+    const { imageSubjects, runNotebook } = reconcilers;
+    for (const book of openBooks(books)) {
+        const tag = bookTag(book);
+        await run({ phase: "reconcile", label: `${tag} jobs.queue.reap()`, run: () => book.engine.jobs.queue.reap() });
+        await run({ phase: "reconcile", label: `${tag} reconcileImageSubjectJobFailures`, run: () => imageSubjects.reconcileImageSubjectJobFailures(book.engine, book.bookId) });
+        await run({ phase: "reconcile", label: `${tag} abortLeasedNotebookRunsOnStartup`, run: () => runNotebook.abortLeasedNotebookRunsOnStartup(book.engine) });
+        await run({ phase: "reconcile", label: `${tag} reconcileGenerationMediaOutputs`, run: () => runNotebook.reconcileGenerationMediaOutputs(book.engine) });
+        await run({ phase: "reconcile", label: `${tag} reconcileQueuedNotebookCells`, run: () => runNotebook.reconcileQueuedNotebookCells(book.engine) });
+    }
+}
+async function reconcileAfterQueue(books, run, reconcilers) {
+    for (const book of openBooks(books)) {
+        await run({
+            phase: "reconcile",
+            label: `${bookTag(book)} reconcileAwaitingNotebookOutputs`,
+            run: () => reconcilers.runNotebook.reconcileAwaitingNotebookOutputs(book.engine, book.bookId),
+        });
+    }
+}
+export async function hydrateLibrary(books, options) {
+    const run = options.runStep ?? runDirectly;
+    await run({ phase: "open", label: "bookManager.ready()", run: () => books.ready() });
+    if (options.devFixtures)
+        await ensureDevFixtures(books, run);
+    const reconcilers = await loadReconcilers(run);
+    await reconcileBeforeQueue(books, run, reconcilers);
+    if (options.startQueue !== false)
+        await run({ phase: "reconcile", label: "queue.start()", run: () => queue.start() });
+    await reconcileAfterQueue(books, run, reconcilers);
+    await run({ phase: "reconcile", label: "loadAndArmAll()", run: () => loadAndArmAll() });
+    if (options.startPostMetrics !== false)
+        startPostMetricsScheduler();
+}

package/dist/image-compress.js

@@ -0,0 +1,77 @@
+import sharp from "sharp";
+const JPEG_REENCODE_THRESHOLD_BYTES = 3 * 1024 * 1024;
+// External image-gen APIs reject or silently degrade sub-300px inputs. Keep both
+// dimensions at or above this floor by upscaling small images to JPEG.
+const MIN_IMAGE_DIMENSION = 300;
+const REENCODABLE_FORMATS = new Set(["jpeg", "png", "webp", "bmp", "tiff", "avif"]);
+function replaceExtension(filename, newExt) {
+    const dot = filename.lastIndexOf(".");
+    return dot === -1 ? `${filename}.${newExt}` : `${filename.slice(0, dot)}.${newExt}`;
+}
+// Re-encode raster images larger than the threshold to high-quality JPEG at
+// the source resolution. Uploads to free hosts and Alibaba/Kie worker fetches
+// are more reliable with smaller payloads, and wan i2v has a ~10 MB base-64
+// cap (≈7 MB raw). Returns the input unchanged for non-images, small files,
+// or cases where re-encoding would not shrink the payload.
+export async function maybeReencodeImage(data, filename) {
+    if (data.byteLength <= JPEG_REENCODE_THRESHOLD_BYTES) {
+        return { data, filename };
+    }
+    let format;
+    try {
+        const meta = await sharp(data).metadata();
+        format = meta.format;
+    }
+    catch {
+        return { data, filename };
+    }
+    if (!format || !REENCODABLE_FORMATS.has(format)) {
+        return { data, filename };
+    }
+    const reencoded = await sharp(data)
+        .rotate()
+        .flatten({ background: "#ffffff" })
+        .jpeg({ quality: 92, mozjpeg: true, progressive: true, chromaSubsampling: "4:2:0" })
+        .toBuffer();
+    if (reencoded.byteLength >= data.byteLength) {
+        return { data, filename };
+    }
+    return { data: new Uint8Array(reencoded), filename: replaceExtension(filename, "jpg") };
+}
+// Upscale raster images whose shortest side is below MIN_IMAGE_DIMENSION so that
+// both dimensions are at least MIN_IMAGE_DIMENSION, preserving aspect ratio.
+// Output is always JPEG. Returns the input unchanged for non-raster formats or
+// images that already meet the floor.
+export async function maybeUpscaleSmallImage(data, filename) {
+    let format;
+    let width;
+    let height;
+    try {
+        const meta = await sharp(data).metadata();
+        format = meta.format;
+        width = meta.width;
+        height = meta.height;
+    }
+    catch {
+        return { data, filename };
+    }
+    if (!format || !REENCODABLE_FORMATS.has(format))
+        return { data, filename };
+    if (!width || !height)
+        return { data, filename };
+    if (width >= MIN_IMAGE_DIMENSION && height >= MIN_IMAGE_DIMENSION) {
+        return { data, filename };
+    }
+    const resized = await sharp(data)
+        .rotate()
+        .flatten({ background: "#ffffff" })
+        .resize({
+        width: MIN_IMAGE_DIMENSION,
+        height: MIN_IMAGE_DIMENSION,
+        fit: "outside",
+        withoutEnlargement: false,
+    })
+        .jpeg({ quality: 92, mozjpeg: true, progressive: true, chromaSubsampling: "4:2:0" })
+        .toBuffer();
+    return { data: new Uint8Array(resized), filename: replaceExtension(filename, "jpg") };
+}

package/dist/image-edit-default.js

@@ -0,0 +1 @@
+export const DEFAULT_IMAGE_EDIT_MODEL_ID = "nano-banana-2-1";

package/dist/image-edit-models.js

@@ -0,0 +1,41 @@
+import { resolveModel } from "./media/descriptor.js";
+import { DEFAULT_IMAGE_EDIT_MODEL_ID } from "./image-edit-default.js";
+export { DEFAULT_IMAGE_EDIT_MODEL_ID } from "./image-edit-default.js";
+const STANDARD_IMAGE_EDIT_CAPABILITIES = {
+    semantic: true,
+    regionReplace: true,
+    wholeImage: true,
+    exactMask: false,
+};
+const EDIT_MODELS = [
+    { catalogModel: `kie:${DEFAULT_IMAGE_EDIT_MODEL_ID}`, label: "Nano Banana 2.1 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" },
+    { catalogModel: "kie:gpt-image-2-image-to-image", label: "GPT Image 2" },
+    { catalogModel: "fal:fal-ai/nano-banana-pro/edit", label: "Nano Banana Pro" },
+    { 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" },
+];
+function imageSlotMax(model) {
+    return model.slots.find((slot) => slot.role === "image")?.max ?? null;
+}
+function editModelInfo(entry) {
+    const model = resolveModel(entry.catalogModel);
+    const provider = model.provider === "fal" ? "fal" : "kie";
+    return {
+        id: model.apiId,
+        catalogModel: model.id,
+        label: entry.label,
+        provider,
+        envKey: provider === "fal" ? "FAL_API_KEY" : "KIE_API_KEY",
+        maxInputImages: imageSlotMax(model),
+        capabilities: STANDARD_IMAGE_EDIT_CAPABILITIES,
+    };
+}
+export const IMAGE_EDIT_MODELS = EDIT_MODELS.map(editModelInfo);
+export const IMAGE_EDIT_MODEL_IDS = IMAGE_EDIT_MODELS.map((model) => model.id);
+export function findImageEditModel(id) {
+    return IMAGE_EDIT_MODELS.find((model) => model.id === id || model.catalogModel === id);
+}

package/dist/image-edit-settings.js

@@ -0,0 +1,11 @@
+const SETTINGS_KEY = "image-edit-model-selection";
+export function readLastImageEditModel(engine) {
+    const stored = engine.settings.get(SETTINGS_KEY);
+    const modelId = stored?.modelId;
+    return typeof modelId === "string" && modelId.trim() ? modelId.trim() : null;
+}
+export function writeLastImageEditModel(engine, modelId) {
+    const written = engine.settings.set(SETTINGS_KEY, { modelId });
+    if (!written.ok)
+        throw new Error(written.error.message);
+}

package/dist/image-region-edit.js

@@ -0,0 +1,32 @@
+import sharp from "sharp";
+export function imageRegionEditPrompt(regions, operation, prompt) {
+    const targets = regions.map((box, index) => `Region ${index + 1}: normalized box x=${box.x.toFixed(6)}, y=${box.y.toFixed(6)}, width=${box.width.toFixed(6)}, height=${box.height.toFixed(6)}`);
+    const instruction = operation === "remove"
+        ? "Remove the contents of the selected regions and fill them naturally from the surrounding scene."
+        : prompt.trim();
+    return [
+        instruction,
+        "Apply the change only inside the following regions of the input image. Coordinates run from 0 to 1, starting at the top-left corner.",
+        ...targets,
+        "Keep the same image dimensions, composition and camera framing. Preserve everything outside the selected regions exactly.",
+    ].join("\n");
+}
+export async function compositeImageRegionEdit(original, generated, regions) {
+    const source = await sharp(original).rotate().png().toBuffer();
+    const { width, height } = await sharp(source).metadata();
+    if (!width || !height)
+        throw new Error("Could not determine source image dimensions");
+    const edited = await sharp(generated).rotate().resize(width, height, { fit: "fill" })
+        .png().toBuffer();
+    const overlays = await Promise.all(regions.map(async (box) => {
+        const left = Math.min(width - 1, Math.floor(box.x * width));
+        const top = Math.min(height - 1, Math.floor(box.y * height));
+        const right = Math.min(width, Math.max(left + 1, Math.ceil((box.x + box.width) * width)));
+        const bottom = Math.min(height, Math.max(top + 1, Math.ceil((box.y + box.height) * height)));
+        const input = await sharp(edited).extract({
+            left, top, width: right - left, height: bottom - top,
+        }).toBuffer();
+        return { input, left, top };
+    }));
+    return sharp(source).composite(overlays).png().toBuffer();
+}