@mevdragon/vidfarm-devcli 0.10.0 → 0.12.0

package/dist/src/primitive-registry.js

@@ -7,6 +7,7 @@ import { config } from "./config.js";
 import { definePrimitive } from "./primitive-sdk.js";
 import { PrimitiveMediaLambdaService } from "./services/primitive-media-lambda.js";
 import { estimateGhostcutCostUsd, isGhostcutConfigured, pollStatus as pollGhostcutStatus, submitSubtitleRemoval } from "./services/ghostcut.js";
+import { buildSrtFromSegments, defaultSpeechModelFor, inferSpeechProviderForVoice, speechVoiceMismatch } from "./services/speech.js";
 import { buildHtmlImageCompositionHtml, buildMediaDedupeCompositionHtml, DEDUPE_DEFAULT_EFFECTS } from "./primitives/hyperframes-media.js";
 const imageProviderSchema = z.enum(["openai", "gemini", "openrouter"]);
 const videoProviderSchema = z.enum(["openai", "gemini", "openrouter"]);
@@ -358,6 +359,56 @@ const trimAudioPayloadSchema = z.object({
     message: "Either duration_ms or end_ms is required.",
     path: ["duration_ms"]
 });
+const speechProviderSchema = z.enum(["openai", "gemini", "openrouter"]);
+const ttsPayloadSchema = z.preprocess((raw) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return raw;
+    const payload = raw;
+    return {
+        ...payload,
+        text: payload.text ?? payload.input ?? payload.script,
+        instructions: payload.instructions ?? payload.style ?? payload.style_instructions ?? payload.voice_style
+    };
+}, z.object({
+    provider: speechProviderSchema.optional(),
+    model: z.string().min(1).optional(),
+    text: z.string().min(1).max(8000),
+    voice: z.string().min(1).max(120).optional(),
+    instructions: z.string().min(1).max(4000).optional(),
+    output_format: z.enum(["mp3", "wav"]).default("mp3")
+}).superRefine((value, ctx) => {
+    // Reject an explicit provider/voice contradiction at enqueue (400) instead
+    // of queueing a job that can only fail at the provider.
+    if (!value.provider || !value.voice)
+        return;
+    const mismatch = speechVoiceMismatch({ provider: value.provider, model: value.model, voice: value.voice });
+    if (mismatch) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["voice"], message: mismatch });
+    }
+}));
+const sttPayloadSchema = z.preprocess((raw) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return raw;
+    const payload = raw;
+    return {
+        ...payload,
+        source_url: payload.source_url ??
+            payload.source_video_url ??
+            payload.source_audio_url ??
+            payload.source_media_url ??
+            payload.video_url ??
+            payload.audio_url ??
+            payload.url
+    };
+}, z.object({
+    provider: speechProviderSchema.optional(),
+    model: z.string().min(1).optional(),
+    source_url: mediaSourceUrlSchema,
+    media_type: z.enum(["auto", "video", "audio"]).default("auto"),
+    diarize: z.boolean().default(true),
+    language: z.string().min(2).max(16).optional(),
+    prompt: z.string().min(1).max(2000).optional()
+}));
 const probeVideoPayloadSchema = z.object({
     source_video_url: mediaSourceUrlSchema
 });
@@ -508,6 +559,14 @@ const PRIMITIVE_BRAINSTORM_ANGLES_ID = "primitive:brainstorm_angles";
 const PRIMITIVE_BRAINSTORM_COLDSTART_ID = "primitive:brainstorm_coldstart";
 const PRIMITIVE_BRAINSTORM_PRODUCT_PLACEMENT_ID = "primitive:brainstorm_product_placement";
 const PRIMITIVE_MEDIA_DEDUPE_ID = "primitive:media_dedupe";
+const PRIMITIVE_TTS_ID = "primitive:tts";
+const PRIMITIVE_STT_ID = "primitive:stt";
+// Gemini inline audio caps out around 20MB; at the 64kbps mono mp3 we extract,
+// that is roughly 40 minutes of speech.
+const MAX_TRANSCRIBE_AUDIO_BYTES = 20 * 1024 * 1024;
+// Keep job results comfortably under the DynamoDB item limit: transcripts
+// longer than this inline budget stay artifact-only (transcript.json).
+const MAX_INLINE_TRANSCRIPT_CHARS = 20_000;
 const primitiveMediaService = new PrimitiveMediaLambdaService();
 const hooksReferenceText = readPrimitiveAsset("SELLING_WITH_HOOKS.md");
 const awarenessReferenceText = readPrimitiveAsset("SELLING_AWARENESS_STAGES.md");
