@mevdragon/vidfarm-devcli 0.13.0 → 0.15.0

package/dist/src/hyperframes/composition.js

@@ -98,10 +98,16 @@ export function normalizeKenBurns(value) {
 export const TRANSITION_PRESETS = [
     "crossfade",
     "fade-black",
+    "fade-white",
+    "flash",
+    "smoke",
+    "blur",
     "slide-left",
     "slide-right",
     "slide-up",
     "slide-down",
+    "whip-left",
+    "whip-right",
     "wipe-left",
     "wipe-right",
     "wipe-up",
@@ -110,14 +116,49 @@ export const TRANSITION_PRESETS = [
     "zoom-out",
     "circle-open"
 ];
+// Exit transitions: the clip animates AWAY over its last data-transition-out-
+// duration seconds. Same declarative contract as the entrance presets; the
+// keyframes omit the `from` state so the animation departs from the element's
+// own inline styles, and the inline --vf-tr-out-delay var (clip duration minus
+// out duration) positions the animation window at the clip's tail so the
+// time-based scrub in the producer and preview runtimes needs no extra logic.
+export const TRANSITION_OUT_PRESETS = [
+    "fade",
+    "fade-black",
+    "fade-white",
+    "flash",
+    "smoke",
+    "blur",
+    "slide-left",
+    "slide-right",
+    "slide-up",
+    "slide-down",
+    "wipe-left",
+    "wipe-right",
+    "wipe-up",
+    "wipe-down",
+    "zoom-in",
+    "zoom-out",
+    "circle-close"
+];
 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}*/
+// V2: entrance AND exit animations compose on one element via cascading custom
+// properties (--vf-tr-in-name / --vf-tr-out-name) feeding a two-slot animation
+// list — per-preset attribute selectors can't merge two animation-names, vars
+// can. The [data-kenburns] combo rules below fix a V1 latent clash where Ken
+// Burns and a transition on the same <img> fought over animation-name (equal
+// specificity, last stylesheet won); the (0,2,0) combo selectors prepend the
+// vf-kb animation to the list instead.
+export const TRANSITION_STYLE_MARKER = "__VF_TRANSITIONS_V2__";
+// The exact V1 block previous builds baked into stored compositions. Injectors
+// string-replace this with the current TRANSITION_CSS so old drafts/publishes
+// upgrade in place instead of accumulating duplicate style blocks.
+export const LEGACY_TRANSITION_CSS_V1 = `/*__VF_TRANSITIONS_V1__*/
 @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; } }
@@ -151,12 +192,119 @@ export const TRANSITION_CSS = `/*${TRANSITION_STYLE_MARKER}*/
 [data-transition="zoom-out"] { animation-name: vf-tr-zoom-out; }
 [data-transition="circle-open"] { animation-name: vf-tr-circle-open; }
 `;
+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-fade-white { 0% { opacity: 0; filter: saturate(0.55) brightness(3); } 45% { opacity: 1; filter: saturate(0.7) brightness(2.1); } }
+@keyframes vf-tr-flash { 0% { filter: saturate(0.3) brightness(5); } 55% { filter: saturate(0.9) brightness(1.6); } }
+@keyframes vf-tr-smoke { 0% { opacity: 0; filter: blur(26px) saturate(0.65) brightness(1.55); } 55% { opacity: 1; } }
+@keyframes vf-tr-blur { from { opacity: 0; filter: blur(16px); } }
+@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-whip-left { 0% { translate: 110% 0; filter: blur(14px); } 60% { filter: blur(5px); } }
+@keyframes vf-tr-whip-right { 0% { translate: -110% 0; filter: blur(14px); } 60% { filter: blur(5px); } }
+@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%); } }
+@keyframes vf-tr-out-fade { to { opacity: 0; } }
+@keyframes vf-tr-out-fade-black { to { filter: brightness(0); } }
+@keyframes vf-tr-out-fade-white { to { filter: saturate(0.35) brightness(6); } }
+@keyframes vf-tr-out-flash { 65% { filter: brightness(1); } 100% { filter: saturate(0.3) brightness(5); } }
+@keyframes vf-tr-out-smoke { to { opacity: 0; filter: blur(24px) saturate(0.7) brightness(1.5); } }
+@keyframes vf-tr-out-blur { to { opacity: 0; filter: blur(16px); } }
+@keyframes vf-tr-out-slide-left { to { translate: -100% 0; } }
+@keyframes vf-tr-out-slide-right { to { translate: 100% 0; } }
+@keyframes vf-tr-out-slide-up { to { translate: 0 -100%; } }
+@keyframes vf-tr-out-slide-down { to { translate: 0 100%; } }
+@keyframes vf-tr-out-wipe-left { from { clip-path: inset(0 0 0 0); } to { clip-path: inset(0 100% 0 0); } }
+@keyframes vf-tr-out-wipe-right { from { clip-path: inset(0 0 0 0); } to { clip-path: inset(0 0 0 100%); } }
+@keyframes vf-tr-out-wipe-up { from { clip-path: inset(0 0 0 0); } to { clip-path: inset(0 0 100% 0); } }
+@keyframes vf-tr-out-wipe-down { from { clip-path: inset(0 0 0 0); } to { clip-path: inset(100% 0 0 0); } }
+@keyframes vf-tr-out-zoom-in { to { opacity: 0; scale: 1.18; } }
+@keyframes vf-tr-out-zoom-out { to { opacity: 0; scale: 0.82; } }
+@keyframes vf-tr-out-circle-close { from { clip-path: circle(75% at 50% 50%); } to { clip-path: circle(0% at 50% 50%); } }
+[data-transition], [data-transition-out] {
+  animation-name: var(--vf-tr-in-name, none), var(--vf-tr-out-name, none);
+  animation-duration: var(--vf-tr-dur, 0.5s), var(--vf-tr-out-dur, 0.5s);
+  animation-delay: 0s, var(--vf-tr-out-delay, 0s);
+  animation-timing-function: var(--vf-tr-ease, ease-in-out), var(--vf-tr-out-ease, ease-in-out);
+  animation-fill-mode: both, both;
+  animation-play-state: paused, paused;
+}
+[data-kenburns][data-transition], [data-kenburns][data-transition-out] {
+  animation-name: var(--vf-kb-name, none), var(--vf-tr-in-name, none), var(--vf-tr-out-name, none);
+  animation-duration: var(--vf-kb-dur, 5s), var(--vf-tr-dur, 0.5s), var(--vf-tr-out-dur, 0.5s);
+  animation-delay: 0s, 0s, var(--vf-tr-out-delay, 0s);
+  animation-timing-function: var(--vf-kb-ease, linear), var(--vf-tr-ease, ease-in-out), var(--vf-tr-out-ease, ease-in-out);
+  animation-fill-mode: both, both, both;
+  animation-play-state: paused, paused, paused;
+}
+[data-kenburns="zoom-in"] { --vf-kb-name: vf-kb-zoom-in; }
+[data-kenburns="zoom-out"] { --vf-kb-name: vf-kb-zoom-out; }
+[data-kenburns="pan-left"] { --vf-kb-name: vf-kb-pan-left; }
+[data-kenburns="pan-right"] { --vf-kb-name: vf-kb-pan-right; }
+[data-kenburns="pan-up"] { --vf-kb-name: vf-kb-pan-up; }
+[data-kenburns="pan-down"] { --vf-kb-name: vf-kb-pan-down; }
+[data-kenburns="zoom-in-left"] { --vf-kb-name: vf-kb-zoom-in-left; }
+[data-kenburns="zoom-in-right"] { --vf-kb-name: vf-kb-zoom-in-right; }
+[data-transition="crossfade"] { --vf-tr-in-name: vf-tr-crossfade; }
+[data-transition="fade-black"] { --vf-tr-in-name: vf-tr-fade-black; }
+[data-transition="fade-white"] { --vf-tr-in-name: vf-tr-fade-white; }
+[data-transition="flash"] { --vf-tr-in-name: vf-tr-flash; --vf-tr-ease: cubic-bezier(0.3, 0, 0.55, 1); }
+[data-transition="smoke"] { --vf-tr-in-name: vf-tr-smoke; --vf-tr-ease: cubic-bezier(0.25, 0.4, 0.3, 1); }
+[data-transition="blur"] { --vf-tr-in-name: vf-tr-blur; }
+[data-transition="slide-left"] { --vf-tr-in-name: vf-tr-slide-left; --vf-tr-ease: cubic-bezier(0.22, 1, 0.36, 1); }
+[data-transition="slide-right"] { --vf-tr-in-name: vf-tr-slide-right; --vf-tr-ease: cubic-bezier(0.22, 1, 0.36, 1); }
+[data-transition="slide-up"] { --vf-tr-in-name: vf-tr-slide-up; --vf-tr-ease: cubic-bezier(0.22, 1, 0.36, 1); }
+[data-transition="slide-down"] { --vf-tr-in-name: vf-tr-slide-down; --vf-tr-ease: cubic-bezier(0.22, 1, 0.36, 1); }
+[data-transition="whip-left"] { --vf-tr-in-name: vf-tr-whip-left; --vf-tr-ease: cubic-bezier(0.16, 1, 0.3, 1); }
+[data-transition="whip-right"] { --vf-tr-in-name: vf-tr-whip-right; --vf-tr-ease: cubic-bezier(0.16, 1, 0.3, 1); }
+[data-transition="wipe-left"] { --vf-tr-in-name: vf-tr-wipe-left; --vf-tr-ease: cubic-bezier(0.45, 0.05, 0.35, 0.95); }
+[data-transition="wipe-right"] { --vf-tr-in-name: vf-tr-wipe-right; --vf-tr-ease: cubic-bezier(0.45, 0.05, 0.35, 0.95); }
+[data-transition="wipe-up"] { --vf-tr-in-name: vf-tr-wipe-up; --vf-tr-ease: cubic-bezier(0.45, 0.05, 0.35, 0.95); }
+[data-transition="wipe-down"] { --vf-tr-in-name: vf-tr-wipe-down; --vf-tr-ease: cubic-bezier(0.45, 0.05, 0.35, 0.95); }
+[data-transition="zoom-in"] { --vf-tr-in-name: vf-tr-zoom-in; --vf-tr-ease: cubic-bezier(0.16, 1, 0.3, 1); }
+[data-transition="zoom-out"] { --vf-tr-in-name: vf-tr-zoom-out; --vf-tr-ease: cubic-bezier(0.16, 1, 0.3, 1); }
+[data-transition="circle-open"] { --vf-tr-in-name: vf-tr-circle-open; --vf-tr-ease: cubic-bezier(0.3, 0.6, 0.3, 1); }
+[data-transition-out="fade"] { --vf-tr-out-name: vf-tr-out-fade; }
+[data-transition-out="fade-black"] { --vf-tr-out-name: vf-tr-out-fade-black; }
+[data-transition-out="fade-white"] { --vf-tr-out-name: vf-tr-out-fade-white; }
+[data-transition-out="flash"] { --vf-tr-out-name: vf-tr-out-flash; --vf-tr-out-ease: cubic-bezier(0.45, 0, 0.7, 0.4); }
+[data-transition-out="smoke"] { --vf-tr-out-name: vf-tr-out-smoke; --vf-tr-out-ease: cubic-bezier(0.7, 0, 0.75, 0.6); }
+[data-transition-out="blur"] { --vf-tr-out-name: vf-tr-out-blur; }
+[data-transition-out="slide-left"] { --vf-tr-out-name: vf-tr-out-slide-left; --vf-tr-out-ease: cubic-bezier(0.55, 0.06, 0.68, 0.19); }
+[data-transition-out="slide-right"] { --vf-tr-out-name: vf-tr-out-slide-right; --vf-tr-out-ease: cubic-bezier(0.55, 0.06, 0.68, 0.19); }
+[data-transition-out="slide-up"] { --vf-tr-out-name: vf-tr-out-slide-up; --vf-tr-out-ease: cubic-bezier(0.55, 0.06, 0.68, 0.19); }
+[data-transition-out="slide-down"] { --vf-tr-out-name: vf-tr-out-slide-down; --vf-tr-out-ease: cubic-bezier(0.55, 0.06, 0.68, 0.19); }
+[data-transition-out="wipe-left"] { --vf-tr-out-name: vf-tr-out-wipe-left; --vf-tr-out-ease: cubic-bezier(0.45, 0.05, 0.35, 0.95); }
+[data-transition-out="wipe-right"] { --vf-tr-out-name: vf-tr-out-wipe-right; --vf-tr-out-ease: cubic-bezier(0.45, 0.05, 0.35, 0.95); }
+[data-transition-out="wipe-up"] { --vf-tr-out-name: vf-tr-out-wipe-up; --vf-tr-out-ease: cubic-bezier(0.45, 0.05, 0.35, 0.95); }
+[data-transition-out="wipe-down"] { --vf-tr-out-name: vf-tr-out-wipe-down; --vf-tr-out-ease: cubic-bezier(0.45, 0.05, 0.35, 0.95); }
+[data-transition-out="zoom-in"] { --vf-tr-out-name: vf-tr-out-zoom-in; --vf-tr-out-ease: cubic-bezier(0.5, 0, 0.75, 0.4); }
+[data-transition-out="zoom-out"] { --vf-tr-out-name: vf-tr-out-zoom-out; --vf-tr-out-ease: cubic-bezier(0.5, 0, 0.75, 0.4); }
+[data-transition-out="circle-close"] { --vf-tr-out-name: vf-tr-out-circle-close; --vf-tr-out-ease: cubic-bezier(0.6, 0, 0.7, 0.4); }
+`;
 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));
 }
