@officexapp/vidfarm-devcli 0.21.12 → 0.21.14

package/dist/src/devcli/local-frontend-server.js

@@ -10,12 +10,16 @@
 //   2. serves their prebuilt static bundles (demo/dist editor + public/assets),
 //   3. reverse-proxies their data/API calls (/api, /raws, /clips, /composition,
 //      /auto-login, /editor/*/composition) to the logged-in cloud host,
-//   4. intercepts the editor's render POST and runs it ON THIS MACHINE via the
-//      bundled hyperframes CLI (free local render — no backend needed; an
-//      explicit render_target:"cloud" still proxies to the billed renderer),
-//   5. serves the same live-reload SSE the full backend does, driven by
-//      polling the cloud working copy of watched forks, so open editor tabs
-//      live-morph when `vidfarm publish` / another tab changes the fork, and
+//   4. intercepts BOTH render POSTs — the VF tools panel's
+//      /api/v1/compositions/:id/render AND the sealed StudioApp Export
+//      button's studio-contract /api/projects/:id/render — and runs them ON
+//      THIS MACHINE via the bundled hyperframes CLI (free local render — no
+//      backend needed; an explicit render_target:"cloud" still proxies to the
+//      billed renderer),
+//   5. serves the studio live-reload SSE (`/api/events`, `file-change`) the
+//      sealed editor subscribes to, driven by polling the cloud working copy
+//      of watched forks, so open editor tabs live-reload when
+//      `vidfarm publish` / another tab changes the fork, and
 //   6. for every OTHER route, shows a small "this page lives in the cloud"
 //      interstitial with an open-in-new-tab button (browser page loads), so
 //      users aren't silently auto-forwarded off localhost; non-HTML requests
@@ -26,7 +30,7 @@
 // and never drags a backend module into the tarball.
 import { createServer } from "node:http";
 import { createReadStream, existsSync, readFileSync, statSync } from "node:fs";
-import { mkdir } from "node:fs/promises";
+import { mkdir, rm } from "node:fs/promises";
 import { createHash, randomUUID } from "node:crypto";
 import os from "node:os";
 import path from "node:path";
@@ -150,19 +154,18 @@ function editorBoot(pathname, query, auth) {
         songUrl: null,
         initialThreadId: query.get("thread") || null,
         jobRunsUrl: accountId ? `/job-runs?account=${encodeURIComponent(accountId)}` : "/job-runs",
-        // Logged out → free-tier client-only editor (IndexedDB autosave, no cloud
-        // persist/render). Logged in → the cloud account is paid, so drop the gate
-        // and let persist/chat/render proxy to the cloud host.
+        // Logged-out /editor never reaches this boot — handleRequest serves the
+        // login interstitial instead (the sealed StudioApp reads/saves the fork
+        // through the cloud proxy, which 401s without a key). The flag stays for
+        // the non-editor shells' shared template.
         freeTier: !loggedIn,
         editorChatApiUrl: "/api/v1/editor-chat",
         vidfarmApiKey: auth?.apiKey ?? null,
-        // Renders run locally (the shell intercepts the render POST and drives the
-        // bundled hyperframes CLI — free; with a login the Render button becomes
-        // the local/cloud picker), and live-reload is on: the shell polls the
-        // cloud working copy of watched forks and pushes the same `reload` SSE the
-        // full-backend serve emits, so `vidfarm publish` / other tabs live-morph
-        // into an open editor instead of requiring a new tab.
-        liveReload: true,
+        // Renders run locally (the shell intercepts the render POSTs and drives
+        // the bundled hyperframes CLI — free; with a login the Render button
+        // becomes the local/cloud picker). Live-reload needs no boot flag: the
+        // sealed editor always subscribes to EventSource("/api/events"), which
+        // this shell serves locally (see the live-reload section).
         localRender: true,
         cloudRenderAvailable: loggedIn
     };
@@ -291,16 +294,21 @@ async function proxyToCloud(req, res, host, pathWithSearch, auth, bodyOverride)
     }
 }
 // ── live reload (cloud-poll edition) ────────────────────────────────────────
