@mevdragon/vidfarm-devcli 0.11.0 → 0.13.0

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,9 +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";
 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"
+]);
 const round3 = (v) => Number(v.toFixed(3));
 const clampPercent = (v) => Math.min(100, Math.max(0, v));
 function serialize(document) {
@@ -221,6 +226,18 @@ function buildMediaClip(document, opts, id, track, geom) {
             styles.push(`--vf-kb-amount:${Math.max(0.04, Math.min(0.5, opts.kenBurnsIntensity))}`);
         }
     }
+    if (opts.transition && TRANSITION_PRESET_SET.has(opts.transition)) {
+        // Scene transition (see src/hyperframes/composition.ts): data-transition
+        // 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;
+        node.setAttribute("data-transition", opts.transition);
+        node.setAttribute("data-transition-duration", String(round3(transitionDuration)));
+        styles.push(`--vf-tr-dur:${round3(transitionDuration)}s`);
+    }
     node.setAttribute("style", `${styles.join(";")};`);
     return node;
 }
@@ -254,6 +271,131 @@ export function insertMediaLayer(html, opts) {
     root.append(node);
     return { html: serialize(document), layerKey: id };
 }
+const CAPTION_DEFAULT_FRAME = { x: 10, y: 70, width: 80, height: 14 };
+function resolveCaptionLook(opts) {
+    const preset = captionStylePresetById(opts.style)
+        ?? (opts.animation ? null : CAPTION_STYLE_PRESETS[0]);
+    const animation = (opts.animation ?? preset?.animation);
+    if (!animation || !CAPTION_ANIMATIONS.includes(animation)) {
+        throw new Error(`Unknown caption animation "${opts.animation ?? opts.style}". Use a preset (${CAPTION_STYLE_PRESETS.map((p) => p.id).join(", ")}) or an animation (${CAPTION_ANIMATIONS.join(", ")}).`);
+    }
+    return {
+        animation,
+        activeColor: opts.activeColor ?? preset?.activeColor,
+        highlightColor: opts.highlightColor ?? preset?.highlightColor,
+        uppercase: opts.uppercase ?? preset?.uppercase,
+        color: opts.color ?? preset?.color ?? "#ffffff",
+        background: opts.background ?? preset?.background ?? "#000000",
+        backgroundStyle: (opts.backgroundStyle ?? preset?.textBackgroundStyle ?? "plain"),
+        fontFamily: opts.fontFamily ?? "Montserrat",
+        fontWeight: opts.fontWeight ?? preset?.fontWeight ?? 800,
+        fontSize: opts.fontSize ?? 38,
+        presetId: preset?.id ?? animation
+    };
+}
+/** Read the animated-caption cues already in a composition (for restyle/list). */
+export function readCaptionCues(html) {
+    const { root } = readCompositionDoc(html);
+    return Array.from(root.querySelectorAll("[data-caption-animation]")).map((node) => {
+        const words = Array.from(node.querySelectorAll("[data-cap-word]"))
+            .map((span) => ({
+            text: String(span.textContent || "").trim(),
+            start: Number.parseFloat(span.getAttribute("data-word-start") ?? "") || 0,
+            end: Number.parseFloat(span.getAttribute("data-word-end") ?? "") || 0
+        }))
+            .filter((word) => word.text);
+        return {
+            layerKey: node.getAttribute("data-hf-id") || node.id || "",
+            track: Number.isFinite(numAttr(node, "data-track-index")) ? numAttr(node, "data-track-index") : 0,
+            text: words.length ? words.map((word) => word.text).join(" ") : String(node.textContent || "").trim(),
+            start: Number.isFinite(numAttr(node, "data-start")) ? numAttr(node, "data-start") : 0,
+            duration: Number.isFinite(numAttr(node, "data-duration")) ? numAttr(node, "data-duration") : 0,
+            words: words.length ? words : undefined
+        };
+    });
+}
+/** Remove every animated-caption layer. Returns the count removed. */
+export function clearCaptionLayers(html) {
+    const { document, root } = readCompositionDoc(html);
+    const nodes = Array.from(root.querySelectorAll("[data-caption-animation]"));
+    for (const node of nodes)
+        node.parentNode?.removeChild(node);
+    return { html: serialize(document), removed: nodes.length };
+}
+/**
+ * Insert an animated-caption cue run: one caption layer per cue on a shared
+ * collision-free track. Replaces any existing animated captions (set
+ * semantics — matching the editor's set_captions action).
+ */
+export function insertCaptionLayers(html, cues, opts = {}) {
+    const usable = cues
+        .filter((cue) => cue.text?.trim() && Number.isFinite(cue.start) && Number.isFinite(cue.duration) && cue.duration > 0)
+        .sort((a, b) => a.start - b.start);
+    if (!usable.length)
+        throw new Error("insertCaptionLayers needs at least one cue with text, start, and duration.");
+    const look = resolveCaptionLook(opts);
+    const { document, root } = readCompositionDoc(html);
+    const existing = Array.from(root.querySelectorAll("[data-caption-animation]"));
+    for (const node of existing)
+        node.parentNode?.removeChild(node);
+    const clips = collectClips(root);
+    const runStart = usable[0].start;
+    const runEnd = usable.reduce((max, cue) => Math.max(max, cue.start + cue.duration), runStart);
+    const initialTrack = opts.track !== undefined && Number.isFinite(opts.track)
+        ? Math.max(0, Math.floor(opts.track))
+        : nextAutoTrack(clips);
+    const track = findNonCollidingTrack(clips, { start: runStart, duration: Math.max(0.1, runEnd - runStart), track: initialTrack }, "");
+    const stamp = Date.now().toString(36);
+    const layerKeys = [];
+    usable.forEach((cue, index) => {
+        const id = `element_cap_${stamp}_${index}`;
+        layerKeys.push(id);
+        const layer = {
+            id,
+            kind: "caption",
+            label: cue.text.slice(0, 48),
+            start: cue.start,
+            duration: cue.duration,
+            track,
+            z: track,
+            x: opts.x ?? CAPTION_DEFAULT_FRAME.x,
+            y: opts.y ?? CAPTION_DEFAULT_FRAME.y,
+            width: opts.width ?? CAPTION_DEFAULT_FRAME.width,
+            height: opts.height ?? CAPTION_DEFAULT_FRAME.height,
+            text: cue.text,
+            color: look.color,
+            background: look.background,
+            textBackgroundStyle: look.backgroundStyle,
+            fontFamily: look.fontFamily,
+            fontWeight: look.fontWeight,
+            fontSize: look.fontSize,
+            captionAnimation: {
+                animation: look.animation,
+                words: cue.words?.length ? cue.words : estimateCaptionWords(cue.text, cue.duration),
+                activeColor: look.activeColor,
+                highlightColor: look.highlightColor,
+                uppercase: look.uppercase
+            }
+        };
+        const container = document.createElement("div");
+        container.innerHTML = renderHyperframeLayerHtml(layer);
+        const node = container.firstElementChild;
+        if (!node)
+            throw new Error(`Failed to render caption cue ${index}.`);
+        node.classList?.add?.("clip");
+        root.append(node);
+    });
+    return { html: serialize(document), layerKeys, replaced: existing.length, styleId: look.presetId };
+}
+/** Restyle existing animated captions in place: same cues/timings/track, new look. */
+export function restyleCaptionLayers(html, opts) {
+    const cues = readCaptionCues(html);
+    if (!cues.length)
+        throw new Error("No animated caption layers found. Run `captions generate` (or add captions in the editor) first.");
+    const track = opts.track ?? cues[0].track;
+    const result = insertCaptionLayers(html, cues, { ...opts, track });
+    return { html: result.html, layerKeys: result.layerKeys, styleId: result.styleId };
+}
 // Replace an existing scene/layer with a generated media clip, taking over its
 // timing + geometry (full-canvas when it was a proxy / full-canvas fill).
 export function replaceLayerWithMedia(html, targetKey, opts) {

package/dist/src/devcli/speech.js

@@ -79,7 +79,9 @@ export async function localGenerateSpeech(input) {
     });
     return { ...result, provider: input.auth.provider, model };
 }
