@mevdragon/vidfarm-devcli 0.13.0 → 0.15.0

package/dist/src/composition-runtime.js

@@ -8,7 +8,8 @@
 export const COMPOSITION_RUNTIME_SCRIPT_BODY = `
 (() => {
   const root = document.querySelector("[data-composition-id]");
-  const duration = Number(root?.getAttribute("data-duration") || 0);
+  let declaredDuration = Number(root?.getAttribute("data-duration") || 0);
+  let duration = declaredDuration;
   let time = 0;
   let playing = false;
   let playbackRate = 1;
@@ -53,6 +54,11 @@ export const COMPOSITION_RUNTIME_SCRIPT_BODY = `
   }
 
   function refreshClips() {
+    // The parent editor can live-patch the composition DOM. Re-read the root's
+    // declared duration so a patched data-duration followed by refreshClips()
+    // never leaves the player clamped to a stale duration.
+    declaredDuration = Number(root?.getAttribute("data-duration") || 0);
+    duration = declaredDuration;
     clips = Array.from(document.querySelectorAll("[data-start]")).filter((node) => node !== root);
     for (const clip of clips) {
       if (clip instanceof HTMLMediaElement && !initialMuted.has(clip)) {
@@ -74,6 +80,7 @@ export const COMPOSITION_RUNTIME_SCRIPT_BODY = `
     activeVideoProxyKey = null;
     activeVideoProxyNode = null;
     hasVideoProxies = clips.some((clip) => clip instanceof Element && clip.getAttribute("data-vf-timeline-proxy") === "video");
+    discoverGeneralCssAnimations();
     apply(time, { forceSeek: true });
   }
 
@@ -146,6 +153,130 @@ export const COMPOSITION_RUNTIME_SCRIPT_BODY = `
     }
   }
 
+  // Runtime-adapter bridge — mirrors the official @hyperframes/producer
+  // deterministic adapters so compositions driven by a registered GSAP
+  // timeline (window.__timelines), Anime.js (window.__hfAnime), Lottie
+  // (window.__hfLottie), or Three.js/TypeGPU (window.__hfThreeTime/
+  // __hfTypegpuTime + the hf-seek CustomEvent) scrub with the player instead
+  // of running on the wall clock. Everything is duck-typed and try/caught so
+  // a broken composition script never kills the apply loop.
+  function compositionTimeline() {
+    let registry = null;
+    try { registry = window.__timelines; } catch { return null; }
+    if (!registry || typeof registry !== "object") return null;
+    const compId = root?.getAttribute("data-composition-id") || "";
+    let timeline = compId ? registry[compId] : null;
+    if (!timeline) {
+      const keys = Object.keys(registry);
+      if (keys.length === 1) timeline = registry[keys[0]];
+    }
+    if (!timeline || typeof timeline.pause !== "function") return null;
+    if (typeof timeline.totalTime !== "function" && typeof timeline.seek !== "function") return null;
+    return timeline;
+  }
+
+  function timelineDuration(timeline) {
+    try {
+      const value = typeof timeline.duration === "function" ? Number(timeline.duration()) : Number(timeline.duration);
+      if (Number.isFinite(value) && value > 0) return value;
+    } catch {}
+    return 0;
+  }
+
+  function syncTimeline() {
+    const timeline = compositionTimeline();
+    if (!timeline) return;
+    try {
+      timeline.pause();
+      // Official gsap adapter seek: nudge to time+1ms with suppressed events,
+      // then land exactly, so gsap re-renders even when the target equals the
+      // timeline's current time.
+      if (typeof timeline.totalTime === "function") {
+        timeline.totalTime(time + 0.001, true);
+        timeline.totalTime(time, false);
+      } else {
+        timeline.seek(time, false);
+      }
+    } catch {}
+  }
+
+  function syncAnimeInstances() {
+    let instances = null;
+    try { instances = window.__hfAnime; } catch { return; }
+    if (!Array.isArray(instances) || instances.length === 0) return;
+    const ms = Math.max(0, time) * 1000;
+    for (const instance of instances) {
+      try {
+        if (instance && typeof instance.seek === "function") instance.seek(ms);
+      } catch {}
+    }
+  }
+
+  function syncLottiePlayers() {
+    let players = null;
+    try { players = window.__hfLottie; } catch { return; }
+    if (!Array.isArray(players) || players.length === 0) return;
+    const safe = Math.max(0, time);
+    for (const player of players) {
+      try {
+        if (!player || typeof player !== "object") continue;
+        if (typeof player.goToAndStop === "function") {
+          player.goToAndStop(safe * 1000, false);
+        } else if (typeof player.pause === "function" && ("totalFrames" in player || "duration" in player)) {
+          if (typeof player.setCurrentRawFrameValue === "function") {
+            const totalFrames = player.totalFrames ?? 0;
+            const frameRate = player.frameRate ?? 30;
+            if (totalFrames > 0) player.setCurrentRawFrameValue(Math.min(safe * frameRate, totalFrames - 1));
+          } else if (typeof player.seek === "function") {
+            player.seek(Math.min(100, (safe / (player.duration ?? 1)) * 100));
+          }
+        }
+      } catch {}
+    }
+  }
+
+  let lastDispatchedSeekTime = -1;
+  function syncSeekGlobals() {
+    const safe = Math.max(0, time);
+    try { window.__hfThreeTime = safe; } catch {}
+    try { window.__hfTypegpuTime = safe; } catch {}
+    // The official three/typegpu adapters dedupe the hf-seek dispatch on the
+    // last dispatched time.
+    if (safe === lastDispatchedSeekTime) return;
+    lastDispatchedSeekTime = safe;
+    try { window.dispatchEvent(new CustomEvent("hf-seek", { detail: { time: safe } })); } catch {}
+  }
+
+  function syncRuntimeAdapters() {
+    syncTimeline();
+    syncAnimeInstances();
+    syncLottiePlayers();
+    syncSeekGlobals();
+  }
+
+  // data-duration on the root is authoritative when present. Arbitrary
+  // compositions may omit it, so infer the duration from clip extents,
+  // preferring a registered GSAP timeline that reports a longer duration.
+  // Recomputed on every apply so a timeline registered after load still
+  // corrects the duration (and seek clamping) lazily.
+  function ensureDuration() {
+    if (declaredDuration > 0) {
+      duration = declaredDuration;
+      return;
+    }
+    let inferred = 0;
+    for (const clip of clips) {
+      const timing = readTiming(clip);
+      if (timing.end > inferred) inferred = timing.end;
+    }
+    const timeline = compositionTimeline();
+    if (timeline) {
+      const reported = timelineDuration(timeline);
+      if (reported > inferred) inferred = reported;
+    }
+    duration = inferred;
+  }
+
   // Ken Burns image clips carry a CSS transform animation (vf-kb-* keyframes)
   // directly on the [data-kenburns] <img>. CSS animations run on the wall clock,
   // not player time, so the runtime scrubs them: pause + set currentTime from
@@ -176,7 +307,10 @@ export const COMPOSITION_RUNTIME_SCRIPT_BODY = `
   // previous clip on its track — so that previous clip must stay active for
   // the transition window. Publish materializes this overlap into
   // data-duration (normalizePublishHtml); the preview grants it live so
-  // butt-cut drafts preview exactly like the render.
+  // butt-cut drafts preview exactly like the render. A [data-transition-out]
+  // clip additionally animates AWAY (vf-tr-out-* keyframes) over its last
+  // data-transition-out-duration seconds — no hold needed, the exit window
+  // lives inside the clip's own span.
   function collectTransitionWindows() {
     const windows = [];
     for (const clip of clips) {
@@ -210,8 +344,26 @@ export const COMPOSITION_RUNTIME_SCRIPT_BODY = `
     return hold;
   }
 
