@mevdragon/vidfarm-devcli 0.12.0 → 0.14.0

package/dist/src/cli.js

@@ -11,6 +11,7 @@ import { pipeline } from "node:stream/promises";
 import { computeCompositionGaps, insertMediaLayer, inspectComposition, replaceLayerWithMedia } from "./devcli/composition-edit.js";
 import { runCaptionsCommand } from "./devcli/captions.js";
 import { runClipsCommand } from "./devcli/clips.js";
+import { runTransitionsCommand } from "./devcli/transitions.js";
 import { MAX_LOCAL_TRANSCRIBE_AUDIO_BYTES, loadSpeechAudioLocally, localGenerateSpeech, localTranscribeSpeech, resolveLocalSpeechAuth } from "./devcli/speech.js";
 import { inferSpeechProviderForVoice } from "./services/speech.js";
 import { initTelemetry, reportCliCrash } from "./devcli/telemetry.js";
@@ -81,6 +82,9 @@ Discover & inspiration (browse the viral-video catalog, add your own source):
                             local MP4/MOV/WebM file — as a private        (files: presign + PUT via
                             template. --title (uploads; defaults to the    /discover/templates/upload)
                             template id), --tagline, --notes optional.
+                            --raw (uploads) marks it as your own raw
+                            project footage — the editor won't auto-
+                            prompt Decompose on it.
   inspiration-rm <id>       Delete a private inspiration/template you own → DELETE /discover/templates/:id
   inspiration-decompose <id>  AI-decompose an inspiration into scenes     → POST /api/v1/inspirations/:id/decompose
 
@@ -145,10 +149,15 @@ Generate AI media and drop it on the timeline (for local coding agents):
     --ken-burns-intensity <n>   Travel/zoom strength 0.04-0.5 (default 0.18)
     --transition <preset>   Scene transition INTO this clip (the previous
                             butt-cut clip is held beneath it automatically):
-                            crossfade|fade-black|slide-left|slide-right|
-                            slide-up|slide-down|wipe-left|wipe-right|wipe-up|
+                            crossfade|fade-black|fade-white|flash|smoke|blur|
+                            slide-left|slide-right|slide-up|slide-down|
+                            whip-left|whip-right|wipe-left|wipe-right|wipe-up|
                             wipe-down|zoom-in|zoom-out|circle-open
     --transition-duration <s>   Transition length in seconds 0.1-2.5 (default 0.5)
+    --transition-out <preset>   Exit transition OUT of this clip at its end:
+                            fade|fade-black|fade-white|flash|smoke|blur|
+                            slide-*|wipe-*|zoom-in|zoom-out|circle-close
+    --transition-out-duration <s>   Exit length in seconds 0.1-2.5 (default 0.5)
   remove-video-captions <forkId>   Read the two video sources:        → GET  .../compositions/:forkId/remove-video-captions
                             original vs decomposed (caption-free),
                             non-billing (alias: ghostcut)
