npm - @officexapp/vidfarm-devcli - Versions diffs - 0.21.10 - Mend

@officexapp/vidfarm-devcli 0.21.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (516) hide show

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

@@ -0,0 +1,1292 @@
+// Composition editing for the devcli — parse a composition.html on disk, find
+// its blank timeline gaps and scene layers, and insert / replace a media clip.
+// This is the local-agent counterpart to the browser editor's applyAddLayerAction
+// (demo/src/HyperframesStudioEditor.tsx): it emits clips with the SAME data-*
+// attributes and inline styles so `vidfarm serve` live-morphs them and `publish`
+// 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, 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"
+]);
+// 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) {
+    return `<!doctype html>\n${document.documentElement.outerHTML}`;
+}
+function reduceAspectRatio(width, height) {
+    if (!width || !height || width <= 0 || height <= 0)
+        return null;
+    const gcd = (a, b) => (b === 0 ? a : gcd(b, a % b));
+    const w = Math.round(width);
+    const h = Math.round(height);
+    const g = gcd(w, h) || 1;
+    return `${w / g}:${h / g}`;
+}
+function numAttr(node, name) {
+    const raw = Number.parseFloat(node?.getAttribute?.(name) ?? "");
+    return Number.isFinite(raw) ? raw : NaN;
+}
+function stylePercent(node, prop) {
+    const raw = node?.style?.[prop];
+    if (!raw)
+        return undefined;
+    const match = raw.match(/(-?\d+(?:\.\d+)?)\s*%/);
+    return match ? Number(match[1]) : undefined;
+}
+// A clip fills the canvas if it's a timeline proxy, an explicit full-canvas
+// marker, or its geometry is ~0,0,100,100. Mirrors the editor's isFullCanvas.
+function isFullCanvasNode(node) {
+    if (node?.getAttribute?.("data-vf-timeline-proxy") === "video")
+        return true;
+    if (node?.getAttribute?.("data-vf-full-canvas") === "true")
+        return true;
+    const x = stylePercent(node, "left");
+    const y = stylePercent(node, "top");
+    const w = stylePercent(node, "width");
+    const h = stylePercent(node, "height");
+    return x !== undefined && y !== undefined && w !== undefined && h !== undefined
+        && x <= 0.5 && y <= 0.5 && w >= 99.5 && h >= 99.5;
+}
+function readCompositionDoc(html) {
+    const { document } = parseHTML(html);
+    const root = document.querySelector("[data-composition-id]");
+    if (!root)
+        throw new Error("Composition root ([data-composition-id]) not found in composition.html.");
+    return { document, root };
+}
+function collectClips(root) {
+    return Array.from(root.querySelectorAll("[data-start]"));
+}
+function layerSummary(node) {
+    const start = numAttr(node, "data-start");
+    const duration = numAttr(node, "data-duration");
+    const track = numAttr(node, "data-track-index");
+    return {
+        key: node.getAttribute("data-hf-id") || node.id || "",
+        kind: node.getAttribute("data-layer-kind"),
+        label: node.getAttribute("data-label"),
+        slug: node.getAttribute("data-hf-slug"),
+        start: Number.isFinite(start) ? start : 0,
+        duration: Number.isFinite(duration) ? duration : 0,
+        track: Number.isFinite(track) ? track : 0,
+        is_timeline_proxy: node.getAttribute("data-vf-timeline-proxy") === "video",
+        is_full_canvas: isFullCanvasNode(node),
+        src: node.getAttribute("src") || node.getAttribute("data-src") || null
+    };
+}
+// Blank spans where NO canvas-filling layer is on screen — the "gaps" an agent
+// fills. Overlays (text/caption/audio) don't count. Mirrors the editor's
+// computeTimelineGaps.
+export function computeCompositionGaps(html) {
+    const { root } = readCompositionDoc(html);
+    const totalDuration = numAttr(root, "data-duration");
+    return gapsFromClips(collectClips(root), Number.isFinite(totalDuration) ? totalDuration : 0);
+}
+function gapsFromClips(clips, totalDuration) {
+    const MIN_GAP = 0.2;
+    if (!Number.isFinite(totalDuration) || totalDuration <= 0)
+        return [];
+    const intervals = [];
+    for (const node of clips) {
+        const kind = (node.getAttribute("data-layer-kind") ?? "").toLowerCase();
+        const isProxy = node.getAttribute("data-vf-timeline-proxy") === "video";
+        const start = numAttr(node, "data-start");
+        const duration = numAttr(node, "data-duration");
+        if ((isProxy || ["video", "image", "html", "shape"].includes(kind)) && Number.isFinite(start) && Number.isFinite(duration) && duration > 0) {
+            intervals.push({ start, end: start + duration });
+        }
+    }
+    intervals.sort((a, b) => a.start - b.start);
+    const merged = [];
+    for (const interval of intervals) {
+        const last = merged[merged.length - 1];
+        if (last && interval.start <= last.end + 0.001)
+            last.end = Math.max(last.end, interval.end);
+        else
+            merged.push({ start: Math.max(0, interval.start), end: interval.end });
+    }
+    const gaps = [];
+    let cursor = 0;
+    for (const interval of merged) {
+        if (interval.start - cursor >= MIN_GAP) {
+            gaps.push({ start: round3(cursor), end: round3(interval.start), duration: round3(interval.start - cursor) });
+        }
+        cursor = Math.max(cursor, interval.end);
+    }
+    if (totalDuration - cursor >= MIN_GAP) {
+        gaps.push({ start: round3(cursor), end: round3(totalDuration), duration: round3(totalDuration - cursor) });
+    }
+    return gaps;
+}
+// Full read-out for `vidfarm pull` / agent grounding: dimensions, scenes, gaps.
+export function inspectComposition(html) {
+    const { root } = readCompositionDoc(html);
+    const clips = collectClips(root);
+    const totalDuration = numAttr(root, "data-duration");
+    const width = numAttr(root, "data-width");
+    const height = numAttr(root, "data-height");
+    const w = Number.isFinite(width) ? width : null;
+    const h = Number.isFinite(height) ? height : null;
+    return {
+        composition_id: root.getAttribute("data-composition-id"),
+        duration_seconds: Number.isFinite(totalDuration) ? totalDuration : 0,
+        width: w,
+        height: h,
+        aspect_ratio: reduceAspectRatio(w, h),
+        layers: clips.map(layerSummary),
+        gaps: gapsFromClips(clips, Number.isFinite(totalDuration) ? totalDuration : 0)
+    };
+}
+function resolveLayerNode(root, key) {
+    const trimmed = key.trim();
+    if (!trimmed)
+        return null;
+    const escaped = trimmed.replace(/["\\]/g, "\\$&");
+    return root.querySelector(`[data-hf-id="${escaped}"]`)
+        ?? root.querySelector(`[data-hf-slug="${escaped}"]`)
+        ?? root.querySelector(`#${escaped.replace(/[^\w-]/g, "")}`)
+        ?? null;
+}
+function nextAutoTrack(clips) {
+    return clips.reduce((max, node) => {
+        const track = numAttr(node, "data-track-index");
+        return Number.isFinite(track) ? Math.max(max, track + 1) : max;
+    }, 0);
+}
+// Enforce "one clip per (track, time)": if the requested track collides with an
+// existing clip's time range, walk upward to the next free lane.
+function findNonCollidingTrack(clips, range, excludeId) {
+    const end = range.start + range.duration;
+    let track = Math.max(0, Math.floor(range.track));
+    const collides = (t) => clips.some((node) => {
+        if ((node.getAttribute("data-hf-id") || node.id) === excludeId)
+            return false;
+        if (numAttr(node, "data-track-index") !== t)
+            return false;
+        const s = numAttr(node, "data-start");
+        const d = numAttr(node, "data-duration");
+        if (!Number.isFinite(s) || !Number.isFinite(d))
+            return false;
+        return s < end && (s + d) > range.start;
+    });
+    while (collides(track))
+        track += 1;
+    return track;
+}
+function buildMediaClip(document, opts, id, track, geom) {
+    const tagName = opts.kind === "video" ? "video" : opts.kind === "audio" ? "audio" : "img";
+    const node = document.createElement(tagName);
+    node.id = id;
+    node.setAttribute("data-hf-id", id);
+    node.setAttribute("data-layer-mode", opts.kind === "audio" ? "both" : "publish");
+    node.setAttribute("data-layer-kind", opts.kind);
+    node.setAttribute("data-viral-note", `AI generated ${opts.kind} (devcli).`);
+    node.setAttribute("data-start", String(round3(geom.start)));
+    node.setAttribute("data-duration", String(round3(geom.duration)));
+    node.setAttribute("data-end", String(round3(geom.start + geom.duration)));
+    node.setAttribute("data-track-index", String(track));
+    node.setAttribute("data-label", opts.label || (opts.kind === "video" ? "AI video" : opts.kind === "audio" ? "Audio track" : "AI image"));
+    node.className = "clip";
+    if (opts.slug)
+        node.setAttribute("data-hf-slug", opts.slug);
+    // Audio is a geometry-free overlay layer: a bare <audio> mirroring the web
+    // editor's renderLayer output (data-timeline-role / data-volume, framework-
+    // managed playback, no CSS box). Multiple audio layers on distinct tracks are
+    // mixed together at render, each at its own volume — so this is how the
+    // devcli overlays narration + a low-volume music bed + SFX as separate tracks.
+    if (opts.kind === "audio") {
+        node.setAttribute("src", opts.src);
+        node.setAttribute("preload", "metadata");
+        node.setAttribute("data-timeline-role", "music");
+        node.setAttribute("data-volume", String(opts.volume ?? 1));
+        if (opts.muted === true || opts.volume === 0)
+            node.setAttribute("muted", "");
+        const ps = String(round3(opts.playbackStart ?? 0));
+        node.setAttribute("data-media-start", ps);
+        node.setAttribute("data-playback-start", ps);
+        return node;
+    }
+    const styles = [
+        "position:absolute",
+        `left:${clampPercent(geom.x)}%`,
+        `top:${clampPercent(geom.y)}%`,
+        `width:${clampPercent(geom.width)}%`,
+        `height:${clampPercent(geom.height)}%`,
+        `z-index:${track}`,
+        "overflow:hidden",
+        `object-fit:${opts.objectFit || "cover"}`
+    ];
+    if (opts.objectPosition?.trim())
+        styles.push(`object-position:${opts.objectPosition.trim()}`);
+    node.setAttribute("src", opts.src);
+    if (opts.kind === "video") {
+        node.setAttribute("playsinline", "");
+        node.setAttribute("preload", "auto");
+        const wantsAudio = opts.muted === false || (opts.volume !== undefined && opts.volume > 0);
+        if (!wantsAudio)
+            node.setAttribute("muted", "");
+        node.setAttribute("data-volume", String(opts.volume ?? 1));
+        if (opts.loop) {
+            node.setAttribute("loop", "");
+            node.setAttribute("data-loop", "true");
+        }
+        const ps = String(round3(opts.playbackStart ?? 0));
+        node.setAttribute("data-media-start", ps);
+        node.setAttribute("data-playback-start", ps);
+        // Skip the opaque backdrop for alpha-capable video (webm/mov cut-outs) —
+        // it would render the file's transparency as a solid black box.
+        if (!/\.(webm|mov)(\?|#|$)/i.test(opts.src))
+            styles.push("background:#050604");
+    }
+    else if (opts.kenBurns && KEN_BURNS_PRESETS.has(opts.kenBurns)) {
+        // Ken Burns lives on the <img> itself (see src/hyperframes/composition.ts):
+        // data-kenburns picks the keyframes; the inline vars supply span + strength.
+        node.setAttribute("data-kenburns", opts.kenBurns);
+        styles.push(`--vf-kb-dur:${round3(geom.duration)}s`);
+        if (opts.kenBurnsIntensity !== undefined && Number.isFinite(opts.kenBurnsIntensity)) {
+            styles.push(`--vf-kb-amount:${Math.max(0.04, Math.min(0.5, opts.kenBurnsIntensity))}`);
+        }
+    }
+    if (opts.transition && TRANSITION_PRESET_SET.has(opts.transition)) {
+        // Scene transition (see src/hyperframes/composition.ts): data-transition
+        // 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 = 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;
+}
+// Insert a NEW media clip. Returns { html, layerKey } — the layerKey resolves in
+// the editor / later CLI calls. Auto-picks a collision-free track.
+export function insertMediaLayer(html, opts) {
+    if (!opts.src?.trim())
+        throw new Error("insertMediaLayer requires a src media URL.");
+    const { document, root } = readCompositionDoc(html);
+    const clips = collectClips(root);
+    const totalDuration = numAttr(root, "data-duration");
+    const dur = Number.isFinite(totalDuration) ? totalDuration : 0;
+    const start = Math.max(0, dur > 0 ? Math.min(dur - 0.1, opts.start ?? 0) : (opts.start ?? 0));
+    const remaining = dur > 0 ? Math.max(0.1, dur - start) : 4;
+    // Audio beds (narration/music/SFX) default to spanning the rest of the
+    // timeline from their start; visual clips default to a 4s slot.
+    const defaultDuration = opts.kind === "audio" ? remaining : Math.min(4, remaining);
+    const duration = Math.max(0.1, dur > 0 ? Math.min(opts.duration ?? defaultDuration, remaining) : (opts.duration ?? 4));
+    const providedKey = opts.layerKey?.trim();
+    const genKey = providedKey && /^[A-Za-z][\w-]{0,63}$/.test(providedKey)
+        ? providedKey
+        : `vf-gen-${Date.now().toString(36)}`;
+    const id = genKey.startsWith("element_") ? genKey : `element_${genKey}`;
+    const initialTrack = opts.track !== undefined && Number.isFinite(opts.track) ? Math.max(0, Math.floor(opts.track)) : nextAutoTrack(clips);
+    const track = findNonCollidingTrack(clips, { start, duration, track: initialTrack }, id);
+    const node = buildMediaClip(document, opts, id, track, {
+        start,
+        duration,
+        x: opts.x ?? 0,
+        y: opts.y ?? 0,
+        width: opts.width ?? 100,
+        height: opts.height ?? 100
+    });
+    root.append(node);
+    return { html: serialize(document), layerKey: id };
+}
+const CAPTION_DEFAULT_FRAME = { x: 10, y: 70, width: 80, height: 14 };
+function resolveCaptionLook(opts) {
+    const preset = captionStylePresetById(opts.style)
+        ?? (opts.animation ? null : CAPTION_STYLE_PRESETS[0]);
+    const animation = (opts.animation ?? preset?.animation);
+    if (!animation || !CAPTION_ANIMATIONS.includes(animation)) {
+        throw new Error(`Unknown caption animation "${opts.animation ?? opts.style}". Use a preset (${CAPTION_STYLE_PRESETS.map((p) => p.id).join(", ")}) or an animation (${CAPTION_ANIMATIONS.join(", ")}).`);
+    }
+    return {
+        animation,
+        activeColor: opts.activeColor ?? preset?.activeColor,
+        highlightColor: opts.highlightColor ?? preset?.highlightColor,
+        uppercase: opts.uppercase ?? preset?.uppercase,
+        color: opts.color ?? preset?.color ?? "#ffffff",
+        background: opts.background ?? preset?.background ?? "#000000",
+        backgroundStyle: (opts.backgroundStyle ?? preset?.textBackgroundStyle ?? "plain"),
+        // A 0 (or empty) font size/family renders the caption invisibly — the shared
+        // action/flag schema lets callers pass font_size:0 or font_family:"", so treat
+        // only a positive size / non-empty family as an intentional override.
+        fontFamily: opts.fontFamily?.trim() ? opts.fontFamily.trim() : "Montserrat",
+        fontWeight: opts.fontWeight ?? preset?.fontWeight ?? 800,
+        fontSize: typeof opts.fontSize === "number" && opts.fontSize > 0 ? opts.fontSize : 38,
+        presetId: preset?.id ?? animation
+    };
+}
+/** Read the animated-caption cues already in a composition (for restyle/list). */
+export function readCaptionCues(html) {
+    const { root } = readCompositionDoc(html);
+    return Array.from(root.querySelectorAll("[data-caption-animation]")).map((node) => {
+        const words = Array.from(node.querySelectorAll("[data-cap-word]"))
+            .map((span) => ({
+            text: String(span.textContent || "").trim(),
+            start: Number.parseFloat(span.getAttribute("data-word-start") ?? "") || 0,
+            end: Number.parseFloat(span.getAttribute("data-word-end") ?? "") || 0
+        }))
+            .filter((word) => word.text);
+        return {
+            layerKey: node.getAttribute("data-hf-id") || node.id || "",
+            track: Number.isFinite(numAttr(node, "data-track-index")) ? numAttr(node, "data-track-index") : 0,
+            text: words.length ? words.map((word) => word.text).join(" ") : String(node.textContent || "").trim(),
+            start: Number.isFinite(numAttr(node, "data-start")) ? numAttr(node, "data-start") : 0,
+            duration: Number.isFinite(numAttr(node, "data-duration")) ? numAttr(node, "data-duration") : 0,
+            words: words.length ? words : undefined
+        };
+    });
+}
+/** Remove every animated-caption layer. Returns the count removed. */
+export function clearCaptionLayers(html) {
+    const { document, root } = readCompositionDoc(html);
+    const nodes = Array.from(root.querySelectorAll("[data-caption-animation]"));
+    for (const node of nodes)
+        node.parentNode?.removeChild(node);
+    return { html: serialize(document), removed: nodes.length };
+}
+/**
+ * Insert an animated-caption cue run: one caption layer per cue on a shared
+ * collision-free track. Replaces any existing animated captions (set
+ * semantics — matching the editor's set_captions action).
+ */
+export function insertCaptionLayers(html, cues, opts = {}) {
+    const usable = cues
+        .filter((cue) => cue.text?.trim() && Number.isFinite(cue.start) && Number.isFinite(cue.duration) && cue.duration > 0)
+        .sort((a, b) => a.start - b.start);
+    if (!usable.length)
+        throw new Error("insertCaptionLayers needs at least one cue with text, start, and duration.");
+    const look = resolveCaptionLook(opts);
+    const { document, root } = readCompositionDoc(html);
+    const existing = Array.from(root.querySelectorAll("[data-caption-animation]"));
+    for (const node of existing)
+        node.parentNode?.removeChild(node);
+    const clips = collectClips(root);
+    const runStart = usable[0].start;
+    const runEnd = usable.reduce((max, cue) => Math.max(max, cue.start + cue.duration), runStart);
+    const initialTrack = opts.track !== undefined && Number.isFinite(opts.track)
+        ? Math.max(0, Math.floor(opts.track))
+        : nextAutoTrack(clips);
+    const track = findNonCollidingTrack(clips, { start: runStart, duration: Math.max(0.1, runEnd - runStart), track: initialTrack }, "");
+    const stamp = Date.now().toString(36);
+    const layerKeys = [];
+    usable.forEach((cue, index) => {
+        const id = `element_cap_${stamp}_${index}`;
+        layerKeys.push(id);
+        const layer = {
+            id,
+            kind: "caption",
+            label: cue.text.slice(0, 48),
+            start: cue.start,
+            duration: cue.duration,
+            track,
+            z: track,
+            x: typeof opts.x === "number" && Number.isFinite(opts.x) ? opts.x : CAPTION_DEFAULT_FRAME.x,
+            y: typeof opts.y === "number" && Number.isFinite(opts.y) ? opts.y : CAPTION_DEFAULT_FRAME.y,
+            // A 0 (or missing) width/height would render the caption invisibly — treat
+            // only a positive number as an intentional override, else use the default.
+            width: typeof opts.width === "number" && opts.width > 0 ? opts.width : CAPTION_DEFAULT_FRAME.width,
+            height: typeof opts.height === "number" && opts.height > 0 ? opts.height : CAPTION_DEFAULT_FRAME.height,
+            text: cue.text,
+            color: look.color,
+            background: look.background,
+            textBackgroundStyle: look.backgroundStyle,
+            fontFamily: look.fontFamily,
+            fontWeight: look.fontWeight,
+            fontSize: look.fontSize,
+            captionAnimation: {
+                animation: look.animation,
+                words: cue.words?.length ? cue.words : estimateCaptionWords(cue.text, cue.duration),
+                activeColor: look.activeColor,
+                highlightColor: look.highlightColor,
+                uppercase: look.uppercase
+            }
+        };
+        const container = document.createElement("div");
+        container.innerHTML = renderHyperframeLayerHtml(layer);
+        const node = container.firstElementChild;
+        if (!node)
+            throw new Error(`Failed to render caption cue ${index}.`);
+        node.classList?.add?.("clip");
+        root.append(node);
+    });
+    return { html: serialize(document), layerKeys, replaced: existing.length, styleId: look.presetId };
+}
+/** Restyle existing animated captions in place: same cues/timings/track, new look. */
+export function restyleCaptionLayers(html, opts) {
+    const cues = readCaptionCues(html);
+    if (!cues.length)
+        throw new Error("No animated caption layers found. Run `captions generate` (or add captions in the editor) first.");
+    const track = opts.track ?? cues[0].track;
+    const result = insertCaptionLayers(html, cues, { ...opts, track });
+    return { html: result.html, layerKeys: result.layerKeys, styleId: result.styleId };
+}
+// Replace an existing scene/layer with a generated media clip, taking over its
+// timing + geometry (full-canvas when it was a proxy / full-canvas fill).
+export function replaceLayerWithMedia(html, targetKey, opts) {
+    if (!opts.src?.trim())
+        throw new Error("replaceLayerWithMedia requires a src media URL.");
+    const { document, root } = readCompositionDoc(html);
+    const target = resolveLayerNode(root, targetKey);
+    if (!target)
+        throw new Error(`Layer to replace not found: ${targetKey}`);
+    const start = opts.start ?? numAttr(target, "data-start");
+    const durationRaw = opts.duration ?? numAttr(target, "data-duration");
+    const trackRaw = opts.track ?? numAttr(target, "data-track-index");
+    const fullCanvas = isFullCanvasNode(target);
+    const geom = fullCanvas
+        ? { x: 0, y: 0, width: 100, height: 100 }
+        : {
+            x: opts.x ?? stylePercent(target, "left") ?? 0,
+            y: opts.y ?? stylePercent(target, "top") ?? 0,
+            width: opts.width ?? stylePercent(target, "width") ?? 100,
+            height: opts.height ?? stylePercent(target, "height") ?? 100
+        };
+    const providedKey = opts.layerKey?.trim();
+    const targetId = target.getAttribute("data-hf-id") || target.id || "";
+    const genKey = providedKey && providedKey !== targetKey && /^[A-Za-z][\w-]{0,63}$/.test(providedKey)
+        ? providedKey
+        : `vf-gen-${Date.now().toString(36)}`;
+    const id = genKey.startsWith("element_") ? genKey : `element_${genKey}`;
+    // Remove the old node, then insert the replacement in its slot.
+    if (target.parentNode)
+        target.parentNode.removeChild(target);
+    const clips = collectClips(root);
+    const initialTrack = Number.isFinite(trackRaw) ? Math.max(0, Math.floor(trackRaw)) : nextAutoTrack(clips);
+    const track = findNonCollidingTrack(clips, { start: Number.isFinite(start) ? start : 0, duration: Number.isFinite(durationRaw) ? durationRaw : 4, track: initialTrack }, id);
+    const node = buildMediaClip(document, opts, id, track, {
+        start: Number.isFinite(start) ? start : 0,
+        duration: Number.isFinite(durationRaw) && durationRaw > 0 ? durationRaw : 4,
+        ...geom
+    });
+    root.append(node);
+    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`);
+}
+// In-place Ken Burns (still-image pan/zoom) toggle on an EXISTING node — mirrors
+// buildMediaClip's ken-burns block (data-kenburns + --vf-kb-dur + --vf-kb-amount)
+// and the web applyKenBurnsToNode. "none"/null clears it.
+function setNodeKenBurns(node, preset, intensity) {
+    if (!preset || preset === "none") {
+        node.removeAttribute("data-kenburns");
+        upsertStyleDecl(node, "--vf-kb-dur", null);
+        upsertStyleDecl(node, "--vf-kb-amount", null);
+        return;
+    }
+    if (!KEN_BURNS_PRESETS.has(preset)) {
+        throw new Error(`Unknown ken-burns preset "${preset}". Use one of: none, ${Array.from(KEN_BURNS_PRESETS).join(", ")}.`);
+    }
+    const dur = numAttr(node, "data-duration");
+    node.setAttribute("data-kenburns", preset);
+    if (Number.isFinite(dur) && dur > 0)
+        upsertStyleDecl(node, "--vf-kb-dur", `${round3(dur)}s`);
+    if (intensity !== undefined && Number.isFinite(intensity)) {
+        upsertStyleDecl(node, "--vf-kb-amount", String(Math.max(0.04, Math.min(0.5, intensity))));
+    }
+}
+// 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));
+}
+const KEYFRAME_EASINGS = ["linear", "ease", "ease-in", "ease-out", "ease-in-out", "step-start", "step-end"];
+// Whitelist the CSS timing-function so an easing can never smuggle arbitrary
+// declarations into the injected <style>/inline style. Mirrors the editor's
+// normalizeKeyframeEasing exactly.
+function normalizeKeyframeEasing(raw) {
+    const value = (raw ?? "").trim().toLowerCase();
+    if (KEYFRAME_EASINGS.includes(value))
+        return value;
+    const cb = /^cubic-bezier\(\s*(-?\d*\.?\d+\s*,\s*){3}-?\d*\.?\d+\s*\)$/;
+    if (cb.test(value))
+        return value;
+    const steps = /^steps\(\s*\d+\s*(,\s*(start|end|jump-(start|end|none|both))\s*)?\)$/;
+    if (steps.test(value))
+        return value;
+    return "linear";
+}
+function nodeTimelineId(node) {
+    return node?.getAttribute?.("data-hf-id") || node?.id || "";
+}
+// Couple the timing fields the way the editor's patchElementTiming does: a start
+// or duration change re-derives data-end; a track change re-derives z-index (the
+// runtime/publish normalizer keeps z-index == track); a media in-point (video/
+// audio) rides on data-media-start + data-playback-start together.
+function applyTimingToNode(node, updates) {
+    let start = numAttr(node, "data-start");
+    let duration = numAttr(node, "data-duration");
+    if (updates.start !== undefined) {
+        start = updates.start;
+        node.setAttribute("data-start", String(round3(start)));
+    }
+    if (updates.duration !== undefined) {
+        duration = updates.duration;
+        node.setAttribute("data-duration", String(round3(duration)));
+    }
+    if (updates.start !== undefined || updates.duration !== undefined) {
+        const s = Number.isFinite(start) ? start : 0;
+        const d = Number.isFinite(duration) ? duration : 0;
+        node.setAttribute("data-end", String(round3(s + d)));
+    }
+    if (updates.track !== undefined) {
+        const t = Math.max(0, Math.trunc(updates.track));
+        node.setAttribute("data-track-index", String(t));
+        upsertStyleDecl(node, "z-index", String(t));
+    }
+    if (updates.playbackStart !== undefined) {
+        const ps = String(round3(Math.max(0, updates.playbackStart)));
+        node.setAttribute("data-media-start", ps);
+        node.setAttribute("data-playback-start", ps);
+    }
+}
+// set_layer_keyframes twin: author a script-free CSS @keyframes animation on ONE
+// layer. The rule lives in a <style data-vf-kf="hfk-…"> in <head> (any prior
+// block for the same layer is removed first); the layer gets an inline
+// `animation: hfk-… <dur>s <easing> both paused`. The keyframe name is NEVER
+// vf-* (those are reserved for kenburns/transition/caption machinery); paused +
+// fill:both keeps it seek-safe in preview AND render.
+export function setLayerKeyframes(html, layerKey, opts) {
+    const frames = (opts.keyframes ?? []).filter((f) => Number.isFinite(f.offset)).sort((a, b) => a.offset - b.offset);
+    if (frames.length < 2) {
+        throw new Error("keyframes requires at least 2 stops, each with a numeric offset in 0..1.");
+    }
+    if (frames.every((f) => f.opacity === undefined && f.translate_x === undefined && f.translate_y === undefined && f.scale === undefined && f.rotate === undefined)) {
+        throw new Error("each keyframe needs at least one animated property (opacity, translate_x, translate_y, scale, rotate).");
+    }
+    const { document, root } = readCompositionDoc(html);
+    const node = resolveLayerNode(root, layerKey);
+    if (!node)
+        throw new Error(`Layer not found: ${layerKey}`);
+    const baseId = nodeTimelineId(node) || "layer";
+    const animName = `hfk-${baseId.replace(/[^A-Za-z0-9_-]/g, "-")}`;
+    const clipDuration = numAttr(node, "data-duration");
+    const durationSec = opts.durationSec !== undefined && opts.durationSec > 0
+        ? opts.durationSec
+        : (Number.isFinite(clipDuration) && clipDuration > 0 ? clipDuration : 1);
+    const easing = normalizeKeyframeEasing(opts.easing);
+    const cssFrames = frames.map((f) => {
+        const pct = Math.max(0, Math.min(100, f.offset * 100));
+        const pctLabel = Number(pct.toFixed(3)).toString();
+        const transforms = [];
+        if (f.translate_x !== undefined || f.translate_y !== undefined) {
+            transforms.push(`translate(${f.translate_x ?? 0}%, ${f.translate_y ?? 0}%)`);
+        }
+        if (f.scale !== undefined)
+            transforms.push(`scale(${f.scale})`);
+        if (f.rotate !== undefined)
+            transforms.push(`rotate(${f.rotate}deg)`);
+        const decls = [];
+        if (transforms.length)
+            decls.push(`transform:${transforms.join(" ")}`);
+        if (f.opacity !== undefined)
+            decls.push(`opacity:${Math.max(0, Math.min(1, f.opacity))}`);
+        return `${pctLabel}%{${decls.join(";")}}`;
+    }).join("");
+    const keyframeCss = `@keyframes ${animName}{${cssFrames}}`;
+    // Replace any prior keyframe block authored for THIS layer, then inject fresh.
+    // animName is already restricted to [A-Za-z0-9_-] so no selector escaping needed.
+    for (const old of Array.from(document.querySelectorAll(`style[data-vf-kf="${animName}"]`))) {
+        old.parentNode?.removeChild(old);
+    }
+    const styleEl = document.createElement("style");
+    styleEl.setAttribute("data-vf-kf", animName);
+    styleEl.textContent = keyframeCss;
+    const head = document.querySelector("head") ?? document.body ?? document.documentElement;
+    head.appendChild(styleEl);
+    upsertStyleDecl(node, "animation", `${animName} ${round3(durationSec)}s ${easing} both paused`);
+    return { html: serialize(document), layerKey: nodeTimelineId(node) || layerKey, stops: frames.length, animName, durationSec: round3(durationSec), easing };
+}
+// nudge_layers twin: relative timeline move of one or more layers, group-aware
+// (a grouped clip carries its whole data-vf-group with it). Start/track clamp to
+// >= 0. Applied in one pass; collisions between the moving clips are NOT
+// auto-resolved (unlike the single-layer restack) — the composition-edit helper
+// only resolves one excluded node at a time.
+export function nudgeLayers(html, keys, opts) {
+    const deltaStart = opts.deltaStart ?? 0;
+    const deltaTrack = opts.deltaTrack ?? 0;
+    if (!deltaStart && !deltaTrack) {
+        throw new Error("nudge needs a non-zero --delta-start (seconds) and/or --delta-track (lanes).");
+    }
+    const cleanKeys = keys.filter((k) => typeof k === "string" && k.trim().length > 0);
+    if (!cleanKeys.length)
+        throw new Error("nudge requires --layer <key> (repeatable).");
+    const { document, root } = readCompositionDoc(html);
+    const moveSet = new Map();
+    for (const key of cleanKeys) {
+        const seed = resolveLayerNode(root, key);
+        if (!seed)
+            throw new Error(`Layer not found: ${key}`);
+        const groupId = seed.getAttribute("data-vf-group");
+        if (groupId) {
+            const escaped = groupId.replace(/["\\]/g, "\\$&");
+            for (const gn of Array.from(root.querySelectorAll(`[data-vf-group="${escaped}"]`))) {
+                moveSet.set(nodeTimelineId(gn) || `n${moveSet.size}`, gn);
+            }
+        }
+        else {
+            moveSet.set(nodeTimelineId(seed) || `n${moveSet.size}`, seed);
+        }
+    }
+    for (const node of moveSet.values()) {
+        const start = numAttr(node, "data-start");
+        const track = numAttr(node, "data-track-index");
+        applyTimingToNode(node, {
+            start: Math.max(0, (Number.isFinite(start) ? start : 0) + deltaStart),
+            track: Math.max(0, (Number.isFinite(track) ? track : 0) + Math.trunc(deltaTrack))
+        });
+    }
+    return { html: serialize(document), moved: Array.from(moveSet.values()).map((n) => nodeTimelineId(n)) };
+}
+// ripple_edit twin: insert (delta > 0) or close (delta < 0) time at `at`,
+// shifting every clip whose data-start >= at across ALL tracks so downstream
+// timing stays in sync. Starts clamp to >= 0.
+export function rippleEdit(html, opts) {
+    if (!Number.isFinite(opts.at))
+        throw new Error("ripple requires --at (seconds on the composition timeline).");
+    if (!opts.delta || !Number.isFinite(opts.delta)) {
+        throw new Error("ripple requires a non-zero --delta (seconds; positive inserts a gap, negative closes one).");
+    }
+    const { document, root } = readCompositionDoc(html);
+    const affected = collectClips(root).filter((node) => {
+        const s = numAttr(node, "data-start");
+        return Number.isFinite(s) && s >= opts.at - 0.0001;
+    });
+    if (!affected.length)
+        throw new Error(`No clips start at or after ${opts.at}s to ripple.`);
+    for (const node of affected) {
+        const s = numAttr(node, "data-start");
+        applyTimingToNode(node, { start: Math.max(0, s + opts.delta) });
+    }
+    return { html: serialize(document), affected: affected.length };
+}
+// trim_layer twin: move ONE edge of a clip to a composition time. edge='start'
+// advances data-start, shrinks data-duration, and (video/audio only) pushes the
+// media in-point forward by the same delta so the visible frame is unchanged;
+// edge='end' just changes data-duration. Guards against non-positive duration.
+export function trimLayer(html, layerKey, opts) {
+    if (opts.edge !== "start" && opts.edge !== "end")
+        throw new Error("trim requires --edge start|end.");
+    if (!Number.isFinite(opts.to))
+        throw new Error("trim requires --to (seconds on the composition timeline).");
+    const { document, root } = readCompositionDoc(html);
+    const node = resolveLayerNode(root, layerKey);
+    if (!node)
+        throw new Error(`Layer not found: ${layerKey}`);
+    const start = numAttr(node, "data-start");
+    const duration = numAttr(node, "data-duration");
+    const s = Number.isFinite(start) ? start : 0;
+    const d = Number.isFinite(duration) ? duration : 0;
+    const end = s + d;
+    const tag = String(node.tagName || "").toLowerCase();
+    const isMedia = tag === "video" || tag === "audio";
+    const mediaStart = numAttr(node, "data-media-start");
+    const ms = Number.isFinite(mediaStart) ? mediaStart : 0;
+    const updates = {};
+    if (opts.edge === "start") {
+        if (opts.to <= s + 0.0001) {
+            throw new Error(`Left trim --to (${opts.to}s) must be after the clip start (${s}s). Use \`move\` to shift the clip earlier.`);
+        }
+        if (opts.to >= end - 0.05) {
+            throw new Error("Left trim would leave no duration — pick a --to before the clip's end.");
+        }
+        const delta = opts.to - s;
+        updates.start = opts.to;
+        updates.duration = d - delta;
+        if (isMedia)
+            updates.playbackStart = ms + delta;
+    }
+    else {
+        if (opts.to <= s + 0.05) {
+            throw new Error(`Right trim --to (${opts.to}s) must be after the clip start (${s}s).`);
+        }
+        updates.duration = opts.to - s;
+    }
+    applyTimingToNode(node, updates);
+    const report = {};
+    if (updates.start !== undefined)
+        report.start = round3(updates.start);
+    if (updates.duration !== undefined)
+        report.duration = round3(updates.duration);
+    if (updates.playbackStart !== undefined)
+        report.playback_start = round3(updates.playbackStart);
+    return { html: serialize(document), layerKey: nodeTimelineId(node) || layerKey, updates: report };
+}
+// set_layer_zindex twin: restack a layer. Stacking == data-track-index (higher
+// draws on top). front = maxTrack+1, back = max(0,minTrack-1), forward = track+1,
+// backward = max(0,track-1); an explicit --track wins. The single-node collision
+// resolver (findNonCollidingTrack) re-lanes upward when the target collides, so
+// 'back'/'backward' are best-effort (two time-overlapping clips can't share a lane).
+export function restackLayer(html, layerKey, opts) {
+    if (!opts.order && opts.track === undefined) {
+        throw new Error("restack needs --order front|back|forward|backward or an explicit --track.");
+    }
+    const { document, root } = readCompositionDoc(html);
+    const node = resolveLayerNode(root, layerKey);
+    if (!node)
+        throw new Error(`Layer not found: ${layerKey}`);
+    const clips = collectClips(root);
+    const tracks = clips.map((n) => numAttr(n, "data-track-index")).filter((t) => Number.isFinite(t));
+    const currentTrack = numAttr(node, "data-track-index");
+    const ct = Number.isFinite(currentTrack) ? currentTrack : 0;
+    const maxTrack = tracks.length ? Math.max(...tracks) : ct;
+    const minTrack = tracks.length ? Math.min(...tracks) : ct;
+    let targetTrack;
+    if (opts.track !== undefined)
+        targetTrack = Math.max(0, Math.trunc(opts.track));
+    else if (opts.order === "front")
+        targetTrack = maxTrack + 1;
+    else if (opts.order === "back")
+        targetTrack = Math.max(0, minTrack - 1);
+    else if (opts.order === "forward")
+        targetTrack = ct + 1;
+    else
+        targetTrack = Math.max(0, ct - 1);
+    const excludeId = nodeTimelineId(node);
+    const start = numAttr(node, "data-start");
+    const dur = numAttr(node, "data-duration");
+    const resolvedTrack = findNonCollidingTrack(clips, { start: Number.isFinite(start) ? start : 0, duration: Number.isFinite(dur) ? dur : 0, track: targetTrack }, excludeId);
+    if (resolvedTrack === ct) {
+        throw new Error(`${excludeId || layerKey} is already at track ${ct} — no stacking change.`);
+    }
+    applyTimingToNode(node, { track: resolvedTrack });
+    return { html: serialize(document), layerKey: excludeId || layerKey, track: resolvedTrack, order: opts.order ?? "explicit" };
+}
+// ---------------------------------------------------------------------------
+// Named layer-edit primitives — the devcli twins of the web editor_action verbs
+// set_layer_text / set_layer_style / set_layer_visual / set_layer_identity /
+// duplicate_layer / split_layer / set_layer_timing, plus set_composition. All
+// follow the same seams as the timeline verbs above: readCompositionDoc →
+// resolveLayerNode → mutate via upsertStyleDecl (inline style, seek-safe) +
+// data-* attrs → serialize. Static look = inline style; timing = data-* attrs;
+// caption/text background = data-text-background-*; identity = data-hf-slug/note.
+/** Rewrite a text/caption layer's visible words, preserving the caption
+ * word-span/outline wrapper (data-vf-text-inline) when present. */
+export function setLayerText(html, layerKey, text) {
+    const { document, root } = readCompositionDoc(html);
+    const node = resolveLayerNode(root, layerKey);
+    if (!node)
+        throw new Error(`Layer not found: ${layerKey}`);
+    const inline = node.querySelector?.("[data-vf-text-inline]");
+    if (inline)
+        inline.textContent = text;
+    else
+        node.textContent = text;
+    node.setAttribute("data-label", text.slice(0, 40));
+    return { html: serialize(document), layerKey: nodeTimelineId(node) || layerKey };
+}
+/** Restyle a layer: typography, colours, and static appearance. Mirrors the web
+ * set_layer_style (+ the opacity lever from set_layer_visual). Text background
+ * is attr-driven (data-text-background-*) like the caption renderer expects;
+ * everything else is inline CSS via upsertStyleDecl. */
+export function setLayerStyle(html, layerKey, opts) {
+    const { document, root } = readCompositionDoc(html);
+    const node = resolveLayerNode(root, layerKey);
+    if (!node)
+        throw new Error(`Layer not found: ${layerKey}`);
+    const changed = [];
+    if (opts.color !== undefined) {
+        upsertStyleDecl(node, "color", opts.color);
+        const inline = node.querySelector?.("[data-vf-text-inline]");
+        if (inline)
+            upsertStyleDecl(inline, "color", opts.color);
+        changed.push("color");
+    }
+    if (opts.backgroundStyle !== undefined || opts.background !== undefined) {
+        const bgStyle = opts.backgroundStyle ?? node.getAttribute("data-text-background-style") ?? "plain";
+        const bgColor = opts.background ?? node.getAttribute("data-text-background-color") ?? "#000000";
+        node.setAttribute("data-text-background-style", bgStyle);
+        node.setAttribute("data-text-background-color", bgColor);
+        changed.push("background");
+    }
+    if (opts.fontFamily !== undefined) {
+        node.setAttribute("data-font-family", opts.fontFamily);
+        upsertStyleDecl(node, "font-family", `'${opts.fontFamily}', 'TikTok Sans', sans-serif`);
+        changed.push("font-family");
+    }
+    if (opts.fontWeight !== undefined) {
+        upsertStyleDecl(node, "font-weight", String(opts.fontWeight));
+        changed.push("font-weight");
+    }
+    if (opts.italic !== undefined) {
+        upsertStyleDecl(node, "font-style", opts.italic ? "italic" : "normal");
+        changed.push("italic");
+    }
+    if (opts.underline !== undefined) {
+        upsertStyleDecl(node, "text-decoration-line", opts.underline ? "underline" : "none");
+        changed.push("underline");
+    }
+    if (opts.textAlign !== undefined) {
+        upsertStyleDecl(node, "text-align", opts.textAlign);
+        changed.push("text-align");
+    }
+    if (opts.borderRadius !== undefined) {
+        upsertStyleDecl(node, "border-radius", `${opts.borderRadius}px`);
+        changed.push("border-radius");
+    }
+    if (opts.fontSize !== undefined) {
+        upsertStyleDecl(node, "font-size", `${opts.fontSize}px`);
+        changed.push("font-size");
+    }
+    if (opts.lineHeight !== undefined) {
+        upsertStyleDecl(node, "line-height", String(opts.lineHeight));
+        changed.push("line-height");
+    }
+    if (opts.letterSpacing !== undefined) {
+        upsertStyleDecl(node, "letter-spacing", `${opts.letterSpacing}px`);
+        changed.push("letter-spacing");
+    }
+    if (opts.opacity !== undefined) {
+        upsertStyleDecl(node, "opacity", String(Math.max(0, Math.min(1, opts.opacity))));
+        changed.push("opacity");
+    }
+    if (changed.length === 0)
+        throw new Error("set-style needs at least one style field.");
+    return { html: serialize(document), layerKey: nodeTimelineId(node) || layerKey, changed };
+}
+/** Geometry + constant opacity, mirroring the web set_layer_visual. All inline. */
+export function setLayerVisual(html, layerKey, opts) {
+    const { document, root } = readCompositionDoc(html);
+    const node = resolveLayerNode(root, layerKey);
+    if (!node)
+        throw new Error(`Layer not found: ${layerKey}`);
+    const changed = [];
+    if (opts.x !== undefined) {
+        upsertStyleDecl(node, "left", `${clampPercent(opts.x)}%`);
+        changed.push("x");
+    }
+    if (opts.y !== undefined) {
+        upsertStyleDecl(node, "top", `${clampPercent(opts.y)}%`);
+        changed.push("y");
+    }
+    if (opts.width !== undefined) {
+        upsertStyleDecl(node, "width", `${clampPercent(opts.width)}%`);
+        changed.push("width");
+    }
+    if (opts.height !== undefined) {
+        upsertStyleDecl(node, "height", `${clampPercent(opts.height)}%`);
+        changed.push("height");
+    }
+    if (opts.fontSize !== undefined) {
+        upsertStyleDecl(node, "font-size", `${opts.fontSize}px`);
+        changed.push("font-size");
+    }
+    if (opts.borderRadius !== undefined) {
+        upsertStyleDecl(node, "border-radius", `${opts.borderRadius}px`);
+        changed.push("border-radius");
+    }
+    if (opts.opacity !== undefined) {
+        upsertStyleDecl(node, "opacity", String(Math.max(0, Math.min(1, opts.opacity))));
+        changed.push("opacity");
+    }
+    if (changed.length === 0)
+        throw new Error("set-visual needs at least one of x/y/width/height/font-size/border-radius/opacity.");
+    return { html: serialize(document), layerKey: nodeTimelineId(node) || layerKey, changed };
+}
+/**
+ * In-place edit of a MEDIA layer (video / image / audio): the devcli twin of the
+ * web set_layer_media (applySetLayerMediaAction). Writes byte-identical
+ * attributes — critically, a --src swap KEEPS the same node, key, geometry and
+ * timing (unlike `place --replace`, which deletes the node and re-inserts a new
+ * one with a fresh key). Subrange sugar: --source-out sets the timeline duration
+ * to (source_out − in-point), exactly like the web MediaSegmentModal's in/out.
+ */
+export function setLayerMedia(html, layerKey, opts) {
+    const { document, root } = readCompositionDoc(html);
+    const node = resolveLayerNode(root, layerKey);
+    if (!node)
+        throw new Error(`Layer not found: ${layerKey}`);
+    const tag = String(node.tagName || "").toLowerCase();
+    const kind = node.getAttribute("data-layer-kind") || (tag === "img" ? "image" : tag);
+    if (tag !== "video" && tag !== "audio" && tag !== "img") {
+        throw new Error(`set-media targets a media layer (video/image/audio); "${layerKey}" is a ${kind || tag} layer. Use set-text / set-style / set-visual instead.`);
+    }
+    const changed = [];
+    if (opts.src !== undefined) {
+        const src = opts.src.trim();
+        if (!src)
+            throw new Error("set-media --src cannot be empty.");
+        node.setAttribute("src", src);
+        // Backdrop follows the new src: alpha-capable media must not sit on the
+        // opaque editor backdrop (transparency would render as a black box), while
+        // an opaque video regains it.
+        if (tag === "video" || tag === "img") {
+            const alpha = tag === "img"
+                ? /\.(png|webp|gif|avif)(\?|#|$)/i.test(src)
+                : /\.(webm|mov)(\?|#|$)/i.test(src);
+            if (alpha)
+                upsertStyleDecl(node, "background", "transparent");
+            else if (tag === "video")
+                upsertStyleDecl(node, "background", "#050604");
+        }
+        changed.push("src");
+    }
+    if (opts.volume !== undefined) {
+        node.setAttribute("data-volume", String(opts.volume));
+        changed.push("volume");
+    }
+    if (opts.muted !== undefined) {
+        if (opts.muted)
+            node.setAttribute("muted", "");
+        else
+            node.removeAttribute("muted");
+        changed.push("muted");
+    }
+    if (opts.loop !== undefined && tag === "video") {
+        if (opts.loop) {
+            node.setAttribute("loop", "");
+            node.setAttribute("data-loop", "true");
+        }
+        else {
+            node.removeAttribute("loop");
+            node.removeAttribute("data-loop");
+        }
+        changed.push("loop");
+    }
+    if (opts.objectFit !== undefined) {
+        upsertStyleDecl(node, "object-fit", opts.objectFit);
+        changed.push("object-fit");
+    }
+    if (opts.objectPosition !== undefined) {
+        upsertStyleDecl(node, "object-position", opts.objectPosition);
+        changed.push("object-position");
+    }
+    if (opts.kenBurns !== undefined) {
+        setNodeKenBurns(node, opts.kenBurns, opts.kenBurnsIntensity);
+        changed.push("ken-burns");
+    }
+    if (opts.transition !== undefined) {
+        setNodeTransition(node, opts.transition, opts.transitionDuration);
+        changed.push("transition");
+    }
+    if (opts.transitionOut !== undefined) {
+        setNodeTransitionOut(node, opts.transitionOut, opts.transitionOutDuration);
+        changed.push("transition-out");
+    }
+    // Subrange: in-point (media-start) and optional out-point → timeline duration.
+    let nextDuration = opts.duration;
+    if (opts.sourceOut !== undefined) {
+        const currentIn = numAttr(node, "data-media-start");
+        const inPoint = opts.playbackStart !== undefined ? opts.playbackStart : (Number.isFinite(currentIn) ? currentIn : 0);
+        const span = opts.sourceOut - inPoint;
+        if (!(span > 0))
+            throw new Error(`--source-out (${opts.sourceOut}s) must be greater than the in-point (${inPoint}s).`);
+        nextDuration = span;
+    }
+    if (opts.playbackStart !== undefined || nextDuration !== undefined) {
+        applyTimingToNode(node, {
+            playbackStart: opts.playbackStart,
+            duration: nextDuration !== undefined ? Math.max(0.1, nextDuration) : undefined
+        });
+        if (opts.playbackStart !== undefined)
+            changed.push("playback-start");
+        if (nextDuration !== undefined)
+            changed.push("duration");
+    }
+    if (changed.length === 0) {
+        throw new Error("set-media needs at least one of --src / --volume / --muted / --loop / --playback-start / --source-out / --duration / --object-fit / --object-position / --ken-burns / --transition / --transition-out.");
+    }
+    return { html: serialize(document), layerKey: nodeTimelineId(node) || layerKey, changed, kind: kind || tag };
+}
+/** Set a layer's stable slug + human note (the AI/viral-DNA handle). Pass an
+ * empty string to clear a note. Mirrors the web set_layer_identity. */
+export function setLayerIdentity(html, layerKey, opts) {
+    if (opts.slug === undefined && opts.note === undefined)
+        throw new Error("set-identity needs --slug and/or --note.");
+    const { document, root } = readCompositionDoc(html);
+    const node = resolveLayerNode(root, layerKey);
+    if (!node)
+        throw new Error(`Layer not found: ${layerKey}`);
+    if (opts.slug !== undefined) {
+        const slug = opts.slug.trim();
+        if (slug)
+            node.setAttribute("data-hf-slug", slug);
+        else
+            node.removeAttribute("data-hf-slug");
+    }
+    if (opts.note !== undefined) {
+        if (opts.note.length)
+            node.setAttribute("data-hf-note", opts.note);
+        else
+            node.removeAttribute("data-hf-note");
+    }
+    return { html: serialize(document), layerKey: nodeTimelineId(node) || layerKey };
+}
+/** Clone a layer, offsetting its start so the copy doesn't sit exactly on top,
+ * and resolving to a collision-free track. Mirrors the web duplicate_layer. */
+export function duplicateLayer(html, layerKey, opts = {}) {
+    const { document, root } = readCompositionDoc(html);
+    const node = resolveLayerNode(root, layerKey);
+    if (!node)
+        throw new Error(`Layer not found: ${layerKey}`);
+    const clips = collectClips(root);
+    const start = numAttr(node, "data-start");
+    const duration = numAttr(node, "data-duration");
+    const track = numAttr(node, "data-track-index");
+    const s = Number.isFinite(start) ? start : 0;
+    const d = Number.isFinite(duration) ? duration : 0.1;
+    const clone = node.cloneNode(true);
+    const providedKey = opts.newKey?.trim();
+    const genKey = providedKey && /^[A-Za-z][\w-]{0,63}$/.test(providedKey) ? providedKey : `vf-dup-${Date.now().toString(36)}`;
+    const newId = genKey.startsWith("element_") ? genKey : `element_${genKey}`;
+    clone.id = newId;
+    clone.setAttribute("data-hf-id", newId);
+    const newStart = opts.start !== undefined && Number.isFinite(opts.start) ? Math.max(0, opts.start) : s + d;
+    const initialTrack = opts.track !== undefined && Number.isFinite(opts.track) ? Math.max(0, Math.floor(opts.track)) : (Number.isFinite(track) ? track : 0);
+    const resolvedTrack = findNonCollidingTrack(clips, { start: newStart, duration: d, track: initialTrack }, newId);
+    applyTimingToNode(clone, { start: newStart, duration: d, track: resolvedTrack });
+    root.append(clone);
+    return { html: serialize(document), layerKey: newId };
+}
+/** Cut a clip in two at splitTime (composition seconds). The tail inherits the
+ * media in-point offset so video/audio stays continuous. Mirrors split_layer. */
+export function splitLayer(html, layerKey, splitTime) {
+    const { document, root } = readCompositionDoc(html);
+    const node = resolveLayerNode(root, layerKey);
+    if (!node)
+        throw new Error(`Layer not found: ${layerKey}`);
+    const start = numAttr(node, "data-start");
+    const duration = numAttr(node, "data-duration");
+    const s = Number.isFinite(start) ? start : 0;
+    const d = Number.isFinite(duration) ? duration : 0;
+    if (!(splitTime > s + 0.001 && splitTime < s + d - 0.001)) {
+        throw new Error(`--at ${splitTime}s must fall strictly inside the clip (${round3(s)}–${round3(s + d)}s).`);
+    }
+    const tail = node.cloneNode(true);
+    const tailId = `element_vf-split-${Date.now().toString(36)}`;
+    tail.id = tailId;
+    tail.setAttribute("data-hf-id", tailId);
+    // First half: trim end to the split point.
+    applyTimingToNode(node, { duration: splitTime - s });
+    // Tail: starts at split, remaining duration, media in-point advanced by the cut.
+    const priorMediaStart = numAttr(node, "data-media-start");
+    const tailMediaStart = (Number.isFinite(priorMediaStart) ? priorMediaStart : 0) + (splitTime - s);
+    applyTimingToNode(tail, { start: splitTime, duration: s + d - splitTime, playbackStart: tailMediaStart });
+    root.append(tail);
+    return { html: serialize(document), firstKey: nodeTimelineId(node) || layerKey, secondKey: tailId };
+}
+/** Absolute set of a layer's timing (start/duration/track/playback-start),
+ * resolving track collisions. The devcli twin of the web set_layer_timing —
+ * unlike trim (edges) or nudge (relative), this sets values directly. */
+export function setLayerTiming(html, layerKey, opts) {
+    if (opts.start === undefined && opts.duration === undefined && opts.track === undefined && opts.playbackStart === undefined) {
+        throw new Error("retime needs at least one of --start/--duration/--track/--playback-start.");
+    }
+    const { document, root } = readCompositionDoc(html);
+    const node = resolveLayerNode(root, layerKey);
+    if (!node)
+        throw new Error(`Layer not found: ${layerKey}`);
+    const clips = collectClips(root);
+    const excludeId = nodeTimelineId(node);
+    const nextStart = opts.start !== undefined ? Math.max(0, opts.start) : numAttr(node, "data-start");
+    const nextDur = opts.duration !== undefined ? Math.max(0.1, opts.duration) : numAttr(node, "data-duration");
+    const wantTrack = opts.track !== undefined ? Math.max(0, Math.floor(opts.track)) : numAttr(node, "data-track-index");
+    const resolvedTrack = findNonCollidingTrack(clips, { start: Number.isFinite(nextStart) ? nextStart : 0, duration: Number.isFinite(nextDur) ? nextDur : 0.1, track: Number.isFinite(wantTrack) ? wantTrack : 0 }, excludeId);
+    applyTimingToNode(node, {
+        start: opts.start !== undefined ? Math.max(0, opts.start) : undefined,
+        duration: opts.duration !== undefined ? Math.max(0.1, opts.duration) : undefined,
+        track: resolvedTrack,
+        playbackStart: opts.playbackStart
+    });
+    return { html: serialize(document), layerKey: excludeId || layerKey, track: resolvedTrack };
+}
+/** Composition-level (canvas / theme) edit: resize the frame, retarget total
+ * render length, or recolour the canvas background. Written on the
+ * [data-composition-id] root per the hyperframes contract (data-width/height/
+ * duration + a background colour). The devcli twin of the web set_composition. */
+export function setComposition(html, opts) {
+    const { document, root } = readCompositionDoc(html);
+    const changed = [];
+    if (opts.width !== undefined && Number.isFinite(opts.width) && opts.width > 0) {
+        root.setAttribute("data-width", String(Math.round(opts.width)));
+        changed.push(`width=${Math.round(opts.width)}`);
+    }
+    if (opts.height !== undefined && Number.isFinite(opts.height) && opts.height > 0) {
+        root.setAttribute("data-height", String(Math.round(opts.height)));
+        changed.push(`height=${Math.round(opts.height)}`);
+    }
+    if (opts.duration !== undefined && Number.isFinite(opts.duration) && opts.duration > 0) {
+        root.setAttribute("data-duration", String(round3(opts.duration)));
+        changed.push(`duration=${round3(opts.duration)}`);
+    }
+    if (opts.backgroundColor !== undefined && opts.backgroundColor.trim()) {
+        upsertStyleDecl(root, "background", opts.backgroundColor.trim());
+        changed.push(`background=${opts.backgroundColor.trim()}`);
+    }
+    if (changed.length === 0)
+        throw new Error("set-composition needs at least one of --width/--height/--duration/--background.");
+    return { html: serialize(document), changed };
+}
+//# sourceMappingURL=composition-edit.js.map