@mevdragon/vidfarm-devcli 0.10.0 → 0.12.0

package/dist/src/editor-chat.js

@@ -34,7 +34,7 @@ export function buildTemplateEditorChatSystemPrompt(input) {
         "Execute REST calls sequentially. Make one API call, inspect the response, then decide the next step.",
         "A queued async POST job is enough inspection for that request. Do not poll it in the same response; continue launching any remaining requested outputs, then summarize the queued jobs.",
         "Primitive routes under /api/v1/primitives are first-class allowed routes in this editor, even when the primitive is not specific to the current template.",
-        "Never say you cannot use primitive image generation, image edit, inpaint, HTML render, AI video generation, or video render routes directly from this editor chat; use the http_request tool when the requested primitive route exists.",
+        "Never say you cannot use primitive image generation, image edit, inpaint, HTML render, AI video generation, text-to-speech, speech transcription, or video render routes directly from this editor chat; use the http_request tool when the requested primitive route exists.",
         "All primitive POST routes require the same outer JSON envelope: top-level tracer, top-level payload containing the primitive-specific fields, and optional webhook_url.",
         "When the user explicitly asks to use primitives or timeline rendering, do not redirect them to old per-template operation routes unless the requested primitive route cannot accept the available inputs.",
         "If the user asks to create, generate, or make a new image similar to an attached image, call POST /api/v1/primitives/images/generate with body { tracer, payload: { prompt, prompt_attachments: [exact attachment URL] } }.",
@@ -42,6 +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/...). 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.",
@@ -63,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.",
@@ -78,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: FIRST call video_context to get the transcript's timestamped segments, then call editor_action action_type=set_captions 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.",
         "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/hyperframes/composition.js

@@ -75,6 +75,269 @@ export function normalizeKenBurns(value) {
         origin
     };
 }