-// The full-backend serve watches the working composition ON DISK and pushes a
-// `reload` SSE so an open editor tab live-morphs when an agent edits the file.
-// This shell has no disk copy — the working state lives on the cloud host — so
-// an open tab used to go stale the moment `vidfarm publish` (or another tab)
-// updated the fork, and users learned to open new tabs. Same SSE contract
-// (`/api/v1/dev/events`, event `reload`, data `{forkId}`), different change
-// source: while at least one tab is subscribed, poll the cloud working copy of
-// every fork a tab has touched and broadcast when its content hash moves.
-// Self-saves are suppressed by pre-seeding the hash from proxied PUT bodies —
-// the shell's equivalent of the backend's compositionWatch.suppressFork.
+// The sealed 0.7.64 StudioApp always subscribes to EventSource("/api/events")
+// and reloads its preview on `file-change` events (data JSON `{path}` — its
+// composition file is "index.html"). On the cloud host that endpoint is a
+// no-op, so an open tab used to go stale the moment `vidfarm publish` (or
+// another tab) updated the fork, and users learned to open new tabs. This
+// shell serves `/api/events` as a REAL local SSE endpoint: while at least one
+// tab is subscribed, poll the cloud working copy (the same studio
+// `/api/projects/:id/files/index.html` route the editor reads) of every fork
+// a tab has touched and broadcast `file-change` when its version moves.
+// Self-saves are suppressed by RESETTING a fork's baseline whenever a studio
+// file write passes through the proxy — the next poll tick re-seeds the
+// version without broadcasting, so a tab's own save never echoes back (the
+// sealed client additionally debounces file-change within 4s of its own
+// saves). The event carries no fork id, so a change broadcasts to every open
+// tab; each merely refetches its own (unchanged) file — cheap and safe.
 const LIVE_POLL_INTERVAL_MS = 3_000;
 const LIVE_WATCH_TTL_MS = 30 * 60_000;
 const LIVE_WATCH_MAX_FORKS = 8;
@@ -311,10 +319,10 @@ let livePollInFlight = false;
 function contentHash(body) {
     return createHash("sha256").update(body).digest("hex");
 }