@@ -204,6 +213,16 @@ Animated captions (word-by-word TikTok/CapCut styles on a pulled/served composit
   captions style <dir>      Restyle existing cues (same text/timings)
   captions list <dir>       Show the current animated caption cues [--json]
   captions clear <dir>      Remove all animated caption layers
+
+Scene transitions (between clips on a pulled/served composition — local file write):
+  transitions apply <dir>   One pass over the whole timeline:
+    --preset <p>              Junction preset at EVERY cut ("none" clears)
+    --duration <s>            0.1-2.5 (default 0.5)
+    --intro <p> --outro <p>   First clip's entrance / last clip's exit
+  transitions set <dir> --layer <key> --in <p> --out <p>   Configure one clip
+  transitions list <dir>    Show transitions on every scene clip [--json]
+  transitions clear <dir>   Remove all transitions
+                            (run 'vidfarm transitions' for presets & all flags)
   versions <forkId>         List immutable version snapshots             → GET  .../compositions/:forkId/versions
   snapshot <forkId>         Save the working state as a new version      → POST .../compositions/:forkId/versions
   render <forkId>           Render the fork to MP4 (--wait to poll)      → POST .../compositions/:forkId/render
@@ -248,15 +267,22 @@ Files (multi-step flows the devcli handles for you):
     --folder <path>         Namescope under a product/offer folder (e.g. acme-skincare)
     --as <name>             Name the saved file (required for --content/--stdin)
     --content <text>        Inline text to save (needs --as); or pipe stdin with --stdin
+    --notes <text>          Metadata notes (what it is / when to use it) — vector-embedded for search
                             e.g. vidfarm put-file About.md --folder acme-skincare
                                  echo "..." | vidfarm put-file --stdin --as About.md --folder acme
   download <url> [dest]     Stream any Vidfarm/media URL to disk
   files                     List My Files assets + folders               → GET /api/v1/user/me/attachments
     --folder <path>         Only files under this folder (e.g. a product/offer)
+    --search <query>        Find files by MEANING (keyword + vector over  → POST /api/v1/user/me/attachments/search
+                            name/folder/notes) instead of listing everything
   get-file <id> [dest]      Resolve a My Files id to its URL and download it
     --print                 Print text contents (md/txt/csv/json) instead of saving
-  put-file / get-file / files are the My Files (persistent) read+write set;
+  annotate-file <id|name>   Set metadata notes on one My Files entry     → PATCH /api/v1/user/me/attachments/:id
+    --notes <text>          The notes to attach (empty string clears); embedded for vector search
+  put-file / get-file / files / annotate-file are the My Files (persistent) set;
   upload is the throwaway temp store for dropping media into a composition.
+  Annotate assets you'll want back — esp. character refs (character_sprite_card.png
+  + about_character.md) — so 'files --search "the mascot"' finds them later.
   Local file paths: to avoid uploading assets to Vidfarm S3 at all, reference
   them straight from disk with 'place --src ./clip.mp4' on a 'serve' box (copied
   to that box's local disk store, free local render). When you DO need a durable
@@ -455,12 +481,18 @@ async function main() {
         case "save-file":
             await runPutFileCommand(rest);
             return;
+        case "annotate-file":
+            await runAnnotateFileCommand(rest);
+            return;
         case "clips":
             await runClipsCommand(rest);
             return;
         case "captions":
             await runCaptionsCommand(rest);
             return;
+        case "transitions":
+            await runTransitionsCommand(rest);
+            return;
         default:
             if (!command.startsWith("-")) {
                 // Positional template id → default to booting the local editor.
@@ -621,6 +653,11 @@ async function runServeCommand(argv) {
     // local-render by definition — cloud rendering is the EXPLICIT
     // render_target="cloud" upstream handoff (the editor's "Render in Cloud").
     process.env.VIDFARM_JOB_STATE_MACHINE_ARN = "";
+    // Same trap for clip hunts: a dev-shell .env carrying the staging clip-scan
+    // ARN would route this box's /clips/scan to the cloud Step Functions. serve
+    // hunts are LOCAL-FIRST (local agent CLI / BYOK keys); the upstream cloud is
+    // the explicit backup inside the scan route itself.
+    process.env.VIDFARM_CLIP_SCAN_STATE_MACHINE_ARN = "";
     // Same trap as the state machine ARN: a dev-shell .env can carry the staging
     // media-lambda URL, which would route probe/thumbnail/trim/etc. to a cloud
     // Lambda that cannot fetch this box's localhost storage URLs ("fetch
@@ -1265,7 +1302,7 @@ async function runVideosCommand(argv) {
     emitResult(result, ctx.json, [["Browse ", discoverFrontendUrl(ctx.host)]]);
 }
 async function runInspirationAddCommand(argv) {
-    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), title: { type: "string" }, tagline: { type: "string" }, notes: { type: "string" } } });
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), title: { type: "string" }, tagline: { type: "string" }, notes: { type: "string" }, raw: { type: "boolean", default: false } } });
     const source = parsed.positionals[0];
     if (!source)
         throw new Error("inspiration-add requires a video URL (TikTok/YouTube/Instagram/X) or a local video file path.");
@@ -1285,7 +1322,10 @@ async function runInspirationAddCommand(argv) {
             fileName: path.basename(localPath),
             title: parsed.values.title,
             tagline: parsed.values.tagline,
-            notes: parsed.values.notes
+            notes: parsed.values.notes,
+            // --raw: this is the user's own footage starting a new project, not an
+            // inspiration to study — the editor skips the auto Decompose prompt.
+            origin: parsed.values.raw ? "raw" : undefined
         });
         emitResult(result, ctx.json, [["Discover ", discoverFrontendUrl(ctx.host)]]);
         return;
@@ -1380,7 +1420,7 @@ async function ingestUploadedVideo(ctx, input) {
         host: ctx.host,
         path: "/discover/templates",
         auth: ctx.auth,
-        body: { upload: { storage_key: storageKey, file_name: uploadedName }, title: input.title, tagline: input.tagline, notes: input.notes }
+        body: { upload: { storage_key: storageKey, file_name: uploadedName }, title: input.title, tagline: input.tagline, notes: input.notes, origin: input.origin }
     });
     assertApiOk(result, "ingest");
     return result;