+// Seconds into the clip at which its exit animation must start so it finishes
+// exactly at the clip's end. Written as the inline --vf-tr-out-delay var.
+export function transitionOutDelaySeconds(layerDurationSeconds, outDurationSeconds) {
+    const layerDuration = Number(layerDurationSeconds);
+    const outDuration = Number(outDurationSeconds);
+    if (!Number.isFinite(layerDuration) || !Number.isFinite(outDuration))
+        return 0;
+    return Math.max(0, Number((layerDuration - outDuration).toFixed(3)));
+}
 export function normalizeTransition(value) {
     if (!value)
         return null;
@@ -168,6 +316,28 @@ export function normalizeTransition(value) {
         duration: raw.duration !== undefined ? clampTransitionDuration(raw.duration) : undefined
     };
 }
+export function normalizeTransitionOut(value) {
+    if (!value)
+        return null;
+    const raw = typeof value === "string" ? { preset: value } : value;
+    if (!TRANSITION_OUT_PRESETS.includes(raw.preset))
+        return null;
+    return {
+        preset: raw.preset,
+        duration: raw.duration !== undefined ? clampTransitionDuration(raw.duration) : undefined
+    };
+}
+// Upgrades stored composition HTML that still carries the V1 transition
+// stylesheet: exact-replaces the legacy block with the current one. If the V1
+// marker is present but the block has drifted, callers' normal marker-guarded
+// injection appends the V2 block AFTER it, which also wins (equal-specificity
+// rules, later source order) — this replace just avoids duplicate blocks in
+// the common case.
+export function upgradeLegacyTransitionCss(html) {
+    if (!html || html.includes(TRANSITION_STYLE_MARKER) || !html.includes("__VF_TRANSITIONS_V1__"))
+        return html;
+    return html.split(LEGACY_TRANSITION_CSS_V1).join(TRANSITION_CSS);
+}
 // ---------------------------------------------------------------------------
 // Animated captions. Same declarative contract as Ken Burns: the caption layer
 // <div> (the element that owns data-start/data-duration) carries