-/** Record that a tab uses this fork; an explicit hash pre-seeds/suppresses. */
-function noteForkSeen(forkId, hash) {
+/** Record that a tab uses this fork (registers it with the change poller). */
+function noteForkSeen(forkId) {
     const existing = watchedForks.get(forkId);
-    watchedForks.set(forkId, { hash: hash ?? existing?.hash ?? null, lastSeen: Date.now() });
+    watchedForks.set(forkId, { hash: existing?.hash ?? null, lastSeen: Date.now() });
     // Keep the watch list tiny — drop the stalest fork beyond the cap.
     if (watchedForks.size > LIVE_WATCH_MAX_FORKS) {
         let oldest = null;
@@ -329,8 +337,19 @@ function noteForkSeen(forkId, hash) {
             watchedForks.delete(oldest);
     }
 }
-function broadcastReload(forkId) {
-    const frame = `event: reload\ndata: ${JSON.stringify({ forkId })}\n\n`;
+/** A tab (or the render mirror) just WROTE this fork's working copy: null the
+ *  baseline so the next poll re-seeds silently instead of echoing the
+ *  self-save back as a file-change. */
+function resetForkBaseline(forkId) {
+    noteForkSeen(forkId);
+    const entry = watchedForks.get(forkId);
+    if (entry)
+        entry.hash = null;
+}
+function broadcastFileChange() {
+    // The studio contract: event `file-change`, data JSON with the changed
+    // project-relative path. Every fork's composition file is "index.html".
+    const frame = `event: file-change\ndata: ${JSON.stringify({ path: "index.html" })}\n\n`;
     for (const client of sseClients) {
         try {
             client.write(frame);
@@ -350,15 +369,20 @@ async function pollWatchedForks(host, auth) {
                 continue;
             }
             try {
-                const res = await fetch(`${host}/api/v1/compositions/${encodeURIComponent(forkId)}/composition.html`, {
+                // Poll the SAME studio files route the sealed editor reads/writes, so
+                // the compared bytes are exactly what a reloading tab would fetch.
+                const res = await fetch(`${host}/api/projects/${encodeURIComponent(forkId)}/files/index.html`, {
                     headers: auth?.apiKey ? { "vidfarm-api-key": auth.apiKey } : {},
                     signal: AbortSignal.timeout(10_000)
                 });
                 if (!res.ok)
                     continue;
-                const hash = contentHash(await res.text());
+                const file = await res.json().catch(() => null);
+                if (typeof file?.content !== "string")
+                    continue;
+                const hash = file.version || contentHash(file.content);
                 if (entry.hash !== null && entry.hash !== hash)
-                    broadcastReload(forkId);
+                    broadcastFileChange();
                 entry.hash = hash;
             }
             catch { /* transient — retry next tick */ }
@@ -423,6 +447,9 @@ function localRenderStatusJson(renderId, record) {
         cost: "$0.00 (local Vidfarm render)",
         outputUrl: record.status === "SUCCEEDED" ? `/local-renders/${encodeURIComponent(renderId)}.mp4` : undefined,
         error: record.error,
+        // The web poller reads the CLOUD status shape `s.errors?.[0]?.error` — emit
+        // both so a local failure surfaces its real message, not "Render failed.".
+        errors: record.error ? [{ error: record.error }] : undefined,
         fatalErrorEncountered: record.status === "FAILED" ? true : undefined
     };
 }
@@ -486,6 +513,126 @@ async function startLocalRender(input) {
     })();
     return { renderId, record };
 }
+const studioRenders = new Map();
+const STUDIO_RENDER_MIME = {
+    ".mp4": "video/mp4",
+    ".webm": "video/webm",
+    ".mov": "video/quicktime"
+};
+// Same synthetic creep as localRenderStatusJson, on the studio 0-100 scale.
+function studioRenderProgress(job) {
+    if (job.status === "complete")
+        return 100;
+    if (job.status !== "rendering")
+        return 0;
+    return Math.round(Math.min(93, 4 + ((Date.now() - job.startedAt) / LOCAL_RENDER_ESTIMATE_MS) * 90));
+}
+function studioProgressPayload(job) {
+    return { progress: studioRenderProgress(job), status: job.status, stage: job.stage, error: job.error };
+}
+async function startStudioRender(input) {
+    // The composition source is the studio files route — exactly what the sealed
+    // editor has been editing (the working copy on the cloud host).
+    const res = await fetch(`${input.host}/api/projects/${encodeURIComponent(input.projectId)}/files/index.html`, {
+        headers: input.auth?.apiKey ? { "vidfarm-api-key": input.auth.apiKey } : {},
+        signal: AbortSignal.timeout(FORK_RESOLVE_TIMEOUT_MS)
+    });
+    if (!res.ok) {
+        throw new Error(`Could not load the composition for ${input.projectId} (${res.status}). Run \`vidfarm login\` and reload the editor.`);
+    }
+    const file = await res.json().catch(() => null);
+    const compositionHtml = typeof file?.content === "string" ? file.content : "";
+    if (!compositionHtml.includes("data-composition-id=")) {
+        throw new Error(`Composition for ${input.projectId} is missing data-composition-id — not renderable.`);
+    }
+    // Validate the studio request body the way the upstream route does; anything
+    // off-contract falls back to its default rather than erroring.
+    const format = (["mp4", "webm", "mov"].includes(String(input.body.format)) ? String(input.body.format) : "mp4");
+    const quality = (["draft", "standard", "high"].includes(String(input.body.quality)) ? String(input.body.quality) : "standard");
+    // Upstream accepts integer fps or an ffmpeg rational string; the local
+    // pipeline takes integers only, so rationals fall back to the root data-fps.
+    const fps = typeof input.body.fps === "number" && Number.isFinite(input.body.fps) && input.body.fps > 0
+        ? Math.round(input.body.fps)
+        : undefined;
+    // Upstream job ids are `${projectId}_${timestamp}` and double as filenames.
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-").replace("T", "_").slice(0, 19);
+    const jobId = `${input.projectId}_${stamp}`;
+    const filename = `${jobId}.${format}`;
+    await mkdir(localRenderDir, { recursive: true });
+    const outputPath = path.join(localRenderDir, filename);
+    const job = {
+        projectId: input.projectId,
+        status: "rendering",
+        startedAt: Date.now(),
+        stage: "preparing",
+        outputPath,
+        filename
+    };
+    studioRenders.set(jobId, job);
+    void (async () => {
+        try {
+            const { renderCompositionLocally } = await import("./local-render.js");
+            await renderCompositionLocally({
+                compositionHtml,
+                outputPath,
+                fps,
+                quality,
+                format,
+                stdio: "capture",
+                log: (event) => {
+                    if (event === "local_render.start" && job.status === "rendering")
+                        job.stage = "rendering";
+                }
+            });
+            // A cancel marks the job terminal for the UI but cannot abort the child
+            // process — don't resurrect a cancelled job when it eventually finishes.
+            if (job.status === "rendering") {
+                job.status = "complete";
+                job.stage = undefined;
+            }
+            job.endedAt = Date.now();
+            console.log(`[vidfarm] local render ${jobId} finished (${((job.endedAt - job.startedAt) / 1000).toFixed(1)}s) → ${outputPath}`);
+        }
+        catch (error) {
+            if (job.status === "rendering")
+                job.status = "failed";
+            job.error = error instanceof Error ? error.message : String(error);
+            job.endedAt = Date.now();
+            console.error(`[vidfarm] local render ${jobId} failed: ${job.error}`);
+        }
+    })();
+    return { jobId, job };
+}
+// The studio progress contract: an SSE stream that snapshots the job every
+// 500ms and ends after the first terminal status (mirrors upstream streamSSE).
+function handleStudioRenderProgressStream(req, res, jobId) {
+    res.statusCode = 200;
+    res.setHeader("content-type", "text/event-stream");
+    res.setHeader("cache-control", "no-store");
+    res.setHeader("connection", "keep-alive");
+    let closed = false;
+    req.on("close", () => { closed = true; });
+    void (async () => {
+        while (!closed) {
+            const job = studioRenders.get(jobId);
+            if (!job)
+                break;
+            try {
+                res.write(`event: progress\ndata: ${JSON.stringify(studioProgressPayload(job))}\n\n`);
+            }
+            catch {
+                break;
+            }
+            if (job.status !== "rendering")
+                break;
+            await new Promise((resolve) => setTimeout(resolve, 500));
+        }
+        try {
+            res.end();
+        }
+        catch { /* already gone */ }
+    })();
+}
 // ── cloud-only interstitial ─────────────────────────────────────────────────
 // Shown instead of an auto-forwarding 302 when a browser navigates to a route
 // the local frontend doesn't serve. Keeps the user oriented on localhost and
@@ -528,6 +675,40 @@ function renderCloudOnlyPage(cloudUrl, pathname) {
 </html>
 `;
 }
+// Shown instead of the editor shell when serve has no persisted login. The
+// sealed StudioApp reads and saves the fork through the cloud proxy
+// (GET/PUT /api/projects/:id/files/*), which 401s without a key — the shell
+// would otherwise render a blank, stuck editor. Other routes are unaffected.
+function renderLoginRequiredPage(pathname) {
+    const safePath = escapeHtml(pathname);
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Log in to edit | VidFarm</title>
+<style>
+  body{margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;background:#fbfbfb;color:#171717;font:15px/1.55 -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif}
+  .card{max-width:460px;margin:24px;padding:36px 32px;background:#fff;border:1px solid #ededed;border-radius:16px;box-shadow:0 4px 24px -8px #00000026,0 1px 2px #0000000d;text-align:center}
+  h1{margin:0 0 8px;font-size:19px}
+  p{margin:0 0 16px;color:#737373}
+  code{font-size:13px;background:#f5f5f5;border-radius:6px;padding:2px 6px}
+  pre{margin:0 0 20px;padding:12px 16px;background:#171717;color:#fafafa;border-radius:10px;font:13px/1.5 ui-monospace,SFMono-Regular,Menlo,monospace;text-align:left;overflow-x:auto}
+  .hint{margin-top:16px;font-size:13px;color:#a3a3a3}
+</style>
+</head>
+<body>
+<div class="card">
+  <h1>Log in to use the local editor</h1>
+  <p>The local editor at <code>${safePath}</code> edits your CLOUD fork — without a login every project read/save fails and the editor loads blank. Run:</p>
+  <pre>vidfarm login</pre>
+  <p>then restart <code>vidfarm serve</code> and reload this page.</p>
+  <div class="hint">Local pages that work without a login: /tools/*, /library, /library/raws</div>
+</div>
+</body>
+</html>
+`;
+}
 export function startLocalFrontendServer(opts) {
     const host = opts.host.replace(/\/+$/, "");
     const server = createServer((req, res) => {
@@ -540,7 +721,11 @@ export function startLocalFrontendServer(opts) {
         });
     });
     return new Promise((resolve, reject) => {
-        server.once("error", reject);
+        server.once("error", (error) => {
+            reject(error.code === "EADDRINUSE"
+                ? new Error(`Port ${opts.port} is already in use (another local job, or an orphaned server). Pass --port <n>, or run \`vidfarm doctor --kill-orphans\` to reclaim it.`)
+                : error);
+        });
         server.listen(opts.port, () => resolve({ port: opts.port, host }));
     });
 }
@@ -557,22 +742,23 @@ async function handleRequest(req, res, host, auth) {
         return;
     }
     // 2. Live-reload SSE for open editor tabs (see the live-reload section).
-    if (pathname === "/api/v1/dev/events" && req.method === "GET") {
+    // The sealed editor subscribes here; MUST be intercepted before the proxy
+    // (/api/events matches isProxyPath and would otherwise forward to the cloud).
+    if (pathname === "/api/events" && req.method === "GET") {
         handleDevEventsStream(req, res, host, auth);
         return;
     }
-    // Track which forks tabs are using, and pre-seed hashes from saves so a
-    // tab's own PUT never bounces back as a reload.
-    const compositionFile = pathname.match(/^\/api\/v1\/compositions\/([^/]+)\/composition\.html\/?$/);
-    if (compositionFile && (req.method === "PUT" || req.method === "POST")) {
-        const forkId = decodeURIComponent(compositionFile[1]);
-        const bodyBuf = await readBody(req);
-        noteForkSeen(forkId, contentHash(bodyBuf));
-        await proxyToCloud(req, res, host, pathname + parsed.search, auth, bodyBuf);
+    // Track which forks tabs are using: the sealed editor's project traffic is
+    // the studio files route (project id == fork id). Writes reset the fork's
+    // poll baseline so a tab's own save never bounces back as a file-change.
+    const studioFile = pathname.match(/^\/api\/projects\/([^/]+)\/files\//);
+    if (studioFile && (req.method === "PUT" || req.method === "POST" || req.method === "PATCH")) {
+        resetForkBaseline(decodeURIComponent(studioFile[1]));
+        await proxyToCloud(req, res, host, pathname + parsed.search, auth);
         return;
     }
-    if (compositionFile && req.method === "GET") {
-        noteForkSeen(decodeURIComponent(compositionFile[1]));
+    if (studioFile && req.method === "GET") {
+        noteForkSeen(decodeURIComponent(studioFile[1]));
     }
     const editorForkPage = req.method === "GET" ? pathname.match(/^\/editor\/[^/]+\/fork\/([^/]+)\/?$/) : null;
     if (editorForkPage)
@@ -595,9 +781,10 @@ async function handleRequest(req, res, host, auth) {
         try {
             const renderForkId = decodeURIComponent(renderPost[1]);
             // The render intercept PUTs the submitted html back to the cloud working
-            // copy — pre-seed the hash so that save doesn't echo back as a reload.
+            // copy — reset the poll baseline so that save doesn't echo back as a
+            // file-change to open editor tabs.
             if (typeof body.html === "string" && body.html)
-                noteForkSeen(renderForkId, contentHash(body.html));
+                resetForkBaseline(renderForkId);
             const { renderId, record } = await startLocalRender({ host, auth, forkId: renderForkId, body });
             sendJson(res, 202, localRenderStatusJson(renderId, record));
         }
@@ -632,6 +819,100 @@ async function handleRequest(req, res, host, auth) {
         createReadStream(record.outputPath).pipe(res);
         return;
     }
+    // 3b. Studio-contract render endpoints (the sealed StudioApp's Export
+    // button; see the studio-contract render section). Everything here must run
+    // BEFORE the proxy — these paths all match isProxyPath, and on the cloud
+    // host the render dispatch can never finish (in-process render on Lambda).
+    const studioRenderPost = req.method === "POST" ? pathname.match(/^\/api\/projects\/([^/]+)\/render\/?$/) : null;
+    if (studioRenderPost) {
+        const bodyBuf = await readBody(req);
+        let body = {};
+        try {
+            body = JSON.parse(bodyBuf.toString("utf8") || "{}");
+        }
+        catch { /* tolerate empty body */ }
+        try {
+            const { jobId } = await startStudioRender({ host, auth, projectId: decodeURIComponent(studioRenderPost[1]), body });
+            sendJson(res, 200, { jobId, status: "rendering" });
+        }
+        catch (error) {
+            sendJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
+        }
+        return;
+    }
+    // Progress SSE for local studio jobs; unknown job ids proxy on (404 upstream).
+    const studioProgress = req.method === "GET" ? pathname.match(/^\/api\/render\/([^/]+)\/progress\/?$/) : null;
+    if (studioProgress && studioRenders.has(decodeURIComponent(studioProgress[1]))) {
+        handleStudioRenderProgressStream(req, res, decodeURIComponent(studioProgress[1]));
+        return;
+    }
+    const studioCancel = req.method === "POST" ? pathname.match(/^\/api\/render\/([^/]+)\/cancel\/?$/) : null;
+    if (studioCancel) {
+        const job = studioRenders.get(decodeURIComponent(studioCancel[1]));
+        if (job) {
+            // The hyperframes child can't be aborted from here; mark the job
+            // cancelled so the SSE stream terminates — the same fallback the
+            // upstream route documents for adapters without a cancel hook.
+            if (job.status === "rendering")
+                job.status = "cancelled";
+            sendJson(res, 200, { status: job.status });
+            return;
+        }
+    }
+    const studioDelete = req.method === "DELETE" ? pathname.match(/^\/api\/render\/([^/]+)\/?$/) : null;
+    if (studioDelete) {
+        const jobId = decodeURIComponent(studioDelete[1]);
+        const job = studioRenders.get(jobId);
+        if (job) {
+            await rm(job.outputPath, { force: true }).catch(() => { });
+            studioRenders.delete(jobId);
+            sendJson(res, 200, { deleted: true });
+            return;
+        }
+    }
+    // Render history: local jobs merged with the cloud's list (best-effort).
+    const studioRendersList = req.method === "GET" ? pathname.match(/^\/api\/projects\/([^/]+)\/renders\/?$/) : null;
+    if (studioRendersList) {
+        const projectId = decodeURIComponent(studioRendersList[1]);
+        const local = Array.from(studioRenders.entries())
+            .filter(([, job]) => job.projectId === projectId && job.status === "complete" && existsSync(job.outputPath))
+            .map(([jobId, job]) => ({
+            id: jobId,
+            filename: job.filename,
+            size: statSync(job.outputPath).size,
+            createdAt: job.endedAt ?? job.startedAt,
+            status: "complete",
+            durationMs: job.endedAt ? job.endedAt - job.startedAt : undefined
+        }));
+        let cloud = [];
+        try {
+            const upstream = await fetch(new URL(pathname, host), {
+                headers: auth?.apiKey ? { "vidfarm-api-key": auth.apiKey } : {},
+                signal: AbortSignal.timeout(10_000)
+            });
+            const json = upstream.ok ? await upstream.json().catch(() => null) : null;
+            if (Array.isArray(json?.renders))
+                cloud = json.renders;
+        }
+        catch { /* cloud history is advisory */ }
+        sendJson(res, 200, { renders: [...local, ...cloud] });
+        return;
+    }
+    // Finished studio render files (the client links /renders/file/<filename>);
+    // filenames we didn't mint proxy on to the cloud's render store.
+    const studioRenderFile = req.method === "GET" ? pathname.match(/^\/api\/projects\/[^/]+\/renders\/file\/([^/]+)$/) : null;
+    if (studioRenderFile) {
+        const filename = decodeURIComponent(studioRenderFile[1]);
+        const job = Array.from(studioRenders.values()).find((j) => j.filename === filename);
+        if (job && existsSync(job.outputPath)) {
+            res.statusCode = 200;
+            res.setHeader("content-type", STUDIO_RENDER_MIME[path.extname(job.outputPath)] ?? "video/mp4");
+            res.setHeader("content-length", String(statSync(job.outputPath).size));
+            res.setHeader("content-disposition", `inline; filename="${filename}"`);
+            createReadStream(job.outputPath).pipe(res);
+            return;
+        }
+    }
     // 4. Data plane → reverse-proxy to the cloud host.
     if (isProxyPath(pathname)) {
         await proxyToCloud(req, res, host, pathname + parsed.search, auth);
@@ -652,6 +933,17 @@ async function handleRequest(req, res, host, auth) {
     }
     // 6. Locally-served page shells (client-hydrated) → snapshot + boot fill.
     const shellFile = shellFileForPath(pathname);
+    // The editor is cloud-backed even on localhost: the sealed StudioApp
+    // reads/saves the fork through the proxied studio files routes, which 401
+    // without a login and leave a blank stuck editor. Show a clear "log in
+    // first" interstitial instead of the broken shell.
+    if (shellFile === "editor.html" && !auth?.apiKey && req.method === "GET") {
+        res.statusCode = 200;
+        res.setHeader("content-type", "text/html; charset=utf-8");
+        res.setHeader("cache-control", "no-cache");
+        res.end(renderLoginRequiredPage(pathname));
+        return;
+    }
     if (shellFile && req.method === "GET") {
         const html = readRootFile(`public/serve-shells/${shellFile}`);
         if (html) {

package/dist/src/devcli/port-utils.js

@@ -0,0 +1,43 @@
+// Backend-free port helpers for the local serve / render loops.
+//
+// Customers routinely run several local video jobs at once (one `vidfarm serve`
+// per fork, plus ad-hoc renders), so a hard-coded port is a foot-gun: the
+// second job would crash with EADDRINUSE. These helpers let `serve` claim the
+// next free port automatically and let `doctor` report contention. Only
+// `node:net` is used, so this stays inside the CLI's backend-free closure.
+import net from "node:net";
+/**
+ * True when `port` can be bound on `host` right now. Resolves false on
+ * EADDRINUSE (and any other bind error — a port we cannot bind is unusable).
+ */
+export function isPortFree(port, host = "127.0.0.1") {
+    return new Promise((resolve) => {
+        const tester = net.createServer();
+        tester.once("error", () => resolve(false));
+        tester.once("listening", () => {
+            tester.close(() => resolve(true));
+        });
+        // Bind on both the loopback (what the browser hits) and, implicitly, the
+        // wildcard the runtime listens on — 127.0.0.1 is the strict subset that
+        // matters for a same-box collision.
+        tester.listen(port, host);
+    });
+}
+/**
+ * Return the first free port at or above `preferred`. Throws only when an
+ * entire window of `maxTries` ports is occupied (effectively never on a dev
+ * box). Sequential probing keeps the chosen port predictable — the Nth
+ * concurrent serve tends to land on preferred+N-1.
+ */
+export async function findFreePort(preferred, opts = {}) {
+    const host = opts.host ?? "127.0.0.1";
+    const maxTries = Math.max(1, opts.maxTries ?? 64);
+    for (let candidate = preferred; candidate < preferred + maxTries; candidate += 1) {
+        if (candidate > 65535)
+            break;
+        if (await isPortFree(candidate, host))
+            return candidate;
+    }
+    throw new Error(`No free TCP port found in ${preferred}..${Math.min(preferred + maxTries - 1, 65535)} — close some local jobs (see \`vidfarm doctor\`) or pass an explicit --port.`);
+}
+//# sourceMappingURL=port-utils.js.map