@@ -1555,7 +1595,10 @@ async function runCreateCommand(argv) {
         throw new Error(`create: could not fetch the generated video (${dl.status}).`);
     const buffer = Buffer.from(await dl.arrayBuffer());
     const title = parsed.values.title ?? prompt.slice(0, 80);
-    const add = await ingestUploadedVideo(ctx, { buffer, fileName: "generated.mp4", contentType: "video/mp4", title });
+    // origin:"raw" — a prompt-generated video is the user's own new project, not
+    // an imported inspiration; the editor must not auto-prompt Decompose (matters
+    // especially with --no-decompose).
+    const add = await ingestUploadedVideo(ctx, { buffer, fileName: "generated.mp4", contentType: "video/mp4", title, origin: "raw" });
     const inspirationId = add.json?.inspiration_id;
     if (!inspirationId)
         throw new Error("create: ingest did not return an inspiration id.");
@@ -2012,6 +2055,8 @@ function placeMediaOnDisk(input) {
         kenBurnsIntensity: input.kenBurnsIntensity,
         transition: input.transition,
         transitionDuration: input.transitionDuration,
+        transitionOut: input.transitionOut,
+        transitionOutDuration: input.transitionOutDuration,
         slug: input.slug
     };
     const result = input.replace
@@ -2045,6 +2090,8 @@ async function runGenerateCommand(argv) {
             "ken-burns-intensity": { type: "string" },
             transition: { type: "string" },
             "transition-duration": { type: "string" },
+            "transition-out": { type: "string" },
+            "transition-out-duration": { type: "string" },
             "layer-key": { type: "string" }
         }
     });
@@ -2120,6 +2167,8 @@ async function runGenerateCommand(argv) {
             kenBurnsIntensity: parsed.values["ken-burns-intensity"] ? Number(parsed.values["ken-burns-intensity"]) : undefined,
             transition: parsed.values.transition,
             transitionDuration: parsed.values["transition-duration"] ? Number(parsed.values["transition-duration"]) : undefined,
+            transitionOut: parsed.values["transition-out"],
+            transitionOutDuration: parsed.values["transition-out-duration"] ? Number(parsed.values["transition-out-duration"]) : undefined,
             layerKey: parsed.values["layer-key"]
         });
         if (!ctx.json)
@@ -2506,6 +2555,8 @@ async function runPlaceCommand(argv) {
             "ken-burns-intensity": { type: "string" },
             transition: { type: "string" },
             "transition-duration": { type: "string" },
+            "transition-out": { type: "string" },
+            "transition-out-duration": { type: "string" },
             "layer-key": { type: "string" },
             slug: { type: "string" },
             // Local file support: where a serve box serves /storage from, and which
@@ -2550,6 +2601,8 @@ async function runPlaceCommand(argv) {
         kenBurnsIntensity: num(parsed.values["ken-burns-intensity"]),
         transition: parsed.values.transition,
         transitionDuration: num(parsed.values["transition-duration"]),
+        transitionOut: parsed.values["transition-out"],
+        transitionOutDuration: num(parsed.values["transition-out-duration"]),
         layerKey: parsed.values["layer-key"],
         slug: parsed.values.slug
     });
@@ -2875,11 +2928,25 @@ async function runDownloadCommand(argv) {
 // This is the same filesystem the /editor AI agent browses via the browse_files
 // tool, so an agent CLI (Claude Code / Codex) can find assets the same way.
 async function runFilesCommand(argv) {
-    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), folder: { type: "string" } } });
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), folder: { type: "string" }, search: { type: "string" } } });
     const ctx = commonContext(parsed.values);
+    const folderFilter = parsed.values.folder ? String(parsed.values.folder).replace(/^\/+|\/+$/g, "") : undefined;
+    if (parsed.values.search) {
+        // Meaning-first lookup: keyword + vector search over every file's
+        // name/folder/notes (BYOK embeddings; keyword-only without a saved key).
+        const result = await apiRequest({
+            method: "POST",
+            host: ctx.host,
+            path: "/api/v1/user/me/attachments/search",
+            auth: ctx.auth,
+            body: { query: String(parsed.values.search), ...(folderFilter ? { folder_path: folderFilter } : {}) }
+        });
+        assertApiOk(result, "files --search");
+        emitResult(result, ctx.json);
+        return;
+    }
     const result = await apiRequest({ method: "GET", host: ctx.host, path: "/api/v1/user/me/attachments", auth: ctx.auth });
     assertApiOk(result, "files");
