@officexapp/vidfarm-devcli 0.21.10

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

@@ -0,0 +1,490 @@
+// devcli fine timeline control — the local-file twins of the browser editor's
+// trackpad-level verbs (set_layer_keyframes / nudge_layers / ripple_edit /
+// trim_layer / set_layer_zindex). Pure local DOM edits (linkedom) on a
+// composition.html: no cloud, no wallet — a running `vidfarm serve` live-morphs
+// the change into open editor tabs and `publish` pushes it like any browser
+// edit. Same read/write/serialize idioms as `vidfarm place` / `captions` /
+// `transitions`.
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { duplicateLayer, nudgeLayers, restackLayer, rippleEdit, setComposition, setLayerIdentity, setLayerKeyframes, setLayerStyle, setLayerText, setLayerTiming, setLayerVisual, splitLayer, trimLayer } from "./composition-edit.js";
+// Convenience motion presets so `keyframes` is usable without hand-writing JSON.
+// Each is a plain KeyframeStop[] — identical to what --keyframes '<json>' takes.
+const KEYFRAME_PRESETS = {
+    "fade-in": [{ offset: 0, opacity: 0 }, { offset: 1, opacity: 1 }],
+    "fade-out": [{ offset: 0, opacity: 1 }, { offset: 1, opacity: 0 }],
+    "fly-up": [{ offset: 0, opacity: 0, translate_y: 40 }, { offset: 1, opacity: 1, translate_y: 0 }],
+    "fly-down": [{ offset: 0, opacity: 0, translate_y: -40 }, { offset: 1, opacity: 1, translate_y: 0 }],
+    "fly-left": [{ offset: 0, opacity: 0, translate_x: 40 }, { offset: 1, opacity: 1, translate_x: 0 }],
+    "fly-right": [{ offset: 0, opacity: 0, translate_x: -40 }, { offset: 1, opacity: 1, translate_x: 0 }],
+    "pop-in": [{ offset: 0, opacity: 0, scale: 0.6 }, { offset: 0.7, opacity: 1, scale: 1.05 }, { offset: 1, opacity: 1, scale: 1 }],
+    "zoom-in": [{ offset: 0, scale: 1 }, { offset: 1, scale: 1.15 }],
+    "spin-in": [{ offset: 0, opacity: 0, rotate: -90, scale: 0.8 }, { offset: 1, opacity: 1, rotate: 0, scale: 1 }],
+    "pulse": [{ offset: 0, scale: 1 }, { offset: 0.5, scale: 1.08 }, { offset: 1, scale: 1 }]
+};
+const KEYFRAMES_HELP = `vidfarm keyframes — author a script-free CSS @keyframes animation on ONE layer (local file write)
+
+  keyframes <dir|composition.html> --layer <key> --preset <name>
+  keyframes <dir|composition.html> --layer <key> --keyframes '<json>'
+    --layer <key>            Target layer (data-hf-id / slug / element id) — required
+    --preset <name>          Built-in motion: ${Object.keys(KEYFRAME_PRESETS).join(" | ")}
+    --keyframes '<json>'     Custom stops: an array of >=2 {offset(0..1), opacity?,
+                             translate_x?, translate_y?, scale?, rotate?}. translate_*
+                             are percentages of the layer's OWN box, rotate is degrees.
+                             e.g. --keyframes '[{"offset":0,"opacity":0,"translate_y":40},{"offset":1,"opacity":1,"translate_y":0}]'
+    --easing <fn>            linear (default) | ease | ease-in | ease-out | ease-in-out
+                             | cubic-bezier(...) | steps(...)  (anything else → linear)
+    --duration <sec>         Seconds the animation spans (default: the clip's duration)
+    --json
+
+Writes a <style data-vf-kf="hfk-<layer>"> keyframe block + an inline
+"animation: hfk-<layer> <dur>s <easing> both paused" on the layer. paused +
+fill:both is seek-safe: it previews, serve-live-morphs, and bakes into the MP4
+identically. The keyframe name is never vf-* (reserved for kenburns/transition/caption).`;
+const MOVE_HELP = `vidfarm move — shift layers on the timeline by a relative delta (local file write)
+
+  move <dir|composition.html> --layer <key> [--layer <key> …]
+    --layer <key>            Layer to move (repeatable); a grouped clip carries its
+                             whole data-vf-group with it
+    --delta-start <sec>      Shift start by N seconds (clamped to >= 0)
+    --delta-track <lanes>    Shift track/lane by N (clamped to >= 0; higher = on top)
+    --json
+
+  Alias: move | nudge. Collisions between the moving clips are not auto-resolved
+  (use \`restack\` for single-layer lane resolution).`;
+const RIPPLE_HELP = `vidfarm ripple — insert or close time across the whole timeline (local file write)
+
+  ripple <dir|composition.html> --at <sec> --delta <sec>
+    --at <sec>               Ripple point on the composition timeline
+    --delta <sec>            Shift every clip that starts at/after --at by N seconds
+                             (positive inserts a gap, negative closes one; clamps >= 0)
+    --json`;
+const TRIM_HELP = `vidfarm trim — move ONE edge of a clip to a time (local file write)
+
+  trim <dir|composition.html> --layer <key> --edge start|end --to <sec>
+    --layer <key>            Clip to trim — required
+    --edge start|end         'start' advances the in-point (and, for video/audio,
+                             pushes the media start so the visible frame is unchanged);
+                             'end' changes the duration
+    --to <sec>               New edge position on the composition timeline
+    --json`;
+const RESTACK_HELP = `vidfarm restack — change a layer's stacking order (local file write)
+
+  restack <dir|composition.html> --layer <key> --order front|back|forward|backward
+  restack <dir|composition.html> --layer <key> --track <n>
+    --layer <key>            Layer to restack — required
+    --order <o>              front (top of all) | back | forward (+1) | backward (-1);
+                             stacking == track index (higher draws on top)
+    --track <n>              Explicit target lane (wins over --order)
+    --json
+
+  Alias: restack | zindex. 'back'/'backward' are best-effort — two time-overlapping
+  clips can't share a lane, so the resolver re-lanes upward on collision.`;
+// Same dir-or-file resolution as `vidfarm place` / `captions` / `transitions`.
+function resolveCompositionHtml(target) {
+    if (!target)
+        throw new Error("Provide the composition dir or composition.html path.");
+    const abs = path.resolve(process.cwd(), target);
+    if (existsSync(abs) && statSync(abs).isDirectory()) {
+        const inside = path.join(abs, "composition.html");
+        if (!existsSync(inside))
+            throw new Error(`No composition.html inside ${abs}. Run \`vidfarm pull <forkId> --dir ${target}\` first.`);
+        return inside;
+    }
+    if (!existsSync(abs))
+        throw new Error(`No such composition file or dir: ${abs}.`);
+    return abs;
+}
+function num(values, key) {
+    const raw = values[key];
+    if (typeof raw !== "string" || !raw.trim())
+        return undefined;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed))
+        throw new Error(`--${key} must be a number.`);
+    return parsed;
+}
+// ── keyframes ────────────────────────────────────────────────────────────────
+export async function runKeyframesCommand(argv) {
+    if (argv[0] === "help" || argv[0] === "--help" || argv[0] === "-h") {
+        console.log(KEYFRAMES_HELP);
+        return;
+    }
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            layer: { type: "string" },
+            preset: { type: "string" },
+            keyframes: { type: "string" },
+            easing: { type: "string" },
+            duration: { type: "string" },
+            json: { type: "boolean" }
+        }
+    });
+    const file = resolveCompositionHtml(positionals[0]);
+    if (typeof values.layer !== "string" || !values.layer.trim()) {
+        throw new Error("keyframes requires --layer <layerKey|slug>.");
+    }
+    let frames;
+    if (typeof values.keyframes === "string" && values.keyframes.trim()) {
+        let parsed;
+        try {
+            parsed = JSON.parse(values.keyframes);
+        }
+        catch {
+            throw new Error("--keyframes must be a JSON array of stops, e.g. '[{\"offset\":0,\"opacity\":0},{\"offset\":1,\"opacity\":1}]'.");
+        }
+        if (!Array.isArray(parsed))
+            throw new Error("--keyframes must be a JSON ARRAY of stops.");
+        frames = parsed;
+    }
+    else if (typeof values.preset === "string" && values.preset.trim()) {
+        const preset = KEYFRAME_PRESETS[values.preset.trim()];
+        if (!preset)
+            throw new Error(`Unknown --preset "${values.preset}". Use one of: ${Object.keys(KEYFRAME_PRESETS).join(", ")} (or pass --keyframes '<json>').`);
+        frames = preset.map((f) => ({ ...f }));
+    }
+    else {
+        throw new Error(`keyframes needs --preset <name> or --keyframes '<json>'. Presets: ${Object.keys(KEYFRAME_PRESETS).join(", ")}.`);
+    }
+    const result = setLayerKeyframes(readFileSync(file, "utf8"), values.layer, {
+        keyframes: frames,
+        easing: typeof values.easing === "string" ? values.easing : undefined,
+        durationSec: num(values, "duration")
+    });
+    writeFileSync(file, result.html, "utf8");
+    if (values.json) {
+        console.log(JSON.stringify({ file, layerKey: result.layerKey, animation: result.animName, stops: result.stops, duration: result.durationSec, easing: result.easing }, null, 2));
+        return;
+    }
+    console.log(`Set a ${result.stops}-stop CSS keyframe animation on ${result.layerKey} (${result.animName} ${result.durationSec}s ${result.easing}).`);
+    console.log(`Wrote ${file}`);
+}
+// ── move / nudge ─────────────────────────────────────────────────────────────
+export async function runMoveCommand(argv) {
+    if (argv[0] === "help" || argv[0] === "--help" || argv[0] === "-h") {
+        console.log(MOVE_HELP);
+        return;
+    }
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            layer: { type: "string", multiple: true },
+            "delta-start": { type: "string" },
+            "delta-track": { type: "string" },
+            json: { type: "boolean" }
+        }
+    });
+    const file = resolveCompositionHtml(positionals[0]);
+    const layers = values.layer ?? [];
+    if (!layers.length)
+        throw new Error("move requires --layer <layerKey|slug> (repeatable).");
+    const result = nudgeLayers(readFileSync(file, "utf8"), layers, {
+        deltaStart: num(values, "delta-start"),
+        deltaTrack: num(values, "delta-track")
+    });
+    writeFileSync(file, result.html, "utf8");
+    if (values.json) {
+        console.log(JSON.stringify({ file, moved: result.moved, delta_start: num(values, "delta-start") ?? 0, delta_track: num(values, "delta-track") ?? 0 }, null, 2));
+        return;
+    }
+    console.log(`Moved ${result.moved.length} layer(s) by Δstart=${num(values, "delta-start") ?? 0}s Δtrack=${Math.trunc(num(values, "delta-track") ?? 0)}: ${result.moved.join(", ")}.`);
+    console.log(`Wrote ${file}`);
+}
+// ── ripple ───────────────────────────────────────────────────────────────────
+export async function runRippleCommand(argv) {
+    if (argv[0] === "help" || argv[0] === "--help" || argv[0] === "-h") {
+        console.log(RIPPLE_HELP);
+        return;
+    }
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { at: { type: "string" }, delta: { type: "string" }, json: { type: "boolean" } }
+    });
+    const file = resolveCompositionHtml(positionals[0]);
+    const at = num(values, "at");
+    const delta = num(values, "delta");
+    if (at === undefined)
+        throw new Error("ripple requires --at <sec>.");
+    if (delta === undefined)
+        throw new Error("ripple requires --delta <sec>.");
+    const result = rippleEdit(readFileSync(file, "utf8"), { at, delta });
+    writeFileSync(file, result.html, "utf8");
+    if (values.json) {
+        console.log(JSON.stringify({ file, at, delta, affected: result.affected }, null, 2));
+        return;
+    }
+    console.log(`Rippled ${result.affected} clip(s) at ${at}s by ${delta > 0 ? "+" : ""}${delta}s.`);
+    console.log(`Wrote ${file}`);
+}
+// ── trim ─────────────────────────────────────────────────────────────────────
+export async function runTrimCommand(argv) {
+    if (argv[0] === "help" || argv[0] === "--help" || argv[0] === "-h") {
+        console.log(TRIM_HELP);
+        return;
+    }
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { layer: { type: "string" }, edge: { type: "string" }, to: { type: "string" }, json: { type: "boolean" } }
+    });
+    const file = resolveCompositionHtml(positionals[0]);
+    if (typeof values.layer !== "string" || !values.layer.trim())
+        throw new Error("trim requires --layer <layerKey|slug>.");
+    if (values.edge !== "start" && values.edge !== "end")
+        throw new Error("trim requires --edge start|end.");
+    const to = num(values, "to");
+    if (to === undefined)
+        throw new Error("trim requires --to <sec>.");
+    const result = trimLayer(readFileSync(file, "utf8"), values.layer, { edge: values.edge, to });
+    writeFileSync(file, result.html, "utf8");
+    if (values.json) {
+        console.log(JSON.stringify({ file, layerKey: result.layerKey, edge: values.edge, to, updates: result.updates }, null, 2));
+        return;
+    }
+    const parts = Object.entries(result.updates).map(([k, v]) => `${k}=${v}`).join(" ");
+    console.log(`Trimmed ${result.layerKey} ${values.edge} to ${to}s (${parts}).`);
+    console.log(`Wrote ${file}`);
+}
+// ── restack / zindex ─────────────────────────────────────────────────────────
+export async function runRestackCommand(argv) {
+    if (argv[0] === "help" || argv[0] === "--help" || argv[0] === "-h") {
+        console.log(RESTACK_HELP);
+        return;
+    }
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { layer: { type: "string" }, order: { type: "string" }, track: { type: "string" }, json: { type: "boolean" } }
+    });
+    const file = resolveCompositionHtml(positionals[0]);
+    if (typeof values.layer !== "string" || !values.layer.trim())
+        throw new Error("restack requires --layer <layerKey|slug>.");
+    const order = values.order;
+    if (order && !["front", "back", "forward", "backward"].includes(order)) {
+        throw new Error(`--order must be front | back | forward | backward (got "${order}").`);
+    }
+    const result = restackLayer(readFileSync(file, "utf8"), values.layer, {
+        order: order,
+        track: num(values, "track")
+    });
+    writeFileSync(file, result.html, "utf8");
+    if (values.json) {
+        console.log(JSON.stringify({ file, layerKey: result.layerKey, track: result.track, order: result.order }, null, 2));
+        return;
+    }
+    console.log(`Restacked ${result.layerKey} to track ${result.track} (${result.order}; higher = on top).`);
+    console.log(`Wrote ${file}`);
+}
+// ── Named layer-edit verbs — devcli twins of the web editor_action set ─────────
+// set-style / set-visual / set-text / set-identity / duplicate / split / retime
+// / set-composition. Same shape as the timeline verbs above: parseArgs →
+// resolveCompositionHtml → primitive → writeFileSync.
+const boolFlag = (values, key) => typeof values[key] === "boolean" ? values[key] : undefined;
+const strVal = (values, key) => typeof values[key] === "string" && values[key].length > 0 ? values[key] : undefined;
+// ── set-style (color/background/typography/opacity) ───────────────────────────
+const SET_STYLE_HELP = `vidfarm set-style — restyle a text/media layer's look (local file write)
+  vidfarm set-style [dir|composition.html] --layer <key|slug> [flags]
+  --color <css>            text foreground color
+  --background <css>       text background color        --background-style plain|outline|highlight-solid|highlight-translucent|fullwidth
+  --font-family <name>     --font-weight <100-900>      --italic / --no-italic   --underline / --no-underline
+  --text-align <left|center|right|justify>              --font-size <px>   --border-radius <px>
+  --line-height <n>        unitless leading             --letter-spacing <px>    negative tightens
+  --opacity <0..1>         constant layer opacity        --json`;
+export async function runSetStyleCommand(argv) {
+    if (argv[0] === "help" || argv[0] === "--help" || argv[0] === "-h") {
+        console.log(SET_STYLE_HELP);
+        return;
+    }
+    const { values, positionals } = parseArgs({
+        args: argv, allowPositionals: true,
+        options: {
+            layer: { type: "string" }, color: { type: "string" }, background: { type: "string" }, "background-style": { type: "string" },
+            "font-family": { type: "string" }, "font-weight": { type: "string" }, italic: { type: "boolean" }, "no-italic": { type: "boolean" },
+            underline: { type: "boolean" }, "no-underline": { type: "boolean" }, "text-align": { type: "string" }, "font-size": { type: "string" },
+            "border-radius": { type: "string" }, "line-height": { type: "string" }, "letter-spacing": { type: "string" }, opacity: { type: "string" }, json: { type: "boolean" }
+        }
+    });
+    const file = resolveCompositionHtml(positionals[0]);
+    if (typeof values.layer !== "string" || !values.layer.trim())
+        throw new Error("set-style requires --layer <layerKey|slug>.");
+    const italic = boolFlag(values, "italic") ?? (boolFlag(values, "no-italic") ? false : undefined);
+    const underline = boolFlag(values, "underline") ?? (boolFlag(values, "no-underline") ? false : undefined);
+    const result = setLayerStyle(readFileSync(file, "utf8"), values.layer, {
+        color: strVal(values, "color"), background: strVal(values, "background"), backgroundStyle: strVal(values, "background-style"),
+        fontFamily: strVal(values, "font-family"), fontWeight: num(values, "font-weight"), italic, underline,
+        textAlign: strVal(values, "text-align"), fontSize: num(values, "font-size"), borderRadius: num(values, "border-radius"),
+        lineHeight: num(values, "line-height"), letterSpacing: num(values, "letter-spacing"), opacity: num(values, "opacity")
+    });
+    writeFileSync(file, result.html, "utf8");
+    if (values.json) {
+        console.log(JSON.stringify({ file, layerKey: result.layerKey, changed: result.changed }, null, 2));
+        return;
+    }
+    console.log(`Restyled ${result.layerKey} (${result.changed.join(" ")}).`);
+    console.log(`Wrote ${file}`);
+}
+// ── set-visual (geometry + opacity) ───────────────────────────────────────────
+const SET_VISUAL_HELP = `vidfarm set-visual — geometry + opacity of a layer (local file write)
+  vidfarm set-visual [dir|composition.html] --layer <key|slug> [--x <%>] [--y <%>] [--width <%>] [--height <%>] [--font-size <px>] [--border-radius <px>] [--opacity <0..1>] [--json]`;
+export async function runSetVisualCommand(argv) {
+    if (argv[0] === "help" || argv[0] === "--help" || argv[0] === "-h") {
+        console.log(SET_VISUAL_HELP);
+        return;
+    }
+    const { values, positionals } = parseArgs({
+        args: argv, allowPositionals: true,
+        options: { layer: { type: "string" }, x: { type: "string" }, y: { type: "string" }, width: { type: "string" }, height: { type: "string" }, "font-size": { type: "string" }, "border-radius": { type: "string" }, opacity: { type: "string" }, json: { type: "boolean" } }
+    });
+    const file = resolveCompositionHtml(positionals[0]);
+    if (typeof values.layer !== "string" || !values.layer.trim())
+        throw new Error("set-visual requires --layer <layerKey|slug>.");
+    const result = setLayerVisual(readFileSync(file, "utf8"), values.layer, {
+        x: num(values, "x"), y: num(values, "y"), width: num(values, "width"), height: num(values, "height"),
+        fontSize: num(values, "font-size"), borderRadius: num(values, "border-radius"), opacity: num(values, "opacity")
+    });
+    writeFileSync(file, result.html, "utf8");
+    if (values.json) {
+        console.log(JSON.stringify({ file, layerKey: result.layerKey, changed: result.changed }, null, 2));
+        return;
+    }
+    console.log(`Updated ${result.layerKey} visual (${result.changed.join(" ")}).`);
+    console.log(`Wrote ${file}`);
+}
+// ── set-text (rewrite words) ──────────────────────────────────────────────────
+const SET_TEXT_HELP = `vidfarm set-text — rewrite a text/caption layer's words (local file write)
+  vidfarm set-text [dir|composition.html] --layer <key|slug> --text "new words" [--json]`;
+export async function runSetTextCommand(argv) {
+    if (argv[0] === "help" || argv[0] === "--help" || argv[0] === "-h") {
+        console.log(SET_TEXT_HELP);
+        return;
+    }
+    const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: { layer: { type: "string" }, text: { type: "string" }, json: { type: "boolean" } } });
+    const file = resolveCompositionHtml(positionals[0]);
+    if (typeof values.layer !== "string" || !values.layer.trim())
+        throw new Error("set-text requires --layer <layerKey|slug>.");
+    if (typeof values.text !== "string")
+        throw new Error("set-text requires --text \"...\".");
+    const result = setLayerText(readFileSync(file, "utf8"), values.layer, values.text);
+    writeFileSync(file, result.html, "utf8");
+    if (values.json) {
+        console.log(JSON.stringify({ file, layerKey: result.layerKey }, null, 2));
+        return;
+    }
+    console.log(`Rewrote text on ${result.layerKey}.`);
+    console.log(`Wrote ${file}`);
+}
+// ── set-identity (slug + note) ────────────────────────────────────────────────
+const SET_IDENTITY_HELP = `vidfarm set-identity — set a layer's slug + note (the AI/viral-DNA handle) (local file write)
+  vidfarm set-identity [dir|composition.html] --layer <key|slug> [--slug <snake_case>] [--note "role"] [--json]  (empty --note clears)`;
+export async function runSetIdentityCommand(argv) {
+    if (argv[0] === "help" || argv[0] === "--help" || argv[0] === "-h") {
+        console.log(SET_IDENTITY_HELP);
+        return;
+    }
+    const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: { layer: { type: "string" }, slug: { type: "string" }, note: { type: "string" }, json: { type: "boolean" } } });
+    const file = resolveCompositionHtml(positionals[0]);
+    if (typeof values.layer !== "string" || !values.layer.trim())
+        throw new Error("set-identity requires --layer <layerKey|slug>.");
+    const result = setLayerIdentity(readFileSync(file, "utf8"), values.layer, {
+        slug: typeof values.slug === "string" ? values.slug : undefined,
+        note: typeof values.note === "string" ? values.note : undefined
+    });
+    writeFileSync(file, result.html, "utf8");
+    if (values.json) {
+        console.log(JSON.stringify({ file, layerKey: result.layerKey }, null, 2));
+        return;
+    }
+    console.log(`Set identity on ${result.layerKey}.`);
+    console.log(`Wrote ${file}`);
+}
+// ── duplicate ─────────────────────────────────────────────────────────────────
+const DUPLICATE_HELP = `vidfarm duplicate — clone a layer (local file write)
+  vidfarm duplicate [dir|composition.html] --layer <key|slug> [--start <sec>] [--track <n>] [--new-key <id>] [--json]`;
+export async function runDuplicateCommand(argv) {
+    if (argv[0] === "help" || argv[0] === "--help" || argv[0] === "-h") {
+        console.log(DUPLICATE_HELP);
+        return;
+    }
+    const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: { layer: { type: "string" }, start: { type: "string" }, track: { type: "string" }, "new-key": { type: "string" }, json: { type: "boolean" } } });
+    const file = resolveCompositionHtml(positionals[0]);
+    if (typeof values.layer !== "string" || !values.layer.trim())
+        throw new Error("duplicate requires --layer <layerKey|slug>.");
+    const result = duplicateLayer(readFileSync(file, "utf8"), values.layer, { start: num(values, "start"), track: num(values, "track"), newKey: strVal(values, "new-key") });
+    writeFileSync(file, result.html, "utf8");
+    if (values.json) {
+        console.log(JSON.stringify({ file, layerKey: result.layerKey }, null, 2));
+        return;
+    }
+    console.log(`Duplicated → ${result.layerKey}.`);
+    console.log(`Wrote ${file}`);
+}
+// ── split ─────────────────────────────────────────────────────────────────────
+const SPLIT_HELP = `vidfarm split — cut a clip in two at a time (local file write)
+  vidfarm split [dir|composition.html] --layer <key|slug> --at <sec> [--json]`;
+export async function runSplitCommand(argv) {
+    if (argv[0] === "help" || argv[0] === "--help" || argv[0] === "-h") {
+        console.log(SPLIT_HELP);
+        return;
+    }
+    const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: { layer: { type: "string" }, at: { type: "string" }, json: { type: "boolean" } } });
+    const file = resolveCompositionHtml(positionals[0]);
+    if (typeof values.layer !== "string" || !values.layer.trim())
+        throw new Error("split requires --layer <layerKey|slug>.");
+    const at = num(values, "at");
+    if (at === undefined)
+        throw new Error("split requires --at <sec>.");
+    const result = splitLayer(readFileSync(file, "utf8"), values.layer, at);
+    writeFileSync(file, result.html, "utf8");
+    if (values.json) {
+        console.log(JSON.stringify({ file, firstKey: result.firstKey, secondKey: result.secondKey }, null, 2));
+        return;
+    }
+    console.log(`Split ${result.firstKey} at ${at}s → tail ${result.secondKey}.`);
+    console.log(`Wrote ${file}`);
+}
+// ── retime (absolute set of start/duration/track/playback-start) ──────────────
+const RETIME_HELP = `vidfarm retime — set a layer's timing directly (local file write)
+  vidfarm retime [dir|composition.html] --layer <key|slug> [--start <sec>] [--duration <sec>] [--track <n>] [--playback-start <sec>] [--json]`;
+export async function runRetimeCommand(argv) {
+    if (argv[0] === "help" || argv[0] === "--help" || argv[0] === "-h") {
+        console.log(RETIME_HELP);
+        return;
+    }
+    const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: { layer: { type: "string" }, start: { type: "string" }, duration: { type: "string" }, track: { type: "string" }, "playback-start": { type: "string" }, json: { type: "boolean" } } });
+    const file = resolveCompositionHtml(positionals[0]);
+    if (typeof values.layer !== "string" || !values.layer.trim())
+        throw new Error("retime requires --layer <layerKey|slug>.");
+    const result = setLayerTiming(readFileSync(file, "utf8"), values.layer, { start: num(values, "start"), duration: num(values, "duration"), track: num(values, "track"), playbackStart: num(values, "playback-start") });
+    writeFileSync(file, result.html, "utf8");
+    if (values.json) {
+        console.log(JSON.stringify({ file, layerKey: result.layerKey, track: result.track }, null, 2));
+        return;
+    }
+    console.log(`Retimed ${result.layerKey} (track ${result.track}).`);
+    console.log(`Wrote ${file}`);
+}
+// ── set-composition (canvas / theme) ──────────────────────────────────────────
+const SET_COMPOSITION_HELP = `vidfarm set-composition — resize the canvas / retarget length / recolor background (local file write)
+  vidfarm set-composition [dir|composition.html] [--width <px>] [--height <px>] [--duration <sec>] [--background <css>] [--json]`;
+export async function runSetCompositionCommand(argv) {
+    if (argv[0] === "help" || argv[0] === "--help" || argv[0] === "-h") {
+        console.log(SET_COMPOSITION_HELP);
+        return;
+    }
+    const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: { width: { type: "string" }, height: { type: "string" }, duration: { type: "string" }, background: { type: "string" }, json: { type: "boolean" } } });
+    const file = resolveCompositionHtml(positionals[0]);
+    const result = setComposition(readFileSync(file, "utf8"), { width: num(values, "width"), height: num(values, "height"), duration: num(values, "duration"), backgroundColor: strVal(values, "background") });
+    writeFileSync(file, result.html, "utf8");
+    if (values.json) {
+        console.log(JSON.stringify({ file, changed: result.changed }, null, 2));
+        return;
+    }
+    console.log(`Updated composition (${result.changed.join(" ")}).`);
+    console.log(`Wrote ${file}`);
+}
+//# sourceMappingURL=timeline-edit.js.map