+// ---------------------------------------------------------------------------
+// Scene transitions. Same declarative contract as Ken Burns: the INCOMING
+// clip (the element that owns data-start) carries data-transition="<preset>"
+// plus data-transition-duration and the inline --vf-tr-dur var, and a static
+// vf-tr-* keyframe animates the clip IN over its first data-transition-duration
+// seconds. Both preview runtimes and the render producer's CSS adapter scrub
+// the animation by (time - data-start), so the motion is identical everywhere.
+//
+// The one thing CSS cannot express is the OUTGOING clip staying on screen
+// beneath the incoming one: stored compositions keep scenes butt-cut (A ends
+// exactly where B starts) so timeline edits and agent edits stay trivial. The
+// preview runtime extends the previous same-track clip's active window live,
+// and normalizePublishHtml materializes the same overlap into data-duration at
+// publish/render time (recorded in data-transition-hold for idempotency),
+// because the render engine derives visibility strictly from data-start/
+// data-duration. Presets animate opacity / clip-path / standalone translate /
+// scale — never `transform` — so they compose with a Ken Burns transform on
+// the same element. Keyframes deliberately omit the `to` state so the
+// animation settles into the element's own inline styles instead of
+// clobbering a custom opacity.
+export const TRANSITION_PRESETS = [
+    "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"
+];
+export const TRANSITION_DEFAULT_DURATION = 0.5;
+export const TRANSITION_MIN_DURATION = 0.1;
+export const TRANSITION_MAX_DURATION = 2.5;
+// Two butt-cut clips can drift by a few ms through timeline edits; treat ends
+// within this window as adjacent when granting the outgoing clip's hold.
+export const TRANSITION_ADJACENCY_EPSILON = 0.05;
+export const TRANSITION_STYLE_MARKER = "__VF_TRANSITIONS_V1__";
+export const TRANSITION_CSS = `/*${TRANSITION_STYLE_MARKER}*/
+@keyframes vf-tr-crossfade { from { opacity: 0; } }
+@keyframes vf-tr-fade-black { 0% { opacity: 0; filter: brightness(0); } 35% { opacity: 1; filter: brightness(0); } }
+@keyframes vf-tr-slide-left { from { translate: 100% 0; } }
+@keyframes vf-tr-slide-right { from { translate: -100% 0; } }
+@keyframes vf-tr-slide-up { from { translate: 0 100%; } }
+@keyframes vf-tr-slide-down { from { translate: 0 -100%; } }
+@keyframes vf-tr-wipe-left { from { clip-path: inset(0 0 0 100%); } to { clip-path: inset(0 0 0 0); } }
+@keyframes vf-tr-wipe-right { from { clip-path: inset(0 100% 0 0); } to { clip-path: inset(0 0 0 0); } }
+@keyframes vf-tr-wipe-up { from { clip-path: inset(100% 0 0 0); } to { clip-path: inset(0 0 0 0); } }
+@keyframes vf-tr-wipe-down { from { clip-path: inset(0 0 100% 0); } to { clip-path: inset(0 0 0 0); } }
+@keyframes vf-tr-zoom-in { from { opacity: 0; scale: 1.18; } }
+@keyframes vf-tr-zoom-out { from { opacity: 0; scale: 0.82; } }
+@keyframes vf-tr-circle-open { from { clip-path: circle(0% at 50% 50%); } to { clip-path: circle(75% at 50% 50%); } }
+[data-transition] {
+  animation-duration: var(--vf-tr-dur, 0.5s);
+  animation-timing-function: var(--vf-tr-ease, ease-in-out);
+  animation-fill-mode: both;
+  animation-play-state: paused;
+}
+[data-transition="crossfade"] { animation-name: vf-tr-crossfade; }
+[data-transition="fade-black"] { animation-name: vf-tr-fade-black; }
+[data-transition="slide-left"] { animation-name: vf-tr-slide-left; }
+[data-transition="slide-right"] { animation-name: vf-tr-slide-right; }
+[data-transition="slide-up"] { animation-name: vf-tr-slide-up; }
+[data-transition="slide-down"] { animation-name: vf-tr-slide-down; }
+[data-transition="wipe-left"] { animation-name: vf-tr-wipe-left; }
+[data-transition="wipe-right"] { animation-name: vf-tr-wipe-right; }
+[data-transition="wipe-up"] { animation-name: vf-tr-wipe-up; }
+[data-transition="wipe-down"] { animation-name: vf-tr-wipe-down; }
+[data-transition="zoom-in"] { animation-name: vf-tr-zoom-in; }
+[data-transition="zoom-out"] { animation-name: vf-tr-zoom-out; }
+[data-transition="circle-open"] { animation-name: vf-tr-circle-open; }
+`;
+export function clampTransitionDuration(value) {
+    const next = Number(value);
+    if (!Number.isFinite(next) || next <= 0)
+        return TRANSITION_DEFAULT_DURATION;
+    return Math.max(TRANSITION_MIN_DURATION, Math.min(TRANSITION_MAX_DURATION, next));
+}
+export function normalizeTransition(value) {
+    if (!value)
+        return null;
+    const raw = typeof value === "string" ? { preset: value } : value;
+    if (!TRANSITION_PRESETS.includes(raw.preset))
+        return null;
+    return {
+        preset: raw.preset,
+        duration: raw.duration !== undefined ? clampTransitionDuration(raw.duration) : undefined
+    };
+}
+// ---------------------------------------------------------------------------
+// Animated captions. Same declarative contract as Ken Burns: the caption layer
+// <div> (the element that owns data-start/data-duration) carries
+// data-caption-animation="<preset>" plus per-cue CSS vars, and each word is a
+// <span data-cap-word> whose inline animation-delay/animation-duration encode
+// that word's window RELATIVE TO THE LAYER START. The render producer's CSS
+// adapter seeks every animation to (frameTime - ancestor data-start), and both
+// preview runtimes scrub the same way, so word-level motion is deterministic
+// and identical across preview and export. Everything is pure HTML+CSS so it
+// survives sanitizeCompositionHtml. Word timings also round-trip through
+// data-word-start/data-word-end so editors can re-derive them without parsing
+// CSS.
+export const CAPTION_ANIMATIONS = [
+    "highlight-pop",
+    "karaoke-fill",
+    "word-pop",
+    "cumulative-reveal",
+    "glow-pulse",
+    "bounce-wave"
+];
+export const CAPTION_STYLE_MARKER = "__VF_CAPTIONS_V1__";
+export const CAPTION_ANIM_CSS = `/*${CAPTION_STYLE_MARKER}*/
+[data-caption-animation] [data-cap-word] {
+  display:inline-block;
+  animation-play-state:paused;
+  animation-timing-function:ease-out;
+  animation-fill-mode:none;
+  will-change:transform,opacity;
+}
+[data-caption-uppercase="1"] { text-transform:uppercase; }
+@keyframes vf-cap-highlight { 14%, 100% { background-color:var(--vf-cap-hl, #7C3AED); color:var(--vf-cap-active, #FFFFFF); transform:scale(1.06); } }
+[data-caption-animation="highlight-pop"] [data-cap-word] { animation-name:vf-cap-highlight; padding:0.08em 0.18em; margin:-0.08em -0.05em; border-radius:0.3em; }
+@keyframes vf-cap-karaoke { to { color:var(--vf-cap-active, #FFE14D); } }
+[data-caption-animation="karaoke-fill"] [data-cap-word] { animation-name:vf-cap-karaoke; animation-fill-mode:forwards; animation-timing-function:linear; }
+@keyframes vf-cap-word-pop { 0% { opacity:0; transform:scale(0.45); } 22% { opacity:1; transform:scale(1.14); } 38%, 100% { opacity:1; transform:scale(1); } }
+[data-caption-animation="word-pop"] [data-vf-text-inline] { display:grid; place-items:center; }
+[data-caption-animation="word-pop"] [data-cap-word] { animation-name:vf-cap-word-pop; opacity:0; grid-area:1 / 1; }
+@keyframes vf-cap-reveal { from { opacity:0; transform:translateY(0.4em); } 40%, 100% { opacity:1; transform:none; } }
+[data-caption-animation="cumulative-reveal"] [data-cap-word] { animation-name:vf-cap-reveal; animation-fill-mode:forwards; opacity:0; }
+@keyframes vf-cap-glow { 20%, 80% { color:var(--vf-cap-active, #9BFF57); text-shadow:0 0 0.14em var(--vf-cap-active, #9BFF57), 0 0 0.5em var(--vf-cap-active, #9BFF57); transform:scale(1.04); } }
+[data-caption-animation="glow-pulse"] [data-cap-word] { animation-name:vf-cap-glow; }
+@keyframes vf-cap-bounce { 25% { transform:translateY(-0.22em) scale(1.08); } 55% { transform:translateY(0.05em); } 75% { transform:none; } }
+[data-caption-animation="bounce-wave"] [data-cap-word] { animation-name:vf-cap-bounce; }
+`;
+export const CAPTION_STYLE_PRESETS = [
+    {
+        id: "spotlight",
+        label: "Spotlight",
+        animation: "highlight-pop",
+        color: "#ffffff",
+        background: "#000000",
+        textBackgroundStyle: "outline",
+        highlightColor: "#7C3AED",
+        activeColor: "#ffffff",
+        fontWeight: 800,
+        uppercase: true
+    },
+    {
+        id: "karaoke",
+        label: "Karaoke",
+        animation: "karaoke-fill",
+        color: "#ffffff",
+        background: "#000000",
+        textBackgroundStyle: "outline",
+        activeColor: "#FFE14D",
+        fontWeight: 800
+    },
+    {
+        id: "word-pop",
+        label: "Word Pop",
+        animation: "word-pop",
+        color: "#ffffff",
+        background: "#000000",
+        textBackgroundStyle: "outline",
+        fontWeight: 900,
+        uppercase: true
+    },
+    {
+        id: "stack-up",
+        label: "Stack Up",
+        animation: "cumulative-reveal",
+        color: "#ffffff",
+        background: "#000000",
+        textBackgroundStyle: "highlight-translucent",
+        fontWeight: 700
+    },
+    {
+        id: "neon",
+        label: "Neon Glow",
+        animation: "glow-pulse",
+        color: "#eafff1",
+        background: "#04140a",
+        textBackgroundStyle: "plain",
+        activeColor: "#9BFF57",
+        fontWeight: 800,
+        uppercase: true
+    },
+    {
+        id: "bounce",
+        label: "Bounce",
+        animation: "bounce-wave",
+        color: "#FFE14D",
+        background: "#000000",
+        textBackgroundStyle: "outline",
+        activeColor: "#FFE14D",
+        fontWeight: 900,
+        uppercase: true
+    }
+];
+export function captionStylePresetById(id) {
+    if (!id)
+        return null;
+    const clean = String(id).trim().toLowerCase();
+    return CAPTION_STYLE_PRESETS.find((preset) => preset.id === clean) || null;
+}
+export function normalizeCaptionConfig(value) {
+    if (!value)
+        return null;
+    const raw = typeof value === "string" ? { animation: value } : value;
+    if (!CAPTION_ANIMATIONS.includes(raw.animation))
+        return null;
+    const words = Array.isArray(raw.words)
+        ? raw.words
+            .map((word) => ({
+            text: String(word?.text ?? "").trim(),
+            start: Math.max(0, Number(word?.start) || 0),
+            end: Math.max(0, Number(word?.end) || 0)
+        }))
+            .filter((word) => word.text && word.end > word.start)
+        : undefined;
+    return {
+        animation: raw.animation,
+        words: words && words.length ? words : undefined,
+        activeColor: typeof raw.activeColor === "string" && raw.activeColor.trim() ? raw.activeColor.trim() : undefined,
+        highlightColor: typeof raw.highlightColor === "string" && raw.highlightColor.trim() ? raw.highlightColor.trim() : undefined,
+        uppercase: raw.uppercase === true ? true : undefined
+    };
+}
+// Char-weighted word windows across a cue when the transcript has no
+// word-level timings (Gemini segments, hand-typed text). Leaves a hair of
+// silence between words so pop/highlight transitions read as discrete.
+export function estimateCaptionWords(text, durationSeconds) {
+    const tokens = String(text || "").trim().split(/\s+/).filter(Boolean);
+    const duration = Number.isFinite(durationSeconds) && durationSeconds > 0 ? durationSeconds : tokens.length * 0.32;
+    if (!tokens.length)
+        return [];
+    const weights = tokens.map((token) => Math.max(2, token.length) + 1.5);
+    const totalWeight = weights.reduce((sum, weight) => sum + weight, 0);
+    const words = [];
+    let cursor = 0;
+    for (let index = 0; index < tokens.length; index += 1) {
+        const span = (weights[index] / totalWeight) * duration;
+        const gap = Math.min(0.03, span * 0.1);
+        words.push({
+            text: tokens[index],
+            start: Number(cursor.toFixed(3)),
+            end: Number(Math.max(cursor + 0.05, cursor + span - gap).toFixed(3))
+        });
+        cursor += span;
+    }
+    return words;
+}
+export function captionInlineVars(config) {
+    const vars = [];
+    if (config.activeColor)
+        vars.push(`--vf-cap-active:${config.activeColor}`);
+    if (config.highlightColor)
+        vars.push(`--vf-cap-hl:${config.highlightColor}`);
+    return vars.join(";");
+}
 export function buildHyperframeCompositionHtml(input) {
     const duration = positiveNumber(input.duration, inferDuration(input.layers));
     const width = positiveInteger(input.width, 720);
@@ -93,6 +356,8 @@ export function buildHyperframeCompositionHtml(input) {
     [data-composition-id] { position:relative; width:100vw; height:100vh; overflow:hidden; background:${background}; }
     audio { display:none; }
     ${KEN_BURNS_CSS}
+    ${CAPTION_ANIM_CSS}
+    ${TRANSITION_CSS}
     ${input.css ?? ""}
   </style>
 </head>
@@ -118,6 +383,11 @@ export function assertHyperframeTimeline(layers) {
             throw new Error(`HyperFrame layer ${layer.id} must have a positive duration.`);
     }
 }
+// Public single-layer serializer so out-of-band builders (devcli composition
+// edits) emit byte-identical layer markup to the composition builder.
+export function renderHyperframeLayerHtml(layer) {
+    return renderLayer(layer);
+}
 function renderLayer(layer) {
     const attrs = timedAttrs(layer);
     const style = layerStyle(layer);
@@ -152,8 +422,39 @@ function renderLayer(layer) {
         "white-space:pre-wrap",
         "overflow:visible"
     ].join(";");
+    const captionConfig = layer.kind === "caption" || layer.kind === "text" ? normalizeCaptionConfig(layer.captionAnimation) : null;
+    if (captionConfig) {
+        const words = captionConfig.words ?? estimateCaptionWords(text, positiveNumber(layer.duration, 0));
+        if (words.length) {
+            const vars = captionInlineVars(captionConfig);
+            // text-transform must be INLINE: layerStyle already writes an inline
+            // text-transform:none, which would beat the [data-caption-uppercase]
+            // stylesheet rule. The attribute stays for round-trip state reads.
+            // overflow:visible (overriding layerStyle's hidden) because caption text
+            // wrapping past the cue box must never clip mid-glyph.
+            const upper = captionConfig.uppercase ? ";text-transform:uppercase" : "";
+            const divStyle = `${style}${vars ? `;${vars}` : ""}${upper};overflow:visible`;
+            const captionAttrs = `${attrs} data-caption-animation="${escapeAttr(captionConfig.animation)}"${captionConfig.uppercase ? " data-caption-uppercase=\"1\"" : ""}`;
+            return `<div ${captionAttrs} style="${escapeAttr(divStyle)}"><span data-vf-text-lines="true" style="${escapeAttr(linesStyle)}"><span data-vf-text-inline="true" style="${escapeAttr(inlineStyle)}">${captionWordSpansHtml(words)}</span></span></div>`;
+        }
+    }
     return `<div ${attrs} style="${escapeAttr(style)}"><span data-vf-text-lines="true" style="${escapeAttr(linesStyle)}"><span data-vf-text-inline="true" style="${escapeAttr(inlineStyle)}">${escapeHtml(text)}</span></span></div>`;
 }
+// Serializes word windows into the <span data-cap-word> run that the caption
+// stylesheet animates. Delay/duration are the word window relative to the
+// layer start — the ONLY timing source the render adapter needs; the
+// data-word-* attrs exist so editing surfaces can re-derive timings without
+// parsing CSS.
+export function captionWordSpansHtml(words) {
+    return words
+        .map((word) => {
+        const start = Math.max(0, positiveNumber(word.start, 0));
+        const end = Math.max(start + 0.05, positiveNumber(word.end, start + 0.05));
+        const wordStyle = `animation-delay:${num(start)}s;animation-duration:${num(end - start)}s`;
+        return `<span data-cap-word="true" data-word-start="${num(start)}" data-word-end="${num(end)}" style="${wordStyle}">${escapeHtml(word.text)}</span>`;
+    })
+        .join(" ");
+}
 function timedAttrs(layer) {
     const attrs = [
         `id="${escapeAttr(layer.id)}"`,
@@ -170,6 +471,12 @@ function timedAttrs(layer) {
         const mediaStart = positiveNumber(layer.playbackStart ?? layer.mediaStart, 0);
         attrs.push(`data-media-start="${num(mediaStart)}"`, `data-playback-start="${num(mediaStart)}"`);
     }
+    if (layer.kind !== "audio") {
+        const transition = normalizeTransition(layer.transition);
+        if (transition) {
+            attrs.push(`data-transition="${escapeAttr(transition.preset)}"`, `data-transition-duration="${num(clampTransitionDuration(transition.duration ?? TRANSITION_DEFAULT_DURATION))}"`);
+        }
+    }
     if (["caption", "text", "shape", "html"].includes(layer.kind)) {
         attrs.push(`data-text-background-style="${escapeAttr(layer.textBackgroundStyle || "plain")}"`, `data-text-background-color="${escapeAttr(layer.background || "#000000")}"`, `data-font-family="${escapeAttr(layer.fontFamily || "TikTok Sans")}"`);
     }
@@ -190,6 +497,14 @@ function layerStyle(layer) {
     if (layer.kind === "video" || layer.kind === "image") {
         styles.push(`object-fit:${layer.fit || "cover"}`);
     }
+    if (layer.kind !== "audio") {
+        // data-transition picks the keyframes; the inline var supplies the span so
+        // the animation covers exactly the transition window.
+        const transition = normalizeTransition(layer.transition);
+        if (transition) {
+            styles.push(`--vf-tr-dur:${num(clampTransitionDuration(transition.duration ?? TRANSITION_DEFAULT_DURATION))}s`);
+        }
+    }
     if (["caption", "text", "shape", "html"].includes(layer.kind)) {
         const fontFamily = layer.fontFamily || "TikTok Sans";
         styles.push("display:flex", "align-items:center", "justify-content:center", "padding:3px", `font-family:${fontCssFamily(fontFamily)}, 'TikTok Sans', Montserrat, Abel, sans-serif`, `font-weight:${positiveInteger(layer.fontWeight, 700)}`, `line-height:${positiveNumber(layer.lineHeight, 1.18)}`, "text-align:center", "text-transform:none", `font-size:${positiveInteger(layer.fontSize, 32)}px`, `color:${layer.color || "#ffffff"}`, layer.kind === "shape" && layer.textBackgroundStyle === "panel"

package/dist/src/primitive-context.js

@@ -181,6 +181,22 @@ export function createPrimitiveJobContext(input) {
                     workerId: input.workerId,
                     ...request
                 });
+            },
+            async generateSpeech(request) {
+                return input.providers.generateSpeech({
+                    customerId: input.customer.id,
+                    jobId: input.job.id,
+                    workerId: input.workerId,
+                    ...request
+                });
+            },
+            async transcribeSpeech(request) {
+                return input.providers.transcribeSpeech({
+                    customerId: input.customer.id,
+                    jobId: input.job.id,
+                    workerId: input.workerId,
+                    ...request
+                });
             }
         },
         hyperframes: {