-    const folderFilter = parsed.values.folder ? String(parsed.values.folder).replace(/^\/+|\/+$/g, "") : undefined;
     if (folderFilter && result.json && Array.isArray(result.json.attachments)) {
         result.json = {
             ...result.json,
@@ -2888,6 +2955,34 @@ async function runFilesCommand(argv) {
     }
     emitResult(result, ctx.json);
 }
+// Attach metadata notes to one My Files entry (by id, or file name as a
+// fallback). Notes describe what the file IS and when to use it; the server
+// vector-embeds them so `files --search` finds the asset by meaning later —
+// the My Files analog of the clip library's semantic search.
+async function runAnnotateFileCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), notes: { type: "string" } } });
+    const fileRef = parsed.positionals[0];
+    if (!fileRef)
+        throw new Error("annotate-file requires a file id or name (run `files` to list ids).");
+    if (parsed.values.notes == null)
+        throw new Error("annotate-file requires --notes <text> (empty string clears existing notes).");
+    const ctx = commonContext(parsed.values);
+    const list = await apiRequest({ method: "GET", host: ctx.host, path: "/api/v1/user/me/attachments", auth: ctx.auth });
+    assertApiOk(list, "annotate-file");
+    const attachments = Array.isArray(list.json?.attachments) ? list.json.attachments : [];
+    const match = attachments.find((file) => file?.id === fileRef) ?? attachments.find((file) => file?.fileName === fileRef);
+    if (!match)
+        throw new Error(`No file with id or name "${fileRef}" in My Files. Run \`files\` to list ids.`);
+    const result = await apiRequest({
+        method: "PATCH",
+        host: ctx.host,
+        path: `/api/v1/user/me/attachments/${encodeURIComponent(match.id)}`,
+        auth: ctx.auth,
+        body: { notes: String(parsed.values.notes) }
+    });
+    assertApiOk(result, "annotate-file");
+    emitResult(result, ctx.json, [["Notes embedded", result.json?.notes_embedded ? "yes (vector-searchable)" : "no (keyword-searchable only — add a gemini/openai provider key to embed)"]]);
+}
 async function runGetFileCommand(argv) {
     const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), print: { type: "boolean", default: false } } });
     const fileId = parsed.positionals[0];
@@ -2941,6 +3036,7 @@ async function runPutFileCommand(argv) {
             folder: { type: "string" },
             as: { type: "string" },
             content: { type: "string" },
+            notes: { type: "string" },
             stdin: { type: "boolean", default: false }
         }
     });