@@ -405,12 +575,12 @@ function renderLayer(layer) {
             // data-start) and it plays across exactly the clip's span.
             const vars = kenBurnsInlineVars(kenBurns, positiveNumber(layer.duration, 0));
             const kbStyle = vars ? `${style};${vars}` : style;
-            return `<img ${attrs} data-kenburns="${escapeAttr(kenBurns.preset)}" src="${escapeAttr(layer.src || "")}" alt="" style="${escapeAttr(kbStyle)}" />`;
+            return `<img class="clip" ${attrs} data-kenburns="${escapeAttr(kenBurns.preset)}" src="${escapeAttr(layer.src || "")}" alt="" style="${escapeAttr(kbStyle)}" />`;
         }
-        return `<img ${attrs} src="${escapeAttr(layer.src || "")}" alt="" style="${escapeAttr(style)}" />`;
+        return `<img class="clip" ${attrs} src="${escapeAttr(layer.src || "")}" alt="" style="${escapeAttr(style)}" />`;
     }
     if (layer.kind === "html") {
-        return `<div ${attrs} style="${escapeAttr(style)}">${layer.html || ""}</div>`;
+        return `<div class="clip" ${attrs} style="${escapeAttr(style)}">${layer.html || ""}</div>`;
     }
     const text = layer.text ?? layer.label ?? "";
     const inlineStyle = textInlineCss(layer.textBackgroundStyle || "plain", layer.color || "#ffffff", layer.background || "#000000", layer.fontFamily || "TikTok Sans", positiveInteger(layer.fontWeight, 700));
