Open source CapCut alternative.
TypeScript
docs: cut guide covers the browser project home
David Lec749c652edc6
diff --git a/docs/guides/cut/README.md b/docs/guides/cut/README.mdindex b16ad59d..2cee1100 100644--- a/docs/guides/cut/README.md+++ b/docs/guides/cut/README.md@@ -1,25 +1,27 @@# Cut-Cut (publicly "Donkey Cut") is a standalone, free video editor. Its product domain is `donkeycut.com` — a marketing landing at `/` and the editor at `/app/…`; links on retired domains are redirected there at the edge (Cloudflare). The host serves only the client bundle — every page is client-rendered — and the page does all real work against the Cut engine: a local server the Donkey Mac app ships and supervises on the user's own Mac. The engine uses local disk, the app's bundled ffmpeg, on-device speech, and the user's own Claude/Codex CLI logins. Using the app requires a Donkey sign-in. Local projects and the library belong to the Mac user, shared by every Donkey account that signs in on that Mac. AI generation — images, video, and voiceovers — and the assistant's Gemini models additionally spend credits: the page posts to Donkey's hosted inference routes with the user's session and credits. `donkeycut.com` owns sign-in directly — the auth pages and the Google callback serve on that host — so the session is a plain host-only cookie. Generated media lands back in the project through the engine like any other file; Gemini chat turns, including their editor tool calls, run entirely in the page.+Donkey Cut is a free video editor that runs in the browser; the code calls it Cut. Its product domain is `donkeycut.com` — a marketing landing at `/` and the editor at `/app/…`; links on retired domains are redirected there at the edge (Cloudflare). The host serves only the client bundle — every page is client-rendered — and using the editor requires a Donkey sign-in.++A project lives in one of three homes, chosen when it is created. A browser project keeps its files in the page's own origin-private storage, so a fully local project needs nothing installed. A project on a Mac talks to the Cut engine — a local server the Donkey Mac app ships and supervises, which uses local disk, the app's bundled ffmpeg, on-device speech, and the user's own Claude/Codex CLI logins; the engine's projects and library belong to the Mac user, shared by every Donkey account that signs in on that Mac. A cloud project stores its doc and media on Donkey's hosted servers. The user chooses between the two places they think in — Local and Cloud — and which store backs Local is the session's business: the Mac's engine once the app has connected, the browser's own storage otherwise.++AI generation — images, video, and voiceovers — and the assistant's Gemini models spend credits: whatever the project's home, the page posts to Donkey's hosted inference routes with the user's session and credits. `donkeycut.com` owns sign-in directly — the auth pages and the Google callback serve on that host — so the session is a plain host-only cookie. Generated media lands back in the project like any other file; Gemini chat turns, including their editor tool calls, run entirely in the page.**The engine rule:** the engine API surface (`/api/cut/*`) runs only on the user's Mac. On a hosted deploy every one of those routes answers 404 before any handler runs, so the unauthenticated routes are unreachable there and nothing can execute off-Mac — the engine has no path to Donkey's production models; the page reaches them only through Donkey's own authenticated inference APIs. Don't wrap the engine's routes in the Donkey auth helper, reach for Prisma from them, or bill them against credits; local-only is the design for everything the engine does.-The cloud adds a second surface with the opposite rules on purpose: `/api/cut-cloud/*` is the engine's hosted twin — the same route shapes, but session-authenticated, storing docs in Postgres and media in R2, and metering model calls through credits. A project lives in exactly one place (this Mac or the cloud), and the client picks the surface per project; the two surfaces never proxy to each other. See [Cloud projects](#cloud-projects).+The cloud adds a second surface with the opposite rules on purpose: `/api/cut-cloud/*` is the engine's hosted twin — the same route shapes, but session-authenticated, storing docs in Postgres and media in R2, and metering model calls through credits. Browser projects answer their storage routes in the page itself, out of origin-private storage, and ride the hosted twin for AI, metered like cloud projects. A project lives in exactly one home, and the client picks the surface per project; the surfaces never proxy to each other. See [Cloud projects](#cloud-projects).## How it works-The hosted domain and the local engine split the work: the page comes from wherever is convenient, the work always happens on the Mac.+The page comes from wherever is convenient — the hosted domain, or one local dev server that serves pages and APIs from the same origin — and the work happens where the project lives.```-page from donkeycut.com (hosted) page from localhost/cut (local dev)- │ client bundle only; │ one local server:- │ every Cut API 404s there │ pages + APIs, same origin- ▼ ▼-browser ── API calls ──▶ Cut engine on 127.0.0.1 (spawned by the Donkey app)- │- ▼- local disk · bundled ffmpeg · on-device speech- · the user's own claude/codex CLI logins+browser (the editor)+ ├─ browser project ─▶ origin-private storage in this browser+ │ (AI rides the hosted twin)+ ├─ cloud project ───▶ /api/cut-cloud/* · Postgres · R2+ └─ local project ───▶ Cut engine on 127.0.0.1 (spawned by the Donkey app)+ local disk · bundled ffmpeg · on-device speech+ · the user's own claude/codex CLI logins```**What loads is cached locally.** Every visit re-reads the same three things: the projects listing, the library, and a project's document. The browser keeps the last answer to each in IndexedDB, scoped to the account and the backend that served it, and paints it on arrival while the real request runs behind it. So returning to a project draws on the next frame instead of after a round trip, and a project you just created opens on a document the client already knows is empty. A snapshot is a head start and the live answer always replaces it; where the two disagree the server wins. The one exception is an edit made on top of a snapshot — that is kept rather than overwritten, saves like any other edit, and a cloud project whose stored copy really has moved on answers that save with the version conflict it already had.@@ -40,15 +42,17 @@ Whether any of this is true of a given build is measured rather than assumed: `n## Cloud projects-Cloud projects make Cut usable in any browser on any OS with nothing installed, and they run alongside local ones: every account has both halves, and which one a project uses is decided per project.+Cloud projects follow the account: the same project opens in any browser on any OS. They run alongside local ones — every account has both halves, and which home a project uses is decided per project.-Every client call goes through a backend seam (`site/src/cut/lib/backend/`): the local driver is the engine transport unchanged, and the cloud driver rewrites the same paths to `/api/cut-cloud/*` with the session cookie. Residency is per project and fixed when the project is created, so creating one is where the user chooses. One picker makes that choice, standing beside New project in the sidebar: it names a shelf — this Mac or the cloud — and everything the browser creates lands there, new projects and anything added to the library alike. The choice sticks on that browser until they change it, and every other New project button follows it rather than asking again. With no Donkey app running there is nothing to choose and every new project is a cloud project; inside a folder the folder decides, since a project files only into a folder beside it. The home lists both shelves as one listing — the Mac's from its stored listing when the app is closed — each project badged with where it lives, and opening one binds the editor to that project's backend. Capability flags on the driver hide what a backend can't do, so components never feature-detect.+Every client call goes through a backend seam (`site/src/cut/lib/backend/`): the local driver is the engine transport unchanged, the cloud driver rewrites the same paths to `/api/cut-cloud/*` with the session cookie, and the browser driver answers storage routes in the page from origin-private storage, falling through to the cloud twin for AI. Residency is per project and fixed when the project is created, so creating one is where the user chooses. One picker makes that choice, standing beside New project in the sidebar: it names a shelf — Local or Cloud — and everything the browser creates lands there, new projects and anything added to the library alike. Local is this Mac's engine when the app has connected and this browser's own storage otherwise, so a machine without the app still has a real local shelf. The choice sticks on that browser until they change it, and every other New project button follows it. Inside a folder the folder decides, since a project files only into a folder beside it. The home lists every shelf as one listing — the Mac's from its stored listing when the app is closed — each project badged with where it lives, and opening one binds the editor to that project's backend. Capability flags on the driver hide what a backend can't do, so components never feature-detect.-The library is the exception, because it is a shelf rather than a place: it lists every residency at once — the Mac's and the cloud's — as one listing, newest first, with a badge saying which shelf each item is on. So a cloud project can pull a clip off this Mac, and a local project can pull one out of the cloud. Each half is remembered on its own, so the Library tab keeps listing the Mac's items with the app closed, read-only, and clicking one raises the same banner an unreachable local project does. The editor's library picker asks only for what it can reach, since an item it cannot copy into the project has no business in a picker. Each item's own shelf answers for it: previews, renames, and deletes go to the backend it came from, and folders belong to one shelf, so items file only into folders beside them. Adding to a project is the one crossing: on the project's own shelf the server copies the file without the bytes leaving it, and off it the browser carries them down and back up.+The library is the exception, because it is the user's one shelf across places: it lists the Mac's half and the cloud's at once as one listing, newest first, with a badge saying which shelf each item is on. The browser's own store holds projects only, so those are the library's two shelves. So a cloud project can pull a clip off this Mac, and a local project can pull one out of the cloud. Each half is remembered on its own, so the Library tab keeps listing the Mac's items with the app closed, read-only, and clicking one raises the same banner an unreachable local project does. The editor's library picker asks only for what it can reach, since an item it cannot copy into the project has no business in a picker. Each item's own shelf answers for it: previews, renames, and deletes go to the backend it came from, and folders belong to one shelf, so items file only into folders beside them. Adding to a project is the one crossing: on the project's own shelf the server copies the file without the bytes leaving it, and off it the browser carries them down and back up.Cloud projects store their doc in Postgres (versioned; a stale autosave 409s and the editor reloads the newer copy) and media in R2: uploads go direct from the browser on presigned URLs (the hosted functions never see the bytes), playback streams on signed range URLs, and a flat per-user quota is enforced at presign time. That quota is visible rather than implicit: a free account editing a cloud project sees what it has used in the editor's top bar, and a presign rejected for space opens an upgrade offer wherever it happened instead of a bare error. The same slot carries the countdown when a subscription is set to cancel, and clicking it opens the billing portal.-A dropped file does not wait for that upload. Because a presign claims the stored name before any bytes move, and the browser can read the file it was handed, an import is measured, named, and placed on the timeline in the same moment it is dropped — playing from the local copy, filmstrip and all — while the bytes go out behind the editor. The saved document is what keeps this honest: an import still uploading is left out of it, along with the clips that use it, so a tab closed mid-upload leaves nothing to reopen broken, and the asset and its clips join the document the moment the upload lands. Export waits on the same line, since a render reads the saved document.+A dropped file does not wait for that upload. Because a presign claims the stored name before any bytes move, and the browser can read the file it was handed, an import is measured, named, and placed on the timeline in the same moment it is dropped — playing from the local copy, filmstrip and all — while the bytes go out behind the editor. When this browser can hold a store, the dropped bytes are written into origin-private storage under the claimed name and pinned: the document references the asset at once, a tab closed mid-upload resumes the upload on the next open, and once the cloud confirms the object the pin clears and the local file becomes a read cache. A tab-scoped import — a browser with no store — keeps itself honest through the saved document instead: the import stays out of it, along with the clips that use it, until the upload lands, so a tab closed mid-upload leaves nothing to reopen broken. Export waits on the same line, since a render reads the saved document.++The cache runs the other way too: opening a cloud project prefetches every asset this browser is missing — one file at a time, nearest timeline use first — and each file that lands swaps the playing asset onto its local bytes, so scrubbing goes local as the queue drains and the next open plays entirely from disk. When the origin's storage quota runs short, the least recently opened projects' caches are dropped to make room; pinned uploads and browser-resident projects are never evicted, so losing a cache only costs a re-download.Storage a subscription paid for outlives the subscription for a while: when Pro ends and the account still holds more than the free tier, it keeps everything for thirty days, warned in the editor and on the projects home. After that the daily sweep brings it back under the cap — least-recently-updated projects first, then the oldest library assets, stopping the moment it fits — so what survives is the recent work, and an account already under the cap is never touched.@@ -84,9 +88,9 @@ Because a GUI-spawned process inherits a bare PATH, the engine rebuilds it: tool| --- | --- | --- || Sign-in | Required account | Required account; local data is per-account on the Mac || Billing | Credits | Free; AI generation, Gemini chat, and cloud transcription spend credits |-| Storage | Database | Local disk; cloud projects use Postgres + R2 behind a per-user quota |+| Storage | Database | Local disk or the browser's own storage; cloud projects use Postgres + R2 behind a per-user quota || Model access | Hosted routes | CLI logins; AI generation, Gemini chat, and cloud transcription use Donkey's hosted routes (signed in) |-| Distribution | The Mac app | Rides the same app; cloud projects need no install |+| Distribution | The Mac app | Rides the same app; browser and cloud projects need no install |The only shared code runs one way: Cut uses a few site UI utilities and the Donkey auth/credits helpers on its cloud surface, and the engine rides the app's process-environment helpers. Nothing in the Donkey product imports Cut. Cut's database models live in their own schema file (`site/prisma/Cut.prisma`) and carry plain user ids.