@@ -2977,6 +3073,8 @@ async function runPutFileCommand(argv) {
     form.append("file", new Blob([new Uint8Array(buffer)], contentType ? { type: contentType } : undefined), fileName);
     if (parsed.values.folder)
         form.append("folder_path", String(parsed.values.folder));
+    if (parsed.values.notes)
+        form.append("notes", String(parsed.values.notes));
     const res = await fetch(new URL("/api/v1/user/me/attachments/upload", ctx.host), {
         method: "POST",
         headers: buildAuthHeaders(ctx.auth),

package/dist/src/composition-runtime.js

@@ -176,7 +176,10 @@ export const COMPOSITION_RUNTIME_SCRIPT_BODY = `
   // previous clip on its track — so that previous clip must stay active for
   // the transition window. Publish materializes this overlap into
   // data-duration (normalizePublishHtml); the preview grants it live so
-  // butt-cut drafts preview exactly like the render.
+  // butt-cut drafts preview exactly like the render. A [data-transition-out]
+  // clip additionally animates AWAY (vf-tr-out-* keyframes) over its last
+  // data-transition-out-duration seconds — no hold needed, the exit window
+  // lives inside the clip's own span.
   function collectTransitionWindows() {
     const windows = [];
     for (const clip of clips) {
@@ -210,8 +213,26 @@ export const COMPOSITION_RUNTIME_SCRIPT_BODY = `
     return hold;
   }
 
-  function syncTransitionClip(clip, timing) {
+  function syncTransitionClip(clip, timing, hold) {
     if (typeof clip.getAnimations !== "function") return;
+    // Exit animations sit at the clip's tail via the inline --vf-tr-out-delay
+    // var. Timeline edits touch data-duration only, so re-derive the delay
+    // (duration + any live hold − out duration) before scrubbing; publish
+    // materializes the same value for the render producer.
+    if (clip.hasAttribute("data-transition-out")) {
+      let outDuration = Number(clip.getAttribute("data-transition-out-duration"));
+      if (!Number.isFinite(outDuration) || outDuration <= 0) outDuration = 0.5;
+      outDuration = Math.min(outDuration, timing.duration);
+      const expectedDelay = Math.max(0, timing.duration + (hold || 0) - outDuration);
+      try {
+        if (Math.abs((parseFloat(clip.style.getPropertyValue("--vf-tr-out-dur")) || 0) - outDuration) > 0.002) {
+          clip.style.setProperty("--vf-tr-out-dur", outDuration.toFixed(3) + "s");
+        }
+        if (Math.abs((parseFloat(clip.style.getPropertyValue("--vf-tr-out-delay")) || 0) - expectedDelay) > 0.002) {
+          clip.style.setProperty("--vf-tr-out-delay", expectedDelay.toFixed(3) + "s");
+        }
+      } catch {}
+    }
     const offsetMs = Math.max(0, (time - timing.start)) * 1000;
     let anims = [];
     try { anims = clip.getAnimations({ subtree: true }); } catch { return; }
@@ -229,16 +250,65 @@ export const COMPOSITION_RUNTIME_SCRIPT_BODY = `
   // Burns there is nothing to normalize — the scrub is simply the absolute
   // offset into the layer. Paused-by-stylesheet + scrubbed-here matches the
   // render producer's CSS adapter exactly.
+  //
+  // Stability: Chrome PERMANENTLY drops a paused fill:none CSS animation the
+  // moment its currentTime is pushed past the effect end, and never re-creates
+  // it while the computed animation-name is unchanged — so one forward scrub
+  // across a word's window would leave that word stuck in its resting state
+  // (invisible for word-pop/stack-up) on every later frame. Past the end, a
+  // parked fill:none animation looks identical to the resting styles, so park
+  // at 0 instead of overshooting. fill:forwards presets (karaoke-fill,
+  // cumulative-reveal) must overshoot to hold their final keyframe — finished
+  // + forwards animations keep applying their effect and survive. If a word's
+  // animation is missing anyway (dropped before this guard, or an innerHTML
+  // morph replaced the spans mid-scrub), restart it declaratively by cycling
+  // animation-name through none.
+  function captionWordAnimationFor(word) {
+    let anims = [];
+    try { anims = word.getAnimations(); } catch { return null; }
+    for (const anim of anims) {
+      if (typeof anim.animationName === "string" && anim.animationName.indexOf("vf-cap-") === 0) return anim;
+    }
+    return null;
+  }
+
   function syncCaptionClip(clip, timing) {
     if (typeof clip.getAnimations !== "function") return;
     const offsetMs = Math.max(0, (time - timing.start)) * 1000;
-    let anims = [];
-    try { anims = clip.getAnimations({ subtree: true }); } catch { return; }
-    for (const anim of anims) {
-      if (typeof anim.animationName !== "string" || anim.animationName.indexOf("vf-cap-") !== 0) continue;
+    let words = [];
+    try { words = Array.from(clip.querySelectorAll('[data-cap-word="true"]')); } catch { return; }
+    for (const word of words) {
+      if (typeof word.getAnimations !== "function") continue;
+      let anim = captionWordAnimationFor(word);
+      if (!anim) {
+        const inlineEndMs =
+          ((parseFloat(word.style.animationDelay) || 0) + (parseFloat(word.style.animationDuration) || 0)) * 1000;
+        let needed = offsetMs <= inlineEndMs;
+        if (!needed) {
+          try { needed = getComputedStyle(word).animationFillMode.indexOf("forward") !== -1 || getComputedStyle(word).animationFillMode.indexOf("both") !== -1; } catch {}
+        }
+        if (!needed) continue;
+        try {
+          word.style.animationName = "none";
+          void word.offsetWidth;
+          word.style.removeProperty("animation-name");
+        } catch { continue; }
+        anim = captionWordAnimationFor(word);
+        if (!anim) continue;
+      }
+      let target = offsetMs;
+      try {
+        const computed = anim.effect && typeof anim.effect.getComputedTiming === "function"
+          ? anim.effect.getComputedTiming()
+          : null;
+        if (computed && typeof computed.endTime === "number" && offsetMs >= computed.endTime
+            && computed.fill !== "forwards" && computed.fill !== "both") {
+          target = 0;
+        }
+      } catch {}
       try {
         anim.pause();
-        anim.currentTime = offsetMs;
+        anim.currentTime = target;
       } catch {}
     }
   }
@@ -261,7 +331,7 @@ export const COMPOSITION_RUNTIME_SCRIPT_BODY = `
         }
         if (clip.hasAttribute("data-kenburns")) syncKenBurnsClip(clip, timing);
         if (clip.hasAttribute("data-caption-animation")) syncCaptionClip(clip, timing);
-        if (clip.hasAttribute("data-transition")) syncTransitionClip(clip, timing);
+        if (clip.hasAttribute("data-transition") || clip.hasAttribute("data-transition-out")) syncTransitionClip(clip, timing, hold);
       }
       if (clip instanceof HTMLMediaElement) {
         applyMediaState(clip);
@@ -369,7 +439,16 @@ export const COMPOSITION_RUNTIME_SCRIPT_BODY = `
       return playbackRate;
     },
     setMuted,
-    refreshClips
+    refreshClips,
+    // Re-scrub caption word animations at the current playhead without a full
+    // apply(). The editor calls this after live-patching a caption layer's
+    // DOM (style/text edits rebuild the word spans, whose fresh CSS-paused
+    // animations sit at currentTime 0 — resting/invisible — until scrubbed).
+    syncCaptions() {
+      for (const clip of Array.from(document.querySelectorAll("[data-caption-animation]"))) {
+        if (clip instanceof HTMLElement) syncCaptionClip(clip, readTiming(clip));
+      }
+    }
   };
 
   refreshClips();

package/dist/src/devcli/clips.js

@@ -166,6 +166,9 @@ async function runScan(argv) {
     const guidance = buildEffectiveGuidance({ contentPrompt: guidancePromptRaw, avoidText }) || undefined;
     // ── BACKUP path: run the hunt on the deployed pipeline (--cloud) ──────────
     if (values.cloud) {
+        const apiProvider = values.provider && !["agent", "local", "local-agent"].includes(values.provider)
+            ? normalizeProvider(values.provider)
+            : undefined; // unset → the cloud auto-picks from the account's saved keys
         return runScanCloud({
             videoArg: positionals[0],
             sourceUrl: values.url?.trim() || undefined,
@@ -173,6 +176,7 @@ async function runScan(argv) {
             apiKey: values["api-key"],
             tracer: values.tracer,
             prompt: guidancePromptRaw,
+            provider: apiProvider,
             windows: rawWindows,
             durationBand,
             aspect,
@@ -431,6 +435,7 @@ async function runScanCloud(input) {
         body: JSON.stringify({
             ...(input.sourceUrl ? { source_url: input.sourceUrl } : { temp_file_id: tempFileId, filename: fileName }),
             prompt: input.prompt ?? "",
+            ...(input.provider ? { provider: input.provider } : {}),
             ...(input.tracer ? { tracer: input.tracer } : {}),
             hunt_spec: {
                 ...(input.windows.length ? { windows: input.windows } : {}),

package/dist/src/devcli/composition-edit.js

@@ -6,14 +6,14 @@
 // pushes them identically to a browser-made edit. Pure DOM (linkedom) — no
 // ffmpeg, no network.
 import { parseHTML } from "linkedom";
-import { CAPTION_ANIMATIONS, CAPTION_STYLE_PRESETS, captionStylePresetById, estimateCaptionWords, renderHyperframeLayerHtml } from "../hyperframes/composition.js";
+import { CAPTION_ANIMATIONS, CAPTION_STYLE_PRESETS, TRANSITION_OUT_PRESETS, TRANSITION_PRESETS, captionStylePresetById, clampTransitionDuration, estimateCaptionWords, renderHyperframeLayerHtml, transitionOutDelaySeconds } from "../hyperframes/composition.js";
 const KEN_BURNS_PRESETS = new Set([
     "zoom-in", "zoom-out", "pan-left", "pan-right", "pan-up", "pan-down", "zoom-in-left", "zoom-in-right"
 ]);
-const TRANSITION_PRESET_SET = new Set([
-    "crossfade", "fade-black", "slide-left", "slide-right", "slide-up", "slide-down",
-    "wipe-left", "wipe-right", "wipe-up", "wipe-down", "zoom-in", "zoom-out", "circle-open"
-]);
+// Preset vocabulary comes straight from the canonical source so the devcli can
+// never drift from the stylesheet.
+const TRANSITION_PRESET_SET = new Set(TRANSITION_PRESETS);
+const TRANSITION_OUT_PRESET_SET = new Set(TRANSITION_OUT_PRESETS);
 const round3 = (v) => Number(v.toFixed(3));
 const clampPercent = (v) => Math.min(100, Math.max(0, v));
 function serialize(document) {
@@ -231,13 +231,19 @@ function buildMediaClip(document, opts, id, track, geom) {
         // picks the keyframes; data-transition-duration + --vf-tr-dur set the span.
         // The overlap with the previous clip is granted by the runtime/publish
         // normalizer — the stored timeline stays butt-cut.
-        const transitionDuration = Number.isFinite(opts.transitionDuration) && opts.transitionDuration > 0
-            ? Math.max(0.1, Math.min(2.5, opts.transitionDuration))
-            : 0.5;
+        const transitionDuration = clampTransitionDuration(opts.transitionDuration ?? 0.5);
         node.setAttribute("data-transition", opts.transition);
         node.setAttribute("data-transition-duration", String(round3(transitionDuration)));
         styles.push(`--vf-tr-dur:${round3(transitionDuration)}s`);
     }
+    if (opts.transitionOut && TRANSITION_OUT_PRESET_SET.has(opts.transitionOut)) {
+        // Exit transition: the inline --vf-tr-out-delay (clip duration − out
+        // duration) parks the animation window at the clip's tail.
+        const outDuration = clampTransitionDuration(opts.transitionOutDuration ?? 0.5);
+        node.setAttribute("data-transition-out", opts.transitionOut);
+        node.setAttribute("data-transition-out-duration", String(round3(outDuration)));
+        styles.push(`--vf-tr-out-dur:${round3(outDuration)}s`, `--vf-tr-out-delay:${transitionOutDelaySeconds(geom.duration, outDuration)}s`);
+    }
     node.setAttribute("style", `${styles.join(";")};`);
     return node;
 }
@@ -438,4 +444,166 @@ export function replaceLayerWithMedia(html, targetKey, opts) {
     void targetId;
     return { html: serialize(document), layerKey: id };
 }
+function upsertStyleDecl(node, name, value) {
+    const styleValue = node.getAttribute("style") || "";
+    const escaped = name.replace(/[.*+?^${}()|[\]\\-]/g, "\\$&");
+    const pattern = new RegExp(`(^|;)\\s*${escaped}\\s*:[^;]*`, "i");
+    let nextStyle;
+    if (value === null) {
+        nextStyle = styleValue.replace(pattern, (_match, lead) => lead);
+    }
+    else if (pattern.test(styleValue)) {
+        nextStyle = styleValue.replace(pattern, (_match, lead) => `${lead}${name}:${value}`);
+    }
+    else {
+        nextStyle = styleValue.length === 0 || styleValue.endsWith(";")
+            ? `${styleValue}${name}:${value}`
+            : `${styleValue};${name}:${value}`;
+    }
+    if (nextStyle !== styleValue)
+        node.setAttribute("style", nextStyle);
+}
+// Scene clips are what junction transitions connect: video/image layers and
+// timeline proxies. Audio, captions, text overlays and the backing source
+// video are excluded (same filter as the editor's timeline chips).
+function isSceneClipNode(node) {
+    if (node?.hasAttribute?.("data-vf-playback-source"))
+        return false;
+    const tag = String(node?.tagName || "").toLowerCase();
+    if (tag === "audio")
+        return false;
+    const kind = node?.getAttribute?.("data-layer-kind");
+    return tag === "video" || tag === "img"
+        || node?.getAttribute?.("data-vf-timeline-proxy") === "video"
+        || kind === "video" || kind === "image";
+}
+function setNodeTransition(node, preset, durationSeconds) {
+    if (!preset || preset === "none") {
+        node.removeAttribute("data-transition");
+        node.removeAttribute("data-transition-duration");
+        upsertStyleDecl(node, "--vf-tr-dur", null);
+        return;
+    }
+    if (!TRANSITION_PRESET_SET.has(preset)) {
+        throw new Error(`Unknown transition preset "${preset}". Use one of: none, ${TRANSITION_PRESETS.join(", ")}.`);
+    }
+    const current = Number.parseFloat(node.getAttribute("data-transition-duration") ?? "");
+    const duration = clampTransitionDuration(durationSeconds ?? (Number.isFinite(current) ? current : undefined));
+    node.setAttribute("data-transition", preset);
+    node.setAttribute("data-transition-duration", String(round3(duration)));
+    upsertStyleDecl(node, "--vf-tr-dur", `${round3(duration)}s`);
+}
+function setNodeTransitionOut(node, preset, durationSeconds) {
+    if (!preset || preset === "none") {
+        node.removeAttribute("data-transition-out");
+        node.removeAttribute("data-transition-out-duration");
+        upsertStyleDecl(node, "--vf-tr-out-dur", null);
+        upsertStyleDecl(node, "--vf-tr-out-delay", null);
+        return;
+    }
+    if (!TRANSITION_OUT_PRESET_SET.has(preset)) {
+        throw new Error(`Unknown exit transition preset "${preset}". Use one of: none, ${TRANSITION_OUT_PRESETS.join(", ")}.`);
+    }
+    const current = Number.parseFloat(node.getAttribute("data-transition-out-duration") ?? "");
+    const duration = clampTransitionDuration(durationSeconds ?? (Number.isFinite(current) ? current : undefined));
+    const layerDuration = numAttr(node, "data-duration");
+    node.setAttribute("data-transition-out", preset);
+    node.setAttribute("data-transition-out-duration", String(round3(duration)));
+    upsertStyleDecl(node, "--vf-tr-out-dur", `${round3(duration)}s`);
+    upsertStyleDecl(node, "--vf-tr-out-delay", `${transitionOutDelaySeconds(Number.isFinite(layerDuration) ? layerDuration : 0, duration)}s`);
+}
+// Bulk pass over the whole timeline — the devcli twin of the AI's
+// set_transitions action and the editor's junction chips.
+export function applyTransitionsAcross(html, opts) {
+    if (opts.junction === undefined && opts.intro === undefined && opts.outro === undefined) {
+        throw new Error("applyTransitionsAcross needs a junction preset, an intro, and/or an outro.");
+    }
+    const { document, root } = readCompositionDoc(html);
+    const scenes = collectClips(root).filter(isSceneClipNode).map((node) => ({
+        node,
+        start: numAttr(node, "data-start") || 0,
+        duration: numAttr(node, "data-duration") || 0,
+        track: numAttr(node, "data-track-index") || 0
+    })).sort((a, b) => (a.start - b.start) || (a.track - b.track));
+    if (!scenes.length)
+        throw new Error("No scene clips (video/image layers) found in the composition.");
+    const firstByTrack = new Map();
+    for (const scene of scenes) {
+        const first = firstByTrack.get(scene.track);
+        if (!first || scene.start < first.start)
+            firstByTrack.set(scene.track, scene);
+    }
+    let junctions = 0;
+    if (opts.junction !== undefined) {
+        for (const scene of scenes) {
+            if (firstByTrack.get(scene.track) === scene)
+                continue;
+            setNodeTransition(scene.node, opts.junction, opts.duration);
+            junctions += 1;
+        }
+    }
+    const firstScene = scenes[0];
+    const lastScene = scenes.reduce((latest, scene) => (scene.start + scene.duration > latest.start + latest.duration ? scene : latest), scenes[0]);
+    if (opts.intro !== undefined && firstScene) {
+        setNodeTransition(firstScene.node, opts.intro, opts.duration);
+    }
+    if (opts.outro !== undefined && lastScene) {
+        setNodeTransitionOut(lastScene.node, opts.outro, opts.outroDuration ?? opts.duration);
+    }
+    return {
+        html: serialize(document),
+        junctions,
+        intro: opts.intro !== undefined && opts.intro !== "none" && opts.intro !== null,
+        outro: opts.outro !== undefined && opts.outro !== "none" && opts.outro !== null
+    };
+}
+// Per-layer control — the devcli twin of set_layer_media's transition fields.
+export function setLayerTransitions(html, layerKey, opts) {
+    if (opts.transition === undefined && opts.transitionOut === undefined) {
+        throw new Error("setLayerTransitions needs --in and/or --out.");
+    }
+    const { document, root } = readCompositionDoc(html);
+    const node = resolveLayerNode(root, layerKey);
+    if (!node)
+        throw new Error(`Layer not found: ${layerKey}`);
+    if (!isSceneClipNode(node) && String(node.tagName || "").toLowerCase() === "audio") {
+        throw new Error("Transitions cannot be applied to audio layers.");
+    }
+    if (opts.transition !== undefined)
+        setNodeTransition(node, opts.transition, opts.transitionDuration);
+    if (opts.transitionOut !== undefined)
+        setNodeTransitionOut(node, opts.transitionOut, opts.transitionOutDuration);
+    return { html: serialize(document), layerKey: node.getAttribute("data-hf-id") || node.id || layerKey };
+}
+export function clearAllTransitions(html) {
+    const { document, root } = readCompositionDoc(html);
+    let cleared = 0;
+    for (const node of collectClips(root)) {
+        const had = node.hasAttribute("data-transition") || node.hasAttribute("data-transition-out");
+        if (!had)
+            continue;
+        setNodeTransition(node, null);
+        setNodeTransitionOut(node, null);
+        cleared += 1;
+    }
+    return { html: serialize(document), cleared };
+}
+export function readTransitions(html) {
+    const { root } = readCompositionDoc(html);
+    return collectClips(root).filter(isSceneClipNode).map((node) => {
+        const duration = Number.parseFloat(node.getAttribute("data-transition-duration") ?? "");
+        const outDuration = Number.parseFloat(node.getAttribute("data-transition-out-duration") ?? "");
+        return {
+            layerKey: node.getAttribute("data-hf-id") || node.id || "",
+            label: node.getAttribute("data-label"),
+            track: numAttr(node, "data-track-index") || 0,
+            start: numAttr(node, "data-start") || 0,
+            duration: numAttr(node, "data-duration") || 0,
+            transition: node.getAttribute("data-transition"),
+            transition_duration: Number.isFinite(duration) ? duration : null,
+            transition_out: node.getAttribute("data-transition-out"),
+            transition_out_duration: Number.isFinite(outDuration) ? outDuration : null
+        };
+    }).sort((a, b) => (a.start - b.start) || (a.track - b.track));
+}
 //# sourceMappingURL=composition-edit.js.map