@@ -435,10 +605,10 @@ function renderLayer(layer) {
             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 class="clip" ${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>`;
+    return `<div class="clip" ${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
@@ -476,6 +646,10 @@ function timedAttrs(layer) {
         if (transition) {
             attrs.push(`data-transition="${escapeAttr(transition.preset)}"`, `data-transition-duration="${num(clampTransitionDuration(transition.duration ?? TRANSITION_DEFAULT_DURATION))}"`);
         }
+        const transitionOut = normalizeTransitionOut(layer.transitionOut);
+        if (transitionOut) {
+            attrs.push(`data-transition-out="${escapeAttr(transitionOut.preset)}"`, `data-transition-out-duration="${num(clampTransitionDuration(transitionOut.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")}"`);
@@ -504,6 +678,13 @@ function layerStyle(layer) {
         if (transition) {
             styles.push(`--vf-tr-dur:${num(clampTransitionDuration(transition.duration ?? TRANSITION_DEFAULT_DURATION))}s`);
         }
+        // Exit transitions additionally need the delay var so the animation window
+        // sits at the clip's tail (duration − out duration).
+        const transitionOut = normalizeTransitionOut(layer.transitionOut);
+        if (transitionOut) {
+            const outDur = clampTransitionDuration(transitionOut.duration ?? TRANSITION_DEFAULT_DURATION);
+            styles.push(`--vf-tr-out-dur:${num(outDur)}s`, `--vf-tr-out-delay:${num(transitionOutDelaySeconds(positiveNumber(layer.duration, 0), outDur))}s`);
+        }
     }
     if (["caption", "text", "shape", "html"].includes(layer.kind)) {
         const fontFamily = layer.fontFamily || "TikTok Sans";

package/dist/src/services/composition-lint.js

@@ -0,0 +1,199 @@
+// Static composition validation shared by the /editor chat copilot
+// (replace_composition_html preflight, both the in-process and Lambda copies),
+// the devcli (`vidfarm lint`), and publish preflights. Mirrors the checks the
+// HyperFrames CLI's `lint` runs against raw projects, adapted to vidfarm's
+// composition vocabulary (data-vf-* proxies, transition holds, caption spans).
+import { parseHTML } from "linkedom";
+import { CAPTION_ANIMATIONS, KEN_BURNS_PRESETS, TRANSITION_OUT_PRESETS, TRANSITION_PRESETS } from "../hyperframes/composition.js";
+const OVERLAP_EPSILON = 0.011;
+function parseNumberAttr(value) {
+    if (typeof value !== "string" || !value.trim()) {
+        return null;
+    }
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function layerKeyFor(element) {
+    return (element.getAttribute("data-hf-id") ||
+        element.getAttribute("id") ||
+        element.getAttribute("data-hf-slug") ||
+        `<${element.tagName.toLowerCase()}>`);
+}
+export function lintCompositionHtml(html) {
+    const issues = [];
+    const push = (level, code, message, layer) => {
+        issues.push({ level, code, message, ...(layer ? { layer } : {}) });
+    };
+    const trimmed = typeof html === "string" ? html.trim() : "";
+    if (!trimmed) {
+        push("error", "empty_document", "Composition HTML is empty.");
+        return finalize(issues);
+    }
+    let document;
+    try {
+        ({ document } = parseHTML(trimmed));
+    }
+    catch (error) {
+        push("error", "unparseable_document", `Composition HTML could not be parsed: ${error instanceof Error ? error.message : String(error)}`);
+        return finalize(issues);
+    }
+    const root = document.querySelector("[data-composition-id]");
+    if (!root) {
+        push("error", "missing_composition_root", "No element carries data-composition-id — the composition root is required.");
+        return finalize(issues);
+    }
+    const width = parseNumberAttr(root.getAttribute("data-width"));
+    const height = parseNumberAttr(root.getAttribute("data-height"));
+    if (width === null || height === null) {
+        push("warning", "missing_canvas_size", "Composition root should declare numeric data-width and data-height (px).");
+    }
+    else if (width <= 0 || height <= 0) {
+        push("error", "invalid_canvas", `Composition root data-width/data-height must be positive (got ${width}x${height}).`);
+    }
+    const fpsRaw = root.getAttribute("data-fps");
+    if (fpsRaw !== null && (parseNumberAttr(fpsRaw) === null || parseNumberAttr(fpsRaw) <= 0)) {
+        push("warning", "invalid_fps", `Composition root data-fps is not a positive number (got "${fpsRaw}").`);
+    }
+    const clips = Array.from(document.querySelectorAll("[data-start]")).filter((el) => el !== root);
+    const rootDuration = parseNumberAttr(root.getAttribute("data-duration"));
+    if (rootDuration === null) {
+        if (clips.length === 0) {
+            push("error", "missing_root_duration", "Composition root has no data-duration and no timed clips to infer one from.");
+        }
+        else {
+            push("warning", "missing_root_duration", "Composition root has no data-duration; the runtime will infer it from the latest clip end. Declare it explicitly for deterministic renders.");
+        }
+    }
+    else if (rootDuration <= 0) {
+        push("error", "invalid_root_duration", `Composition root data-duration must be positive (got ${rootDuration}).`);
+    }
+    if (clips.length === 0) {
+        push("warning", "no_clips", "Composition has no timed clips ([data-start] elements).");
+    }
+    const timings = [];
+    const seenKeys = new Map();
+    for (const clip of clips) {
+        const key = layerKeyFor(clip);
+        const tag = clip.tagName.toLowerCase();
+        const isMedia = tag === "video" || tag === "audio";
+        const isProxy = clip.hasAttribute("data-vf-timeline-proxy");
+        const explicitKey = clip.getAttribute("data-hf-id") || clip.getAttribute("id");
+        if (explicitKey) {
+            seenKeys.set(explicitKey, (seenKeys.get(explicitKey) ?? 0) + 1);
+        }
+        const start = parseNumberAttr(clip.getAttribute("data-start"));
+        if (start === null || start < 0) {
+            push("error", "invalid_clip_timing", `Clip has a non-numeric or negative data-start ("${clip.getAttribute("data-start")}").`, key);
+            continue;
+        }
+        const duration = parseNumberAttr(clip.getAttribute("data-duration"));
+        if (duration === null) {
+            if (isMedia) {
+                push("warning", "media_missing_duration", "Media clip has no data-duration; it will fall back to the source's intrinsic length. Declare it for predictable trims.", key);
+            }
+            else {
+                push("error", "missing_clip_duration", "Non-media clip requires a positive data-duration.", key);
+            }
+        }
+        else if (duration <= 0) {
+            push("error", "invalid_clip_duration", `Clip data-duration must be positive (got ${duration}).`, key);
+        }
+        const trackRaw = clip.getAttribute("data-track-index");
+        const track = parseNumberAttr(trackRaw);
+        if (trackRaw === null || track === null || !Number.isInteger(track) || track < 0) {
+            push("warning", "missing_track_index", `Clip should declare an integer data-track-index >= 0 (got "${trackRaw ?? "<absent>"}").`, key);
+        }
+        // Nested clips fight parent visibility toggling and are unregistered in
+        // the upstream HyperFrames runtime (clips must be direct children).
+        let ancestor = clip.parentElement;
+        while (ancestor && ancestor !== root) {
+            if (ancestor.hasAttribute("data-start")) {
+                push("warning", "nested_clip", "Clip is nested inside another timed clip; move clips to the composition root.", key);
+                break;
+            }
+            ancestor = ancestor.parentElement;
+        }
+        if (isMedia && clip.parentElement && clip.parentElement !== root) {
+            push("warning", "nested_media", "video/audio elements should be direct children of the composition root — nested media renders blank/black under the HyperFrames runtime.", key);
+        }
+        if ((tag === "video" || tag === "img" || tag === "audio") && !isProxy) {
+            const src = clip.getAttribute("src") || clip.getAttribute("data-src");
+            const hasSourceChild = Boolean(clip.querySelector("source[src]"));
+            if (!src && !hasSourceChild) {
+                push("error", "media_missing_src", `<${tag}> clip has no src / data-src.`, key);
+            }
+        }
+        const kenBurns = clip.getAttribute("data-kenburns") ?? clip.querySelector("img[data-kenburns]")?.getAttribute("data-kenburns");
+        if (kenBurns && kenBurns !== "none" && !KEN_BURNS_PRESETS.includes(kenBurns)) {
+            push("error", "unknown_ken_burns", `Unknown data-kenburns preset "${kenBurns}".`, key);
+        }
+        const transition = clip.getAttribute("data-transition");
+        if (transition && transition !== "none" && !TRANSITION_PRESETS.includes(transition)) {
+            push("error", "unknown_transition", `Unknown data-transition preset "${transition}".`, key);
+        }
+        const transitionOut = clip.getAttribute("data-transition-out");
+        if (transitionOut && transitionOut !== "none" && !TRANSITION_OUT_PRESETS.includes(transitionOut)) {
+            push("error", "unknown_transition_out", `Unknown data-transition-out preset "${transitionOut}".`, key);
+        }
+        const captionAnimation = clip.getAttribute("data-caption-animation");
+        if (captionAnimation && captionAnimation !== "none" && !CAPTION_ANIMATIONS.includes(captionAnimation)) {
+            push("error", "unknown_caption_animation", `Unknown data-caption-animation preset "${captionAnimation}".`, key);
+        }
+        const effectiveDuration = duration !== null && duration > 0 ? duration : 0;
+        timings.push({
+            element: clip,
+            key,
+            start,
+            end: start + effectiveDuration,
+            track: track !== null && Number.isInteger(track) && track >= 0 ? track : null,
+            hasTransitionHold: clip.hasAttribute("data-transition-hold")
+        });
+    }
+    for (const [key, count] of seenKeys) {
+        if (count > 1) {
+            push("warning", "duplicate_layer_id", `Layer id "${key}" appears ${count} times; layer keys must be unique for editor/chat targeting.`);
+        }
+    }
+    // Same-track temporal overlap. Materialized transition holds
+    // (data-transition-hold) legitimately overlap their successor.
+    const byTrack = new Map();
+    for (const timing of timings) {
+        if (timing.track === null || timing.end <= timing.start) {
+            continue;
+        }
+        const bucket = byTrack.get(timing.track) ?? [];
+        bucket.push(timing);
+        byTrack.set(timing.track, bucket);
+    }
+    for (const [track, bucket] of byTrack) {
+        bucket.sort((a, b) => a.start - b.start || a.end - b.end);
+        for (let i = 1; i < bucket.length; i += 1) {
+            const prev = bucket[i - 1];
+            const current = bucket[i];
+            if (current.start < prev.end - OVERLAP_EPSILON && !prev.hasTransitionHold && !current.hasTransitionHold) {
+                push("error", "track_overlap", `Clips "${prev.key}" and "${current.key}" overlap on track ${track} (${prev.start}-${prev.end}s vs ${current.start}s start). Same-track clips must not overlap.`, current.key);
+            }
+        }
+    }
+    const scripts = document.querySelectorAll("script");
+    if (scripts.length > 0) {
+        push("warning", "scripts_stripped_on_save", `Composition contains ${scripts.length} <script> tag(s). Scripts survive local serve/disk renders, but every cloud/web editor save strips them (stored-XSS defense) — script-driven animation will be lost there. Prefer the declarative preset vocabulary (data-kenburns, data-transition, data-caption-animation) for compositions that round-trip through the web editor.`);
+    }
+    return finalize(issues);
+}
+function finalize(issues) {
+    const errors = issues.filter((issue) => issue.level === "error");
+    const warnings = issues.filter((issue) => issue.level === "warning");
+    return { ok: errors.length === 0, errors, warnings };
+}
+export function formatCompositionLintIssues(result) {
+    const lines = [];
+    for (const issue of result.errors) {
+        lines.push(`error  ${issue.code}${issue.layer ? ` [${issue.layer}]` : ""}: ${issue.message}`);
+    }
+    for (const issue of result.warnings) {
+        lines.push(`warn   ${issue.code}${issue.layer ? ` [${issue.layer}]` : ""}: ${issue.message}`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=composition-lint.js.map