@mevdragon/vidfarm-devcli 0.18.0 → 0.19.0

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

@@ -180,20 +180,38 @@ function findNonCollidingTrack(clips, range, excludeId) {
     return track;
 }
 function buildMediaClip(document, opts, id, track, geom) {
-    const node = document.createElement(opts.kind === "video" ? "video" : "img");
+    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", "publish");
+    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" : "AI image"));
+    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)}%`,
@@ -204,6 +222,8 @@ function buildMediaClip(document, opts, id, track, geom) {
         "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", "");
@@ -258,7 +278,10 @@ export function insertMediaLayer(html, opts) {
     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;
-    const duration = Math.max(0.1, dur > 0 ? Math.min(opts.duration ?? Math.min(4, remaining), remaining) : (opts.duration ?? 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
@@ -364,10 +387,12 @@ export function insertCaptionLayers(html, cues, opts = {}) {
             duration: cue.duration,
             track,
             z: track,
-            x: opts.x ?? CAPTION_DEFAULT_FRAME.x,
-            y: opts.y ?? CAPTION_DEFAULT_FRAME.y,
-            width: opts.width ?? CAPTION_DEFAULT_FRAME.width,
-            height: opts.height ?? CAPTION_DEFAULT_FRAME.height,
+            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,
@@ -512,6 +537,27 @@ function setNodeTransitionOut(node, preset, durationSeconds) {
     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) {
@@ -606,4 +652,608 @@ export function readTransitions(html) {
         };
     }).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);
+        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.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 / --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