@mevdragon/vidfarm-devcli 0.11.0 → 0.13.0

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"