-/** Local STT: audio bytes → transcript (diarized on gemini) on the user's own key. */
+/** Local STT: audio bytes → transcript (diarized on gemini) on the user's own key.
+ * wordTimestamps requests word-level timings (real on openai/whisper-1; other
+ * providers stay segment-level and downstream callers estimate word windows). */
 export async function localTranscribeSpeech(input) {
     const model = input.model?.trim() || defaultSpeechModelFor("stt", input.auth.provider);
     if (!model) {
@@ -93,6 +95,7 @@ export async function localTranscribeSpeech(input) {
         prompt: input.prompt,
         language: input.language,
         diarize: input.diarize,
+        wordTimestamps: input.wordTimestamps,
         apiKey: input.auth.apiKey
     });
     return { ...result, provider: input.auth.provider, model, srt: buildSrtFromSegments(result.segments) };

package/dist/src/editor-chat.js

@@ -42,7 +42,7 @@ export function buildTemplateEditorChatSystemPrompt(input) {
         "If the user asks to modify an attached image and the message includes an attachment URL, call POST /api/v1/primitives/images/edit with source_image_url inside payload set to that exact URL and instruction inside payload set to the requested edit.",
         "If the user asks to generate a new AI video from text or reference images, call POST /api/v1/primitives/videos/generate with body { tracer, payload: { prompt, input_references?, duration? } }. AI video duration is seconds; use duration: 4 for a 4-second video and never use duration_ms on /videos/generate. input_references must be direct image asset URLs, not webpage or social post URLs. Use frame_images for exact first/last-frame image-to-video.",
         "If the user asks to render HTML/design into an image, call POST /api/v1/primitives/images/render-html. If the user asks to turn existing media URLs into a slideshow/video, call POST /api/v1/primitives/videos/render-slides. If the user asks to dedupe, camouflage, or apply small zoom/tilt/rotate/filter/tint transforms to an image or video for reuse, call POST /api/v1/primitives/media/dedupe with body { tracer, payload: { source_media_url, media_type?, effects?: { zoom?, tilt?, rotate?, saturation?, speed?, horizontal_flip?, contrast?, brightness?, hue_rotate?, blur? }, tint_color?, tint_opacity?, width?, height?, duration_ms?, object_fit?, background_color?, output_format? }, webhook_url? }. Primitive media utility routes are also allowed directly here, including /videos/trim, /videos/remove-captions, /videos/extract-audio, /videos/probe, /videos/extract-frame, /videos/mute, /videos/replace-audio, /videos/concat, /audio/trim, /audio/probe, /audio/concat, and /audio/normalize. If the user asks to remove burned-in captions, subtitles, or on-screen text from a video, call POST /api/v1/primitives/videos/remove-captions with body { tracer, payload: { source_video_url } } — an async job that returns a durable caption-free MP4 and bills about $0.10 per 30 seconds of source video. Caption removal is capped at ~15 minutes of source and must NEVER be used on long-form video: when the user wants short clips out of a long video (a podcast, stream VOD, webinar, or a YouTube/TikTok/IG/X URL), call POST /clips/scan instead with body { source_url | temp_file_id | s3_key, prompt, ranges?: [\"MM:SS-MM:SS\"], target_duration_sec?, aspect?: \"9:16\"|\"16:9\"|\"4:3\"|\"1:1\", avoid_text?, tracer? } — target_duration_sec is a SOFT range (30 → 20-40s), ranges restrict the hunt to those source windows (big cost saver), aspect crops every clip, and avoid_text prefers text-free scenes via scene SELECTION (never caption removal on the source). The hunt is async (202 + scan_id): poll GET /clips/scan/:scanId, then browse GET /clips/feed?source=<source_video_id> or POST /clips/search. Hunts bill AWS compute only — the AI tagging runs on the user's own saved provider keys. To erase captions from a finished HUNTED clip, pass that short mp4 to /videos/remove-captions afterwards.",
-        "SPEECH PRIMITIVES (TTS/STT) are first-class here. VOICEOVER / NARRATION: when the user wants a script, hook, caption, or dub read aloud as AI audio, call POST /api/v1/primitives/audio/speech with body { tracer, payload: { text, voice?, instructions?, provider?, model?, output_format? } } — instructions is a free-form voice-STYLE prompt (tone, pacing, accent, emotion, persona; e.g. 'calm warm bedtime narrator' or 'excited sports announcer, fast paced'), and voice picks a provider preset (OpenAI: alloy/ash/coral/...; Gemini: Kore/Puck/Charon/...). The finished job returns a durable audio URL — place it on the timeline with editor_action add_layer (kind=audio, src=that URL), typically starting where the narration should begin. TRANSCRIPTION: when the user wants a transcript, subtitles/captions from speech, a translation source, or to know who says what, call POST /api/v1/primitives/audio/transcribe with body { tracer, payload: { source_url, diarize?, language?, prompt? } } — source_url may be a VIDEO or AUDIO URL (video audio is demuxed automatically; pick the fork's source via GET /api/v1/compositions/:forkId/remove-video-captions first when transcribing the current composition). One job returns BOTH formats: a simple subtitle version (plain transcript text + timed SRT cues, stored as transcript.txt/transcript.srt) and an advanced multi-speaker version (speaker-attributed timed segments in output.segments and transcript.json) for multi-narration sources like podcasts and interviews. diarize defaults to true and speaker attribution needs a Gemini key — openai/openrouter keys degrade to a plain single-speaker transcript. For transcript-grounded caption work on THIS fork, the read-only video_context tool may already contain the decompose-time transcript; prefer it before running a new billable-key transcription, and use /audio/transcribe for other URLs, multi-speaker attribution, or SRT output.",
+        "SPEECH PRIMITIVES (TTS/STT) are first-class here. VOICEOVER / NARRATION: when the user wants a script, hook, caption, or dub read aloud as AI audio, call POST /api/v1/primitives/audio/speech with body { tracer, payload: { text, voice?, instructions?, provider?, model?, output_format? } } — instructions is a free-form voice-STYLE prompt (tone, pacing, accent, emotion, persona; e.g. 'calm warm bedtime narrator' or 'excited sports announcer, fast paced'), and voice picks a provider preset (OpenAI: alloy/ash/coral/...; Gemini: Kore/Puck/Charon/...). When sending a voice you may omit provider — it is inferred from the voice preset; a voice paired with the WRONG provider (e.g. voice 'Kore' with provider 'openai') is rejected with a 400, so never mix families. The finished job returns a durable audio URL — place it on the timeline with editor_action add_layer (kind=audio, src=that URL), typically starting where the narration should begin. TRANSCRIPTION: when the user wants a transcript, subtitles/captions from speech, a translation source, or to know who says what, call POST /api/v1/primitives/audio/transcribe with body { tracer, payload: { source_url, diarize?, language?, prompt? } } — source_url may be a VIDEO or AUDIO URL (video audio is demuxed automatically; pick the fork's source via GET /api/v1/compositions/:forkId/remove-video-captions first when transcribing the current composition). One job returns BOTH formats: a simple subtitle version (plain transcript text + timed SRT cues, stored as transcript.txt/transcript.srt) and an advanced multi-speaker version (speaker-attributed timed segments in output.segments and transcript.json) for multi-narration sources like podcasts and interviews. diarize defaults to true and speaker attribution needs a Gemini key — openai/openrouter keys degrade to a plain single-speaker transcript. For transcript-grounded caption work on THIS fork, the read-only video_context tool may already contain the decompose-time transcript; prefer it before running a new billable-key transcription, and use /audio/transcribe for other URLs, multi-speaker attribution, or SRT output.",
         "Brainstorm primitives are also available directly here. If the user explicitly asks for hooks, angles, awareness-stage advice, a cold-start strategy questionnaire, or product-placement opportunities in a video, call the matching brainstorm primitive immediately instead of brainstorming in chat from memory. Use POST /api/v1/primitives/brainstorm/coldstart with body { tracer, payload: { user_message }, webhook_url? } when the user is clueless and needs foundational strategy questions. Use /brainstorm/awareness_stages with body { tracer, payload: { offer_description }, webhook_url? } when they are unsure what type of ads to make. Use /brainstorm/angles with body { tracer, payload: { offer_description, problem_awareness, solution_awareness }, webhook_url? } when they want persuasive ad angles; problem_awareness must be problem_unaware or problem_aware, and solution_awareness must be solution_unaware or solution_aware. Use /brainstorm/hooks with body { tracer, payload: { offer_description }, webhook_url? } when they are stuck on openings and want many hooks.",
         "Product placement is a first-class brainstorm primitive, just like angles and hooks. When the user asks to identify product-placement opportunities in a video, or to repurpose a video into a native ad for their product, prefer POST /api/v1/primitives/brainstorm/product_placement with body { tracer, payload: { source_video_url, offer_description }, webhook_url? }. source_video_url is the exact video to analyze — for the current composition, first call GET /api/v1/compositions/:forkId/remove-video-captions to pick the correct source (the ORIGINAL uploaded video vs the DECOMPOSED, caption-free video), then pass that URL. offer_description is the user's product/offer. This primitive watches the video and returns timestamped, native placement opportunities. It prefers a Gemini key for video understanding.",
         "BEFORE calling /brainstorm/product_placement for the CURRENT composition, first call the product_placement_context tool (or GET /api/v1/compositions/:forkId/product-placement.json). Decompose already scouted product-AGNOSTIC placement surfaces for this fork — real, grounded moments (timestamp, surface_type, surface_note, best_for, why_it_works). Use those surfaces to ground your answer and to seed the primitive: fold the strongest surfaces into offer_description (for example append 'Known native placement surfaces: 0:04 empty desk prop; 0:12 phone screen swap') so the product-specific pass builds on grounded moments instead of re-watching blind. If the user just wants a quick conversational take on where their product could go, the surfaces from product_placement_context are often enough to answer directly without the billable primitive.",
@@ -64,7 +64,7 @@ export function buildTemplateEditorChatSystemPrompt(input) {
         "If the user asks for each output to have its own chat thread, call frontend_action with action=create_thread for each tracer before or alongside the corresponding POST request.",
         "If multiple tracers are available, mention which tracer you are using when it matters.",
         "If the user asks to add, remove, switch tracers, or create a separate chat thread for a tracer, use the frontend_action tool so the page state updates directly.",
-        "If the user asks to add, remove, retime, reposition, resize, restyle, swap media, tag, note, group, ungroup, duplicate, or split layers on the composition timeline, call the editor_action tool. Supported action_type values are add_layer, remove_layer, set_layer_timing, set_layer_visual, set_layer_style, set_layer_media, set_layer_text, set_layer_identity, duplicate_layer, split_layer, group_layers, ungroup_layers, generate_layer, replace_composition_html, and export_composition.",
+        "If the user asks to add, remove, retime, reposition, resize, restyle, swap media, tag, note, group, ungroup, duplicate, or split layers on the composition timeline, call the editor_action tool. Supported action_type values are add_layer, remove_layer, set_layer_timing, set_layer_visual, set_layer_style, set_layer_media, set_layer_text, set_layer_identity, duplicate_layer, split_layer, group_layers, ungroup_layers, generate_layer, replace_composition_html, export_composition, and set_captions.",
         "If the user asks to export, render, publish, or produce the final MP4 for this composition (phrases like 'export it', 'render this', 'kick off the export', 'make the mp4'), call editor_action with action_type=export_composition and a brief explanation. This is the same action as the editor's Export button — it queues the composition on production AWS Lambda. Do NOT try to hit any /api/v1/compositions/:id/export route via http_request for this; use the editor_action tool. After calling export_composition, tell the user the export has started and that the finished MP4 URL will appear once the render succeeds; do not fabricate a URL or claim success until a later turn shows last_export_url populated in editor_context.",
         "The editor_context block includes last_export_url, last_export_title, last_export_status, and last_export_render_id when a render has succeeded in this session. Treat last_export_url as the current 'finished Export MP4' for this composition. If the user asks to approve, package, share, or schedule the exported video without providing an explicit URL, use last_export_url as the primary MP4 media (kind=video, role=primary) for POST /api/v1/approved/posts. If last_export_url is null, tell the user to Export first (or offer to call editor_action with action_type=export_composition on their behalf) instead of guessing a URL.",
         "Each layer in editor_context includes element_id (data-hf-id), optional slug (data-hf-slug), and optional note (data-hf-note). layer_key on any editor_action may be EITHER the element_id or the slug — prefer the slug when the user (or a viral DNA blurb) refers to a layer by its human name like 'the hero_image'. Use set_layer_identity to add/change a layer's slug or note. Slugs are the stable AI-friendly handle: when planning viral DNA notes, reference the element by its slug (e.g., 'raise the {{hero_image}} to full canvas at 4s') so future turns can resolve it deterministically.",
@@ -79,6 +79,8 @@ export function buildTemplateEditorChatSystemPrompt(input) {
         "When placing generated character media on the timeline, prefer generate_layer (it applies the placement rules for you): to drop the character into a blank moment use intent='fill_gap' with start/duration on a timeline_gaps span; to swap them into an existing scene use intent='replace_layer' with replace_layer_key (its timing and full-canvas geometry are copied automatically). Always set aspect_ratio to the canvas (e.g. 9:16 for vertical) so the clip fills the frame. Only when you already have a finished media URL should you fall back to add_layer with explicit collision-free start/duration and full-canvas geometry (x=0, y=0, width=100, height=100) for a timeline-proxy/full-canvas replacement.",
         "Use set_layer_visual for geometry (x, y, width, height in %, plus font_size and border_radius in px). Use set_layer_style for text/color styling (color, background, background_style plain|outline|highlight-solid|highlight-translucent, font_family, font_weight, italic, underline, text_align, border_radius, font_size). Use set_layer_media to swap src, volume, muted, playback_start, or object_fit on media layers. Use set_layer_timing for start, duration, track index, playback_start.",
         "KEN BURNS / ANIMATE STILL IMAGES: every still-image layer supports a built-in Ken Burns effect — a slow pan or zoom that spans the clip's full duration in both the preview and the final render. Apply it with editor_action set_layer_media and the ken_burns field (presets: zoom-in, zoom-out, pan-left, pan-right, pan-up, pan-down, zoom-in-left, zoom-in-right; 'none' removes it), optionally ken_burns_intensity (0.04-0.5, default 0.18; ~0.1 subtle, ~0.3 dramatic). When the user says 'animate the images', 'make the photos move', 'ken burns', or similar, apply a preset to EVERY still-image layer in one pass (one set_layer_media call per layer), varying presets across adjacent clips — e.g. zoom-in, then pan-left, then zoom-out — so consecutive stills don't repeat the same motion. Zoom presets suit subjects centered in frame (products, faces); pan presets suit wide scenery or tall screenshots. You can also seed ken_burns directly on add_layer (kind=image) or generate_layer (media_type=image) so freshly placed stills arrive already animated. It only applies to image layers — never set it on video, text, or audio.",
+        "SCENE TRANSITIONS: every visual clip supports a first-class transition at its start — the clip animates IN over the previous clip on its track, which is automatically held on screen beneath it for the transition window, in both the preview and the final render. Apply it with editor_action set_layer_media and the transition field ON THE INCOMING CLIP — the clip AFTER the cut, never the one before it (presets: crossfade, fade-black, slide-left/right/up/down, wipe-left/right/up/down, zoom-in, zoom-out, circle-open; 'none' removes it), optionally transition_duration (0.1-2.5s, default 0.5; ~0.3 snappy, ~1.0 slow cinematic). When the user says 'add transitions', 'smooth out the cuts', 'crossfade between scenes', or similar, apply a transition to EVERY scene clip except the first in one pass (one set_layer_media call per clip). Match the preset to the template's energy: crossfade/fade-black read calm and cinematic, slide/wipe read energetic (vary directions across cuts), zoom-in/zoom-out/circle-open read punchy and meme-y; keep ONE family per video unless asked otherwise. You can also seed transition directly on add_layer or generate_layer so a newly placed scene arrives with its entrance. Transitions belong on video/image scene clips — never on audio; on text overlays prefer them only when the user asks. Timing is handled for you — never move clip starts or durations to 'make room' for a transition.",
+        "ANIMATED CAPTIONS (word-by-word, TikTok/CapCut style): the composition supports first-class animated captions — caption layers whose words animate one at a time in both the preview and the final render. Available preset looks (caption_style): spotlight (active word gets a rounded highlight pill on bold outlined text — the classic Hormozi/CapCut look), karaoke (words fill with a color as they are spoken and stay lit), word-pop (one word at a time, punchy scale-in), stack-up (words fade/rise in and accumulate), neon (active word pulses with a glow), bounce (active word bounces). When the user asks to 'add captions', 'add animated captions', 'add subtitles', or similar, pick the cue source by where the speech lives: (a) narration that needs TRANSCRIBING — a TTS voiceover layer, replaced audio, or when word-accurate karaoke timing matters — call the captions primitive: POST /api/v1/primitives/audio/captions with body { tracer, payload: { source_url: <the narration audio/video URL from editor_context>, style } }; the finished job's result carries captions (the cue array) and set_captions_action (fully-formed editor_action arguments) — apply them verbatim with editor_action action_type=set_captions. Real word timestamps need an OpenAI key (tried first; gemini/openrouter degrade to estimated word windows). (b) speech that is the SOURCE VIDEO's own audio on an already-decomposed fork — video_context already has the transcript's timestamped segments, so skip the job and call editor_action action_type=set_captions directly with captions=[{text, start, duration, words?}] cues derived from those segments — split segment text into pages of 3-5 words, keep each cue inside its segment's time window, and pass word timings when the transcript provides them (otherwise omit words and the editor estimates). Pick caption_style to match the template's voice (composition_context), or spotlight by default; override colors with caption_active_color / caption_highlight_color / color / background / background_style, and caption_uppercase for shouty formats. set_captions REPLACES all existing animated caption layers in one call — use it for 'restyle all the captions' too (same cues, new style) when cue text/timing is already in editor_context (each caption layer's text and caption_animation are listed there). For a single cue, set_layer_style with caption_* fields restyles just that layer, set_layer_text rewrites its words (timings re-estimate), and caption_animation='none' flattens it back to static text. Never hand-build word-by-word captions out of many add_layer text layers — always use set_captions. There is also a ONE-STEP server route, POST /api/v1/compositions/:forkId/captions { audio_url?|text?, style?, ... }, which transcribes the fork's own narration and writes the caption layers into the working composition server-side — use it ONLY for headless/automation flows, never while this editor session is open (the editor's next auto-save would overwrite the server-side change; in the editor always mutate through editor_action set_captions).",
         "Use duplicate_layer to clone an existing layer; supply layer_key for the source, and optionally start/duration/track/label on the duplicate. Use split_layer with layer_key and split_time to cut at a moment in the timeline. Use group_layers with layer_keys (>=2) and optional group_label; ungroup_layers with layer_keys of any grouped members.",
         "Prefer one editor_action call per mutation. For a multi-layer composition, sequence calls: generate or fetch each asset, then add or edit each layer with its own editor_action call. Chain edits by reusing the layer_key you assigned during add_layer.",
         "Layer/track ordering is the ONLY thing that controls visual stacking. `track` is both the timeline layer index AND the CSS z-index — the editor forces `z-index = track` on every layer at publish time. Higher track draws visually on top; lower track draws underneath. There is no separate z-index override — if the AI wants a layer above another, give it a higher track. If html/text overlays should sit ABOVE a video/image, their track must be a larger integer than the visual media below them.",

package/dist/src/frontend/homepage-view.js

@@ -378,7 +378,7 @@ function TemplateCard(input) {
             ? _jsx(LazyVideo, { src: template.previewUrl, controls: false })
             : _jsx("img", { className: "preview", src: template.previewUrl, alt: `${template.title} preview`, loading: "lazy", decoding: "async" })
         : _jsx("div", { className: "preview preview-empty", children: template.status === "processing" ? "Downloading…" : "No preview" });
-    return (_jsxs("li", { className: "discover-card row", "data-template-id": template.templateId, children: [template.previewUrl ? (_jsxs("button", { className: "discover-card-media discover-card-media-button", type: "button", "aria-label": `Open ${template.title} preview`, onClick: () => input.onOpenPreview?.(template), children: [media, _jsx("span", { className: "discover-card-media-affordance", "aria-hidden": "true", children: "View" })] })) : (_jsx("div", { className: "discover-card-media", children: media })), _jsxs("div", { className: "discover-card-copy", children: [_jsxs("div", { className: "discover-card-head", children: [_jsxs("div", { className: "discover-card-title-wrap", children: [_jsx("h2", { children: template.title }), _jsx("p", { className: "discover-card-meta", children: formatTemplateMeta(template) })] }), _jsxs("div", { className: "discover-card-actions", children: [_jsx(BookmarkButton, { templateId: template.templateId, title: template.title, isBookmarked: input.isBookmarked, onToggleBookmark: input.onToggleBookmark }), isPending ? (_jsx("span", { className: "cta-button discover-card-cta-disabled", "aria-disabled": "true", children: template.status === "failed" ? "Failed" : "Preparing…" })) : (_jsx(CreateButton, { templateId: template.templateId, accountUserId: input.accountUserId })), _jsx(CardMenu, { template: template, isBookmarked: input.isBookmarked, onToggleBookmark: input.onToggleBookmark, onDeleteTemplate: input.onDeleteTemplate, accountUserId: input.accountUserId })] })] }), _jsx("div", { className: "discover-card-body", children: _jsx("p", { children: String(template.viralDna || "").trim() || "No layer strategy provided for this composition yet." }) }), _jsxs("div", { className: "discover-card-tags", children: [template.visibility === "private" ? (_jsx("div", { className: "pill-tag private-pill", title: "Only visible to your account", children: "Only you" })) : null, template.status === "processing" ? (_jsx("div", { className: "pill-tag processing-pill", children: "Processing" })) : template.status === "failed" ? (_jsx("div", { className: "pill-tag failed-pill", children: "Download failed" })) : null, _jsx("div", { className: "pill-tag difficulty-pill", "data-difficulty": template.difficulty, children: formatDifficulty(template.difficulty) }), _jsx("div", { className: "pill-tag", children: template.sourceType || (isVideoPreview(template.previewUrl) ? "Video source" : "Image sequence") }), _jsx(CopyInlineButton, { text: template.templateId, label: template.templateId })] })] })] }));
+    return (_jsxs("li", { className: "discover-card row", "data-template-id": template.templateId, children: [template.previewUrl ? (_jsxs("button", { className: "discover-card-media discover-card-media-button", type: "button", "aria-label": `Open ${template.title} preview`, onClick: () => input.onOpenPreview?.(template), children: [media, _jsx("span", { className: "discover-card-media-affordance", "aria-hidden": "true", children: "View" })] })) : (_jsx("div", { className: "discover-card-media", children: media })), _jsxs("div", { className: "discover-card-copy", children: [_jsxs("div", { className: "discover-card-head", children: [_jsxs("div", { className: "discover-card-title-wrap", children: [_jsx("h2", { children: template.title }), _jsx("p", { className: "discover-card-meta", children: formatTemplateMeta(template) })] }), _jsxs("div", { className: "discover-card-actions", children: [_jsx(BookmarkButton, { templateId: template.templateId, title: template.title, isBookmarked: input.isBookmarked, onToggleBookmark: input.onToggleBookmark }), isPending ? (_jsx("span", { className: "cta-button discover-card-cta-disabled", "aria-disabled": "true", children: template.status === "failed" ? "Failed" : "Preparing…" })) : (_jsx(CreateButton, { templateId: template.templateId, accountUserId: input.accountUserId })), _jsx(CardMenu, { template: template, isBookmarked: input.isBookmarked, onToggleBookmark: input.onToggleBookmark, onDeleteTemplate: input.onDeleteTemplate, accountUserId: input.accountUserId })] })] }), _jsx("div", { className: "discover-card-body", children: _jsx("p", { children: String(template.viralDna || "").trim() || "No layer strategy provided for this composition yet." }) }), _jsxs("div", { className: "discover-card-tags", children: [template.origin === "raw" ? (_jsx("div", { className: "pill-tag origin-pill", title: "Your own project \u2014 created from a prompt or your raw clips, not an imported inspiration", children: "Your project" })) : null, template.visibility === "private" ? (_jsx("div", { className: "pill-tag private-pill", title: "Only visible to your account", children: "Only you" })) : null, template.status === "processing" ? (_jsx("div", { className: "pill-tag processing-pill", children: "Processing" })) : template.status === "failed" ? (_jsx("div", { className: "pill-tag failed-pill", children: "Download failed" })) : null, _jsx("div", { className: "pill-tag difficulty-pill", "data-difficulty": template.difficulty, children: formatDifficulty(template.difficulty) }), _jsx("div", { className: "pill-tag", children: template.sourceType || (isVideoPreview(template.previewUrl) ? "Video source" : "Image sequence") }), _jsx(CopyInlineButton, { text: template.templateId, label: template.templateId })] })] })] }));
 }
 function PreviewModal(input) {
     const { onClose, template } = input;

package/dist/src/frontend/template-editor-chat.js

@@ -3624,10 +3624,12 @@ export function TemplateEditorChat({ boot }) {
             }
             if (!storageKey)
                 throw new Error("upload did not return a storage key.");
+            // origin:"raw" — a prompt-generated video is the user's own new project,
+            // not an imported inspiration; the editor must not auto-prompt Decompose.
             const addRes = await fetch(new URL("/discover/templates", origin), {
                 method: "POST",
                 headers: jsonHeaders,
-                body: JSON.stringify({ upload: { storage_key: storageKey, file_name: uploadedName }, title })
+                body: JSON.stringify({ upload: { storage_key: storageKey, file_name: uploadedName }, title, origin: "raw" })
             });
             const add = await readJson(addRes);
             if (!addRes.ok)

package/dist/src/homepage.js

@@ -366,6 +366,13 @@ export function renderHomepage(input) {
         font-weight: 800;
       }
 
+      .origin-pill {
+        border-color: rgba(46, 160, 100, 0.35);
+        background: rgba(46, 160, 100, 0.1);
+        color: #1f7a4d;
+        font-weight: 800;
+      }
+
       .processing-pill {
         border-color: rgba(88, 132, 196, 0.4);
         background: rgba(88, 132, 196, 0.12);