@@ -1566,6 +1625,183 @@ const audioTrimPrimitive = definePrimitive({
         }
     }
 });
+const ttsPrimitive = definePrimitive({
+    id: PRIMITIVE_TTS_ID,
+    kind: "tts",
+    operations: {
+        run: {
+            description: "Generate spoken narration audio from text (TTS) with a promptable voice style, persisted as a reusable platform audio URL.",
+            inputSchema: ttsPayloadSchema,
+            workflow: "run"
+        }
+    },
+    jobs: {
+        async run(ctx, input) {
+            const payload = ttsPayloadSchema.parse(input);
+            ctx.logger.progress(0.12, "Generating speech audio");
+            // A bare voice preset implies its provider ("Puck" → gemini) — blindly
+            // defaulting to openai would guarantee a cross-family voice failure.
+            const provider = payload.provider ?? inferSpeechProviderForVoice(payload.voice) ?? "openai";
+            const model = payload.model ?? defaultSpeechModelFor("tts", provider) ?? "";
+            const generated = await ctx.providers.generateSpeech({
+                provider,
+                model,
+                text: payload.text,
+                voice: payload.voice,
+                instructions: payload.instructions,
+                responseFormat: payload.output_format
+            });
+            // Gemini TTS answers in wav regardless of the requested format; name the
+            // artifact after what actually came back.
+            const extension = generated.contentType.includes("wav") ? "wav" : "mp3";
+            const stored = await ctx.storage.putBuffer(`speech.${extension}`, generated.bytes, {
+                contentType: generated.contentType,
+                kind: "audio",
+                metadata: {
+                    primitive: "tts",
+                    provider,
+                    model,
+                    voice: payload.voice ?? null,
+                    styleInstructions: payload.instructions ?? null
+                }
+            });
+            ctx.logger.progress(1, "Speech generation complete");
+            return {
+                progress: 1,
+                output: {
+                    files: compactUrls([stored.url]),
+                    primary_file_url: stored.url,
+                    audioUrl: stored.url,
+                    audio: {
+                        file_url: stored.url,
+                        content_type: generated.contentType,
+                        provider,
+                        model,
+                        voice: payload.voice ?? null,
+                        style_instructions: payload.instructions ?? null,
+                        text_length: payload.text.length
+                    }
+                }
+            };
+        }
+    }
+});
+const sttPrimitive = definePrimitive({
+    id: PRIMITIVE_STT_ID,
+    kind: "stt",
+    operations: {
+        run: {
+            description: "Transcribe speech from a video or audio URL (STT) into a simple subtitle transcript plus speaker-attributed multi-narration segments.",
+            inputSchema: sttPayloadSchema,
+            workflow: "run"
+        }
+    },
+    jobs: {
+        async run(ctx, input) {
+            const payload = sttPayloadSchema.parse(input);
+            const sourceKind = payload.media_type === "auto" ? inferSpeechSourceKind(payload.source_url) : payload.media_type;
+            let audioBytes;
+            let audioContentType;
+            let extractionMetadata = null;
+            if (sourceKind === "audio") {
+                ctx.logger.progress(0.1, "Fetching source audio");
+                const response = await fetch(payload.source_url);
+                if (!response.ok) {
+                    throw new Error(`Could not fetch source audio (${response.status}).`);
+                }
+                audioBytes = new Uint8Array(await response.arrayBuffer());
+                audioContentType = response.headers.get("content-type")?.split(";")[0]?.trim() || "audio/mpeg";
+            }
+            else {
+                // Videos (and unknown extensions) go through the ffmpeg seam: it
+                // demuxes video AND normalizes odd audio containers into a small
+                // mono mp3 the speech providers accept.
+                ctx.logger.progress(0.1, "Extracting audio track from source", {
+                    executionMode: config.VIDFARM_PRIMITIVE_MEDIA_LAMBDA_URL ? "lambda" : "local_fallback"
+                });
+                const extracted = await executePrimitiveMediaOperation(ctx, {
+                    operation: "video_extract_audio",
+                    payload: {
+                        source_video_url: payload.source_url,
+                        output_format: "mp3",
+                        audio_bitrate_kbps: 64
+                    },
+                    outputKey: "source-audio.mp3"
+                });
+                if (!extracted.publicUrl) {
+                    throw new Error("Audio extraction produced no readable audio URL.");
+                }
+                const response = await fetch(extracted.publicUrl);
+                if (!response.ok) {
+                    throw new Error(`Could not read extracted audio (${response.status}).`);
+                }
+                audioBytes = new Uint8Array(await response.arrayBuffer());
+                audioContentType = extracted.contentType || "audio/mpeg";
+                extractionMetadata = extracted.metadata ?? null;
+            }
+            if (audioBytes.byteLength > MAX_TRANSCRIBE_AUDIO_BYTES) {
+                const sizeMb = Math.round(audioBytes.byteLength / (1024 * 1024));
+                const maxMb = Math.round(MAX_TRANSCRIBE_AUDIO_BYTES / (1024 * 1024));
+                throw new Error(`Audio is too large to transcribe (${sizeMb}MB > ${maxMb}MB, roughly 40 minutes of speech). Trim the source with /videos/trim or /audio/trim and transcribe in parts.`);
+            }
+            ctx.logger.progress(0.45, "Transcribing speech");
+            const provider = payload.provider ?? "gemini";
+            const model = payload.model ?? defaultSpeechModelFor("stt", provider) ?? "";
+            const transcription = await ctx.providers.transcribeSpeech({
+                provider,
+                model,
+                audio: audioBytes,
+                contentType: audioContentType,
+                prompt: payload.prompt,
+                language: payload.language,
+                diarize: payload.diarize
+            });
+            ctx.logger.progress(0.85, "Storing transcript artifacts");
+            const speakers = [...new Set(transcription.segments.map((segment) => segment.speaker))];
+            const srt = buildSrtFromSegments(transcription.segments);
+            const storedText = await ctx.storage.putText("transcript.txt", transcription.text || "");
+            const storedSrt = srt ? await ctx.storage.putText("transcript.srt", srt, "application/x-subrip; charset=utf-8") : null;
+            const storedJson = await ctx.storage.putJson("transcript.json", {
+                source_url: payload.source_url,
+                provider,
+                model,
+                language: transcription.language,
+                diarization: transcription.diarization,
+                text: transcription.text,
+                speakers,
+                segments: transcription.segments,
+                ...(extractionMetadata ? { extraction: extractionMetadata } : {})
+            });
+            const inlineOk = (transcription.text?.length ?? 0) <= MAX_INLINE_TRANSCRIPT_CHARS;
+            ctx.logger.progress(1, "Speech transcription complete");
+            return {
+                progress: 1,
+                output: {
+                    files: compactUrls([storedJson.url, storedSrt?.url, storedText.url]),
+                    primary_file_url: storedJson.url,
+                    sourceUrl: payload.source_url,
+                    text: inlineOk ? transcription.text : transcription.text.slice(0, MAX_INLINE_TRANSCRIPT_CHARS),
+                    text_truncated: !inlineOk,
+                    language: transcription.language,
+                    diarization: transcription.diarization,
+                    // Format 1 — SIMPLE SUBTITLE VERSION: plain transcript + SRT cues (no speakers).
+                    subtitles: {
+                        srt: inlineOk ? srt : null,
+                        srt_url: storedSrt?.url ?? null,
+                        text_url: storedText.url
+                    },
+                    // Format 2 — ADVANCED MULTI-SPEAKER VERSION: speaker-attributed timed segments.
+                    speakers,
+                    segments: inlineOk ? transcription.segments : undefined,
+                    transcript: {
+                        json_url: storedJson.url,
+                        content_type: "application/json"
+                    }
+                }
+            };
+        }
+    }
+});
 const videoProbePrimitive = definePrimitive({
     id: PRIMITIVE_VIDEO_PROBE_ID,
     kind: "video_probe",
@@ -2142,6 +2378,8 @@ class PrimitiveRegistry {
         [videoConcatPrimitive.id, videoConcatPrimitive],
         [audioConcatPrimitive.id, audioConcatPrimitive],
         [audioNormalizePrimitive.id, audioNormalizePrimitive],
+        [ttsPrimitive.id, ttsPrimitive],
+        [sttPrimitive.id, sttPrimitive],
         [hyperframesRenderPrimitive.id, hyperframesRenderPrimitive],
         [brainstormHooksPrimitive.id, brainstormHooksPrimitive],
         [brainstormAwarenessStagesPrimitive.id, brainstormAwarenessStagesPrimitive],
@@ -2266,6 +2504,11 @@ function defaultTextModelForProvider(provider) {
             return "gpt-5.4-mini";
     }
 }
+// Extensions that are safe to feed a speech provider without the ffmpeg
+// normalization pass; everything else (video or unknown) gets demuxed first.
+function inferSpeechSourceKind(sourceUrl) {
+    return /\.(mp3|m4a|aac|ogg|oga|flac|wav)(\?|#|$)/i.test(sourceUrl) ? "audio" : "video";
+}
 function normalizeAiVideoDurationSeconds(explicitSeconds, milliseconds) {
     const seconds = Number(explicitSeconds);
     if (Number.isFinite(seconds) && seconds > 0) {

package/dist/src/services/captions.js

@@ -0,0 +1,123 @@
+// Turns a transcript into animated-caption cues. Shared by the devcli
+// `captions` command group, the /editor chat agent's set_captions action, and
+// any server surface that wants captions from STT output. Pure — no network,
+// no filesystem — so it is safe to import from the devcli.
+//
+// A "cue" is one caption layer on the timeline: a short run of words shown
+// together (CapCut-style pages of ~3-5 words), with per-word windows relative
+// to the cue start driving the animation. Word timings come from the provider
+// when available (openai whisper-1) and are char-weight estimated inside each
+// segment otherwise (gemini estimates, hand-typed text) — see
+// estimateCaptionWords.
+import { estimateCaptionWords } from "../hyperframes/composition.js";
+const CUE_TAIL_SEC = 0.12;
+const MIN_WORD_SPAN_SEC = 0.05;
+/** Flattens transcript segments into absolute-timed words, estimating windows
+ * for segments the provider left word-less (or entirely time-less — those
+ * distribute across fallbackDurationSec). */
+export function transcriptWordTimeline(segments, fallbackDurationSec) {
+    const words = [];
+    const timeless = segments.filter((segment) => typeof segment.start_sec !== "number");
+    for (const segment of segments) {
+        if (segment.words?.length) {
+            words.push(...segment.words.map((word) => ({ ...word, text: word.text.trim() })).filter((word) => word.text));
+            continue;
+        }
+        let base;
+        let span;
+        if (typeof segment.start_sec === "number") {
+            base = segment.start_sec;
+            span = typeof segment.end_sec === "number" && segment.end_sec > segment.start_sec
+                ? segment.end_sec - segment.start_sec
+                : 0;
+        }
+        else {
+            // No timings at all (plain-text providers): spread the blob across the
+            // caller-provided window so captions still land somewhere sensible.
+            base = 0;
+            span = Number.isFinite(fallbackDurationSec) && fallbackDurationSec > 0 && timeless.length
+                ? fallbackDurationSec / timeless.length
+                : 0;
+            if (timeless.length > 1) {
+                base = (span || 0) * timeless.indexOf(segment);
+            }
+        }
+        const estimated = estimateCaptionWords(segment.text, span);
+        words.push(...estimated.map((word) => ({
+            text: word.text,
+            start_sec: base + word.start,
+            end_sec: base + word.end
+        })));
+    }
+    return words
+        .filter((word) => Number.isFinite(word.start_sec) && Number.isFinite(word.end_sec) && word.end_sec > word.start_sec)
+        .sort((a, b) => a.start_sec - b.start_sec);
+}
+export function buildCaptionCues(segments, options) {
+    const words = transcriptWordTimeline(segments, options?.fallbackDurationSec);
+    return cuesFromWordTimeline(words, options);
+}
+export function cuesFromWordTimeline(words, options) {
+    const maxWords = Math.max(1, Math.round(options?.maxWordsPerCue ?? 4));
+    const maxDuration = Math.max(0.4, options?.maxCueDurationSec ?? 2.6);
+    const gapBreak = Math.max(0.15, options?.gapBreakSec ?? 0.6);
+    const offset = Number.isFinite(options?.offsetSec) ? options?.offsetSec : 0;
+    const cues = [];
+    let bucket = [];
+    const flush = () => {
+        if (!bucket.length)
+            return;
+        const start = bucket[0].start_sec;
+        const end = bucket[bucket.length - 1].end_sec + CUE_TAIL_SEC;
+        cues.push({
+            text: bucket.map((word) => word.text).join(" "),
+            start: round3(start + offset),
+            duration: round3(Math.max(MIN_WORD_SPAN_SEC * bucket.length, end - start)),
+            words: bucket.map((word) => ({
+                text: word.text,
+                start: round3(Math.max(0, word.start_sec - start)),
+                end: round3(Math.max(word.start_sec - start + MIN_WORD_SPAN_SEC, word.end_sec - start))
+            }))
+        });
+        bucket = [];
+    };
+    for (const word of words) {
+        if (bucket.length) {
+            const cueStart = bucket[0].start_sec;
+            const previous = bucket[bucket.length - 1];
+            const silence = word.start_sec - previous.end_sec;
+            const wouldRun = word.end_sec - cueStart;
+            const sentenceBreak = /[.!?…]["')\]]?$/.test(previous.text);
+            if (bucket.length >= maxWords || silence > gapBreak || wouldRun > maxDuration || sentenceBreak) {
+                flush();
+            }
+        }
+        bucket.push(word);
+    }
+    flush();
+    // Clamp each cue against the next so consecutive caption layers never
+    // overlap on the shared track (one-clip-per-(track,time) invariant).
+    for (let index = 0; index < cues.length - 1; index += 1) {
+        const cue = cues[index];
+        const next = cues[index + 1];
+        const maxEnd = next.start - 0.02;
+        if (cue.start + cue.duration > maxEnd) {
+            cue.duration = round3(Math.max(MIN_WORD_SPAN_SEC, maxEnd - cue.start));
+        }
+    }
+    return cues.filter((cue) => cue.duration > 0);
+}
+/** Cues straight from plain text spread across a window — the no-transcript
+ * path (AI-authored captions, manual cue text). */
+export function cuesFromText(text, startSec, durationSec, options) {
+    const words = estimateCaptionWords(text, durationSec).map((word) => ({
+        text: word.text,
+        start_sec: startSec + word.start,
+        end_sec: startSec + word.end
+    }));
+    return cuesFromWordTimeline(words, options);
+}
+function round3(value) {
+    return Number(value.toFixed(3));
+}
+//# sourceMappingURL=captions.js.map

package/dist/src/services/hyperframes.js

@@ -13,7 +13,7 @@ import ffprobeStatic from "ffprobe-static";
 import { parseHTML } from "linkedom";
 import { config } from "../config.js";
 import { devErrorFields, devLog } from "../lib/dev-log.js";
-import { KEN_BURNS_CSS, KEN_BURNS_STYLE_MARKER, buildHyperframeCompositionHtml } from "../hyperframes/composition.js";
+import { CAPTION_ANIM_CSS, CAPTION_STYLE_MARKER, KEN_BURNS_CSS, KEN_BURNS_STYLE_MARKER, TRANSITION_ADJACENCY_EPSILON, TRANSITION_CSS, TRANSITION_PRESETS, TRANSITION_STYLE_MARKER, buildHyperframeCompositionHtml, clampTransitionDuration } from "../hyperframes/composition.js";
 import { applyMarkupUsd } from "./billing-pricing.js";
 // The scene-annotation pass reuses the clip library's controlled vocabulary and
 // embedding-text recipe verbatim so a source scene's clip-match query is
@@ -2296,6 +2296,102 @@ function compositionHasCoverageGap(intervals, total, minGap = 0.2) {
     }
     return cursor < total - minGap;
 }
+// Scene transitions: the INCOMING clip carries data-transition and its vf-tr-*
+// animation plays over the clip's first data-transition-duration seconds — the
+// render engine's CSS adapter scrubs that on its own. What the render engine
+// canNOT do is keep the OUTGOING clip on screen beneath it (visibility is
+// derived strictly from data-start/data-duration), so materialize the overlap
+// here: extend the previous same-track butt-cut clip's data-duration by the
+// transition length. The granted extension is recorded in data-transition-hold
+// so the pass is idempotent and self-healing — every run first restores each
+// clip's nominal duration (duration - hold), then re-grants from the current
+// set of [data-transition] clips (so removed/retimed transitions shrink their
+// neighbor back). Stored drafts stay butt-cut; only publish/render output
+// carries the overlap. The preview runtime applies the same window live.
+function materializeTransitionOverlaps(document) {
+    const clips = [];
+    for (const el of Array.from(document.querySelectorAll("[data-start]"))) {
+        if (el.hasAttribute("data-composition-id"))
+            continue;
+        const start = Number.parseFloat(el.getAttribute("data-start") || "");
+        const duration = Number.parseFloat(el.getAttribute("data-duration") || "");
+        if (!Number.isFinite(start) || !Number.isFinite(duration) || duration <= 0)
+            continue;
+        const priorHold = Number.parseFloat(el.getAttribute("data-transition-hold") || "");
+        const hold = Number.isFinite(priorHold) && priorHold > 0 ? Math.min(priorHold, duration) : 0;
+        clips.push({
+            el,
+            track: Number.parseInt(el.getAttribute("data-track-index") || "0", 10) || 0,
+            start,
+            nominal: duration - hold,
+            hold: 0
+        });
+    }
+    if (!clips.length)
+        return;
+    for (const clip of clips) {
+        const transitionEl = clip.el;
+        const preset = transitionEl.getAttribute("data-transition");
+        if (!preset)
+            continue;
+        if (!TRANSITION_PRESETS.includes(preset)) {
+            // Unknown preset would render as a permanently-paused animation with no
+            // keyframes — harmless — but drop it so agents get clean state back.
+            transitionEl.removeAttribute("data-transition");
+            transitionEl.removeAttribute("data-transition-duration");
+            continue;
+        }
+        const tagName = transitionEl.tagName?.toLowerCase?.() ?? "";
+        if (tagName === "audio") {
+            transitionEl.removeAttribute("data-transition");
+            transitionEl.removeAttribute("data-transition-duration");
+            continue;
+        }
+        // The animation cannot outlast its own clip.
+        const duration = Math.min(clampTransitionDuration(transitionEl.getAttribute("data-transition-duration")), clip.nominal);
+        const durationValue = Number(duration.toFixed(3));
+        transitionEl.setAttribute("data-transition-duration", String(durationValue));
+        // Keep the inline var (which drives animation-duration) in lockstep, same
+        // as the --vf-kb-dur re-derivation above.
+        const styleValue = transitionEl.getAttribute("style") || "";
+        const durDecl = `--vf-tr-dur:${durationValue}s`;
+        const nextStyle = /(^|;)\s*--vf-tr-dur\s*:[^;]*/i.test(styleValue)
+            ? styleValue.replace(/(^|;)\s*--vf-tr-dur\s*:[^;]*/i, (_match, lead) => `${lead}${durDecl}`)
+            : styleValue.length === 0 || styleValue.endsWith(";")
+                ? `${styleValue}${durDecl}`
+                : `${styleValue};${durDecl}`;
+        if (nextStyle !== styleValue)
+            transitionEl.setAttribute("style", nextStyle);
+        // Grant the hold to the clip this one cuts away from: same track, nominal
+        // end at (within epsilon of) this clip's start.
+        for (const candidate of clips) {
+            if (candidate === clip || candidate.track !== clip.track)
+                continue;
+            if (Math.abs(candidate.start + candidate.nominal - clip.start) > TRANSITION_ADJACENCY_EPSILON)
+                continue;
+            const candidateTag = candidate.el.tagName?.toLowerCase?.() ?? "";
+            if (candidateTag === "audio")
+                continue;
+            candidate.hold = Math.max(candidate.hold, duration);
+        }
+    }
+    for (const clip of clips) {
+        const nextDuration = Number((clip.nominal + clip.hold).toFixed(3));
+        const currentDuration = Number.parseFloat(clip.el.getAttribute("data-duration") || "");
+        if (currentDuration !== nextDuration) {
+            clip.el.setAttribute("data-duration", String(nextDuration));
+        }
+        if (clip.el.hasAttribute("data-end")) {
+            clip.el.setAttribute("data-end", String(Number((clip.start + nextDuration).toFixed(3))));
+        }
+        if (clip.hold > 0) {
+            clip.el.setAttribute("data-transition-hold", String(Number(clip.hold.toFixed(3))));
+        }
+        else {
+            clip.el.removeAttribute("data-transition-hold");
+        }
+    }
+}
 export function normalizePublishHtml(html) {
     const { document } = parseHTML(html);
     // Coverage gaps: any interval of the timeline with no active canvas-filling
@@ -2412,6 +2508,22 @@ export function normalizePublishHtml(html) {
         styleEl.textContent = KEN_BURNS_CSS;
         (document.head ?? document.documentElement)?.appendChild(styleEl);
     }
+    // Animated captions: word windows are stored relative to the layer start
+    // (inline animation-delay/duration on each [data-cap-word]), so retimes need
+    // no re-derivation — but the shared vf-cap-* keyframes stylesheet must
+    // travel with compositions stored before the builder embedded it, or every
+    // word renders in its resting state.
+    if (document.querySelector("[data-caption-animation]") && !html.includes(CAPTION_STYLE_MARKER)) {
+        const styleEl = document.createElement("style");
+        styleEl.textContent = CAPTION_ANIM_CSS;
+        (document.head ?? document.documentElement)?.appendChild(styleEl);
+    }
+    materializeTransitionOverlaps(document);
+    if (document.querySelector("[data-transition]") && !html.includes(TRANSITION_STYLE_MARKER)) {
+        const styleEl = document.createElement("style");
+        styleEl.textContent = TRANSITION_CSS;
+        (document.head ?? document.documentElement)?.appendChild(styleEl);
+    }
     // Editor sessions occasionally leave inline style attributes with double
     // quotes inside CSS values (font-family: "TikTok Sans"). When serialized into
     // an HTML attribute, those quotes become &quot; entities. The render lambda

package/dist/src/services/provider-errors.js

@@ -0,0 +1,77 @@
+// Provider error taxonomy + HTTP-response classification, shared by every
+// surface that talks to an AI provider directly: ProviderService (cloud, leased
+// BYOK keys) and the speech module (also driven key-less from the devcli with a
+// local env key). Lives outside providers.ts so speech.ts can import it without
+// a circular dependency.
+export class ProviderKeyUnavailableError extends Error {
+}
+export class ProviderAuthError extends Error {
+}
+/** A TTS voice preset that belongs to a different provider family — user input error, never retryable. */
+export class SpeechVoiceMismatchError extends Error {
+}
+export class ProviderQuotaExceededError extends Error {
+}
+export class ProviderWaitExceededError extends Error {
+}
+export class ProviderLeaseTimeoutError extends Error {
+    retryAfterSeconds;
+    constructor(message, retryAfterSeconds = 5) {
+        super(message);
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+}
+export class ProviderRateLimitError extends Error {
+    retryAfterSeconds;
+    constructor(message, retryAfterSeconds = 60) {
+        super(message);
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+}
+export class ProviderTransientError extends Error {
+    retryAfterSeconds;
+    constructor(message, retryAfterSeconds = 5) {
+        super(message);
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+}
+export function parseRetryAfterSeconds(value) {
+    if (!value) {
+        return 60;
+    }
+    const numeric = Number(value);
+    if (Number.isFinite(numeric) && numeric > 0) {
+        return Math.max(1, Math.min(Math.ceil(numeric), 60 * 60));
+    }
+    const parsedDate = Date.parse(value);
+    if (Number.isFinite(parsedDate)) {
+        return Math.max(1, Math.min(Math.ceil((parsedDate - Date.now()) / 1000), 60 * 60));
+    }
+    return 60;
+}
+export function isHardQuotaError(details) {
+    const normalized = details.toLowerCase();
+    return [
+        "insufficient_quota",
+        "quota_exceeded",
+        "exceeded your current quota",
+        "billing",
+        "insufficient credits",
+        "not enough credits",
+        "credit balance",
+        "prepaid credits",
+        "resource_exhausted"
+    ].some((pattern) => normalized.includes(pattern));
+}
+export function conciseProviderDetails(details) {
+    const compact = details.replace(/\s+/g, " ").trim();
+    return compact ? `: ${compact.slice(0, 500)}` : "";
+}
+export async function rateLimitOrQuotaError(provider, response) {
+    const details = await response.text();
+    if (isHardQuotaError(details)) {
+        return new ProviderQuotaExceededError(`${provider} quota or billing limit was reached${conciseProviderDetails(details)}`);
+    }
+    return new ProviderRateLimitError(`${provider} rate limited${conciseProviderDetails(details)}`, parseRetryAfterSeconds(response.headers.get("retry-after")));
+}
+//# sourceMappingURL=provider-errors.js.map