@mevdragon/vidfarm-devcli 0.18.1 → 0.19.0

package/dist/src/config.js

@@ -101,6 +101,13 @@ const schema = z.object({
     RAPIDAPI_REMOVE_BACKGROUND_URL: z.string().url().default("https://remove-background18.p.rapidapi.com/public/remove-background/url"),
     RAPIDAPI_REMOVE_BACKGROUND_HOST: z.string().default("remove-background18.p.rapidapi.com"),
     RAPIDAPI_REMOVE_BACKGROUND_COST_USD: z.coerce.number().min(0).default(0.005),
+    // Local sharp chroma-key background removal (no third-party API) — a small
+    // compute/convenience wallet fee, far cheaper than the RapidAPI matting above.
+    GREENSCREEN_CHROMA_KEY_COST_USD: z.coerce.number().min(0).default(0.002),
+    // Two-step "create media overlay": BYOK AI image gen (provider cost rides the
+    // caller's own key) + local chroma key. This fee bills only the platform
+    // convenience/compute leg of the combined primitive.
+    MEDIA_OVERLAY_COST_USD: z.coerce.number().min(0).default(0.008),
     SUPERAGENCY_KEY: z.string().optional(),
     ARTIFACT_SIGNING_SECRET: z.string().optional(),
     HYPERFRAMES_LAMBDA_STACK_NAME: z.string().default("hyperframes-vidfarm-prod"),

package/dist/src/devcli/clips.js

@@ -136,6 +136,7 @@ async function runScan(argv) {
             cloud: { type: "boolean" },
             url: { type: "string" },
             tracer: { type: "string" },
+            folder: { type: "string" },
             "api-url": { type: "string" },
             "api-key": { type: "string" },
             "dry-run": { type: "boolean" },
@@ -188,6 +189,7 @@ async function runScan(argv) {
             apiUrl: values["api-url"],
             apiKey: values["api-key"],
             tracer: values.tracer,
+            folder: values.folder,
             prompt: guidancePromptRaw,
             provider: apiProvider,
             windows: rawWindows,
@@ -455,6 +457,7 @@ async function runScanCloud(input) {
             prompt: input.prompt ?? "",
             ...(input.provider ? { provider: input.provider } : {}),
             ...(input.tracer ? { tracer: input.tracer } : {}),
+            ...(input.folder ? { folder_path: input.folder } : {}),
             hunt_spec: {
                 ...(input.windows.length ? { windows: input.windows } : {}),
                 ...(input.durationBand ? { duration_band: input.durationBand } : {}),

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) {
@@ -868,4 +914,346 @@ export function restackLayer(html, layerKey, opts) {
     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

package/dist/src/devcli/local-backend.js

@@ -0,0 +1,123 @@
+// In-process LOCAL backend for the devcli — the "local" half of local-first,
+// dual local/cloud operation.
+//
+// The whole Vidfarm backend already runs over disk-backed drivers when
+// RECORDS_DRIVER=local + STORAGE_DRIVER=local (the same drivers `vidfarm serve`
+// uses). Rather than re-implement the directory / files / raws logic a second
+// time, we boot the real Hono `app` in-process and drive it with `app.request()`
+// — Hono's fetch interface runs the full middleware + handler stack WITHOUT
+// binding a socket. So `vidfarm directory ls --local` and `vidfarm serve` share
+// one on-disk backend, and a `clips scan --local` is instantly browsable in a
+// running serve UI.
+//
+// IMPORTANT (env-before-import): `config.ts` binds the driver + data dir from
+// env at module load. We MUST set the local env BEFORE the first `import` of
+// `../app.js` / any service. `cli.ts`'s static import graph deliberately does
+// not reach `config.js`, so setting env here (then dynamic-importing) flips the
+// drivers correctly — exactly the discipline `runServeCommand` follows.
+import path from "node:path";
+import { homedir } from "node:os";
+/** The durable per-user local home. Everything the local backend persists lives
+ *  under here: records + storage at `<home>/data`, legacy clips at
+ *  `<home>/clips.db`, provider config at `<home>/config.json`. */
+export function resolveLocalHome(overrideDir) {
+    if (overrideDir)
+        return path.resolve(overrideDir);
+    if (process.env.VIDFARM_HOME)
+        return path.resolve(process.env.VIDFARM_HOME);
+    return path.join(homedir(), ".vidfarm");
+}
+/** The data dir (records + storage) for the local backend. */
+export function resolveLocalDataDir(overrideDir) {
+    return path.join(resolveLocalHome(overrideDir), "data");
+}
+let cached = null;
+/**
+ * Boot (once) the in-process local backend and return a handle. Idempotent:
+ * repeated calls return the same booted app. Safe to call from any local
+ * command; cloud-only commands never call this, so the cloud path is untouched.
+ */
+export async function withLocalBackend(opts = {}) {
+    if (cached)
+        return cached;
+    const home = resolveLocalHome(opts.home);
+    const dataDir = resolveLocalDataDir(opts.home);
+    // Force the fully-local drivers, and blank every knob that would otherwise
+    // route this in-process box at the cloud (mirrors runServeCommand). These
+    // MUST be set before app.js / config.js is imported below.
+    process.env.RECORDS_DRIVER = "local";
+    process.env.STORAGE_DRIVER = "local";
+    process.env.AWS_S3_BUCKET = "";
+    process.env.VIDFARM_JOB_STATE_MACHINE_ARN = "";
+    process.env.VIDFARM_CLIP_SCAN_STATE_MACHINE_ARN = "";
+    process.env.VIDFARM_PRIMITIVE_MEDIA_LAMBDA_URL = "";
+    process.env.VIDFARM_PRIMITIVE_MEDIA_LAMBDA_SECRET = "";
+    // The one records-touching service that bypasses the local shim and talks to a
+    // real DynamoDB table via middleware — blank it or every /api/* 500s when a
+    // dev-shell .env carries a table name. In-process service calls don't hit
+    // middleware, but app.request() does, so this must be blank.
+    process.env.VIDFARM_RATE_LIMITS_TABLE_NAME = "";
+    process.env.VIDFARM_DATA_DIR = dataDir;
+    if (!process.env.NODE_ENV)
+        process.env.NODE_ENV = "development";
+    process.env.HYPERFRAMES_NO_TELEMETRY ||= "1";
+    process.env.HYPERFRAMES_SKIP_SKILLS ||= "1";
+    // No cloud passthrough by default for pure-local commands; sync/`--cloud` reach
+    // the cloud host directly via the devcli's own apiRequest, not this app.
+    process.env.VIDFARM_UPSTREAM_HOST ||= "";
+    process.env.VIDFARM_UPSTREAM_API_KEY ||= "";
+    // A stable local bootstrap key. The same value auto-provisions the local
+    // customer (tryBootstrapFromEnv) and authenticates app.request() calls. An
+    // empty/whitespace override falls through to the env key or the fixed default
+    // (so `--api-key ""` never breaks the local backend).
+    const apiKey = (opts.apiKey && opts.apiKey.trim()) ||
+        (process.env.VIDFARM_API_KEY && process.env.VIDFARM_API_KEY.trim()) ||
+        "vidfarm-local-dev-key";
+    process.env.VIDFARM_API_KEY = apiKey;
+    // Dynamic imports AFTER env is set, so config.ts binds the local drivers.
+    const { ServerlessAuthService } = await import("../services/serverless-auth.js");
+    const customer = await new ServerlessAuthService().authenticate(apiKey);
+    const appMod = await import("../app.js");
+    const app = appMod.default;
+    cached = { app, apiKey, ownerId: customer.id, home };
+    return cached;
+}
+/**
+ * Dispatch a REST call to the in-process local app. Mirrors the cloud
+ * `apiRequest` shape so commands can branch on target without reshaping results.
+ */
+export async function localApiRequest(input) {
+    const backend = await withLocalBackend({ home: input.home, apiKey: input.auth?.apiKey });
+    // A synthetic origin — only the path + query matter to Hono routing.
+    const url = new URL(input.path, "http://vidfarm.local");
+    for (const [key, value] of Object.entries(input.query ?? {})) {
+        if (value !== undefined && value !== null && value !== "")
+            url.searchParams.set(key, value);
+    }
+    const headers = {
+        accept: "application/json",
+        "vidfarm-api-key": input.auth?.apiKey || backend.apiKey
+    };
+    if (input.auth?.shareToken)
+        headers["vidfarm-share-token"] = input.auth.shareToken;
+    let body;
+    if (input.body !== undefined) {
+        headers["content-type"] = "application/json";
+        body = JSON.stringify(input.body);
+    }
+    const res = await backend.app.request(url.pathname + url.search, {
+        method: input.method.toUpperCase(),
+        headers,
+        body
+    });
+    const text = await res.text();
+    let json = null;
+    try {
+        json = text ? JSON.parse(text) : null;
+    }
+    catch {
+        json = null;
+    }
+    return { status: res.status, ok: res.ok, json, text };
+}
+//# sourceMappingURL=local-backend.js.map