-  function syncTransitionClip(clip, timing) {
+  function syncTransitionClip(clip, timing, hold) {
     if (typeof clip.getAnimations !== "function") return;
+    // Exit animations sit at the clip's tail via the inline --vf-tr-out-delay
+    // var. Timeline edits touch data-duration only, so re-derive the delay
+    // (duration + any live hold − out duration) before scrubbing; publish
+    // materializes the same value for the render producer.
+    if (clip.hasAttribute("data-transition-out")) {
+      let outDuration = Number(clip.getAttribute("data-transition-out-duration"));
+      if (!Number.isFinite(outDuration) || outDuration <= 0) outDuration = 0.5;
+      outDuration = Math.min(outDuration, timing.duration);
+      const expectedDelay = Math.max(0, timing.duration + (hold || 0) - outDuration);
+      try {
+        if (Math.abs((parseFloat(clip.style.getPropertyValue("--vf-tr-out-dur")) || 0) - outDuration) > 0.002) {
+          clip.style.setProperty("--vf-tr-out-dur", outDuration.toFixed(3) + "s");
+        }
+        if (Math.abs((parseFloat(clip.style.getPropertyValue("--vf-tr-out-delay")) || 0) - expectedDelay) > 0.002) {
+          clip.style.setProperty("--vf-tr-out-delay", expectedDelay.toFixed(3) + "s");
+        }
+      } catch {}
+    }
     const offsetMs = Math.max(0, (time - timing.start)) * 1000;
     let anims = [];
     try { anims = clip.getAnimations({ subtree: true }); } catch { return; }
@@ -292,25 +444,144 @@ export const COMPOSITION_RUNTIME_SCRIPT_BODY = `
     }
   }
 
+  // Generalized CSS keyframe scrub — the preview twin of the official
+  // producer CSS adapter: every element whose computed animation-name is set
+  // gets its animations paused and scrubbed to the player time relative to
+  // the nearest ancestor-or-self [data-start] (0 when none). vf-* animations
+  // (Ken Burns, transitions, captions) keep their dedicated machinery above.
+  // Discovery is cached per refreshClips like the official adapter's discover
+  // pass; elements added by live patches are picked up on the next refresh.
+  // Each entry also caches its clip-relative start at discovery so the
+  // per-frame sync skips the ancestor walk; a re-parented or retimed element
+  // is likewise re-resolved on the next refreshClips discovery.
+  let generalCssEntries = [];
+
+  function discoverGeneralCssAnimations() {
+    generalCssEntries = [];
+    let nodes = [];
+    try { nodes = document.querySelectorAll("*"); } catch { return; }
+    for (const node of nodes) {
+      if (!(node instanceof HTMLElement) || typeof node.getAnimations !== "function") continue;
+      let names = "";
+      try { names = getComputedStyle(node).animationName || ""; } catch { continue; }
+      if (!names || names === "none") continue;
+      const expected = [];
+      for (const name of names.split(",")) {
+        const trimmed = name.trim();
+        if (!trimmed || trimmed === "none" || trimmed.indexOf("vf-") === 0) continue;
+        expected.push(trimmed);
+      }
+      if (expected.length) generalCssEntries.push({ el: node, names: expected, start: generalClipStartFor(node) });
+    }
+  }
+
+  function hasAnimationNamed(anims, name) {
+    for (const anim of anims) {
+      if (anim.animationName === name) return true;
+    }
+    return false;
+  }
+
+  function generalClipStartFor(node) {
+    const holder = node.closest("[data-start]");
+    return holder ? readNumberAttr(holder, ["data-start"], 0) : 0;
+  }
+
+  // Cycling animation-name through none re-creates dropped CSS animations
+  // declaratively (same trick as the caption resurrection above), preserving
+  // any authored inline animation-name.
+  function resurrectCssAnimations(node) {
+    try {
+      const inline = node.style.animationName;
+      node.style.animationName = "none";
+      void node.offsetWidth;
+      if (inline && inline !== "none") {
+        node.style.animationName = inline;
+      } else {
+        node.style.removeProperty("animation-name");
+      }
+    } catch {}
+  }
+
+  function scrubGeneralAnimation(anim, offsetMs) {
+    let target = offsetMs;
+    try {
+      const computed = anim.effect && typeof anim.effect.getComputedTiming === "function"
+        ? anim.effect.getComputedTiming()
+        : null;
+      const endTime = computed && typeof computed.endTime === "number" ? computed.endTime : NaN;
+      if (Number.isFinite(endTime) && offsetMs >= endTime) {
+        // Same Chrome guard as the caption scrub: paused fill:none/backwards
+        // animations pushed past their effect end are destroyed permanently,
+        // so park them at 0; fill:forwards/both hold their final keyframe at
+        // the clamped end. Infinite-iteration animations (endTime Infinity)
+        // take the raw clip-relative offset like the official CSS adapter —
+        // the browser resolves the iteration phase.
+        target = computed.fill === "forwards" || computed.fill === "both" ? endTime : 0;
+      }
+    } catch {}
+    try {
+      anim.pause();
+      anim.currentTime = target;
+    } catch {}
+  }
+
+  function syncGeneralCssAnimations() {
+    for (const entry of generalCssEntries) {
+      const node = entry.el;
+      if (!node.isConnected) continue;
+      const offsetMs = Math.max(0, time - entry.start) * 1000;
+      let anims = [];
+      try { anims = node.getAnimations(); } catch { continue; }
+      let missing = null;
+      for (const name of entry.names) {
+        if (!hasAnimationNamed(anims, name)) (missing || (missing = [])).push(name);
+      }
+      if (missing) {
+        resurrectCssAnimations(node);
+        try { anims = node.getAnimations(); } catch { anims = []; }
+        // Names that still have no live animation (e.g. a display:none
+        // subtree) are dropped until the next discovery so a hidden element
+        // is not forced through a reflow every frame.
+        entry.names = entry.names.filter((name) => missing.indexOf(name) === -1 || hasAnimationNamed(anims, name));
+      }
+      for (const anim of anims) {
+        if (typeof anim.animationName !== "string" || anim.animationName.indexOf("vf-") === 0) continue;
+        scrubGeneralAnimation(anim, offsetMs);
+      }
+    }
+  }
+
   function apply(nextTime, options = {}) {
     const forceSeek = Boolean(options.forceSeek);
     const fromClock = Boolean(options.fromClock);
+    ensureDuration();
     time = clampTime(nextTime);
     let activeVideoProxy = null;
+    let activeVideoProxyStart = -Infinity;
     const transitionWindows = collectTransitionWindows();
     for (const clip of clips) {
       const timing = readTiming(clip);
       const hold = transitionHoldFor(clip, timing, transitionWindows);
-      const active = time >= timing.start && time < timing.end + hold;
+      // hyperframes-core clip windows are inclusive of both ends — the final
+      // frame holds.
+      const active = time >= timing.start && time <= timing.end + hold;
       if (clip instanceof HTMLElement && !(clip instanceof HTMLAudioElement)) {
         if (clip.getAttribute("data-vf-timeline-proxy") === "video") {
-          if (active) activeVideoProxy = clip;
+          // Clip windows are inclusive of both ends, so at an exact butt-cut
+          // the outgoing AND incoming proxies are both active. Prefer the
+          // greatest data-start (timeline order — the incoming clip wins);
+          // DOM order only breaks ties between equal starts.
+          if (active && timing.start >= activeVideoProxyStart) {
+            activeVideoProxy = clip;
+            activeVideoProxyStart = timing.start;
+          }
         } else {
           setVisibility(clip, active);
         }
         if (clip.hasAttribute("data-kenburns")) syncKenBurnsClip(clip, timing);
         if (clip.hasAttribute("data-caption-animation")) syncCaptionClip(clip, timing);
-        if (clip.hasAttribute("data-transition")) syncTransitionClip(clip, timing);
+        if (clip.hasAttribute("data-transition") || clip.hasAttribute("data-transition-out")) syncTransitionClip(clip, timing, hold);
       }
       if (clip instanceof HTMLMediaElement) {
         applyMediaState(clip);
@@ -328,6 +599,8 @@ export const COMPOSITION_RUNTIME_SCRIPT_BODY = `
         }
       }
     }
