Open source CapCut alternative.
TypeScript
refactor(cut): render captured revisions through project commands [rebuild]
David Le236f37e5ba22
diff --git a/docs/guides/cut/README.md b/docs/guides/cut/README.mdindex c6ad0b16..cc713380 100644--- a/docs/guides/cut/README.md+++ b/docs/guides/cut/README.md@@ -28,6 +28,24 @@ AI is hosted whatever the home: image, video, and voiceover generation and the aThe preview scrubs and plays from per-clip decoders held in memory. It shows a frame the moment it arrives and refines behind it, so the timeline always answers and a jump lands on a picture. Every cache is bounded by one memory budget sized to the machine. The performance guide holds the frame budget and how a change is measured.+Background previews capture a project operation and a render document before asynchronous work starts. The operation carries the project, residency, document version, capabilities, and transport. The preview queue coalesces edits and drains the final edit when the editor closes. Cloud exports requested from a document store that document in the queued job, so a later edit cannot change the export's input.++```+Project operation + captured document+ ↓+ Render preparation+ ↓+ Residency renderer+ ↓+ Preview artifact+ ↓+ ArtifactVideo+```++Browser previews use the browser compositor and replace one cached proxy in OPFS. A browser without the required encoders borrows the cloud worker and brings the result back to OPFS. Automatic browser renders run while the page is hidden and stop when editing resumes or the editor closes; the shelf uses the last completed proxy or its source thumbnail. Mac previews use the engine, retain a file per live job, and publish the project card atomically. Cloud preview jobs have immutable object keys; only the newest requested job can publish the project's preview pointer. A job ID resolves to a fresh delivery URL. Retired cloud previews expire after a day, while the current project preview stays available. The shared viewer plays MP4 or HLS with its own media element and releases its resources on source changes and unmount.++Cloud source media, generated media, and retained exports count toward storage. Derived previews, share cards, and HLS ladders are quota-exempt; staging inputs are temporary. Garbage collection also corrects accounting for older preview and card objects in bounded batches. Transports expose structured storage, credit, and authentication failures. Each host chooses their presentation; the website mounts its storage dialog separately.+Timeline and preview share selection: ⌘/Ctrl-click or Shift-click toggles items, and dragging moves them together with one undo step. Items move independently until grouped, and groups save with the project.Guides draw over the preview from the button beside the timeline zoom: thirds, center, safe margins, the short-form keep-out zone where TikTok, Reels and Shorts draw their own UI or crop the sides of a 9:16 frame, and custom lines dragged into place on the preview. They save with the project, snap a dragged element to their edges, never export, and the assistant reads the safe area they leave when it places graphics.diff --git a/docs/guides/cut/ai-assistant.md b/docs/guides/cut/ai-assistant.mdindex 860aa847..c9a797db 100644--- a/docs/guides/cut/ai-assistant.md+++ b/docs/guides/cut/ai-assistant.md@@ -147,3 +147,7 @@ Two mechanical paths are guarded without a model at all, because no ear settlesThe shared catalog (system prompt, tools, skills), the chat route with its provider runners, the browser-tool bridge, its tab-less executor (`server/ai/headlessTools.ts`), and the stdio MCP proxy live with the engine's AI code under the site's `cut/` folder (`server/ai/`, `server/http/ai.ts`). The page side holds the snapshot builder (`lib/aiContext.ts`), the tool implementations (`lib/aiTools.ts`), the pi-based chat loop and its adapters (`lib/pi/`), the model catalog (`lib/aiModels.ts`), and the chat panel with threads and transport (`components/AiPanel.tsx`). Running the same loop with no browser is `lib/headless/`, the turns route in `server/cloud/turns.ts`, and the worker job in `worker/turnJob.ts`.The brief-to-video pipeline is its own subsystem: the orchestrator, coverage invariant, and role interfaces in `lib/genvideo/`, its hosted-model adapters in `lib/genvideo/adapters/`, the browser controller in `lib/genScene.ts`, and the progress card in `components/SceneCard.tsx`. Its strategy — story planning, the identity ladder, where audio goes next — is the [Brief to Video](brief-to-video.md) guide.++Project commands share the editor's tool schemas and executor through `PROJECT_TOOLS` and `runProjectCommand`. The command boundary checks the active project and excludes editor-only actions. Headless callers keep the existing serialized engine session or isolated cloud worker, since the editing store belongs to that session. Deterministic editing commands call the executor directly; hosted generation keeps its credit checks.++`render_preview` captures the current cut and returns a render job with its revision and playback URL. Cloud and Mac jobs include a status URL for the host to poll. A headless turn can enqueue the render and finish, freeing its worker slot for the render. A Mac session without the media runtime returns the existing detached-media error and can run the command from the editor tab.diff --git a/site/src/cut/components/Editor.tsx b/site/src/cut/components/Editor.tsxindex ffde466d..a4a27da1 100644--- a/site/src/cut/components/Editor.tsx+++ b/site/src/cut/components/Editor.tsx@@ -15,12 +15,10 @@ import {import { knownDocVersion } from "@/cut/lib/backend/cloud";import { loadedDocVersion } from "@/cut/lib/backend/shared";import { flushCachedDocWrites, writeCachedDoc, writeCachedDocDirty } from "@/cut/lib/docCache";-import {- refreshShareCard,- refreshShareLadder,- renderPreviewProxy,- type ExportDoc,-} from "@/cut/lib/exportClient";+import { refreshProjectPreviews } from "@/cut/lib/exportClient";+import { captureRenderSnapshot, renderDoc, type ExportDoc } from "@/cut/lib/renderSnapshot";+import { projectOperation, type ProjectOperation } from "@/cut/lib/projectOperation";+import { createPreviewQueue } from "@/cut/lib/previewQueue";import { EMPTY_LIBRARY, fileZoneAt, hasRefDrag, parseMentions, refCandidatesOf } from "@/cut/lib/assetRef";import { placeRefAtPlayhead } from "@/cut/lib/refPlace";import { copyTimelineSelection, pasteCutPayload, payloadFromHtml } from "@/cut/lib/cutClipboard";@@ -428,41 +426,35 @@ export function Editor({// own export queued behind it.useEffect(() => {if (viewer) return;- let pending: ExportDoc | null = null;- let rendering = false;- let lastRun = 0;- // The stashed doc renders as captured, so a flush that lands after the- // store has moved on still writes this project's proxy rather than nothing.- // `final` marks a one-shot exit (the project closing, the page going away):- // there is no next chance, so it skips the rate floor rather than leaving- // the card frozen mid-edit.- const flush = async (final = false) => {- const doc = pending;- if (!doc || rendering || (!final && Date.now() - lastRun < PROXY_MIN_GAP_MS)) return;- pending = null;- rendering = true;- lastRun = Date.now();- try {- await renderPreviewProxy(projectId, doc);- refreshShareCard(projectId);- // The share's streaming ladder rides this same lull. It is the most- // expensive of the three — the whole cut, once per rung — so it runs- // last, and it no-ops for a project that isn't shared.- await refreshShareLadder(projectId);- } finally {- rendering = false;- }- };+ let closing = false;+ let browserRender: AbortController | null = null;+ const queue = createPreviewQueue<{ operation: ProjectOperation; doc: ExportDoc }, void>(+ async ({ operation, doc }) => {+ // Browser encoding yields to visible editing and ends with its page.+ if (operation.residency === "browser" && (closing || document.visibilityState !== "hidden")) return;+ const controller = operation.residency === "browser" ? new AbortController() : null;+ browserRender = controller;+ try {+ await refreshProjectPreviews(captureRenderSnapshot(operation, doc), controller?.signal);+ } finally {+ if (browserRender === controller) browserRender = null;+ }+ },+ PROXY_MIN_GAP_MS+ );+ const flush = queue.flush;// Backgrounding the tab is the reliable signal that the user has stepped// away — it fires on a tab switch, a window blur, and on the way out of the// page, where an unmount alone never runs.const onVisibility = () => {if (document.visibilityState === "hidden") void flush();+ else { closing = false; browserRender?.abort(); }};- const onPageHide = () => void flush(true);+ const onPageHide = () => { closing = true; browserRender?.abort(); void flush(true); };document.addEventListener("visibilitychange", onVisibility);window.addEventListener("pagehide", onPageHide);let last: {+ assets: unknown;clips: unknown;audioClips: unknown;overlays: unknown;@@ -476,7 +468,8 @@ export function Editor({if (!s.loaded || s.projectId !== projectId) return;const changed =last !== null &&- (s.clips !== last.clips ||+ (s.assets !== last.assets ||+ s.clips !== last.clips ||s.audioClips !== last.audioClips ||s.overlays !== last.overlays ||s.subtitles !== last.subtitles ||@@ -485,6 +478,7 @@ export function Editor({s.fadeOut !== last.fadeOut ||s.background !== last.background);last = {+ assets: s.assets,clips: s.clips,audioClips: s.audioClips,overlays: s.overlays,@@ -498,23 +492,15 @@ export function Editor({// A cut of titles and shapes over the background has a picture to show;// only an empty project has nothing to render a card from.if (projectDuration(s) <= 0) return;- pending = {- aspect: s.aspect,- assets: s.assets,- clips: s.clips,- audioClips: s.audioClips,- overlays: s.overlays,- subtitles: s.subtitles,- fadeIn: s.fadeIn,- fadeOut: s.fadeOut,- background: s.background,- };+ queue.stage({ operation: projectOperation(projectId), doc: renderDoc(s) });});return () => {unsub();document.removeEventListener("visibilitychange", onVisibility);window.removeEventListener("pagehide", onPageHide);- void flush(true); // the project is closing: land whatever is still stashed+ closing = true;+ browserRender?.abort();+ void flush(true);};}, [projectId, viewer]);diff --git a/site/src/cut/components/Preview.tools.ts b/site/src/cut/components/Preview.tools.tsindex 302dcc09..25c027a0 100644--- a/site/src/cut/components/Preview.tools.ts+++ b/site/src/cut/components/Preview.tools.ts@@ -8,6 +8,11 @@import { bool, num, obj, type AiToolDef } from "@/cut/lib/aiToolDef";export const PREVIEW_TOOLS = [+ {+ name: "render_preview",+ description: "Render a low-resolution video of the current cut, including overlays and captions. Returns a job with its captured revision, status and playback URL. A queued cloud or Mac job becomes playable when its status URL reports done. This renders the whole cut; use capture_frame for a single frame.",+ inputSchema: obj({}),+ },{name: "move_selection",description: "Move selected visual items together in the preview, preserving their spacing. dx/dy are fractions of frame width/height. Supports video, titles, shapes, stickers, and caption tracks; audio and effects keep their timing. Keyframed items receive position keys at the playhead. One undo step.",diff --git a/site/src/cut/components/Timeline.tsx b/site/src/cut/components/Timeline.tsxindex b34726a0..c9e603b6 100644--- a/site/src/cut/components/Timeline.tsx+++ b/site/src/cut/components/Timeline.tsx@@ -42,7 +42,8 @@ import {saveAssetToLibrary,type LibraryAsset,} from "@/cut/lib/library";-import { originalSettings, type ExportDoc } from "@/cut/lib/exportClient";+import { originalSettings } from "@/cut/lib/exportClient";+import type { ExportDoc } from "@/cut/lib/renderSnapshot";import { useExports } from "@/cut/lib/exportStore";import { isDragActive, startDrag, subscribeDragActive } from "@/cut/lib/drag";import { keyboardToEditor, shortcutDecline } from "@/cut/lib/shortcutGate";diff --git a/site/src/cut/lib/aiTools.ts b/site/src/cut/lib/aiTools.tsindex 2027168a..981bb641 100644--- a/site/src/cut/lib/aiTools.ts+++ b/site/src/cut/lib/aiTools.ts@@ -1,5 +1,11 @@"use client";+import { projectRevision } from "@/cut/lib/projectRevision";+import { assertProjectCommand } from "./projectCommands";+import { projectOperation, type ProjectOperation } from "./projectOperation";+import { captureRenderSnapshot, renderDoc } from "./renderSnapshot";+import { submitPreviewSnapshot } from "./exportClient";+import { ITEM_KIND_IDS, ITEM_KINDS, type ItemKind } from "./itemKinds";import { timelineItem } from "./timelineItems";import { movePreviewSelection, previewSelectionSnapshot } from "@/cut/lib/previewSelection";@@ -405,7 +411,7 @@ type BrowserToolName = Exclude<type Editor = ReturnType<typeof useEditor.getState>;-type ToolRun = (s: Editor, input: Record<string, unknown>) => Promise<unknown> | unknown;+type ToolRun = (s: Editor, input: Record<string, unknown>, operation?: ProjectOperation) => Promise<unknown> | unknown;/** The browser handler for every tool, keyed by the names the `*.tools.ts`* modules beside the components export, so a tool added, removed, or renamed@@ -808,6 +814,11 @@ const toolRuns: Record<BrowserToolName, ToolRun> = {return buildAiContext({ fullCues: true });},+ render_preview: async (s, _input, operation) => {+ if (!s.projectId || !s.loaded) throw new ToolError("No project open.");+ return submitPreviewSnapshot(captureRenderSnapshot(operation ?? projectOperation(s.projectId), renderDoc(s)));+ },+capture_frame: async (s, input) => {// Composited through the render path, so the frame carries what the// finished file would carry — clips, transitions, effects, elements,@@ -4218,21 +4229,6 @@ const toolRuns: Record<BrowserToolName, ToolRun> = {class ToolError extends Error {}-/**- * Execute an assistant tool call against the live editor store.- * Returns a small JSON-safe result; throws ToolError with a readable message.- */-/** Tools whose whole effect is the editor UI in an open tab — panel focus,- * scroll, playback. A session with no page answers them with a typed no-op so- * the model keeps its footing. Everything else runs anywhere the media- * primitives do. */-export const UI_TOOLS: ReadonlySet<string> = new Set([- "set_side_panel",- "set_view",- "open_export",- "set_playing",-]);-/** Tools that decode or rasterize media — frame grabs, audio scans, image* decodes, the transcription mixdown. A page has those primitives and a* headless process installs them; a process that installed neither refuses@@ -4246,6 +4242,7 @@ export const MEDIA_RUNTIME_TOOLS: ReadonlySet<string> = new Set(["detect_beats","refine_speech_cuts","capture_frame",+ "render_preview","freeze_frame","create_sticker","subtitles_generate",@@ -4260,13 +4257,31 @@ export async function runAiTool(name: string,input: Record<string, unknown>): Promise<unknown> {- const s = useEditor.getState();+ return dispatchTool(useEditor.getState(), name, input);+}+async function dispatchTool(s: Editor, name: string, input: Record<string, unknown>, operation?: ProjectOperation): Promise<unknown> {// "update_title" stays as an alias so older threads keep working.const key = name === "update_title" ? "update_overlay" : name;const run = (toolRuns as Partial<Record<string, ToolRun>>)[key];if (!run) throw new ToolError(`Unknown tool: ${name}`);- return run(s, input);+ return run(s, input, operation);+}++/** Used inside the existing serialized engine session or isolated cloud worker.+ * The caller supplies a hydrated project; deterministic commands invoke no model. */+export async function runProjectCommand(+ operation: ProjectOperation,+ name: string,+ input: Record<string, unknown>+): Promise<unknown> {+ const state = useEditor.getState();+ assertProjectCommand(operation, state.projectId, name, projectRevision(operation.projectId));+ if (!state.loaded) throw new ToolError("The project is still opening.");+ const result = await dispatchTool(state, name, input, operation);+ if (useEditor.getState().projectId !== operation.projectId)+ throw new ToolError("The project changed while the command was running.");+ return result;}/** Synthesize speech segments with hosted Gemini voices (the user's Donkeydiff --git a/site/src/cut/lib/backend/browser/opfs.ts b/site/src/cut/lib/backend/browser/opfs.tsindex eaa990b8..4668e4d5 100644--- a/site/src/cut/lib/backend/browser/opfs.ts+++ b/site/src/cut/lib/backend/browser/opfs.ts@@ -17,6 +17,7 @@// Project directories are named by id — no Finder here, so nothing follows// display names. Everything is functions over handles; no module-level DOM or// storage access, because this file rides along in the engine bundle.+import { registerBlobFile } from "./registry";import { isDeliveryName } from "../../exportDelivery";import type { ProjectDoc, ProjectFolder, ProjectSummary } from "../../types";import { currentEngineUser } from "../../api";@@ -222,6 +223,8 @@ async function dirBytes(dir: FileSystemDirectoryHandle | null): Promise<number>/** The engine's summary shape for a doc in the store. */export async function summarize(id: string, doc: ProjectDoc): Promise<ProjectSummary> {+ const preview = await readFileAt(await projectDir(id), "preview.mp4");+ if (preview) registerBlobFile(`/api/cut/projects/${id}/preview`, preview);const track0 = doc.clips.filter((c) => (c.track ?? 0) === 0);const firstClip = track0[0];const firstClipAsset = firstClip ? doc.assets.find((a) => a.id === firstClip.assetId) : undefined;@@ -238,7 +241,7 @@ export async function summarize(id: string, doc: ProjectDoc): Promise<ProjectSumpreviewFile: previewAsset?.fileName,previewIsImage: previewAsset?.type === "image",previewStart: firstClipAsset && firstClip ? firstClip.in : 0,- hasPreview: false,+ hasPreview: preview !== null,aspect: doc.aspect,folderId: doc.folderId ?? null,sizeBytes: await dirBytes(await projectDir(id)),diff --git a/site/src/cut/lib/backend/browser/router.ts b/site/src/cut/lib/backend/browser/router.tsindex 05fcdeeb..3b19d7d3 100644--- a/site/src/cut/lib/backend/browser/router.ts+++ b/site/src/cut/lib/backend/browser/router.ts@@ -402,6 +402,10 @@ export async function dispatchBrowserRoute(}// /projects/:id/<action>if (rest.length === 3) {+ if (rest[2] === "preview" && method === "GET") {+ const file = await store.readFileAt(await store.projectDir(id), "preview.mp4");+ return file ? serveFile(file, "preview.mp4", download) : err("Preview not ready.", 404);+ }if (rest[2] === "duplicate" && method === "POST") return duplicateProject(id);if (rest[2] === "move" && method === "POST") return moveProject(req(), id);if (rest[2] === "media" && method === "POST") return uploadMedia(req(), id);diff --git a/site/src/cut/lib/exportClient.ts b/site/src/cut/lib/exportClient.tsindex aea74699..09cea184 100644--- a/site/src/cut/lib/exportClient.ts+++ b/site/src/cut/lib/exportClient.ts@@ -1,5 +1,9 @@"use client";+import { captureRenderSnapshot, renderDoc, type ExportDoc, type RenderSnapshot } from "./renderSnapshot";+import { operationFailure, type OperationFailure } from "./operationFailure";+import { projectOperation } from "./projectOperation";+import { apiFetch, apiJson, getBackend, type CutBackend } from "./backend";import { engineFeatures } from "./api";import type { EngineFeature } from "./engineFeatures";@@ -8,11 +12,11 @@ import {reserveBrowserExportJob,updateBrowserExportJob,} from "./backend/browser/exportJobs";-import { exportsDir, readFileAt, saveExport } from "./backend/browser/opfs";+import { exportsDir, projectDir, writeFileAt, readFileAt, saveExport } from "./backend/browser/opfs";import { holdRegistered, registerBlobFile, releaseRegistered, resolveRegisteredBlob } from "./backend/browser/registry";-import { cloudBackend, quotaErrorMessage } from "./backend/cloud";+import { captureCloudBackend } from "./backend/cloud";import { downloadFromUrl } from "./download";-import { bitrateFor, renderProjectToMp4 } from "./exportRender";+import { bitrateFor, canRenderInBrowser, renderProjectToMp4 } from "./exportRender";import { putSigned } from "./media";import { renderRemovalPieces } from "./removalVideo";import { createRasterCanvas, rasterCanvasToPng } from "./raster";@@ -445,25 +449,6 @@ export async function deleteExport(projectId: string, file: string) {}}-export interface ExportDoc {- /** Output frame ratio the cut renders at — keeps burn-in layout (caption- * wrap) in the same design space as the live preview. */- aspect: Aspect;- assets: MediaAsset[];- /** Every video clip, any track (track 0 folds sequentially, others composite). */- clips: VideoClip[];- audioClips: AudioClip[];- overlays: Overlay[];- subtitles: SubtitlesBlock;- /** Whole-video fades (seconds): in from black / out to black on the final- * composite. */- fadeIn?: number;- fadeOut?: number;- /** The frame's own color behind every clip and element (hex); absent = black. */- background?: string;-}--/** The neutral built cut: the engine spec plus the browser-rendered overlay* PNGs. The local path serializes it to the engine's multipart form; the* cloud path presigns the PNGs to R2 and posts the spec as JSON. */@@ -1359,16 +1344,17 @@ export async function buildExportPayload(* its render cap. The worker would say the same, so the export ends here with* the gate's own words.*/-export class ExportRefusedError extends Error {}+export class ExportRefusedError extends Error {+ constructor(message: string, readonly failure?: OperationFailure) { super(message); }+}/** Concurrent PUTs a cloud export's inputs go up on. */const UPLOAD_LANES = 4;function cloudRefusal(res: Response, body: { error?: string; bytes?: number; quotaBytes?: number } | null | undefined): ExportRefusedError | null {if (res.ok) return null;- if (res.status === 401) return new ExportRefusedError("Sign in to render this export in the cloud.");- const quota = quotaErrorMessage(res.status, body);- if (quota) return new ExportRefusedError(quota);+ const failure = operationFailure(res.status, body);+ if (failure) return new ExportRefusedError(failure.message, failure);if (res.status === 429 || res.status === 413) return new ExportRefusedError(body?.error ?? "Export failed to start.");return null;}@@ -1395,12 +1381,14 @@ async function postExport(extra?: Record<string, unknown>,signal?: AbortSignal): Promise<Response> {+ signal?.throwIfAborted();if (backend.kind !== "cloud") {return backend.fetch("/api/cut/export", { method: "POST", body: exportFormFromPayload(payload) });}const overlays: { name: string; key: string }[] = [];if (payload.pngs.length > 0) {const pre = await backend.fetch("/api/cut/export/presign", {+ signal,method: "POST",headers: { "Content-Type": "application/json" },body: JSON.stringify({@@ -1430,6 +1418,7 @@ async function postExport();for (const p of payload.pngs) overlays.push({ name: p.name, key: byName.get(p.name)!.key });}+ signal?.throwIfAborted();return backend.fetch("/api/cut/export", {method: "POST",headers: { "Content-Type": "application/json" },@@ -1437,6 +1426,13 @@ async function postExport(});}+function renderAssetUrl(projectId: string, asset: MediaAsset): string {+ const state = useEditor.getState();+ return state.projectId === projectId+ ? state.assets.find((candidate) => candidate.id === asset.id)?.url ?? asset.url+ : asset.url;+}+/** The output's file name: what the user typed, or the project's name, under* the one sanitize rule every residency shares (the engine dedupes on disk). */function exportOutName(settings: ExportSettings): string {@@ -1459,7 +1455,7 @@ export async function pollExport(progress?: number;outName?: string;}>(st);- if (!st.ok || status.status === "error") throw new Error(status.error ?? "Export failed.");+ if (!st.ok || status.status === "error" || status.status === "canceled") throw new Error(status.error ?? "Export failed.");onProgress("Rendering", status.progress ?? 0);if (status.status === "done") return status.outName ?? "export.mp4";}@@ -1502,14 +1498,13 @@ export async function createExportJob(doc: ExportDoc,settings: ExportSettings): Promise<string> {- const backend = getBackend(); // pinned: the payload build takes a while+ const backend = projectOperation(projectId).backend;+ const outName = exportOutName(settings);if (backend.kind === "local") await assertEngineCarries(settings);const payload = await buildExportPayload(projectId, doc, settings, "export");- const res = await postExport(projectId, payload, exportOutName(settings), backend);+ const res = await postExport(projectId, payload, outName, backend);const body = await apiJson<{ id?: string }>(res);if (!res.ok || !body.id) {- // A quota rejection raises the upgrade wall on its way through, the same as- // one from an upload — otherwise the only sign is a terse line in the dock.throw cloudRefusal(res, body) ?? new Error(body.error ?? "Export failed to start.");}return body.id;@@ -1544,7 +1539,7 @@ export async function runBrowserExport(onClaimed?: (jobId: string) => void;} = {}): Promise<string> {- const backend = getBackend(); // pinned: the render outlives navigation+ const backend = projectOperation(projectId).backend;if (backend.kind === "browser") return runStoreExport(projectId, doc, settings, opts);if (backend.kind === "local") return runEngineExport(projectId, doc, settings, opts, backend);@@ -1574,7 +1569,7 @@ export async function runBrowserExport(// snapshot: a long render can outlive the links it started with, and the// store re-mints them behind it.resolve: (asset) =>- useEditor.getState().assets.find((a) => a.id === asset.id)?.url ?? asset.url,+ renderAssetUrl(projectId, asset),signal: opts.signal,// The render is nearly all of the work; the upload is the tail of the bar.onProgress: ({ ratio }) => opts.onProgress?.(ratio * 0.9),@@ -1664,7 +1659,7 @@ async function runEngineExport(try {const rendered = await renderProjectToMp4(doc, settings, {resolve: (asset) =>- useEditor.getState().assets.find((a) => a.id === asset.id)?.url ?? asset.url,+ renderAssetUrl(projectId, asset),signal: opts.signal,// The render is nearly all of the work; the hand-in to the engine on// this machine is the tail of the bar.@@ -1718,13 +1713,14 @@ async function runStoreExport(settings: ExportSettings,opts: Parameters<typeof runBrowserExport>[3] = {}): Promise<string> {+ const requestedName = exportOutName(settings);const job = reserveBrowserExportJob(projectId, opts.projectName);opts.onClaimed?.(job.id);holdRegistered(`/api/cut/projects/${projectId}/`);try {const rendered = await renderProjectToMp4(doc, settings, {resolve: (asset) =>- useEditor.getState().assets.find((a) => a.id === asset.id)?.url ?? asset.url,+ renderAssetUrl(projectId, asset),signal: opts.signal,onProgress: ({ ratio }) => {opts.onProgress?.(ratio);@@ -1733,7 +1729,7 @@ async function runStoreExport(});let outName: string;try {- outName = await saveExport(projectId, rendered.file, exportOutName(settings));+ outName = await saveExport(projectId, rendered.file, requestedName);} finally {void rendered.discard();}@@ -1769,83 +1765,70 @@ async function runStoreExport(* project's own exports folder. The cloud keeps nothing: the uploads and the* output are the job's scratch, gone when the job is dismissed or swept.*/-async function runBorrowedExport(+async function renderBorrowedFile(projectId: string,doc: ExportDoc,settings: ExportSettings,+ target: "export" | "preview",opts: Parameters<typeof runBrowserExport>[3] = {}-): Promise<string> {- const job = reserveBrowserExportJob(projectId, opts.projectName);- opts.onClaimed?.(job.id);+): Promise<File> {+ const backend = captureCloudBackend();+ const requestedName = exportOutName(settings);let cloudJobId: string | null = null;- const stop = () => {- if (opts.signal?.aborted) throw new DOMException("Export canceled.", "AbortError");- };- // The payload build reads the project's store-served blob URLs and can take- // a while; the hold keeps them alive if the user opens another project- // meanwhile, and the asset's URL is read live for the same reason.+ const stop = () => opts.signal?.throwIfAborted();holdRegistered(`/api/cut/projects/${projectId}/`);try {- const payload = await buildExportPayload(projectId, doc, settings, "export");+ const payload = await buildExportPayload(projectId, doc, settings, target);stop();for (const name of specMediaFiles(payload.spec as Parameters<typeof specMediaFiles>[0])) {const asset = doc.assets.find((a) => a.fileName === name);- const url = asset- ? (useEditor.getState().assets.find((a) => a.id === asset.id)?.url ?? asset.url)- : null;+ const url = asset ? renderAssetUrl(projectId, asset) : null;const blob = url ? resolveRegisteredBlob(url) : null;if (!blob) throw new Error(`${name} is not in this browser's storage.`);payload.pngs.push({ name, blob });}- const res = await postExport(- projectId,- payload,- exportOutName(settings),- cloudBackend,- { mediaFrom: "overlays" },- opts.signal- );+ const res = await postExport(projectId, payload, requestedName, backend, { mediaFrom: "overlays" }, opts.signal);const body = await apiJson<{ id?: string }>(res);- if (!res.ok || !body.id) {- throw cloudRefusal(res, body) ?? new Error(body.error ?? "Export failed to start.");- }+ if (!res.ok || !body.id) throw cloudRefusal(res, body) ?? new Error(body.error ?? "Render failed to start.");cloudJobId = body.id;- // The cloud row is this export too; the dock shows the local row alone.opts.onClaimed?.(cloudJobId);- const outName = await pollExport(- cloudJobId,- (_stage, ratio) => {- opts.onProgress?.(ratio * 0.95);- updateBrowserExportJob(job.id, { progress: ratio * 0.95 });- },- () => !!opts.signal?.aborted,- cloudBackend- );+ const outName = await pollExport(cloudJobId, (_stage, ratio) => opts.onProgress?.(ratio * 0.95), () => !!opts.signal?.aborted, backend);stop();- const fileRes = await cloudBackend.fetch(`/api/cut/export/${cloudJobId}/file`, {- signal: opts.signal,- });- if (!fileRes.ok) throw new Error("Could not fetch the rendered export.");- const file = new File([await fileRes.blob()], outName, {- type: deliveryContainer(settings.container).mime,- });+ const fileRes = await backend.fetch(`/api/cut/export/${cloudJobId}/file`, { signal: opts.signal });+ if (!fileRes.ok) throw new Error("Could not fetch the rendered file.");+ const file = new File([await fileRes.blob()], outName, { type: deliveryContainer(settings.container).mime });stop();- const saved = await saveExport(projectId, file, outName);+ return file;+ } finally {+ if (cloudJobId) cancelExportJob(cloudJobId, backend);+ releaseRegistered(`/api/cut/projects/${projectId}/`);+ }+}++async function runBorrowedExport(+ projectId: string,+ doc: ExportDoc,+ settings: ExportSettings,+ opts: Parameters<typeof runBrowserExport>[3] = {}+): Promise<string> {+ const job = reserveBrowserExportJob(projectId, opts.projectName);+ opts.onClaimed?.(job.id);+ try {+ const file = await renderBorrowedFile(projectId, doc, settings, "export", {+ ...opts,+ onProgress: (progress) => { opts.onProgress?.(progress); updateBrowserExportJob(job.id, { progress }); },+ });+ const saved = await saveExport(projectId, file, file.name);const stored = await readFileAt(await exportsDir(projectId), saved);if (stored) {registerBlobFile(`/api/cut/export/${job.id}/file`, stored);registerBlobFile(`/api/cut/projects/${projectId}/exports/${encodeURIComponent(saved)}`, stored);}updateBrowserExportJob(job.id, { status: "done", progress: 1, outName: saved });- // The cloud's copy was the job's scratch; dismissing the job drops it.- cancelExportJob(cloudJobId, cloudBackend);return job.id;- } catch (err) {- if (cloudJobId) cancelExportJob(cloudJobId, cloudBackend);+ } catch (error) {removeBrowserExportJob(job.id);- throw err;- } finally {- releaseRegistered(`/api/cut/projects/${projectId}/`);+ throw error;}}@@ -1886,9 +1869,9 @@ export function cancelExportJob(jobId: string, backend: CutBackend = getBackend(export async function renderShareLadder(projectId: string,doc: ExportDoc,- shareSubtitles: boolean+ shareSubtitles: boolean,+ backend: CutBackend = getBackend()): Promise<void> {- const backend = getBackend(); // pinned: the ladder outlives the dialog// The master renders at "Original" — the ladder caps its top rung at this// frame, so anything given up here is given up for every viewer. The encode// preset is loosened because this master is an intermediate: every rung is@@ -1913,23 +1896,87 @@ export async function renderShareLadder(}}-/** Low-res proxy of the actual edit for the project card's hover preview.- * Renders through the same pipeline (overlays and all), writing the project's- * preview.mp4. Best-effort: silently no-ops if a slot is busy or there's no- * footage yet. */-export async function renderPreviewProxy(projectId: string, doc: ExportDoc) {- const backend = getBackend(); // pinned: the proxy render outlives navigation+export type PreviewArtifact = { id: string; projectId: string; revision: string; url: string; expiresAt?: number };+export type PreviewJob = PreviewArtifact & { status: "queued" | "done"; statusUrl?: string };++export async function submitPreviewSnapshot(+ snapshot: RenderSnapshot,+ onProgress: (stage: string, ratio: number) => void = () => {},+ signal?: AbortSignal+): Promise<PreviewJob> {+ const { operation: { projectId, backend }, doc, revision } = snapshot;+ signal?.throwIfAborted();const settings: ExportSettings = { ...scaledFrame(doc.aspect, 360), fps: 24, crf: 30, preset: "veryfast", ...DELIVERY_DEFAULTS };- let res: Response;+ if (backend.kind === "browser") {+ const directory = await projectDir(projectId);+ if (!directory) throw new Error("Project not found in browser storage.");+ holdRegistered(`/api/cut/projects/${projectId}/`);+ try {+ const rendered = await canRenderInBrowser(doc, settings)+ ? await renderProjectToMp4(doc, settings, {+ resolve: (asset) => asset.url, signal,+ onProgress: ({ ratio }) => onProgress("Rendering", ratio),+ })+ : {+ file: await renderBorrowedFile(projectId, doc, { ...settings, name: "preview" }, "preview", {+ signal, onProgress: (ratio) => onProgress("Rendering", ratio),+ }),+ discard: async () => {},+ };+ try {+ signal?.throwIfAborted();+ await writeFileAt(directory, "preview.mp4", rendered.file);+ const file = await readFileAt(directory, "preview.mp4");+ if (!file) throw new Error("Could not read the rendered preview.");+ const url = registerBlobFile(`/api/cut/projects/${projectId}/preview`, file);+ return { id: revision, projectId, revision, url, status: "done" };+ } finally {+ await rendered.discard();+ }+ } finally {+ releaseRegistered(`/api/cut/projects/${projectId}/`);+ }+ }+ const payload = await buildExportPayload(projectId, doc, settings, "preview");+ signal?.throwIfAborted();+ const res = await postExport(projectId, payload, "preview.mp4", backend, { revision }, signal);+ const body = await apiJson<{ id?: string }>(res);+ if (!res.ok || !body.id) throw cloudRefusal(res, body) ?? new Error(body.error ?? "Preview failed to start.");+ if (signal?.aborted) {+ cancelExportJob(body.id, backend);+ signal.throwIfAborted();+ }+ return {+ id: body.id, projectId, revision, status: "queued",+ url: backend.url(`/api/cut/export/${body.id}/file`),+ statusUrl: backend.url(`/api/cut/export/${body.id}`),+ };+}++export async function renderPreviewSnapshot(+ snapshot: RenderSnapshot,+ onProgress: (stage: string, ratio: number) => void = () => {},+ signal?: AbortSignal+): Promise<PreviewArtifact> {+ const job = await submitPreviewSnapshot(snapshot, onProgress, signal);+ if (job.status === "done") return job;+ const backend = snapshot.operation.backend;+ const cancel = () => cancelExportJob(job.id, backend);+ signal?.addEventListener("abort", cancel, { once: true });try {- const payload = await buildExportPayload(projectId, doc, settings, "preview");- res = await postExport(projectId, payload, "preview.mp4", backend);- } catch {- return; // no clips yet+ if (signal?.aborted) cancel();+ await pollExport(job.id, onProgress, () => signal?.aborted === true, backend);+ if (backend.kind === "cloud") {+ const response = await backend.fetch(`/api/cut/export/${job.id}`);+ const body = await apiJson<{ artifact?: { url: string; expiresIn: number } }>(response);+ if (!response.ok || !body.artifact) throw new Error(body.error ?? "Preview is unavailable.");+ return { id: job.id, projectId: job.projectId, revision: job.revision, url: body.artifact.url,+ expiresAt: Date.now() + body.artifact.expiresIn * 1000 };+ }+ return { id: job.id, projectId: job.projectId, revision: job.revision, url: job.url };+ } finally {+ signal?.removeEventListener("abort", cancel);}- const body = (await res.json().catch(() => ({}))) as { id?: string };- if (!res.ok || !body.id) return; // a slot was busy; try again later- await pollExport(body.id, () => {}, undefined, backend).catch(() => {});}/** Seconds of the cut a share card shows. */@@ -1986,8 +2033,7 @@ function cardSettings(aspect: Aspect): ExportSettings {** Best-effort throughout — a project with no footage, an unconfigured* backend, or a busy render slot simply keeps the card it already had. */-async function renderShareCard(projectId: string, doc: ExportDoc): Promise<void> {- const backend = getBackend(); // pinned: the card render outlives navigation+async function renderShareCard(projectId: string, doc: ExportDoc, backend: CutBackend): Promise<void> {if (backend.kind !== "cloud") return;try {const res = await backend.fetch(`/api/cut/projects/${projectId}/share`);@@ -2019,17 +2065,8 @@ async function renderShareCard(projectId: string, doc: ExportDoc): Promise<void>export function refreshShareCard(projectId: string): void {const s = useEditor.getState();if (!s.loaded || s.projectId !== projectId || projectDuration(s) <= 0) return;- void renderShareCard(projectId, {- aspect: s.aspect,- assets: s.assets,- clips: s.clips,- audioClips: s.audioClips,- overlays: s.overlays,- subtitles: s.subtitles,- fadeIn: s.fadeIn,- fadeOut: s.fadeOut,- background: s.background,- }).catch(() => {});+ const snapshot = captureRenderSnapshot(projectOperation(projectId), renderDoc(s));+ void renderShareCard(projectId, snapshot.doc, snapshot.operation.backend).catch(() => {});}/**@@ -2048,29 +2085,25 @@ export function refreshShareCard(projectId: string): void {export async function refreshShareLadder(projectId: string): Promise<void> {const s = useEditor.getState();if (!s.loaded || s.projectId !== projectId || projectDuration(s) <= 0) return;- const backend = getBackend();- // The share decides what the render may contain, so it is read first. This- // also settles whether to render at all: an unshared project has no viewer to- // build a ladder for.+ const snapshot = captureRenderSnapshot(projectOperation(projectId), renderDoc(s));+ await refreshSnapshotLadder(snapshot);+}++async function refreshSnapshotLadder({ operation, doc }: RenderSnapshot): Promise<void> {+ const { projectId, backend } = operation;+ if (backend.kind !== "cloud") return;const res = await backend.fetch(`/api/cut/projects/${projectId}/share`).catch(() => null);if (!res?.ok) return;const body = (await res.json().catch(() => null)) as {share?: { features?: { subtitles?: boolean } } | null;} | null;- if (!body?.share) return;- await renderShareLadder(- projectId,- {- aspect: s.aspect,- assets: s.assets,- clips: s.clips,- audioClips: s.audioClips,- overlays: s.overlays,- subtitles: s.subtitles,- fadeIn: s.fadeIn,- fadeOut: s.fadeOut,- background: s.background,- },- body.share.features?.subtitles === true- );+ if (body?.share) await renderShareLadder(projectId, doc, body.share.features?.subtitles === true, backend);+}++/** All derived representations consume the same captured document and transport. */+export async function refreshProjectPreviews(snapshot: RenderSnapshot, signal?: AbortSignal): Promise<void> {+ const { projectId, backend } = snapshot.operation;+ await renderPreviewSnapshot(snapshot, undefined, signal);+ await renderShareCard(projectId, snapshot.doc, backend);+ await refreshSnapshotLadder(snapshot);}diff --git a/site/src/cut/lib/exportRender.test.ts b/site/src/cut/lib/exportRender.test.tsindex 189040fe..56c573ef 100644--- a/site/src/cut/lib/exportRender.test.ts+++ b/site/src/cut/lib/exportRender.test.ts@@ -1,7 +1,7 @@import { describe, expect, test } from "bun:test";import { foldClips } from "./audioMix";import { bitrateFor, mixSpecFor } from "./exportRender";-import type { ExportDoc } from "./exportClient";+import type { ExportDoc } from "./renderSnapshot";import type { MediaAsset, VideoClip } from "./types";const asset = (id: string): MediaAsset => ({diff --git a/site/src/cut/lib/exportRender.ts b/site/src/cut/lib/exportRender.tsindex 0f8fc939..0a9e5bce 100644--- a/site/src/cut/lib/exportRender.ts+++ b/site/src/cut/lib/exportRender.ts@@ -46,7 +46,8 @@ import { exportFrameSynth, SYNTH_EDGE, synthWeight, type FrameSynth } from "./frimport { renderElementPng } from "./textRender";import { assetIsSilent, behindSubjectOverlay, clipCovers, frameOf, frontSubjectOverlay, isEffectOverlay, isTextOverlay, laneOf, overlayAnimStyle, projectBackground, projectFadeSeconds, rectOf, removalActive } from "./types";import type { ClipAnim, ClipSpan, EffectOverlay, MediaAsset, Overlay, StickerOverlay } from "./types";-import type { ExportDoc, ExportSettings } from "./exportClient";+import type { ExportDoc } from "./renderSnapshot";+import type { ExportSettings } from "./exportClient";import { deliverySpan, KEYFRAME_INTERVAL_S, videoBitrateFor } from "./exportDelivery";/** Audio is written at the rate and width a delivery file wants, rather thandiff --git a/site/src/cut/lib/exportStore.ts b/site/src/cut/lib/exportStore.tsindex d36934b0..948909bc 100644--- a/site/src/cut/lib/exportStore.ts+++ b/site/src/cut/lib/exportStore.ts@@ -13,9 +13,9 @@ import {ExportRefusedError,runBrowserExport,runBrowserExportInCloud,- type ExportDoc,type ExportSettings,} from "./exportClient";+import type { ExportDoc } from "./renderSnapshot";import { canRenderInBrowser } from "./exportRender";import { useGenNotify } from "./genNotify";diff --git a/site/src/cut/lib/headless/docExport.ts b/site/src/cut/lib/headless/docExport.tsindex 05b09efd..f34d0dd6 100644--- a/site/src/cut/lib/headless/docExport.ts+++ b/site/src/cut/lib/headless/docExport.ts@@ -5,19 +5,16 @@ import {EXPORT_PRESETS,originalSettings,presetSettings,- type ExportDoc,type ExportSettings,} from "../exportClient";+import { renderDoc, type ExportDoc } from "@/cut/lib/renderSnapshot";import { useEditor } from "../store";import { bindHeadlessSession, type HeadlessSession } from "./bind";-import { openCloudProject } from "./docSession";+import { openCloudSnapshot, type CloudDocSnapshot } from "./docSession";-// A whole-timeline export built where the tab used to be. A client that can-// render the cut itself sends the finished spec up; a client that cannot —-// the phone — asks for the project by id, and this builds the same spec from-// the stored document: open the doc into the editor store, run the export-// payload builder the dialog runs, and drop the overlay pictures straight-// into the render's own tmp dir.+// Queued document exports hydrate their captured revision in an isolated+// worker, prepare the same payload as the editor, and stage its overlay+// pictures in the render's own scratch directory./** The sizes a doc-built export offers, named as the export dialog names* them. `original` is derived from the footage on the timeline; the rest are@@ -30,22 +27,6 @@ export function isDocExportPreset(value: unknown): value is DocExportPreset {return typeof value === "string" && (DOC_EXPORT_PRESETS as readonly string[]).includes(value);}-/** The editor store's current contents as the builder's neutral document. */-function docFromStore(): ExportDoc {- const s = useEditor.getState();- return {- aspect: s.aspect,- assets: s.assets,- clips: s.clips,- audioClips: s.audioClips,- overlays: s.overlays,- subtitles: s.subtitles,- fadeIn: s.fadeIn,- fadeOut: s.fadeOut,- background: s.background,- };-}-function settingsFor(preset: DocExportPreset, doc: ExportDoc): ExportSettings {const fixed = EXPORT_PRESETS.find((p) => p.id === preset);return fixed@@ -62,11 +43,12 @@ export async function buildDocExportSpec(session: HeadlessSession,projectId: string,preset: DocExportPreset,- tmpDir: string+ tmpDir: string,+ snapshot: CloudDocSnapshot): Promise<object> {bindHeadlessSession(session);- await openCloudProject(session, projectId);- const doc = docFromStore();+ await openCloudSnapshot(session, projectId, snapshot);+ const doc = renderDoc(useEditor.getState());const payload = await buildExportPayload(projectId, doc, settingsFor(preset, doc), "export");await Promise.all(payload.pngs.map(async (p) =>diff --git a/site/src/cut/lib/headless/docSession.ts b/site/src/cut/lib/headless/docSession.tsindex ba23822b..a7937729 100644--- a/site/src/cut/lib/headless/docSession.ts+++ b/site/src/cut/lib/headless/docSession.ts@@ -1,4 +1,5 @@import type { HeadlessSession } from "./bind";+import { noteProjectRevision } from "../projectRevision";import { fetchWithRetry } from "./http";import { syncFontAssets } from "../fontAssets";import { syncLinkedLibrary } from "../linkedLibrary";@@ -35,6 +36,16 @@ export async function openCloudProject(if (!version)throw new Error("The project read carried no doc version; refusing an unversioned session.");const doc = (await res.json()) as ProjectDoc;+ return openCloudSnapshot(s, projectId, { doc, version });+}++export type CloudDocSnapshot = { doc: ProjectDoc; version: string };++export async function openCloudSnapshot(+ s: HeadlessSession,+ projectId: string,+ { doc, version }: CloudDocSnapshot+): Promise<HeadlessDocSession> {// Media rides signed R2 URLs: tool paths that read asset bytes (attachment// refs, sticker decodes) fetch them bare, and the /media route would answer// those unauthenticated fetches 401. The route URL stays the fallback for@@ -63,6 +74,7 @@ export async function openCloudProject(url: signed.get(a.fileName) ?? `${projectPath(s, projectId)}/media/${encodeURIComponent(a.fileName)}`,}));await useEditor.getState().openProjectDoc(projectId, doc, assets);+ noteProjectRevision(projectId, version);// The page does this from the editor; a run has to do it before it draws,// or a title set in the user's own font comes out in the fallback face. The// account's shelf fonts come along the same way — a run reaches the cloud@@ -95,5 +107,6 @@ export async function pushCloudProject(if (!res.ok) throw new Error(`Could not save project ${session.projectId} (${res.status}).`);const body = (await res.json()) as { version?: number };if (body.version !== undefined) session.version = String(body.version);+ noteProjectRevision(session.projectId, session.version);return session;}diff --git a/site/src/cut/lib/maskVideo.ts b/site/src/cut/lib/maskVideo.tsindex 09c358c0..5259d928 100644--- a/site/src/cut/lib/maskVideo.ts+++ b/site/src/cut/lib/maskVideo.ts@@ -26,7 +26,7 @@ import { personSegmenter, segmentSubjectAlpha } from "./cutout";import { FrameCompositor, MISSING_FRAME } from "./composite";import { overlayPlan, trackZeroPlan } from "./framePlan";import { ClipReader, WORKING_VIDEO_CODECS } from "./exportRender";-import type { ExportDoc } from "./exportClient";+import type { ExportDoc } from "./renderSnapshot";import { createRasterCanvas } from "./raster";import { getClipSpans } from "./store";import { clipCovers, frameOf, isEffectOverlay, isTextOverlay, rectOf, subjectMasked, type ClipSpan, type MediaAsset } from "./types";diff --git a/site/src/cut/lib/pi/serverDeps.ts b/site/src/cut/lib/pi/serverDeps.tsindex 686e35d2..894a26b8 100644--- a/site/src/cut/lib/pi/serverDeps.ts+++ b/site/src/cut/lib/pi/serverDeps.ts@@ -1,7 +1,10 @@import { geminiModelRoleNames } from "@/lib/inference/gemini-models";+import { UI_TOOLS } from "@/cut/lib/projectCommands";import { AI_SKILL_INDEX, AI_SKILLS } from "@/cut/server/ai/catalog";+import { projectOperation } from "../projectOperation";+import { useEditor } from "../store";import { buildAiContext } from "../aiContext";-import { MEDIA_RUNTIME_TOOLS, runAiTool, UI_TOOLS } from "../aiTools";+import { MEDIA_RUNTIME_TOOLS, runProjectCommand } from "../aiTools";import { normalizeRef } from "../assetRef";import { DETACHED_UI_NOTE } from "../chatResume";import { NO_CREDITS_MESSAGE } from "../credits";@@ -39,7 +42,9 @@ export function headlessDeps(session: HeadlessSession): CutAgentDeps {"This session has no media runtime, so it cannot decode or draw media. Work from the editor state and the transcript instead.");}- return runAiTool(name, args);+ const projectId = useEditor.getState().projectId;+ if (!projectId) throw new Error("No project open.");+ return runProjectCommand(projectOperation(projectId), name, args);},models: {simple: geminiModelRoleNames.chatSimple,diff --git a/site/src/cut/lib/previewQueue.test.ts b/site/src/cut/lib/previewQueue.test.tsnew file mode 100644index 00000000..10a293d1--- /dev/null+++ b/site/src/cut/lib/previewQueue.test.ts@@ -0,0 +1,52 @@+import { expect, test } from "bun:test";+import { createPreviewQueue } from "./previewQueue";++function deferred<T>() {+ let resolve!: (value: T) => void;+ let reject!: (error: Error) => void;+ const promise = new Promise<T>((yes, no) => { resolve = yes; reject = no; });+ return { promise, resolve, reject };+}++test("closing during a render drains the latest edit and coalesces intermediate edits", async () => {+ const first = deferred<string>();+ const calls: number[] = [];+ const queue = createPreviewQueue(async (input: number) => {+ calls.push(input);+ return input === 1 ? first.promise : String(input);+ }, 60_000);+ queue.stage(1);+ const running = queue.flush();+ queue.stage(2);+ queue.stage(3);+ const closing = queue.flush(true);+ first.resolve("1");+ await Promise.all([running, closing]);+ expect(calls).toEqual([1, 3]);+ expect(queue.getState()).toEqual({ status: "done", result: "3" });+});++test("an old completion cannot replace the queued revision's state", async () => {+ const first = deferred<string>();+ const queue = createPreviewQueue(() => first.promise, 60_000);+ queue.stage(1);+ const running = queue.flush();+ queue.stage(2);+ first.resolve("old");+ await running;+ expect(queue.getState()).toEqual({ status: "queued" });+});++test("a failed render exposes its error and releases the queue for the next revision", async () => {+ const error = new Error("render failed");+ const queue = createPreviewQueue(async (input: number) => {+ if (input === 1) throw error;+ return input;+ }, 60_000);+ queue.stage(1);+ await queue.flush();+ expect(queue.getState()).toEqual({ status: "error", error });+ queue.stage(2);+ await queue.flush(true);+ expect(queue.getState()).toEqual({ status: "done", result: 2 });+});diff --git a/site/src/cut/lib/previewQueue.ts b/site/src/cut/lib/previewQueue.tsnew file mode 100644index 00000000..19a68223--- /dev/null+++ b/site/src/cut/lib/previewQueue.ts@@ -0,0 +1,45 @@+/** A host owns lifecycle signals; this queue owns coalescing and completion. */+export type PreviewState<R> =+ | { status: "idle" | "queued" | "running" }+ | { status: "done"; result: R }+ | { status: "error"; error: unknown };++export function createPreviewQueue<T, R>(+ render: (input: T) => Promise<R>,+ minimumGapMs: number,+ onChange: (state: PreviewState<R>) => void = () => {}+) {+ let pending: { input: T; sequence: number } | null = null;+ let sequence = 0;+ let running: Promise<void> | null = null;+ let drain = false;+ let lastRun = -Infinity;+ let state: PreviewState<R> = { status: "idle" };+ const publish = (next: PreviewState<R>) => { state = next; onChange(next); };+ const flush = (final = false): Promise<void> => {+ drain ||= final;+ if (running) return running;+ if (!pending) { drain = false; return Promise.resolve(); }+ if (!drain && Date.now() - lastRun < minimumGapMs) return Promise.resolve();+ running = (async () => {+ do {+ const next = pending!;+ pending = null;+ lastRun = Date.now();+ publish({ status: "running" });+ try {+ const result = await render(next.input);+ if (next.sequence === sequence) publish({ status: "done", result });+ } catch (error) {+ if (next.sequence === sequence) publish({ status: "error", error });+ }+ } while (drain && pending);+ })().finally(() => { running = null; drain = false; });+ return running;+ };+ return {+ stage(input: T) { pending = { input, sequence: ++sequence }; publish({ status: "queued" }); },+ flush,+ getState: () => state,+ };+}diff --git a/site/src/cut/lib/projectCommands.test.ts b/site/src/cut/lib/projectCommands.test.tsnew file mode 100644index 00000000..4bfb6958--- /dev/null+++ b/site/src/cut/lib/projectCommands.test.ts@@ -0,0 +1,26 @@+import { expect, spyOn, test } from "bun:test";+import { runProjectCommand } from "./aiTools";+import { browserBackend } from "./backend/browser";+import { projectOperation } from "./projectOperation";+import { noteProjectRevision } from "./projectRevision";+import { useEditor } from "./store";++test("a headless project command edits the document without an inference request", async () => {+ const before = useEditor.getState();+ const fetcher = spyOn(globalThis, "fetch").mockImplementation(() => { throw new Error("Unexpected network request"); });+ try {+ useEditor.setState({ projectId: "project-command-edit", loaded: true, background: "#000000" });+ noteProjectRevision("project-command-edit", "1");+ const operation = projectOperation("project-command-edit", browserBackend);+ const result = await runProjectCommand(operation, "set_background", { color: "#123456" });+ expect(result).toEqual({ background: "#123456" });+ expect(useEditor.getState().background).toBe("#123456");+ expect(fetcher).not.toHaveBeenCalled();+ noteProjectRevision("project-command-edit", "2");+ await expect(runProjectCommand(operation, "set_background", { color: "#ffffff" })).rejects.toThrow("changed since");+ expect(useEditor.getState().background).toBe("#123456");+ } finally {+ fetcher.mockRestore();+ useEditor.setState(before, true);+ }+});diff --git a/site/src/cut/lib/projectCommands.ts b/site/src/cut/lib/projectCommands.tsnew file mode 100644index 00000000..3df74d3e--- /dev/null+++ b/site/src/cut/lib/projectCommands.ts@@ -0,0 +1,13 @@+import type { ProjectOperation } from "@/cut/lib/projectOperation";++export const UI_TOOLS: ReadonlySet<string> = new Set([+ "set_side_panel", "set_view", "open_export", "set_playing",+]);++export function assertProjectCommand(operation: ProjectOperation, activeProjectId: string | null, name: string, activeVersion?: string | null): void {+ if (operation.residency === "shared") throw new Error("A shared project is read-only.");+ if (operation.projectId !== activeProjectId) throw new Error("The command's project is no longer open.");+ if (operation.version !== null && activeVersion != null && operation.version !== activeVersion)+ throw new Error("The project changed since this command was prepared.");+ if (UI_TOOLS.has(name)) throw new Error("This command requires an editor interface.");+}diff --git a/site/src/cut/lib/renderSnapshot.test.ts b/site/src/cut/lib/renderSnapshot.test.tsnew file mode 100644index 00000000..ebff610d--- /dev/null+++ b/site/src/cut/lib/renderSnapshot.test.ts@@ -0,0 +1,32 @@+import { expect, test } from "bun:test";+import { captureRenderSnapshot, type ExportDoc } from "./renderSnapshot";+import { projectOperation } from "./projectOperation";+import { browserBackend } from "./backend/browser";+import { sharedBackend } from "./backend/shared";+import { assertProjectCommand } from "./projectCommands";++const doc: ExportDoc = {+ aspect: "16:9", assets: [], clips: [], audioClips: [], overlays: [],+ subtitles: { cues: [], showOnVideo: false, showOnTimeline: false },+ background: "#000000",+};++test("render input remains unchanged after its source document is edited", () => {+ const source = structuredClone(doc);+ const operation = projectOperation("a", browserBackend);+ const snapshot = captureRenderSnapshot(operation, source);+ source.background = "#ffffff";+ source.subtitles.showOnVideo = true;+ expect(snapshot.doc.background).toBe("#000000");+ expect(snapshot.doc.subtitles.showOnVideo).toBe(false);+ expect(snapshot.operation.backend).toBe(browserBackend);+ expect(snapshot.revision).not.toBe(captureRenderSnapshot(operation, source).revision);+});++test("project commands reject a different project, a read-only share, and editor-only actions", () => {+ const operation = projectOperation("a", browserBackend);+ expect(() => assertProjectCommand(operation, "b", "split_clip")).toThrow("no longer open");+ expect(() => assertProjectCommand(operation, "a", "set_playing")).toThrow("editor interface");+ expect(() => projectOperation("a", sharedBackend)).toThrow("read-only");+ expect(() => assertProjectCommand(operation, "a", "split_clip")).not.toThrow();+});diff --git a/site/src/cut/lib/renderSnapshot.ts b/site/src/cut/lib/renderSnapshot.tsnew file mode 100644index 00000000..52563e94--- /dev/null+++ b/site/src/cut/lib/renderSnapshot.ts@@ -0,0 +1,39 @@+import type { Aspect, MediaAsset, VideoClip, AudioClip, Overlay, SubtitlesBlock } from "@/cut/lib/types";+import type { ProjectOperation } from "@/cut/lib/projectOperation";++export type ExportDoc = {+ /** Output frame ratio the cut renders at — keeps burn-in layout (caption+ * wrap) in the same design space as the live preview. */+ aspect: Aspect;+ assets: MediaAsset[];+ /** Every video clip, any track (track 0 folds sequentially, others composite). */+ clips: VideoClip[];+ audioClips: AudioClip[];+ overlays: Overlay[];+ subtitles: SubtitlesBlock;+ /** Whole-video fades (seconds): in from black / out to black on the final+ * composite. */+ fadeIn?: number;+ fadeOut?: number;+ /** The frame's own color behind every clip and element (hex); absent = black. */+ background?: string;+};++export type RenderSnapshot = {+ operation: ProjectOperation;+ revision: string;+ doc: ExportDoc;+};++/** Called when work is submitted, outside playback and store subscriptions. */+export function captureRenderSnapshot(operation: ProjectOperation, doc: ExportDoc): RenderSnapshot {+ return { operation, revision: crypto.randomUUID(), doc: structuredClone(doc) };+}++export function renderDoc(doc: ExportDoc): ExportDoc {+ return {+ aspect: doc.aspect, assets: doc.assets, clips: doc.clips, audioClips: doc.audioClips,+ overlays: doc.overlays, subtitles: doc.subtitles, fadeIn: doc.fadeIn,+ fadeOut: doc.fadeOut, background: doc.background,+ };+}diff --git a/site/src/cut/server/ai/catalog.ts b/site/src/cut/server/ai/catalog.tsindex db0a8cf0..334d63f4 100644--- a/site/src/cut/server/ai/catalog.ts+++ b/site/src/cut/server/ai/catalog.ts@@ -9,6 +9,7 @@* here, so the UI and the model always offer the same catalog.*/+import { UI_TOOLS } from "@/cut/lib/projectCommands";import { STOCK_SFX_CATEGORIES } from "@/cut/lib/stock";import { AI_PANEL_TOOLS } from "@/cut/components/AiPanel.tools";import {@@ -80,6 +81,10 @@ export const AI_TOOLS: AiToolDef[] = [...EDITOR_TOOLS,];+/** Shared project schemas for hosts that provide their own conversation UI. */+export const PROJECT_TOOLS: AiToolDef[] = AI_TOOLS.filter((tool) => !tool.server && !UI_TOOLS.has(tool.name));++/** Deep documentation the model can pull in on demand. */export const AI_SKILLS: Record<string, string> = {"editor-overview": `# Cut editor overviewdiff --git a/site/src/cut/server/ai/headlessTools.ts b/site/src/cut/server/ai/headlessTools.tsindex 107af31e..f714c722 100644--- a/site/src/cut/server/ai/headlessTools.ts+++ b/site/src/cut/server/ai/headlessTools.ts@@ -1,5 +1,8 @@import { copyFile } from "node:fs/promises";-import { runAiTool, UI_TOOLS } from "../../lib/aiTools";+import { UI_TOOLS } from "@/cut/lib/projectCommands";+import { runProjectCommand } from "../../lib/aiTools";+import { projectOperation } from "../../lib/projectOperation";+import { localBackend } from "../../lib/backend/local";import { DETACHED_MEDIA_ERROR, DETACHED_SESSION_ERROR, DETACHED_UI_NOTE } from "../../lib/chatResume";import { mp4NameFor, setHostMediaStore } from "../../lib/mediaConvert";import { setHostDocStore } from "../../lib/projectReference";@@ -31,6 +34,7 @@ const PAGE_MEDIA_TOOLS: ReadonlySet<string> = new Set(["refine_speech_cuts","freeze_frame","capture_frame",+ "render_preview","create_sticker","subtitles_generate","captions_generate",@@ -153,7 +157,7 @@ async function executeHeadlessTool(const doc = await ensureOpen(projectId);if (!doc) return { errorText: "Project not found on this Mac." };try {- const output = await runAiTool(toolName, (input ?? {}) as Record<string, unknown>);+ const output = await runProjectCommand(projectOperation(projectId, localBackend), toolName, (input ?? {}) as Record<string, unknown>);await flush(doc);return { output: output ?? null };} catch (err) {diff --git a/site/src/cut/server/cloud/jobs.ts b/site/src/cut/server/cloud/jobs.tsindex 9908b6de..71149a1f 100644--- a/site/src/cut/server/cloud/jobs.ts+++ b/site/src/cut/server/cloud/jobs.ts@@ -6,7 +6,7 @@ import { prisma } from "@/lib/prisma";import { cutLimitsFor, EXPORT_QUOTA_MARGIN, renderJobCheck } from "./limits";import { wakeRenderWorker } from "./wake";import { getProject } from "./projects";-import { MEDIA_REDIRECT_HEADERS, mediaObjectUrl } from "./mediaCdn";+import { MEDIA_REDIRECT_HEADERS, mediaObjectUrl, mediaUrlLifetime } from "./mediaCdn";import { del, head, overlayKey, overlayPrefix, presignPut, projectExportKey } from "./r2";import { contentTypeFor } from "../serveFile";import { containerOfName, deliveryContainer, exportBaseName, specMediaFiles, type ExportContainer } from "../../lib/exportDelivery";@@ -50,6 +50,7 @@ const IMPORT_MAX_BYTES = 2 * 1024 ** 3;const HEARTBEAT_QUIET_MS = 30_000;type JobRow = {+ spec: unknown;id: string;projectId: string | null;kind: string;@@ -201,15 +202,13 @@ export const jobsCloud = {};if (!Array.isArray(files) || files.length === 0) return err("files is required.", 400);if (files.length > MAX_OVERLAY_FILES) return err("Too many overlays.", 400);- // The overlays exist for a render, so the gates that render passes apply- // here too: a user's export meets the daily and live caps, the editor's- // own renders (proxy, card, ladder) only the storage margin.+ // Retained exports pass their storage and render gates before staging inputs.if (target === undefined || target === "export") {const capped = await renderJobCheck(userId);if (capped) return capped;+ const over = await quotaCheck(userId, 0, EXPORT_QUOTA_MARGIN);+ if (over) return over;}- const over = await quotaCheck(userId, 0, EXPORT_QUOTA_MARGIN);- if (over) return over;let total = 0;for (const f of files) {if (!Number.isInteger(f.bytes) || f.bytes! < 1) return err("Every overlay needs its size.", 400);@@ -251,6 +250,7 @@ export const jobsCloud = {projectId?: string;outName?: string;burnedSubtitles?: boolean;+ revision?: string;/** "overlays": the cut's media was uploaded beside the stills, so the* project it names is not one the cloud stores — a browser-resident* project borrowing the worker. */@@ -259,6 +259,8 @@ export const jobsCloud = {if (!body.spec || typeof body.spec !== "object") return err("spec is required.", 400);const projectId = body.projectId ?? body.spec.projectId;if (!projectId) return err("projectId is required.", 400);+ if (body.revision !== undefined && (typeof body.revision !== "string" || body.revision.length > 128 || !body.revision))+ return err("Invalid render revision.", 400);const borrowed = body.mediaFrom === "overlays";const project = await getProject(userId, projectId);if (!project && !borrowed) return err("Project not found.", 400);@@ -290,25 +292,45 @@ export const jobsCloud = {: "export";const refused = specRefusal(body.spec as Record<string, unknown>);if (refused) return err(refused, 400);- // Every render lands bytes, so every target passes the storage margin.- // The finished file's size isn't knowable until it renders; what is- // knowable is whether this account is already too far past its quota to- // be handed more, so that is the gate. The daily and live caps count- // renders the user asked for; the editor's own renders are held to one- // running and one queued per project below.+ // Retained exports pass storage and render gates. Derived playback+ // artifacts use a bounded queue and expire through garbage collection.if (target === "export") {const capped = await renderJobCheck(userId);if (capped) return capped;+ const over = await quotaCheck(userId, 0, EXPORT_QUOTA_MARGIN);+ if (over) return over;}- const over = await quotaCheck(userId, 0, EXPORT_QUOTA_MARGIN);- if (over) return over;const jobSpec = {+ ...(body.revision ? { revision: body.revision } : {}),spec: body.spec,overlays: body.overlays ?? [],...(borrowed ? { mediaFrom: "overlays" } : {}),...(target === "hls" ? { burnedSubtitles: body.burnedSubtitles === true } : {}),} as unknown as Prisma.InputJsonValue;+ if (target === "preview") {+ const row = await prisma.$transaction(async (tx) => {+ if (body.revision) {+ const existing = await tx.cutRenderJob.findFirst({+ where: { userId, projectId, kind: target, state: { in: ["queued", "running", "done"] },+ spec: { path: ["revision"], equals: body.revision } },+ });+ if (existing && (existing.state !== "done" || (existing.outputKey && await tx.cutMediaObject.findUnique({+ where: { r2Key: existing.outputKey }, select: { id: true },+ })))) return existing;+ }+ await tx.cutRenderJob.updateMany({+ where: { userId, projectId, kind: target, state: "queued" },+ data: { state: "canceled", error: "A newer preview was requested." },+ });+ return tx.cutRenderJob.create({+ data: { userId, projectId, kind: target, spec: jobSpec, outName: "preview.mp4" },+ });+ }, { isolationLevel: "Serializable" });+ wakeRenderWorker();+ return Response.json({ id: row.id });+ }+if (target !== "export") {if (target === "hls") {// A ladder is only worth rendering for a project someone can actually@@ -362,13 +384,7 @@ export const jobsCloud = {}},- /**- * Queue a whole-timeline export for a client that cannot build a render spec- * — the phone. The row carries the project and the size; the worker opens- * the project document and builds the spec itself, so what renders is the- * cut as it stands, overlays and captions and all, exactly as the web- * dialog would have rendered it.- */+ /** Capture the requested document in the queue; the worker prepares its render spec. */async exportFromDoc(userId: string, projectId: string, req: Request) {try {const body = (await req.json().catch(() => ({}))) as { preset?: string };@@ -387,7 +403,7 @@ export const jobsCloud = {userId,projectId,kind: "export",- spec: { fromDoc: { preset } } as unknown as Prisma.InputJsonValue,+ spec: { fromDoc: { preset, snapshot: { doc: project.doc, version: String(project.version) } } } as unknown as Prisma.InputJsonValue,outName,},});@@ -408,6 +424,11 @@ export const jobsCloud = {progress: row.progress,error,outName: row.outName || undefined,+ artifact: row.state === "done" && row.outputKey ? {+ id: row.id, projectId: row.projectId, kind: row.kind,+ url: mediaObjectUrl(row.outputKey), expiresIn: mediaUrlLifetime(),+ revision: (row.spec as { revision?: string } | null)?.revision ?? null,+ } : null,});},@@ -570,6 +591,10 @@ export const jobsCloud = {if (!row || row.state !== "done" || !row.outputKey) {return new Response("Export not ready.", { status: 404 });}+ if (row.kind === "preview" && !row.outputKey.startsWith(overlayPrefix(userId))) {+ const artifact = await prisma.cutMediaObject.findUnique({ where: { r2Key: row.outputKey }, select: { id: true } });+ if (!artifact) return err("Preview expired. Render it again.", 410);+ }// A finished job's output never changes, so the redirect is cacheable.return redirect(mediaObjectUrl(row.outputKey, row.outName ? { downloadName: row.outName } : undefined),diff --git a/site/src/cut/server/jobRegistry.test.ts b/site/src/cut/server/jobRegistry.test.tsnew file mode 100644index 00000000..5356a96c--- /dev/null+++ b/site/src/cut/server/jobRegistry.test.ts@@ -0,0 +1,20 @@+import { expect, test } from "bun:test";+import { createJobRegistry } from "./jobRegistry";++test("preview resources are evicted once across backlog trimming and expiry", async () => {+ const key = `__previewRegistryTest_${crypto.randomUUID()}`;+ const evicted: string[] = [];+ const registry = createJobRegistry<{ id: string; status: string }>(key, {+ maxJobs: 1, retireMs: 5, onEvict: (job) => { evicted.push(job.id); },+ });+ for (const id of ["a", "b"]) {+ const job = { id, status: "done" };+ registry.jobs.set(id, job);+ registry.retire(job);+ }+ expect(evicted).toEqual(["a"]);+ await new Promise((resolve) => setTimeout(resolve, 15));+ expect(evicted).toEqual(["a", "b"]);+ expect(registry.jobs.size).toBe(0);+ delete (globalThis as unknown as Record<string, unknown>)[key];+});diff --git a/site/src/cut/server/jobRegistry.ts b/site/src/cut/server/jobRegistry.tsindex 3e897e35..dafab28d 100644--- a/site/src/cut/server/jobRegistry.ts+++ b/site/src/cut/server/jobRegistry.ts@@ -15,7 +15,7 @@ export interface JobRegistry<J> {export function createJobRegistry<J extends { id: string; status: string }>(globalKey: string,- opts: { maxJobs?: number; retireMs?: number; isTerminal?: (job: J) => boolean } = {}+ opts: { maxJobs?: number; retireMs?: number; isTerminal?: (job: J) => boolean; onEvict?: (job: J) => void } = {}): JobRegistry<J> {const maxJobs = opts.maxJobs ?? 50;const retireMs = opts.retireMs ?? 10 * 60 * 1000;@@ -37,12 +37,12 @@ export function createJobRegistry<J extends { id: string; status: string }>(if (retiring.has(job.id)) return;retiring.add(job.id);setTimeout(() => {- jobs.delete(job.id);+ if (jobs.delete(job.id)) opts.onEvict?.(job);retiring.delete(job.id);}, retireMs).unref();const terminal = [...jobs.values()].filter(isTerminal);for (let i = 0; i < terminal.length - maxJobs; i++) {- jobs.delete(terminal[i].id);+ if (jobs.delete(terminal[i].id)) opts.onEvict?.(terminal[i]);retiring.delete(terminal[i].id);}};diff --git a/site/src/cut/server/jobs.test.ts b/site/src/cut/server/jobs.test.tsindex f45ed2de..192489a2 100644--- a/site/src/cut/server/jobs.test.ts+++ b/site/src/cut/server/jobs.test.ts@@ -1,5 +1,7 @@-import { afterAll, beforeAll, describe, expect, test } from "bun:test";-import { mkdtemp, readFile, rm, stat } from "node:fs/promises";+import { afterAll, beforeAll, describe, expect, spyOn, test } from "bun:test";+import { mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";+import * as pipeline from "./exportPipeline";+import type { Job } from "./jobs";import os from "node:os";import path from "node:path";@@ -9,6 +11,7 @@ const root = await mkdtemp(path.join(os.tmpdir(), "cut-jobs-test-"));process.env.DONKEY_CUT_DATA_DIR = root;const jobs = await import("./jobs");const projects = await import("./projects");+afterAll(async () => { await rm(root, { recursive: true, force: true }); });const exists = (file: string) =>stat(file).then(@@ -29,9 +32,6 @@ describe("a render the tab carries itself", () => {beforeAll(async () => {projectId = (await projects.createProject("Tab Render")).id;});- afterAll(async () => {- await rm(root, { recursive: true, force: true });- });test("holds a name and a running row, then lands the file under that name", async () => {const job = await jobs.createClientJob(projectId, "mp4");@@ -107,3 +107,55 @@ describe("a render the tab carries itself", () => {expect(job.status).toBe("error");});});++describe("preview publication", () => {+ async function request(projectId: string) {+ const form = new FormData();+ form.set("spec", JSON.stringify({ projectId, target: "preview" }));+ return jobs.createJob(form);+ }++ async function settled(job: Job) {+ const deadline = Date.now() + 2000;+ while ((job.status === "running" || job.status === "queued") && Date.now() < deadline)+ await new Promise((resolve) => setTimeout(resolve, 5));+ expect(["done", "error"]).toContain(job.status);+ }++ for (const outcome of ["rejected", "failed", "done"] as const) {+ test(`a newer ${outcome} preview ${outcome === "done" ? "keeps its publication" : "allows the earlier render to publish"}`, async () => {+ const projectId = (await projects.createProject(`Preview ${outcome}`)).id;+ const finishes = new Map<pipeline.RenderHandle, { resolve: () => void; reject: (error: Error) => void }>();+ const render = spyOn(pipeline, "runExport").mockImplementation(async (job) => {+ await new Promise<void>((resolve, reject) => finishes.set(job, { resolve, reject }));+ await writeFile(job.outPath, path.basename(job.outPath));+ });+ const created: Job[] = [];+ try {+ const first = await request(projectId);+ created.push(first);+ if (outcome === "rejected") {+ const other = (await projects.createProject("Busy preview slot")).id;+ created.push(await request(other));+ }+ const newer = await request(projectId);+ created.push(newer);+ if (outcome === "failed") finishes.get(newer)!.reject(new Error("Render failed"));+ if (outcome === "done") finishes.get(newer)!.resolve();+ await settled(newer);+ expect(newer.status).toBe(outcome === "done" ? "done" : "error");+ finishes.get(first)!.resolve();+ await settled(first);+ expect(first.status).toBe("done");+ const winner = outcome === "done" ? newer : first;+ expect(await readFile(path.join(projects.projectDir(projectId), "preview.mp4"), "utf8"))+ .toBe(path.basename(winner.outPath));+ } finally {+ for (const finish of finishes.values()) finish.resolve();+ await Promise.all(created.map(settled));+ for (const job of created) jobs.cancelJob(job.id);+ render.mockRestore();+ }+ });+ }+});diff --git a/site/src/cut/server/jobs.ts b/site/src/cut/server/jobs.tsindex 8e0198b9..12c5105e 100644--- a/site/src/cut/server/jobs.ts+++ b/site/src/cut/server/jobs.ts@@ -1,5 +1,5 @@import { type ChildProcess } from "node:child_process";-import { mkdir, mkdtemp, open, readdir, rename, rm, writeFile } from "node:fs/promises";+import { copyFile, mkdir, mkdtemp, open, readdir, rename, rm, writeFile } from "node:fs/promises";import os from "node:os";import path from "node:path";import { assertLocalRuntime } from "./local-only";@@ -45,6 +45,7 @@ const MAX_RUNNING = 2; // concurrent ffmpeg exports; extra exports queue behind// are active work, not backlog, so they are exempt from eviction.const { jobs, retire } = createJobRegistry<Job>("__veditorJobs", {isTerminal: (j) => j.status === "done" || j.status === "error",+ onEvict: (job) => { if (job.target === "preview" && job.outPath) void rm(job.outPath, { force: true }); },});/** Renders holding an ffmpeg slot. A tab's own render is in the feed with@@ -104,13 +105,39 @@ function pump() {}}+const previewPublications = new Map<string, Promise<void>>();++function publishPreview(job: Job): Promise<void> {+ const directory = projectDir(job.projectId);+ const previous = previewPublications.get(directory) ?? Promise.resolve();+ const next = previous.catch(() => {}).then(async () => {+ const newest = [...jobs.values()].filter((j) =>+ j.projectId === job.projectId && j.target === "preview" && j.status !== "error"+ ).at(-1);+ if (newest?.id !== job.id) return;+ const staged = path.join(directory, `.preview-${job.id}.mp4`);+ try {+ await copyFile(job.outPath, staged);+ await rename(staged, path.join(directory, "preview.mp4"));+ } finally {+ await rm(staged, { force: true });+ }+ });+ previewPublications.set(directory, next);+ void next.finally(() => {+ if (previewPublications.get(directory) === next) previewPublications.delete(directory);+ }).catch(() => {});+ return next;+}+/** Move a job from queued to running and drive its ffmpeg render. Its settle* frees the slot and pumps the queue. */function startRun(job: Job, spec: ExportSpec) {job.status = "running";job.startedAt = Date.now();void runExport(job, spec, (file) => mediaPath(spec.projectId, file))- .then(() => {+ .then(async () => {+ if (job.target === "preview") await publishPreview(job);job.status = "done";}).catch((err: unknown) => {@@ -265,10 +292,17 @@ export async function createJob(form: FormData): Promise<Job> {if (preview) job.outName = "preview.mp4";else await claimExportName(job, spec.name ?? doc.name, containerExtension(spec));job.outPath = path.join(- preview ? projectDir(spec.projectId) : exportsDir(spec.projectId),- job.outName+ preview ? path.join(projectDir(spec.projectId), ".previews") : exportsDir(spec.projectId),+ preview ? `${job.id}.mp4` : job.outName);await mkdir(path.dirname(job.outPath), { recursive: true });+ if (preview) {+ const activePaths = new Set([...jobs.values()].map((entry) => entry.outPath));+ for (const name of await readdir(path.dirname(job.outPath))) {+ const file = path.join(path.dirname(job.outPath), name);+ if (!activePaths.has(file)) await rm(file, { force: true });+ }+ }job.tmpDir = await mkdtemp(path.join(os.tmpdir(), "veditor-"));// Overlay PNGs are rendered in the browser and uploaded with the spec.for (const [key, value] of form.entries()) {diff --git a/site/src/cut/worker/exportJob.ts b/site/src/cut/worker/exportJob.tsindex 219105b0..7fe915c5 100644--- a/site/src/cut/worker/exportJob.ts+++ b/site/src/cut/worker/exportJob.ts@@ -1,11 +1,12 @@import { mkdir, mkdtemp, rm } from "node:fs/promises";import os from "node:os";import path from "node:path";+import type { CloudDocSnapshot } from "../lib/headless/docSession";import { buildDocExportSpec, isDocExportPreset } from "../lib/headless/docExport";import { runExport, type ExportSpec, type RenderHandle } from "../server/exportPipeline";import { storeCardArtifacts } from "./cardJob";import { prisma, registerObject, type ClaimedJob } from "./db";-import { downloadToFile, exportKey, mediaKey, mimeFor, previewKey, uploadFile } from "./r2";+import { downloadToFile, exportKey, mediaKey, mimeFor, uploadFile } from "./r2";import { overlayKey } from "../server/cloud/r2";import { specMediaFiles } from "../lib/exportDelivery";import { runnerSession } from "./session";@@ -19,7 +20,7 @@ export interface ExportJobSpec {/** A render asked for by a client that cannot build a spec — the phone. The* row carries the size and nothing else; the worker opens the project doc* and builds the spec itself. */- fromDoc?: { preset?: string };+ fromDoc?: { preset?: string; snapshot: CloudDocSnapshot };overlays?: { name: string; key: string }[];/** "overlays": the cut's media came up with the job — a browser-resident* project borrowing this worker. Its output is the job's scratch too: it@@ -119,6 +120,8 @@ export async function runExportJob(const stored = job.spec as ExportJobSpec;const projectId = job.projectId ?? stored.spec?.projectId;if (!projectId) throw new Error("Export job has no project.");+ if (stored.fromDoc && !stored.fromDoc.snapshot?.doc)+ throw new Error("This render has no captured document. Queue the export again.");if (!stored.fromDoc && (!stored.spec || !Array.isArray(stored.spec.clips))) {throw new Error("Malformed export spec.");}@@ -135,7 +138,8 @@ export async function runExportJob(runnerSession(job),projectId,isDocExportPreset(stored.fromDoc.preset) ? stored.fromDoc.preset : "original",- handle.tmpDir+ handle.tmpDir,+ stored.fromDoc.snapshot)) as ExportSpec,}: stored;@@ -175,7 +179,7 @@ export async function runExportJob(return { outputKey: key, outName };}const key = preview- ? previewKey(job.userId, projectId)+ ? `cut/${job.userId}/projects/${projectId}/previews/${job.id}.mp4`: exportKey(job.userId, projectId, outName);const bytes = await uploadFile(key, handle.outPath, mime);await registerObject({@@ -188,10 +192,20 @@ export async function runExportJob(kind: preview ? "preview" : "export",});if (preview) {- // Best-effort: a project deleted mid-render just drops its proxy.- await prisma.cutProject- .update({ where: { id: projectId }, data: { previewKey: key } })- .catch(() => {});+ await prisma.$transaction(async (tx) => {+ const project = await tx.cutProject.findUnique({ where: { id: projectId }, select: { previewKey: true } });+ if (!project) return;+ const newest = await tx.cutRenderJob.findFirst({+ where: { userId: job.userId, projectId, kind: "preview" },+ orderBy: [{ createdAt: "desc" }, { id: "desc" }], select: { id: true },+ });+ if (newest?.id !== job.id) return;+ // A newer completion changes the pointer, so this write cannot replace it.+ await tx.cutProject.updateMany({+ where: { id: projectId, userId: job.userId, previewKey: project.previewKey },+ data: { previewKey: key },+ });+ });}return { outputKey: key, outName };});diff --git a/site/src/cut/worker/main.ts b/site/src/cut/worker/main.tsindex 3b2bf0cd..7305c317 100644--- a/site/src/cut/worker/main.ts+++ b/site/src/cut/worker/main.ts@@ -92,11 +92,25 @@ async function claimNext(): Promise<ClaimedJob | null> {select: { id: true, userId: true, projectId: true, kind: true, spec: true, outName: true },});for (const c of candidates) {- const { count } = await prisma.cutRenderJob.updateMany({- where: { id: c.id, state: "queued" },- data: { state: "running", claimedAt: new Date(), progress: 0, error: null },- });- if (count === 1) return c;+ const claimed = await prisma.$transaction(async (tx) => {+ if (["preview", "card", "hls"].includes(c.kind)) {+ const running = await tx.cutRenderJob.findFirst({+ where: { userId: c.userId, projectId: c.projectId, kind: c.kind, state: "running" },+ select: { id: true },+ });+ if (running) return null;+ }+ const updated = await tx.cutRenderJob.updateMany({+ where: { id: c.id, state: "queued" },+ data: { state: "running", claimedAt: new Date(), progress: 0, error: null },+ });+ if (updated.count !== 1) return null;+ return tx.cutRenderJob.findUnique({+ where: { id: c.id },+ select: { id: true, userId: true, projectId: true, kind: true, spec: true, outName: true },+ });+ }, { isolationLevel: "Serializable" });+ if (claimed) return claimed;}}return null;