@officexapp/vidfarm-devcli 0.21.11 → 0.21.14

package/dist/src/cli.js

@@ -20,6 +20,8 @@ import { resolveFfmpeg } from "./services/clip-curation/ffmpeg.js";
 import { parseHyperframesJson, runHyperframesCommand } from "./devcli/hyperframes-cli.js";
 import { renderCompositionStills } from "./devcli/stills.js";
 import { runDoctorCommand } from "./devcli/doctor.js";
+import { findFreePort } from "./devcli/port-utils.js";
+import { scanLocalServers } from "./devcli/process-scan.js";
 import { runSkillsCommand } from "./devcli/skills.js";
 import { initTelemetry, reportCliCrash } from "./devcli/telemetry.js";
 import { resolveLocalDataDir, localBackendAvailable, LocalModeUnavailableError, localApiRequest } from "./devcli/local-backend.js";
@@ -91,7 +93,8 @@ Local editor loop:
                               With a template_id or --fork, pulls that composition
                               (or the template's default/shared decomposition) from
                               the cloud host onto local disk to edit offline.
-    --port <n>                Server port (default: 3000)
+    --port <n>                Server port (default: 3000; auto-advances to the next
+                              free port so concurrent local jobs never collide)
     --dir <path>              Local data dir (default: ~/.vidfarm/data or VIDFARM_HOME/data)
     --key <api-key>           Bootstrap/browser key (default: VIDFARM_API_KEY or a dev key)
     --fork <id>               Pull + open a specific cloud fork
@@ -489,7 +492,11 @@ Local media engines & toolchain (all local, free, no account — no cloud key ne
   doctor                    Health-check the local toolchain: node,       (local)
                             ffmpeg, hyperframes engines, Chrome, API key
                             (whoami), provider keys, agent CLI, poisoned
-                            env, port 3000, installed skills [--json]
+                            env, local serve/preview processes, installed
+                            skills [--json] [--kill-orphans]
+    --kill-orphans           Reap orphaned local serve/preview servers
+                            (running from a deleted package path) so their
+                            squatted ports are reclaimed
   skills <list|add <names…>|update>   Install/refresh agent skills into   → GET /skill-pack/* (or the
                             <root>/.agents/skills/<name> + a relative      copies bundled in this repo)
                             .claude/skills symlink; skills-lock.json is
@@ -504,15 +511,19 @@ Local media engines & toolchain (all local, free, no account — no cloud key ne
 
 Approve & schedule (publish a finished MP4 as a shareable post):
   approve                   Approve media into a preview/share page      → POST /api/v1/approved/posts
-    --video <url|file>      Primary MP4 (URL, or a local file auto-uploaded to temp/)
-    --media <url|file>      Extra media (repeatable; local files auto-upload to temp/)
-    --folder <path>         Temp-store folder for uploaded local files (default: temp)
+    --video <url|file>      Primary MP4 (URL, /files path, or local file → durable My Files)
+    --media <url|file>      Extra media (repeatable; local files → durable My Files)
+    --folder <path>         Destination subfolder for uploaded local files (default: approved)
+    --temp                  Upload local files to the 30-day TEMP store instead of
+                            durable My Files (throwaway preview; share video dies at day 30)
     --caption <text>        Post caption (required)
-                            Approve takes media by URL; a local file is
-                            presigned + PUT straight to S3 + finalized into a
-                            durable URL first (up to 200 MB — bypasses the ~6 MB
-                            Lambda body limit), so a locally rendered MP4 works:
+                            An approved post is PERMANENT, so a local file uploads
+                            to DURABLE My Files (never expires) by default —
+                            presigned + PUT straight to S3 + finalized (up to
+                            200 MB, bypassing the ~6 MB Lambda body). A locally
+                            rendered MP4 gets a share link that never breaks:
                             'vidfarm approve --video ./final.mp4 --caption "..."'
+                            (add --temp only for a disposable 30-day preview.)
   posts                     List your approved posts                     → GET  /api/v1/approved/posts
   post <postId>             Read one approved post (prints share URL)    → GET  /api/v1/approved/posts/:postId
   schedule <postId>         Schedule an approved post to a channel       → POST /api/v1/approved/posts/:postId/schedules
@@ -606,7 +617,11 @@ Marketplace (paid, cloud-only — the bazaar never renders locally):
   Local file paths: to avoid uploading assets to Vidfarm S3 at all, reference
   them straight from disk with 'place --src ./clip.mp4' on a 'serve' box (copied
   to that box's local disk store, free local render). When you DO need a durable
-  URL (cloud render/approve), keep it under a throwaway 'temp/' folder.
+  URL, mind the store: a 'place'/edit intermediate can live in the throwaway
+  'temp/' folder (30-day TTL), but anything you APPROVE is permanent — 'approve'
+  uploads local files to DURABLE My Files by default so the share link never dies
+  (the 'temp/' store would delete the video after 30 days; use --temp only for a
+  disposable preview).
 
 Cost spectrum (default to the cheapest approach that works; see SKILL.director.md):
   free        Reuse a decomposed template, swap captions/images/existing MP4s
@@ -641,7 +656,7 @@ Common options (any command):
   --json              Print only the raw JSON response (agent-friendly)
 
 Serve-mode options:
-  --port <n>          Local server port (default: 3000)
+  --port <n>          Local server port (default: 3000; auto-advances to the next free port)
   --dir <path>        Local data dir for disk records + storage (default: ./.vidfarm-local)
   --key <api-key>     Bootstrap/browser key (default: VIDFARM_API_KEY or a dev key)
   --fork <id>         Open a specific fork (multiple forks editable at once)
@@ -1322,10 +1337,29 @@ async function runFrontendServeCommand(argv) {
             "no-open": { type: "boolean", default: false }
         }
     });
-    const port = Number(parsed.values.port);
-    if (!Number.isFinite(port) || port <= 0) {
+    const requestedPort = Number(parsed.values.port);
+    if (!Number.isFinite(requestedPort) || requestedPort <= 0) {
         throw new Error(`Invalid --port: ${parsed.values.port}`);
     }
+    // Multiple concurrent local serves must coexist — auto-advance to the next
+    // free port instead of crashing the 2nd job with EADDRINUSE.
+    const port = await findFreePort(requestedPort);
+    if (port !== requestedPort) {
+        let squatterNote = "";
+        try {
+            const holder = scanLocalServers().servers.find((s) => s.port === requestedPort && !s.isSelf);
+            if (holder?.orphaned) {
+                squatterNote = ` (orphaned ${holder.kind} pid ${holder.pid} squatting it — \`vidfarm doctor --kill-orphans\` reclaims it)`;
+            }
+            else if (holder) {
+                squatterNote = ` (held by a running ${holder.kind}, pid ${holder.pid})`;
+            }
+        }
+        catch {
+            // advisory only
+        }
+        console.warn(`[vidfarm] serve: port ${requestedPort} busy${squatterNote}; using ${port} instead.`);
+    }
     const stored = readStoredAuth();
     const host = trimTrailingSlash(String(parsed.values.host ?? stored?.host ?? DEFAULT_HOST));
     // Only reuse the persisted key when it was minted for this host.
@@ -1397,10 +1431,33 @@ async function runServeCommand(argv) {
             "no-cloud": { type: "boolean", default: false }
         }
     });
-    const port = Number(parsed.values.port);
-    if (!Number.isFinite(port) || port <= 0) {
+    const requestedPort = Number(parsed.values.port);
+    if (!Number.isFinite(requestedPort) || requestedPort <= 0) {
         throw new Error(`Invalid --port: ${parsed.values.port}`);
     }
+    // Customers run several local video jobs at once, so never hard-fail on a
+    // busy port: claim the next free one upward from the request. This makes the
+    // 2nd/3rd `vidfarm serve` "just work" instead of crashing with EADDRINUSE.
+    const port = await findFreePort(requestedPort);
+    if (port !== requestedPort) {
+        // If an ORPHANED serve/preview (running from a deleted package path) is
+        // squatting the requested port, say so — that dead process will never free
+        // it on its own, and `vidfarm doctor --kill-orphans` reclaims it.
+        let squatterNote = "";
+        try {
+            const holder = scanLocalServers().servers.find((s) => s.port === requestedPort && !s.isSelf);
+            if (holder?.orphaned) {
+                squatterNote = ` (an orphaned ${holder.kind} pid ${holder.pid} is squatting it — reclaim with \`vidfarm doctor --kill-orphans\`)`;
+            }
+            else if (holder) {
+                squatterNote = ` (held by a running ${holder.kind}, pid ${holder.pid})`;
+            }
+        }
+        catch {
+            // advisory only
+        }
+        console.warn(`[vidfarm] serve: port ${requestedPort} busy${squatterNote}; using ${port} instead.`);
+    }
     const dataDir = parsed.values.dir
         ? path.resolve(process.cwd(), parsed.values.dir)
         : resolveLocalDataDir();
@@ -1551,7 +1608,7 @@ function printServeBanner(input) {
     console.log(line);
     console.log(`  server      ${input.base}`);
     console.log(`  data dir    ${input.dataDir}`);
-    console.log(`  render      ${DIM}local (in-process HyperFrames render — free, no cloud charge)${RESET}`);
+    console.log(`  render      ${DIM}local (in-process Vidfarm render — free, no cloud charge)${RESET}`);
     if (input.login) {
         console.log(`  login       ${GREEN}${input.login.email}${RESET} ${input.login.isPaidPlan ? DIM + "(paid)" + RESET : DIM + "(free)" + RESET}`);
     }
@@ -2824,7 +2881,8 @@ async function runCreateCommand(argv) {
     guardBilled(ctx, {
         label: "create (AI base-VIDEO generation + decompose)",
         estimate: "expensive, ~$1+ (AI video)",
-        freeAlternative: "fork a template and paint scenes with raw clips + HTML hyperframes instead of AI video"
+        freeAlternative: "fork a template and paint scenes with raw clips + HTML hyperframes, or drop in free stock via " +
+            'vidfarm media search "<meaning>" --type video|image (Pixabay/Openverse, $0) instead of AI video'
     });
     const refs = await resolveReferenceUrls(ctx, parsed.values.ref);
     // 1. Generate the base video from the prompt.
@@ -3140,7 +3198,7 @@ async function runRenderCommand(argv) {
                 console.log(`${DIM}Media prep: ${prepCuts.map((n) => `${n.action} ×${n.refs} (${n.url.slice(0, 60)}…)`).join("; ")}${RESET}`);
             }
             console.log(`${GREEN}Rendered locally in ${(result.durationMs / 1000).toFixed(1)}s → ${result.outputPath}${RESET}`);
-            console.log(`${DIM}$0.00 — local render, no cloud charge.${RESET}`);
+            console.log(`${DIM}$0.00 — local Vidfarm render, no cloud charge.${RESET}`);
         }
         return;
     }
@@ -3494,6 +3552,92 @@ async function uploadLocalToTempStore(ctx, absPath, folder) {
         throw new Error("local media upload returned no durable URL.");
     return url;
 }
+// Pull the durable view URL out of an /me/attachments finalize (or presign)
+// response. Finalize returns { attachment: { viewUrl } }; presign returns a
+// top-level view_url before the bytes land.
+function readAttachmentUrl(json) {
+    const a = json?.attachment ?? {};
+    return a.viewUrl ?? a.view_url ?? a.publicUrl ?? a.public_url ?? json?.view_url ?? json?.s3_url ?? null;
+}
+// Upload a local file to DURABLE My Files (root `files`, via /me/attachments),
+// optionally namescoped under a folder, and return its permanent URL.
+//
+// This is the durable twin of uploadLocalToTempStore: same presign → PUT-to-S3
+// → finalize shape (so a big MP4 never traverses the ~6 MB Lambda body), but the
+// object is NOT temp-tagged, so it never hits the 30-day lifecycle deletion.
+// Use it for anything that must outlive 30 days — chiefly a locally rendered MP4
+// being approved into a shareable cloud post.
+async function uploadLocalToMyFiles(ctx, absPath, folder) {
+    if (!existsSync(absPath))
+        throw new Error(`No such local file: ${absPath}`);
+    const buffer = readFileSync(absPath);
+    const fileName = path.basename(absPath);
+    const contentType = guessContentType(fileName);
+    // Step 1: presign. On an S3-backed box this returns a direct PUT URL.
+    const presign = await fetch(new URL("/api/v1/user/me/attachments/presign", ctx.host), {
+        method: "POST",
+        headers: { ...buildAuthHeaders(ctx.auth), "content-type": "application/json" },
+        body: JSON.stringify({ file_name: fileName, content_type: contentType, size_bytes: buffer.byteLength, folder_path: folder })
+    });
+    const presignJson = await presign.json().catch(() => null);
+    if (presign.ok && presignJson?.transport === "presigned" && presignJson?.upload?.url) {
+        // Step 2a: PUT the bytes straight to S3 (bypasses the Lambda body limit).
+        const put = await fetch(presignJson.upload.url, {
+            method: presignJson.upload.method || "PUT",
+            headers: presignJson.upload.headers || {},
+            body: new Uint8Array(buffer)
+        });
+        if (!put.ok)
+            throw new Error(`My Files upload failed with HTTP ${put.status}.`);
+        // Step 3: finalize — record the durable attachment now that the bytes landed.
+        const finalize = await fetch(new URL("/api/v1/user/me/attachments", ctx.host), {
+            method: "POST",
+            headers: { ...buildAuthHeaders(ctx.auth), "content-type": "application/json" },
+            body: JSON.stringify({
+                attachment_id: presignJson.attachment_id,
+                file_name: presignJson.file_name || fileName,
+                content_type: presignJson.content_type || contentType,
+                size_bytes: buffer.byteLength,
+                storage_key: presignJson.storage_key,
+                folder_path: presignJson.folder_path
+            })
+        });
+        const finalizeText = await finalize.text();
+        let finalizeJson = null;
+        try {
+            finalizeJson = finalizeText ? JSON.parse(finalizeText) : null;
+        }
+        catch {
+            finalizeJson = null;
+        }
+        if (!finalize.ok)
+            throw new Error(`My Files upload finalize failed (${finalize.status}): ${finalizeText.slice(0, 200)}`);
+        const url = readAttachmentUrl(finalizeJson) ?? presignJson.view_url ?? null;
+        if (!url)
+            throw new Error("My Files upload returned no durable URL.");
+        return url;
+    }
+    // Step 2b (fallback): local-storage box — POST the bytes as multipart form.
+    const form = new FormData();
+    form.append("file", new Blob([buffer], { type: contentType }), fileName);
+    if (folder)
+        form.append("folder_path", folder);
+    const res = await fetch(new URL("/api/v1/user/me/attachments/upload", ctx.host), { method: "POST", headers: buildAuthHeaders(ctx.auth), body: form });
+    const text = await res.text();
+    let json = null;
+    try {
+        json = text ? JSON.parse(text) : null;
+    }
+    catch {
+        json = null;
+    }
+    if (!res.ok)
+        throw new Error(`My Files upload failed (${res.status}): ${text.slice(0, 200)}`);
+    const url = readAttachmentUrl(json);
+    if (!url)
+        throw new Error("My Files upload returned no durable URL.");
+    return url;
+}
 // A value like "/raws/demos/hero.mp4" or "/files/logos/logo.png" is a My Files
 // directory path (one of the five unified roots), NOT a URL or a local disk
 // path — resolve it through the directory API. (Prefixes are inlined, not a
@@ -3632,9 +3776,17 @@ async function runGenerateCommand(argv) {
         ? {
             label: "AI video generation",
             estimate: "expensive, ~$1+",
-            freeAlternative: "reuse a raw clip (vidfarm raws) or author the beat as an HTML hyperframe"
-        }
-        : { label: "AI image generation", estimate: "cheap, ~$0.01–$0.05" });
+            freeAlternative: 'free stock video — vidfarm media search "<meaning>" --type video (Pixabay, $0; needs a free ' +
+                "pixabay key — it may already be saved: check vidfarm provider-keys), reuse a raw clip (vidfarm " +
+                "raws), or author the beat as an HTML hyperframe"
+        }
+        : {
+            label: "AI image generation",
+            estimate: "cheap, ~$0.01–$0.05",
+            freeAlternative: 'free stock image/vector — vidfarm media search "<meaning>" --type image|vector ($0). ' +
+                "Openverse (CC images) is keyless and always on — check it first; a free Pixabay key adds " +
+                "photos/vectors and may already be saved (check vidfarm provider-keys)"
+        });
     const refs = await resolveReferenceUrls(ctx, parsed.values.ref);
     const payload = { prompt };
     if (parsed.values["aspect-ratio"])
@@ -4516,7 +4668,8 @@ async function runMusicCommand(argv) {
     guardBilled(ctx, {
         label: `AI music generation${parsed.values["own-key"] ? " (your ElevenLabs key)" : ""}`,
         estimate: "billed (ElevenLabs)",
-        freeAlternative: "reuse a track from My Files / your library, or a licensed BGM asset"
+        freeAlternative: 'free stock music/SFX — vidfarm media search "<meaning>" --type bgm|sfx (Openverse CC/CC0, $0, ' +
+            "no key needed), or reuse a track from My Files / your library"
     });
     let musicLengthMs;
     const lengthMs = parsed.values["length-ms"]?.trim();
@@ -5618,6 +5771,7 @@ async function runApproveCommand(argv) {
             title: { type: "string" },
             pinned: { type: "string" },
             folder: { type: "string" },
+            temp: { type: "boolean" },
             tracer: { type: "string" }
         }
     });
@@ -5625,15 +5779,29 @@ async function runApproveCommand(argv) {
     const caption = parsed.values.caption;
     if (!caption)
         throw new Error("approve requires --caption <text>.");
-    // An approved post is a shareable cloud page, so any media must be a durable
-    // URL the page can load. Pass an http(s) URL through; a local file is uploaded
-    // to the ephemeral temp store (default folder `temp/`) first.
-    const uploadFolder = parsed.values.folder ?? "temp";
+    // An approved post is a PERMANENT shareable cloud page, so its media must live
+    // as long as the page. A local file therefore uploads to DURABLE My Files by
+    // default (never expires). `--temp` opts into the 30-day temp store for a
+    // throwaway preview — the share video then stops loading after 30 days.
+    const useTemp = Boolean(parsed.values.temp);
+    const uploadFolder = parsed.values.folder ?? (useTemp ? "temp" : "approved");
     const resolveApproveMedia = async (value) => {
-        if (/^https?:\/\//i.test(value.trim()))
-            return value.trim();
-        const abs = path.resolve(process.cwd(), value.trim());
-        return uploadLocalToTempStore(ctx, abs, uploadFolder);
+        const v = value.trim();
+        if (/^https?:\/\//i.test(v))
+            return v;
+        // A My Files path (/files/… · /raws/… · /projects/… · /approved/… · /temp/…)
+        // already lives server-side — resolve it to its view URL instead of
+        // re-uploading. (A /temp/… path stays 30-day; the caller chose it.)
+        if (looksLikeMyFilesPath(v)) {
+            const resolved = await resolveMyFilesPathToUrl(ctx, v);
+            if (!resolved)
+                throw new Error(`approve media "${value}" looks like a My Files path but no file was found there. Browse it with \`vidfarm directory ls ${v.replace(/\/[^/]*$/, "") || "/"}\` (add --cloud if it lives on vidfarm.cc), or pass the file's view URL.`);
+            return resolved.url;
+        }
+        const abs = path.resolve(process.cwd(), v);
+        return useTemp
+            ? uploadLocalToTempStore(ctx, abs, uploadFolder)
+            : uploadLocalToMyFiles(ctx, abs, uploadFolder);
     };
     const media = [];
     if (parsed.values.video)

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

@@ -16,8 +16,35 @@ const TRANSITION_PRESET_SET = new Set(TRANSITION_PRESETS);
 const TRANSITION_OUT_PRESET_SET = new Set(TRANSITION_OUT_PRESETS);
 const round3 = (v) => Number(v.toFixed(3));
 const clampPercent = (v) => Math.min(100, Math.max(0, v));
+// Matches an open tag and captures its attribute blob / self-close slash.
+// KEEP IN SYNC with OPEN_TAG_RE in src/services/composition-sanitize.ts.
+const OPEN_TAG_RE = /<([a-zA-Z][a-zA-Z0-9-]*)((?:\s+[^\s"'>/=]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s"'`=<>]+))?)*)\s*(\/?)>/g;
+// Quoted attribute values only — the capture keeps the quote character.
+// KEEP IN SYNC with QUOTED_ATTR_RE in src/services/composition-sanitize.ts.
+const QUOTED_ATTR_RE = /(\s+[^\s"'>/=]+\s*=\s*)("[^"]*"|'[^']*')/g;
+// Re-escape raw ">" inside quoted attribute values as "&gt;". Legal HTML, but
+// DOM serializers (linkedom here, browser outerHTML in the web editor) emit
+// the raw form, and the sealed StudioApp's string-offset source editor treats
+// the FIRST ">" as the end of an open tag — which once spliced an imported
+// layer into the middle of a root's data-viral-dna JSON. Idempotent.
+// KEEP IN SYNC with escapeGtInAttributeValues in
+// src/services/composition-sanitize.ts (backend) and
+// demo/src/vidfarm-composition-edit.ts (client twin).
+function escapeGtInAttributeValues(html) {
+    if (!html || !html.includes(">"))
+        return html;
+    return html.replace(OPEN_TAG_RE, (match, tag, rawAttrs, selfClose) => {
+        if (!rawAttrs || rawAttrs.indexOf(">") < 0)
+            return match;
+        const fixed = rawAttrs.replace(QUOTED_ATTR_RE, (_m, lead, quoted) => {
+            const q = quoted[0];
+            return lead + q + quoted.slice(1, -1).replace(/>/g, "&gt;") + q;
+        });
+        return `<${tag}${fixed}${selfClose ? "/" : ""}>`;
+    });
+}
 function serialize(document) {
-    return `<!doctype html>\n${document.documentElement.outerHTML}`;
+    return escapeGtInAttributeValues(`<!doctype html>\n${document.documentElement.outerHTML}`);
 }
 function reduceAspectRatio(width, height) {
     if (!width || !height || width <= 0 || height <= 0)
@@ -148,10 +175,45 @@ function resolveLayerNode(root, key) {
     if (!trimmed)
         return null;
     const escaped = trimmed.replace(/["\\]/g, "\\$&");
-    return root.querySelector(`[data-hf-id="${escaped}"]`)
-        ?? root.querySelector(`[data-hf-slug="${escaped}"]`)
-        ?? root.querySelector(`#${escaped.replace(/[^\w-]/g, "")}`)
-        ?? null;
+    const byAttr = root.querySelector(`[data-hf-id="${escaped}"]`)
+        ?? root.querySelector(`[data-hf-slug="${escaped}"]`);
+    if (byAttr)
+        return byAttr;
+    // id fallback via an attribute selector — a `#…` selector would throw a
+    // querySelector SyntaxError when the sanitized key ends up empty/invalid
+    // (e.g. an all-symbol key producing bare "#").
+    const idSafe = trimmed.replace(/[^\w-]/g, "");
+    return idSafe ? (root.querySelector(`[id="${idSafe}"]`) ?? null) : null;
+}
+// A miss should teach, not stonewall: name the layer keys that DO exist so an
+// agent can self-correct in one round trip (mirrors the web editLayerByKey).
+function layerNotFoundError(root, key) {
+    const available = collectClips(root).map((node) => {
+        const id = node.getAttribute?.("data-hf-id") || node.id || "";
+        const slug = node.getAttribute?.("data-hf-slug");
+        return slug && slug !== id ? `${id || slug} (slug: ${slug})` : id;
+    }).filter(Boolean);
+    const hint = available.length
+        ? ` Available layer keys: ${available.slice(0, 24).join(", ")}${available.length > 24 ? ", …" : ""}.`
+        : " The composition has no [data-start] layers.";
+    return new Error(`Layer not found: ${key}.${hint}`);
+}
+// The web editor's appendLayerHtml grows the root's data-duration whenever a
+// clip's end runs past it — mirror that after any op that can push a clip out
+// (insert/duplicate/nudge/ripple/retime/trim/set-media), so devcli edits never
+// leave clips dangling past the render window. Never shrinks.
+function extendRootDurationToCover(root) {
+    let furthest = 0;
+    for (const node of collectClips(root)) {
+        const s = numAttr(node, "data-start");
+        const d = numAttr(node, "data-duration");
+        if (Number.isFinite(s) && Number.isFinite(d))
+            furthest = Math.max(furthest, s + d);
+    }
+    const total = numAttr(root, "data-duration");
+    if (furthest > (Number.isFinite(total) ? total : 0) + 0.001) {
+        root.setAttribute("data-duration", String(round3(furthest)));
+    }
 }
 function nextAutoTrack(clips) {
     return clips.reduce((max, node) => {
@@ -283,12 +345,18 @@ export function insertMediaLayer(html, opts) {
     const clips = collectClips(root);
     const totalDuration = numAttr(root, "data-duration");
     const dur = Number.isFinite(totalDuration) ? totalDuration : 0;
-    const start = Math.max(0, dur > 0 ? Math.min(dur - 0.1, opts.start ?? 0) : (opts.start ?? 0));
-    const remaining = dur > 0 ? Math.max(0.1, dur - start) : 4;
+    // An EXPLICIT start/duration may run past the current timeline end — the
+    // root's data-duration is extended below (extendRootDurationToCover), the
+    // same way the web editor's appendLayerHtml grows the composition. Only the
+    // DEFAULTS are fitted to the existing timeline.
+    const start = Math.max(0, opts.start ?? 0);
+    const remaining = dur > start ? dur - start : 0;
     // 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 defaultDuration = opts.kind === "audio"
+        ? (remaining > 0.1 ? remaining : 4)
+        : Math.min(4, remaining > 0.1 ? remaining : 4);
+    const duration = Math.max(0.1, opts.duration ?? defaultDuration);
     const providedKey = opts.layerKey?.trim();
     const genKey = providedKey && /^[A-Za-z][\w-]{0,63}$/.test(providedKey)
         ? providedKey
@@ -305,6 +373,7 @@ export function insertMediaLayer(html, opts) {
         height: opts.height ?? 100
     });
     root.append(node);
+    extendRootDurationToCover(root);
     return { html: serialize(document), layerKey: id };
 }
 const CAPTION_DEFAULT_FRAME = { x: 10, y: 70, width: 80, height: 14 };
@@ -445,7 +514,7 @@ export function replaceLayerWithMedia(html, targetKey, opts) {
     const { document, root } = readCompositionDoc(html);
     const target = resolveLayerNode(root, targetKey);
     if (!target)
-        throw new Error(`Layer to replace not found: ${targetKey}`);
+        throw layerNotFoundError(root, targetKey);
     const start = opts.start ?? numAttr(target, "data-start");
     const durationRaw = opts.duration ?? numAttr(target, "data-duration");
     const trackRaw = opts.track ?? numAttr(target, "data-track-index");
@@ -476,6 +545,7 @@ export function replaceLayerWithMedia(html, targetKey, opts) {
         ...geom
     });
     root.append(node);
+    extendRootDurationToCover(root);
     void targetId;
     return { html: serialize(document), layerKey: id };
 }
@@ -621,7 +691,7 @@ export function setLayerTransitions(html, layerKey, opts) {
     const { document, root } = readCompositionDoc(html);
     const node = resolveLayerNode(root, layerKey);
     if (!node)
-        throw new Error(`Layer not found: ${layerKey}`);
+        throw layerNotFoundError(root, layerKey);
     if (!isSceneClipNode(node) && String(node.tagName || "").toLowerCase() === "audio") {
         throw new Error("Transitions cannot be applied to audio layers.");
     }
@@ -729,7 +799,7 @@ export function setLayerKeyframes(html, layerKey, opts) {
     const { document, root } = readCompositionDoc(html);
     const node = resolveLayerNode(root, layerKey);
     if (!node)
-        throw new Error(`Layer not found: ${layerKey}`);
+        throw layerNotFoundError(root, layerKey);
     const baseId = nodeTimelineId(node) || "layer";
     const animName = `hfk-${baseId.replace(/[^A-Za-z0-9_-]/g, "-")}`;
     const clipDuration = numAttr(node, "data-duration");
@@ -788,7 +858,7 @@ export function nudgeLayers(html, keys, opts) {
     for (const key of cleanKeys) {
         const seed = resolveLayerNode(root, key);
         if (!seed)
-            throw new Error(`Layer not found: ${key}`);
+            throw layerNotFoundError(root, key);
         const groupId = seed.getAttribute("data-vf-group");
         if (groupId) {
             const escaped = groupId.replace(/["\\]/g, "\\$&");
@@ -808,6 +878,7 @@ export function nudgeLayers(html, keys, opts) {
             track: Math.max(0, (Number.isFinite(track) ? track : 0) + Math.trunc(deltaTrack))
         });
     }
+    extendRootDurationToCover(root);
     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`,
@@ -830,6 +901,7 @@ export function rippleEdit(html, opts) {
         const s = numAttr(node, "data-start");
         applyTimingToNode(node, { start: Math.max(0, s + opts.delta) });
     }
+    extendRootDurationToCover(root);
     return { html: serialize(document), affected: affected.length };
 }
 // trim_layer twin: move ONE edge of a clip to a composition time. edge='start'
@@ -844,7 +916,7 @@ export function trimLayer(html, layerKey, opts) {
     const { document, root } = readCompositionDoc(html);
     const node = resolveLayerNode(root, layerKey);
     if (!node)
-        throw new Error(`Layer not found: ${layerKey}`);
+        throw layerNotFoundError(root, layerKey);
     const start = numAttr(node, "data-start");
     const duration = numAttr(node, "data-duration");
     const s = Number.isFinite(start) ? start : 0;
@@ -882,6 +954,7 @@ export function trimLayer(html, layerKey, opts) {
         report.duration = round3(updates.duration);
     if (updates.playbackStart !== undefined)
         report.playback_start = round3(updates.playbackStart);
+    extendRootDurationToCover(root);
     return { html: serialize(document), layerKey: nodeTimelineId(node) || layerKey, updates: report };
 }
 // set_layer_zindex twin: restack a layer. Stacking == data-track-index (higher
@@ -896,7 +969,7 @@ export function restackLayer(html, layerKey, opts) {
     const { document, root } = readCompositionDoc(html);
     const node = resolveLayerNode(root, layerKey);
     if (!node)
-        throw new Error(`Layer not found: ${layerKey}`);
+        throw layerNotFoundError(root, 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");
@@ -938,7 +1011,7 @@ 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}`);
+        throw layerNotFoundError(root, layerKey);
     const inline = node.querySelector?.("[data-vf-text-inline]");
     if (inline)
         inline.textContent = text;
@@ -955,7 +1028,7 @@ 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}`);
+        throw layerNotFoundError(root, layerKey);
     const changed = [];
     if (opts.color !== undefined) {
         upsertStyleDecl(node, "color", opts.color);
@@ -1021,7 +1094,7 @@ 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}`);
+        throw layerNotFoundError(root, layerKey);
     const changed = [];
     if (opts.x !== undefined) {
         upsertStyleDecl(node, "left", `${clampPercent(opts.x)}%`);
@@ -1067,7 +1140,7 @@ 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}`);
+        throw layerNotFoundError(root, 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") {
@@ -1158,6 +1231,7 @@ export function setLayerMedia(html, layerKey, opts) {
     if (changed.length === 0) {
         throw new Error("set-media needs at least one of --src / --volume / --muted / --loop / --playback-start / --source-out / --duration / --object-fit / --object-position / --ken-burns / --transition / --transition-out.");
     }
+    extendRootDurationToCover(root);
     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
@@ -1168,7 +1242,7 @@ export function setLayerIdentity(html, layerKey, opts) {
     const { document, root } = readCompositionDoc(html);
     const node = resolveLayerNode(root, layerKey);
     if (!node)
-        throw new Error(`Layer not found: ${layerKey}`);
+        throw layerNotFoundError(root, layerKey);
     if (opts.slug !== undefined) {
         const slug = opts.slug.trim();
         if (slug)
@@ -1190,7 +1264,7 @@ 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}`);
+        throw layerNotFoundError(root, layerKey);
     const clips = collectClips(root);
     const start = numAttr(node, "data-start");
     const duration = numAttr(node, "data-duration");
@@ -1208,6 +1282,7 @@ export function duplicateLayer(html, layerKey, opts = {}) {
     const resolvedTrack = findNonCollidingTrack(clips, { start: newStart, duration: d, track: initialTrack }, newId);
     applyTimingToNode(clone, { start: newStart, duration: d, track: resolvedTrack });
     root.append(clone);
+    extendRootDurationToCover(root);
     return { html: serialize(document), layerKey: newId };
 }
 /** Cut a clip in two at splitTime (composition seconds). The tail inherits the
@@ -1216,7 +1291,7 @@ 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}`);
+        throw layerNotFoundError(root, layerKey);
     const start = numAttr(node, "data-start");
     const duration = numAttr(node, "data-duration");
     const s = Number.isFinite(start) ? start : 0;
@@ -1247,7 +1322,7 @@ export function setLayerTiming(html, layerKey, opts) {
     const { document, root } = readCompositionDoc(html);
     const node = resolveLayerNode(root, layerKey);
     if (!node)
-        throw new Error(`Layer not found: ${layerKey}`);
+        throw layerNotFoundError(root, layerKey);
     const clips = collectClips(root);
     const excludeId = nodeTimelineId(node);
     const nextStart = opts.start !== undefined ? Math.max(0, opts.start) : numAttr(node, "data-start");
@@ -1260,6 +1335,7 @@ export function setLayerTiming(html, layerKey, opts) {
         track: resolvedTrack,
         playbackStart: opts.playbackStart
     });
+    extendRootDurationToCover(root);
     return { html: serialize(document), layerKey: excludeId || layerKey, track: resolvedTrack };
 }
 /** Composition-level (canvas / theme) edit: resize the frame, retarget total