+    syncGeneralCssAnimations();
+    syncRuntimeAdapters();
     if (backingVideo instanceof HTMLVideoElement) {
       applyMediaState(backingVideo);
       const shouldShowBackingVideo = !hasVideoProxies || Boolean(activeVideoProxy);
@@ -436,6 +709,13 @@ export const COMPOSITION_RUNTIME_SCRIPT_BODY = `
       if (!playing) apply(time, { forceSeek: true });
     });
   }
+  window.addEventListener("load", () => {
+    // Composition scripts may register adapter instances (GSAP timelines,
+    // Lottie players, ...) or start CSS animations on the load event —
+    // re-discover and re-scrub so late registrations preview correctly.
+    discoverGeneralCssAnimations();
+    if (!playing) apply(time, { forceSeek: true });
+  });
 
   // Cache the parent frame's origin from the first accepted control message
   // and pin all outbound postMessages to it. Falls back to document.referrer's

package/dist/src/devcli/composition-edit.js

@@ -6,14 +6,14 @@
 // pushes them identically to a browser-made edit. Pure DOM (linkedom) — no
 // ffmpeg, no network.
 import { parseHTML } from "linkedom";
-import { CAPTION_ANIMATIONS, CAPTION_STYLE_PRESETS, captionStylePresetById, estimateCaptionWords, renderHyperframeLayerHtml } from "../hyperframes/composition.js";
+import { CAPTION_ANIMATIONS, CAPTION_STYLE_PRESETS, TRANSITION_OUT_PRESETS, TRANSITION_PRESETS, captionStylePresetById, clampTransitionDuration, estimateCaptionWords, renderHyperframeLayerHtml, transitionOutDelaySeconds } from "../hyperframes/composition.js";
 const KEN_BURNS_PRESETS = new Set([
     "zoom-in", "zoom-out", "pan-left", "pan-right", "pan-up", "pan-down", "zoom-in-left", "zoom-in-right"
 ]);
-const TRANSITION_PRESET_SET = new Set([
-    "crossfade", "fade-black", "slide-left", "slide-right", "slide-up", "slide-down",
-    "wipe-left", "wipe-right", "wipe-up", "wipe-down", "zoom-in", "zoom-out", "circle-open"
-]);
+// Preset vocabulary comes straight from the canonical source so the devcli can
+// never drift from the stylesheet.
+const TRANSITION_PRESET_SET = new Set(TRANSITION_PRESETS);
+const TRANSITION_OUT_PRESET_SET = new Set(TRANSITION_OUT_PRESETS);
 const round3 = (v) => Number(v.toFixed(3));
 const clampPercent = (v) => Math.min(100, Math.max(0, v));
 function serialize(document) {
@@ -231,13 +231,19 @@ function buildMediaClip(document, opts, id, track, geom) {
         // picks the keyframes; data-transition-duration + --vf-tr-dur set the span.
         // The overlap with the previous clip is granted by the runtime/publish
         // normalizer — the stored timeline stays butt-cut.
-        const transitionDuration = Number.isFinite(opts.transitionDuration) && opts.transitionDuration > 0
-            ? Math.max(0.1, Math.min(2.5, opts.transitionDuration))
-            : 0.5;
+        const transitionDuration = clampTransitionDuration(opts.transitionDuration ?? 0.5);
         node.setAttribute("data-transition", opts.transition);
         node.setAttribute("data-transition-duration", String(round3(transitionDuration)));
         styles.push(`--vf-tr-dur:${round3(transitionDuration)}s`);
     }
+    if (opts.transitionOut && TRANSITION_OUT_PRESET_SET.has(opts.transitionOut)) {
+        // Exit transition: the inline --vf-tr-out-delay (clip duration − out
+        // duration) parks the animation window at the clip's tail.
+        const outDuration = clampTransitionDuration(opts.transitionOutDuration ?? 0.5);
+        node.setAttribute("data-transition-out", opts.transitionOut);
+        node.setAttribute("data-transition-out-duration", String(round3(outDuration)));
+        styles.push(`--vf-tr-out-dur:${round3(outDuration)}s`, `--vf-tr-out-delay:${transitionOutDelaySeconds(geom.duration, outDuration)}s`);
+    }
     node.setAttribute("style", `${styles.join(";")};`);
     return node;
 }
@@ -438,4 +444,166 @@ export function replaceLayerWithMedia(html, targetKey, opts) {
     void targetId;
     return { html: serialize(document), layerKey: id };
 }
+function upsertStyleDecl(node, name, value) {
+    const styleValue = node.getAttribute("style") || "";
+    const escaped = name.replace(/[.*+?^${}()|[\]\\-]/g, "\\$&");
+    const pattern = new RegExp(`(^|;)\\s*${escaped}\\s*:[^;]*`, "i");
+    let nextStyle;
+    if (value === null) {
+        nextStyle = styleValue.replace(pattern, (_match, lead) => lead);
+    }
+    else if (pattern.test(styleValue)) {
+        nextStyle = styleValue.replace(pattern, (_match, lead) => `${lead}${name}:${value}`);
+    }
+    else {
+        nextStyle = styleValue.length === 0 || styleValue.endsWith(";")
+            ? `${styleValue}${name}:${value}`
+            : `${styleValue};${name}:${value}`;
+    }
+    if (nextStyle !== styleValue)
+        node.setAttribute("style", nextStyle);
+}
+// Scene clips are what junction transitions connect: video/image layers and
+// timeline proxies. Audio, captions, text overlays and the backing source
+// video are excluded (same filter as the editor's timeline chips).
+function isSceneClipNode(node) {
+    if (node?.hasAttribute?.("data-vf-playback-source"))
+        return false;
+    const tag = String(node?.tagName || "").toLowerCase();
+    if (tag === "audio")
+        return false;
+    const kind = node?.getAttribute?.("data-layer-kind");
+    return tag === "video" || tag === "img"
+        || node?.getAttribute?.("data-vf-timeline-proxy") === "video"
+        || kind === "video" || kind === "image";
+}
+function setNodeTransition(node, preset, durationSeconds) {
+    if (!preset || preset === "none") {
+        node.removeAttribute("data-transition");
+        node.removeAttribute("data-transition-duration");
+        upsertStyleDecl(node, "--vf-tr-dur", null);
+        return;
+    }
+    if (!TRANSITION_PRESET_SET.has(preset)) {
+        throw new Error(`Unknown transition preset "${preset}". Use one of: none, ${TRANSITION_PRESETS.join(", ")}.`);
+    }
+    const current = Number.parseFloat(node.getAttribute("data-transition-duration") ?? "");
+    const duration = clampTransitionDuration(durationSeconds ?? (Number.isFinite(current) ? current : undefined));
+    node.setAttribute("data-transition", preset);
+    node.setAttribute("data-transition-duration", String(round3(duration)));
+    upsertStyleDecl(node, "--vf-tr-dur", `${round3(duration)}s`);
+}
+function setNodeTransitionOut(node, preset, durationSeconds) {
+    if (!preset || preset === "none") {
+        node.removeAttribute("data-transition-out");
+        node.removeAttribute("data-transition-out-duration");
+        upsertStyleDecl(node, "--vf-tr-out-dur", null);
+        upsertStyleDecl(node, "--vf-tr-out-delay", null);
+        return;
+    }
+    if (!TRANSITION_OUT_PRESET_SET.has(preset)) {
+        throw new Error(`Unknown exit transition preset "${preset}". Use one of: none, ${TRANSITION_OUT_PRESETS.join(", ")}.`);
+    }
+    const current = Number.parseFloat(node.getAttribute("data-transition-out-duration") ?? "");
+    const duration = clampTransitionDuration(durationSeconds ?? (Number.isFinite(current) ? current : undefined));
+    const layerDuration = numAttr(node, "data-duration");
+    node.setAttribute("data-transition-out", preset);
+    node.setAttribute("data-transition-out-duration", String(round3(duration)));
+    upsertStyleDecl(node, "--vf-tr-out-dur", `${round3(duration)}s`);
+    upsertStyleDecl(node, "--vf-tr-out-delay", `${transitionOutDelaySeconds(Number.isFinite(layerDuration) ? layerDuration : 0, duration)}s`);
+}
+// Bulk pass over the whole timeline — the devcli twin of the AI's
+// set_transitions action and the editor's junction chips.
+export function applyTransitionsAcross(html, opts) {
+    if (opts.junction === undefined && opts.intro === undefined && opts.outro === undefined) {
+        throw new Error("applyTransitionsAcross needs a junction preset, an intro, and/or an outro.");
+    }
+    const { document, root } = readCompositionDoc(html);
+    const scenes = collectClips(root).filter(isSceneClipNode).map((node) => ({
+        node,
+        start: numAttr(node, "data-start") || 0,
+        duration: numAttr(node, "data-duration") || 0,
+        track: numAttr(node, "data-track-index") || 0
+    })).sort((a, b) => (a.start - b.start) || (a.track - b.track));
+    if (!scenes.length)
+        throw new Error("No scene clips (video/image layers) found in the composition.");
+    const firstByTrack = new Map();
+    for (const scene of scenes) {
+        const first = firstByTrack.get(scene.track);
+        if (!first || scene.start < first.start)
+            firstByTrack.set(scene.track, scene);
+    }
+    let junctions = 0;
+    if (opts.junction !== undefined) {
+        for (const scene of scenes) {
+            if (firstByTrack.get(scene.track) === scene)
+                continue;
+            setNodeTransition(scene.node, opts.junction, opts.duration);
+            junctions += 1;
+        }
+    }
+    const firstScene = scenes[0];
+    const lastScene = scenes.reduce((latest, scene) => (scene.start + scene.duration > latest.start + latest.duration ? scene : latest), scenes[0]);
+    if (opts.intro !== undefined && firstScene) {
+        setNodeTransition(firstScene.node, opts.intro, opts.duration);
+    }
+    if (opts.outro !== undefined && lastScene) {
+        setNodeTransitionOut(lastScene.node, opts.outro, opts.outroDuration ?? opts.duration);
+    }
+    return {
+        html: serialize(document),
+        junctions,
+        intro: opts.intro !== undefined && opts.intro !== "none" && opts.intro !== null,
+        outro: opts.outro !== undefined && opts.outro !== "none" && opts.outro !== null
+    };
+}
+// Per-layer control — the devcli twin of set_layer_media's transition fields.
+export function setLayerTransitions(html, layerKey, opts) {
+    if (opts.transition === undefined && opts.transitionOut === undefined) {
+        throw new Error("setLayerTransitions needs --in and/or --out.");
+    }
+    const { document, root } = readCompositionDoc(html);
+    const node = resolveLayerNode(root, layerKey);
+    if (!node)
+        throw new Error(`Layer not found: ${layerKey}`);
+    if (!isSceneClipNode(node) && String(node.tagName || "").toLowerCase() === "audio") {
+        throw new Error("Transitions cannot be applied to audio layers.");
+    }
+    if (opts.transition !== undefined)
+        setNodeTransition(node, opts.transition, opts.transitionDuration);
+    if (opts.transitionOut !== undefined)
+        setNodeTransitionOut(node, opts.transitionOut, opts.transitionOutDuration);
+    return { html: serialize(document), layerKey: node.getAttribute("data-hf-id") || node.id || layerKey };
+}
+export function clearAllTransitions(html) {
+    const { document, root } = readCompositionDoc(html);
+    let cleared = 0;
+    for (const node of collectClips(root)) {
+        const had = node.hasAttribute("data-transition") || node.hasAttribute("data-transition-out");
+        if (!had)
+            continue;
+        setNodeTransition(node, null);
+        setNodeTransitionOut(node, null);
+        cleared += 1;
+    }
+    return { html: serialize(document), cleared };
+}
+export function readTransitions(html) {
+    const { root } = readCompositionDoc(html);
+    return collectClips(root).filter(isSceneClipNode).map((node) => {
+        const duration = Number.parseFloat(node.getAttribute("data-transition-duration") ?? "");
+        const outDuration = Number.parseFloat(node.getAttribute("data-transition-out-duration") ?? "");
+        return {
+            layerKey: node.getAttribute("data-hf-id") || node.id || "",
+            label: node.getAttribute("data-label"),
+            track: numAttr(node, "data-track-index") || 0,
+            start: numAttr(node, "data-start") || 0,
+            duration: numAttr(node, "data-duration") || 0,
+            transition: node.getAttribute("data-transition"),
+            transition_duration: Number.isFinite(duration) ? duration : null,
+            transition_out: node.getAttribute("data-transition-out"),
+            transition_out_duration: Number.isFinite(outDuration) ? outDuration : null
+        };
+    }).sort((a, b) => (a.start - b.start) || (a.track - b.track));
+}
 //# sourceMappingURL=composition-edit.js.map