Skip to content

Open source CapCut alternative.

TypeScript

docs: Cut guide as a short overview

David Le4cccfb66765d
diff --git a/docs/guides/cut/README.md b/docs/guides/cut/README.md
index ef46959e..3747777e 100644
--- a/docs/guides/cut/README.md
+++ b/docs/guides/cut/README.md
@@ -1,189 +1,45 @@
# Donkey Cut
-Donkey Cut is a free video editor that runs in the browser; code and paths shorten the name to `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.
+Donkey Cut is a free video editor that runs in the browser at `donkeycut.com`. The page is the whole editor: it decodes, draws, and mixes the cut, runs the assistant, and renders the export. Code and paths use the shorter name `cut`.
-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 Donkey 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 — and the session cookie is scoped to `donkeycut.com`, so it also reaches the site's own subdomains. 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. 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).
+**The one rule:** the engine's routes run only on the user's Mac. On a hosted deploy every one of them answers 404 before a handler runs, so nothing the engine does can execute off-Mac and the engine never reaches Donkey's production models. Never wrap an engine route in the Donkey auth helper, read Prisma from it, or bill it against credits.
## How it works
-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.
-
-```
-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 ───▶ the 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
+A project lives in one of three homes, chosen when it is created.
+
+```text
+ the page (the editor)
+ |
+ +--------------------+--------------------+
+ | | |
+ browser project Mac project cloud project
+ origin-private engine in the Postgres doc,
+ storage in the Donkey Mac app media in R2
+ page (local disk, ffmpeg,
+ on-device speech)
```
-**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.
-
-The client probes the engine's health endpoint (dedicated port first, dev server second) and remembers the winner. Browsers permission-gate a hosted page's calls to the local machine, so the page probes only when that raises no prompt — it is served by the engine, or the permission is already granted — and starts in the cloud otherwise. The engine grants the hosted origin cross-origin access, and only that origin. Nothing walls the app, because cloud editing always works. Closing the Donkey app does not hide the work made in it either: a browser that has reached this Mac's engine before keeps listing that shelf from the listing it stored, so those projects stay on the home beside the cloud ones, each badged with where it lives. They are read-only while the app is away — no renames, moves, or deletes — and opening one says that it lives on this Mac rather than guessing at a cloud copy that was never there. That is where the warning belongs, so that is the only place it appears: a banner over the thing that will not open, which the user cannot dismiss and which opens the recovery steps in a dialog with the button that fires the browser's permission prompt. Probing continues behind it, so starting the app clears the banner and loads the project. Engine updates ride the Donkey app's own auto-updater, so the client never prompts to update.
-
-**A cut needs no footage.** The frame starts as a color the project owns, and everything else — clips, titles, shapes, stickers — draws over it. So a video made entirely of text and graphics is an ordinary project: it plays, exports, shares, and renders on the worker like any other, and the same color letterboxes a fitted clip and fills a gap on track 0. Elements stack by row: two on one row slide clear of each other in time, so a title that sits over a card lives a row above it. An element rides the frames of the clip under it: its ends are remembered as that clip's source seconds, so moving the clip carries the element, a speed change stretches it with the picture, a trim leaves it on the frames it covered, a split hands it to the half that plays them, and deleting the clip leaves it in place over whatever is there now. The store's one write path keeps that true for every edit, the assistant's included, and the Inspector frees an element that should stay put. Type stays inside the picture on its own: a line wider than the room its anchor leaves is measured against the face it will actually be drawn in and broken onto another line, in the preview and in the export alike, so whoever writes the words — a person, the assistant — picks the size the design wants and lets the frame do the breaking.
-
-**Framing is per clip.** Every video clip meets its box — the whole frame, or the region it was given — through one geometry: fitted with margins or covering with a crop, zoomed in further, panned to choose what the crop keeps, turned, faded, cornered, masked, and shadowed. One function computes where the picture lands, the preview draws that rectangle, and the export graph scales and crops to the same numbers, so a reframed clip looks the same on every surface, freeze frames and headless renders included. On the stage the selected clip wears two outlines: a blue box for its layout — a drag anywhere on it moves the clip, its grips resize it, the button above turns it — and a grey dashed one standing where the source really lands, so the part a crop discards stays visible: its corners zoom the picture and dragging the discarded part slides the crop. The shadow is cast by the shape the clip actually shows, mask included, which is what makes a circle-masked camera bubble throw a circular shadow.
-
-**A cutout keys the clip to a matte.** Every video clip can carry a cutout — the Inspector's Cutout tab: an alpha matte decides which of its pixels stay, ink can trace the selection's silhouette, and a color or image can fill in behind it, with lower tracks showing through wherever nothing fills. The cutout runs in either direction — keep the selection and remove the background around it, or remove the selection and keep the rest — and the matte is the same in both, so flipping the direction re-bakes nothing. Every mode resolves to that one matte in the clip's own pixels, baked into a small grayscale video stored as a project asset: auto mattes the person with the on-device segmenter in seconds and for free, and a hosted tracker (credits, like all AI work) re-bakes it at quality and swaps the asset in when the user asks for the upgrade; a custom selection goes straight to the tracker, seeded by a few words naming the subject or by the strokes painted on the stage, and the stored words and seeds make every bake reproducible. Every bake starts from an explicit Apply — picking a mode or painting only describes the selection, and the chat tool's call counts as the ask. A long clip tracks in parts: the span splits into pieces of a few minutes, each submitted to the tracker as its own billable job with the selection handed across the seam, and a persisted ticket pins the submitted parts and the exact span they were cut from — a reload resumes the run on the paid pieces, and a part whose track dies is re-bought alone on retry. A fingerprint on the matte records what it was baked from — the source and the selection, trims left out — so a retrim inside the baked range keeps the matte and its bill, while a changed selection re-bakes; a background sweep settles bakes against the doc through undo, redo, and deletion, and holds them while a brush session is still painting. Switching the cutout off keeps the removal and its baked matte on the clip — nothing renders and nothing bakes until it is switched back on, and the switch back is free. For the ffmpeg export each cutout clip ships as a client-rendered pair of videos — the keyed picture's color and its alpha — baked by the same compositor that draws the preview, so the engine and the worker composite exactly what the tab showed. Headless surfaces consume stored mattes; a turn that runs with no browser writes the cutout onto the clip and the next editor session's sweep starts the bake it owes.
+The user sees two places, Local and Cloud. Local is the Mac's engine once the app has connected and the browser's own storage otherwise, so a fully local project needs nothing installed. A project lives in exactly one home and the surfaces never proxy to each other.
-**Words as the picture.** A lyric video, a kinetic-typography passage, a quote sequence: the assistant places a whole run of lines in one call, carrying a named look. A look is the design of the whole run rather than of one line — the frame color, the cards it cycles, and the ensemble the run walks across its length: the faces it rotates through, the entrances, where successive lines land in the frame, and what each line does while it holds. That is what stops a hundred lines coming out identical and dead center, which is the failure a text video actually has. The looks live in one registry the tools and the skills both read, so adding a look teaches the assistant a new style with no other change. Words ride one of two carriers — a caption track, which holds per-word timings, or elements, which give each line its own card, color and motion. Both carriers play a line word by word, and what a word does is data like everything else: three poses — before its moment, at it, and after — and the seconds between them. An emphasis travels along a line that is fully up, because the pose after a word's moment is the pose before it; a build assembles the line as it is spoken, because the pose after is the pose it arrived at. That one shape covers a karaoke highlight, a word swelling on the beat, a sentence appearing a word at a time, and a faint line going solid word by word, and it is what makes adding another an entry in the catalog. One evaluator resolves each word to a color, an opacity and a pose, and the preview, the burn-in and the frame samplers all read that, so a word effect looks the same wherever it plays. Text the user already has (lyrics, a script) is timed by aligning it to a transcript of the audio: the recognizer supplies the clock and the user's wording is kept exactly, which is what makes it survive singing.
-
-**Motion is data.** Every animation in the editor — an entrance, an exit, a loop, and the moves an element makes while it holds — is one format: a pose keyframed over a normalized window with cubic-bezier easing, plus a range selector that says how the motion is handed from one character to the next. That is the After Effects text-animator model, the one Lottie serializes, and picking it means a preset and a hand-keyed track are the same object at two levels of convenience: the named entrances, loops, and moves are slots on the element, evaluated internally, and anything no name covers is keyed directly on the element's own pose track — the track stays whatever the user keys by hand. The library is a JSON asset in the effects kit rather than code, and the menus, tool enums, prompts, and the frame sampler's crop budget are all read from it, so adding an animation is adding an entry. One evaluator samples it, which is what keeps the preview, the export, and the headless worker showing the same motion. A slot may also carry a preset of its own rather than naming one from the library, in the same shape a library entry has — the evaluator cannot tell the two apart, so an animation composed inside a project plays wherever a shipped one does.
-
-**An effect treats what runs under it.** An effect is a stretch of the timeline rather than a property of a clip, so it can cover part of a shot, a whole one, or a run of them, and it is trimmed and moved like any other element. Some of them treat the picture — a grade, a grain, a shake, a push in — and some treat the sound: everything audible under the window, clip audio, upper tracks and soundtrack, mixed and then filtered as one. The sound treatments are described as data — a dry level, delay taps, filter bands, a tremolo, a bit crush — and three renderers read that one description: the Web Audio graph the preview plays, the same graph folded offline for an in-tab export, and an ffmpeg chain for the engine and the cloud worker. That is what keeps the export sounding like the preview; the ffmpeg side cuts the window out of the mix, runs the chain over it, and pads the result back to the length it went in at, so a chain that rings past its window cannot walk the rest of the sound late. The window's edges cross over rather than switch, in both mixes, so an effect coming in cannot click. A picture effect can be shown on its tile; a sound treatment has to be heard, so the tile plays — a line of recorded speech run through the same chain the mix would build. The line is one of the voice personas already shipped with the site, fetched once and kept decoded for the session, so the shelf demonstrates itself in a project with no footage in it yet.
-
-**A clip carries its own sound treatment.** Beside the volume in the Inspector's Audio tab, a clip — a video clip's own sound or a soundtrack clip — has a Sound quality section: a seven-band equalizer, a compressor and a limiter. The treatment belongs to the clip and runs on its sound alone, ahead of its level, fades and any ducking, so shaping a voice never colors the music under it. It is described with the same recipe the sound effects use and read by the same three renderers, which is what keeps the preview, the in-tab export and the ffmpeg export on one sound; the compressor and the limiter are dynamics stages on that recipe, spelled as ffmpeg's compressor and lookahead limiter on one side and the browser's dynamics node on the other. The band frequencies are fixed, so a treatment is seven decibel values and two small stages, which is what makes it a preset: the editor ships a flat one and a voice one, and the user saves their own to the Library, where a preset is a template carrying nothing but a treatment — every shelf stores and lists it with the machinery templates already have, and the template shelf leaves it out. The assistant applies and saves the same presets by name.
-
-**A handover is on the picture or on the sound.** A transition is a blend at the cut rather than an overlap: the clips still abut, the layout never moves, and the incoming clip starts exactly at the cut. Most styles blend the picture across the outgoing clip's last seconds. The cross dissolve hands over on the sound instead — the picture cuts while the two clips ramp past each other, half the handover either side of it. Its bar sits across the cut for that reason, where every other bar ends on the boundary it plays. The two windows sit on separate fields, so everything that draws the picture reads a plain cut and only the mix ramps: the preview, the in-tab export, and the ffmpeg graph the engine and the worker build all follow from that one split. A sound handover needs a second clip's sound to cross into, so a bar of it parked on a clip's open head or tail plays nothing.
-
-**A clip's rate is a curve over its footage.** A clip plays at one speed, or at a speed that changes through it: nodes pinned to moments in the source, each with a rate, joined by a smooth curve that holds its shape through trims and splits because the nodes belong to the footage. One map sits under it — timeline seconds to source seconds and back — and everything that reads a clip reads that map: the preview's decoder and its pitch-held sound, the in-tab export, the filmstrip on the bar, the beat dots, the assistant's cue arithmetic, and the ffmpeg graph the engine and the cloud worker build. The picture side of that graph is the map itself written as a timestamp expression; the sound side is baked first, since ffmpeg's tempo filter only takes a constant, so all three renderers stretch the sound with the same code. The curve is edited in a strip over the timeline — the footage behind the graph, the beats as ticks a node snaps to, presets for the usual ramps — and the assistant lays one from a description with the same tool. A clip can also play backward: the same map read from its far end, so the footprint, the curve and every reader above hold as they are. The preview serves it off the decoder's backward walk, the sound is the span turned before it is stretched, and the engine and the worker bake the span into a turned copy in bounded chunks ahead of the graph and render the clip forward off that.
-
-**A crossing needs handle, and holds its loudness.** Clips never overlap, so for the length of a cross dissolve each one plays into the other's time out of its handle — the media its trim left behind, the outgoing clip past its out point and the incoming clip before its in point. That is what makes both sides really audible over a cut their pictures hard-join, and it is why the ramps are equal-power (sine and cosine) rather than straight lines: two signals meeting at half level sum to the loudness they each had, so the mix never dips through the join. A clip trimmed to the end of its source has no handle to reach into; its side of the crossing stops at the cut, and the handover reads as a dip instead of a crossing. Every renderer works from the same two numbers on a span — how far the crossing runs, and how far each side reaches — so the preview, the browser fold and the ffmpeg graph land on one sound. It opens at 0.3 seconds, shorter than a picture blend's half second: that covers the jump in room tone at a cut while staying under the length where the ear starts hearing two voices, and it asks less of the trim each clip has left. It is picked where the other work on the sound is picked — the Effects tab's Sound family — while the styles that blend the picture are picked from the Transitions tab. A bar can also be hidden, like anything else on the timeline: it grays out and plays nothing while keeping the cut it sits on, so the joint runs hard and the blend is one click away again.
+AI is hosted whatever the home: image, video, and voiceover generation and the assistant's Gemini models run through Donkey's authenticated inference routes against the user's credits, and the results land in the project like any other file. The cloud's routes are the engine's hosted twin, same shapes with session auth and credit metering.
## The preview
-The preview decodes the cut itself. Every clip on screen owns a decoder reading its file directly — the container is parsed in the page and frames come off WebCodecs — and a small ring of already-decoded frames sits beside it. Drawing a frame is a question answered from that ring, never a wait: playing walks each file forward and keeps the ring ahead of the playhead, scrubbing asks for one moment and the newest ask wins, and if the exact frame has not landed the nearest one already decoded goes up and is replaced when the real one arrives. A held frame is worth more than a stall. Backing the playhead up runs the same walk the other way: each window of frames just below the playhead decodes once from its keyframe, the next window lands while the playhead crosses the current one, and a half-size spread over the keyframe span stands in wherever a fast drag gets ahead of the windows.
-
-Holding on to a walk is what makes that cheap, and it matters most exactly when it is hardest. A walk that has not yet reached its first frame is doing the only work that can produce a picture — finding the keyframe before the moment asked for, fetching the bytes it sits in, and decoding forward to it — so nothing replaces it while it is coming, however far the playhead has gone past it in the meantime. A walk that has landed frames and then been outrun is re-aimed, and it is aimed ahead of the playhead by what reaching a frame has been costing: anchored where the playhead stands it would land its first frame at a moment already gone by and be outrun again immediately, which is the creep-freeze-jump people report as choppiness. Aiming ahead gives up the span in between, and that span was never going to arrive in time anyway — the sound is going there regardless, and a picture that arrives with it beats one that arrives behind it.
-
-The other rule is about walks that stop. A walk reports the same ending whether it read the file's last frame or gave up on it, and a reader whose bytes never came, or whose decoder was closed under it, ends the same way. Believed, an ending a second into a long clip pins the picture on the frame before it and nothing asks for another, so the sound plays the rest of the cut over one still. So an ending short of the film is treated as a walk that failed, and another goes after the film it did not reach. Three things keep that from running away: a walk that gets no further than a previous one has found where the film really stops and is believed, a walk that died does not aim ahead again, since dying at that anchor has disproved the aim, and a source with two dead walks behind it waits a beat before sending the next. Once an ending is believed, moments past it go to the single-frame fetch — a finished walk cannot be crept along, and a reader that keeps asking it gets no frame and no repaint to ask again on, which is a drag position that never paints and a parked playhead that never goes quiet. A cloud project reads its media over the network in resident chunks, so a slow link puts a reader in these positions for real.
-
-A play whose clip has decoded nothing at all has nothing to play, and carrying the clock through that spends a stretch of the cut nobody saw or heard — the playhead arrives somewhere further on when the file finally opens, and the sound plays over a picture that is not moving. So the clock stops where it is, the preview says it is waiting, and the play carries on from the same moment once a frame is there. A moment of it is a decoder a frame or two behind rather than a stall, so a stall has to hold before it counts; a gap in the timeline is empty on purpose and plays through.
-
-Some machines cannot decode the footage as fast as it plays, and no reader can invent frames that the decoder has not produced. Left alone that play never recovers: the sound goes on, the picture falls further behind with every second, and a minute in it is half a minute stale. So a preview that has stayed behind its sound for a few seconds decodes smaller from then on, and the picture catches up at a lower resolution. It is a trade taken once per play and never taken back — every open decoder is abandoned when the size changes and each source pays a fresh keyframe seek, so undoing it would cost more than the pixels are worth. Two things are excluded from it. The opening seconds of a play, where every machine trails while nothing is decoded yet and files are being opened, and a reader whose walk is waiting on bytes: decoding smaller does nothing for a picture that is late because the link has not delivered it, and the preview would end up softer for the rest of the session having gained nothing. The floor is 360, below which there is no picture worth keeping in sync.
-
-A play is the urgent read. The reads behind the editor — a waveform, a filmstrip, a scene probe, the strip's tile captures — open the same file the preview is playing from, and on a big file they take what the picture needs: decoder slots, the link's width, the thread the frames are drawn on. A 4K recording dropped and played at once used to move the playhead over a picture that stood still, because four readers were decoding its keyframes beside the one walk that mattered. So that work waits for the play to stop and picks up where it was, publishing what it had reached; a clip-edge capture, which a trim is waiting on, still goes straight through. The Mac's shelf lands a clip without moving it, too: the engine clones the file into the project before the asset exists, so the first read opens the project's own copy and no reader ever holds the file at two addresses.
-
-Decoders live in a bounded pool, and leaving the pool is suspension before it is closure: an idle source gives up its decoder but keeps the parsed file and the canvases its frames land on, so the next visit wakes it for the cost of one keyframe seek. The canvases are the part that must not churn — a montage of short clips replayed for a few minutes, allocating a fresh set on every reopen, floods the GPU process until frames stop arriving at all. They also must not pile up, so the warm shelf of stood-down sources is capped by the memory it holds rather than by a count of them: a small stage keeps a montage's whole cast, a large one keeps a few, and what does not fit closes for real. A file that moves to a new address mid-play — an import landing in project storage, a signed link re-minted ahead of expiry — keeps its source: the frames already decoded carry the picture while a fresh reader opens on the new address behind them, and the walk goes on from wherever the playhead stands. Closing there instead would put a cold open in front of the very next frame, and the picture would freeze for exactly as long as the open takes.
-
-Those caps are shares of one number. A cut is built out of expensive pictures — frames held inside the platform's decoder, canvases behind every source the pool keeps warm, the bytes of the files they were decoded from — and each of those was capped in whatever currency its own subsystem thought in: a count of decoders, a number of pixels, a number of open files. The tab's real ceiling was whatever those happened to add up to on the machine the tuning was done on. Now every cache says what it holds in bytes and asks what it may hold, and the answer is the smaller of the size it was tuned to want and its share of a quarter of the machine's memory. Where there is room the tuned size is the smaller one and the preview behaves as it was tuned to. Where there is not, the share binds first and every cache sheds together. Which caches stand in a share, and how much of it each may stand on, is written in that one place as well, so two caches cannot be handed the same room and a cache that only reports what it holds still has room set aside for it. File bytes are the share the tab itself stands on, and they are held once. A file is opened once for the tab: a cut of forty segments from one recording has forty sources, and they share the one parsed file and its reader cache, each holding only its own decoder and canvases; the voices and the filmstrip's readers join the same open file. Under that, every read of a cloud file goes through one chunk memory, and a reader keeps for itself only the few megabytes its own walk is standing on. A file addressed by the page's own route, while it has no signed link, reads through the same store, since the route redirects to the object the store keys on; a cut shared with someone reads through the share's route the same way, so a viewer holds the file once the way its owner does.
-
-The ceiling is a model. The memory that runs a machine out is memory a page cannot see — decoded frames sit inside the platform's decoder, canvas backing sits in the GPU process, and the browser reports the size of neither — so the counting happens at the allocation sites, where the sizes are known exactly. What the browser does report is roughly how much memory the machine has, which is enough to tell a laptop from a workstation.
-
-An editor left in a background tab lets go of the expensive part: every decoder and the canvases behind them, the element pictures, the mattes, and the sound decoded ahead. Standing a source down is something the frame loop does, and a hidden tab is given almost no frames, so that memory would sit out of the machine's reach for as long as the person is away doing something else. The canvas keeps showing the frame it last painted, and coming back costs one keyframe seek per visible clip. The timeline's own strips stay, because they are what the person sees the moment the tab is theirs again.
-
-Two things follow from that. A cut is a read from a different ring rather than a handover between players, so crossing a join costs nothing and needs no clock to change hands; and the picture answers a moved playhead inside a frame, because the answer was already in memory. Sound is scheduled on one audio context and its clock is what playback runs on — the picture follows the sound rather than the two chasing each other. When a browser holds that context suspended, as it does until the page has been interacted with, wall time carries the cut and the audio clock is picked up once it agrees — and when the clock jumps instead of agreeing, a context resumed late or an output device switched mid-play, every scheduled window restarts where the clock now stands rather than playing out the moment it was placed for. A context that stops running mid-play is asked back every frame, because the picture would otherwise carry on against wall time over a cut gone silent.
-
-Each voice reads its file the way the picture's readers do: a walk held open, pulled forward about a second at a time. Reading in order is what keeps sound and picture in the same part of the file. A voice asking for a long span at once is asking for the whole interleaved stretch that span is scattered through — twenty seconds of sound is a hundred megabytes of a phone recording — so over a link that merely keeps up with playback its every read arrives after the moment it was for, and a cut that sounded for its first stretch plays out in silence. The rule about endings is the picture's rule, for the same reason: a walk reports the same ending whether it read the track's last sample or gave up on it, and an ending believed a few seconds into a long clip plays the rest of the cut in silence while the picture reads happily past it. So an ending short of the clip is treated as a walk that failed and another goes after the sound it did not reach, and a walk that gets no further than the one before it has found where the track really stops — which is often a fraction before the picture does. Nothing else about a read is final either. A read that fails, comes back empty, or stops answering leaves the voice waiting a moment and asking again, quickly at first and then on a slow cadence for as long as the failure holds, and it asks the link keeper for a fresh URL on the way — the same footing the picture's readers are on, which is what stops a blip from silencing a clip whose picture healed seconds later. Opening a walk is nearly all a walk costs — a container read out of a hundred megabytes over a link — so a voice holding sound for a moment that has gone by re-aims the reader it already has, the way the picture's readers are re-aimed. Giving the file up there would start the open again a second behind where it just was, and again after that: the voice pays the open for the rest of the play and never once catches the clock, which is the same silence arrived at from the other direction. The reader moves for a new address too — a library clip copied into the project behind the editor moves off the URL it arrived on mid-play — and the sound already read plays out across the change. A reader is opened before it is needed, on the same footing as the picture's: a clip under a parked playhead has had a decoder open on it all along, which is why the picture starts on the frame, and the sound now opens its file and takes one read where the playhead stands rather than doing all of it once the clock is already running. That is what a play straight after a seek used to wait seconds for. The first window a standing start schedules — a play begun, a seek landed, a picture-hold released — is a short one, so the sound joins the picture's first frame and the windows behind it extend the lead by whole groups; and a play held for a clip still opening primes its sound during the hold, so the picture and the sound open together and the release finds both ready.
-
-What is on screen at a given instant is still a pure function of the document and a time, and it is still the same function an export asks. The preview reaches an instant by playing toward it and an export by jumping straight there; because both draw through one compositor from one plan, the file cannot quietly disagree with what was watched.
-
-The stage sits under a camera. The picture opens fitted to its pane, and that fit is 100%: from there a pinch or ⌘-scroll zooms about the cursor, a plain scroll pans, and a drag on the empty room around the picture — or a middle-button drag anywhere — moves the view. A drag on the picture belongs to the picture, whatever is drawn over it: a title, a shape, a sticker, a caption all hand the gesture down to whatever the footage itself would do with it — move the view, or move the selected clip. Selection is what arms something to be moved; a press that never travels selects what it landed on, and the drag after that moves it. The camera holds its place on screen when a panel opens or the selection changes shape; the pan absorbs the layout's move, so the picture stays where the eye left it. A round control in the pane's top-right corner appears while the camera moves and lingers a moment after, opening into the zoom level, a step in each direction, and a Reset that refits.
-
-The playhead lives apart from the document. It moves sixty times a second and the document does not, so a moved playhead wakes the surfaces that draw it and nothing else — and a paused editor with nothing changing schedules no frames at all.
-
-Whether any of this is true of a given build is measured rather than assumed: `npm run eval:cut-perf` drives a real editor in a real browser against fixture montages and reports whether the picture answers a moved playhead on the next frame painted (counted in frames, so a sixty-hertz and a hundred-and-twenty-hertz display read the same), whether any frame crossing a cut was the wrong one, and whether a fast-cut montage replayed for minutes still holds the picture to the clock the way its first pass did. Its committed report is the baseline a change is diffed against.
-
-The machine it measures on is part of the measurement. A developer desktop has decode slots to spare and never falls behind, so the preview's caps never bind there and a change that would ruin a laptop reads as a clean sheet. `--machine` puts the page on a smaller one: it takes away hardware decode slots, so decoders past the limit deliver their frames late the way software decoding does, it slows the main thread to a fraction of this one, and it paces the media over a link the way a cloud project reads it. That last one is its own axis: a reader short of bytes and a reader short of decode both show a picture drifting behind the sound, each takes its own fix, and `--net` and `--rtt` open the link up on a failing case to say which it was. The fixtures cover the shape that binding actually happens in — one long clip on the timeline, read the way a cloud project reads it, played cold and played again after the editor has been closed and reopened. `npm run eval:cut-perf-lowend` is the profile the reports come from. The nightly run holds the scrub cases on the `ci` profile, a runner with no video decoder at all: it starts Chrome with hardware decode off and budgets a jump and a drag's tail for what a software decoder costs, and running that profile on a desktop reproduces a nightly failure. What the gates ask there is what a viewer would ask — did the frames arrive, did the picture hitch a quarter second behind the sound, and was the last pass as good as the first — and each machine has its own budget for those, because a number that is honest on a desktop is fantasy on a fifteen-watt laptop.
-
-A profile it cannot model is the one someone is actually editing on, so the preview can report on itself. Settings carries a diagnostics switch, off until an account turns it on; with it on, the engine counts what its played frames did — how many arrived late, how far the picture sat behind its own sound, what every cache was holding and how near that came to this machine's ceiling, how long the main thread was blocked — and sends one summary per half minute of playback, alongside what the machine brought: cores, memory, the size it is decoding at, and which codecs it decodes in hardware. The record of a blocked frame carries the memory total as well, which is what separates a machine short of processor from one that stopped for a page fault — the two are identical from outside, and the second is the one a smaller ceiling fixes. That last one separates two stutters that look identical from outside: a machine spending its time after the decoder, and one whose decoder refused the footage and put every stream on the CPU. A summary also carries how many walks the window started and the worst wait for a single frame off one, which separates the third: a reader whose bytes had not arrived waits seconds on one frame and nothing on the next, where a decoder that is merely slow answers every one of them in tens of milliseconds. The summaries are numbers; no frame, no sound, and nothing naming the project leaves the browser.
-
-## Color grading
-
-A clip's color is one field on the clip: an optional preset underneath and manual adjustments on top — sliders, tone curves, color wheels, per-hue bands. Every part is absent when neutral, so an untouched clip carries nothing, and the preset's intensity scales its parameters toward neutral so half-strength means half the move, never a crossfade through gray.
-
-Presets are JSON documents beside the effects kit, one file per category, and the kit's parser is the only doorway that data has into the engine — the shipped catalog loads through the same validation a user-imported or shared grade will use later. Every shipped recipe is an original design on this model.
-
-Every preset is measured, not eyeballed, in two tiers. The first is safety, held to the references a colorist grades against: the ColorChecker chart pushed through each preset's real lookup table, skin kept on the vectorscope's skin-tone line and under a saturation ceiling, the gray ramp monotonic, shadow detail preserved, and any white-balance cast kept inside warming-gel range.
-
-The second tier is identity. Every preset names something real — a film stock, a lab process, a lighting condition — and has to measure like the thing it names, so each one declares its referent alongside the signature that referent leaves on a chart. A bleach bypass has to actually drain color while contrast climbs; an expired stock has to show the crossover uneven dye decay produces; a sepia has to collapse the frame onto one tone rather than tinting surviving color. Presets also have to differ from each other: two recipes that land on the chart together are one look wearing two names, which is how a pair of near-duplicates can otherwise sit on the shelf unnoticed. Both tiers walk the catalog itself, so a preset added to the JSON must declare what it is and is held to the same standard without being registered anywhere.
-
-Skin protection is one rule rather than a habit each stage has to keep. A preset marked to protect skin applies its tone in full and then blends the color it moved back toward the pixel's own, scaled to wherever the tone landed — so hue and saturation survive while brightness follows the grade. Because the rule sits at the end of a layer, a stage added later cannot leak color onto faces by forgetting to damp itself.
-
-One transform renders everywhere. Grades that stay within the original scalar sliders keep the long-standing cheap path — a CSS filter string in the canvas and a lutrgb/hue chain in ffmpeg, derived from the same numbers — and saved grades from before the extension render byte-for-byte as they always did. Anything richer compiles to a single 3D lookup table sampled from one pure function: ffmpeg applies it as a .cube file through lut3d, the browser preview applies it in a WebGL pass, and a headless export applies it on the CPU, all three interpolating the same way. The timeline filmstrip alone approximates, carrying the scalar part of the grade as CSS and stating so in code; the preview and every export render the whole grade.
-
-The assistant grades through the same model: tools for presets, sliders, curves, wheels and hue bands, a stats reader so it grades from measured numbers, and a matcher that computes a grade carrying one shot onto a reference image or neighboring clip by quantile-mapping the channels into curves.
-
-## Cloud projects
-
-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, 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. Folders file into folders on every shelf: a tile drags onto another tile or up onto a crumb, every level shows the shelf, the grid and New folder the top does, a folder nests only beside itself on its own shelf, and deleting one brings what it held up a level. 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 the user's one shelf across places: every residency keeps a library, and the Library lists them at once 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 browser project can pull one out of the cloud. A shelf that lives in the page holds its media in the same origin-private storage its projects use, and a link imported onto it rides the cloud worker — a page can't fetch a video off a YouTube link — with the bytes coming back down and the staged cloud copy dropped after. The Mac's shelf takes that same route as a second try: sites refuse fetches on the strength of the tool making them, so a link the engine's own tools can't bring back is fetched by the worker and lands here anyway. Each shelf 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. Library folders nest the way project folders do, on the Library page and in the editor's library panel alike. Adding to a project is the one crossing: on the project's own shelf the server copies the file without the bytes leaving it — on the Mac as a clone, landed before the clip is placed — and off it the browser carries them down and back up. Filing an item into a folder on another shelf crosses the same way — the bytes come down and go back up, a file with its cover and a template with its own media, and the copy left behind comes off.
-
-The phone feeds the cloud shelf. Clips recorded in the iOS app upload themselves to it, marked as camera footage; that marker gives the desktop its Camera Roll — a tab of phone clips kept out of the main Library grid, and a locked Camera Roll folder in the editor's library panel so the footage drops into any project. A recording arrives named after the clock it was shot on, which says nothing about which clip it is, so each one is titled from itself: the page reads the opening of the clip and one frame, a light model names it in a few words, and the shelf keeps that answer, so the work happens once and the card, the viewer and the assistant all read the same title. The tile shows the title with the date under it, and hands over the whole line when the tile is too narrow to hold it. The file's own name stays what a prompt's reference resolves against. Inspiration saved on the phone lands in an Inspiration folder on the same shelf, links riding the same worker import every shelf uses. What the phone put on the shelf it also mirrors: deleting a clip from the Camera Roll or the Library tombstones it, and the phone deletes its own copy on the next pass, so the roll on the phone and the roll at the desk stay one set. Notes are edited on both sides: the phone and the desktop's Notes tab work the same set, the newer edit winning, deletes carrying across. Notes file into folders of their own, on the shelf's folder table, and folders file into folders: the desktop files them by dragging onto the same folder tiles the Library uses — a folder tile drags too, onto another tile or back out to a crumb — the phone by dragging a card or a row onto a folder row, and every level shows the same shelf, grid and New folder the top does, and nothing above it. A folder made on either side is on the other by the next pass, and deleting one brings what it held up a level. Every request from the app carries a client marker, the server remembers accounts it has seen it from, and only those accounts get the phone tabs — a desktop-only account's sidebar never changes. The app's own guide covers the phone side: [The iOS App](../ios-app.md).
-
-Some of what the Library holds is lent. Most items are copied when they are used — a clip's bytes become the project's own — but a font is pointed at: every title set in it names it, and the file stays on the shelf where every project can reach it. Lent items follow three rules. They are identified by their bytes, so the same file on two shelves is one entry in the menu and one id in a document. A new one lands on the shelf every surface can read, whenever it is small and the account has room. And a project moving to the cloud takes what it points at with it, so a title keeps its typeface when it starts rendering there — since the id is the bytes, not a word of the document changes. Fonts are the first of these; a .ttf, .otf, .woff or .woff2 dropped on the Library is filed in folders, deleted, and counted against storage like anything else, and every project offers it for titles and captions. A font download arrives as a zip, so the zip is droppable: the faces come out of it and the licence text stays behind, and a family of eighteen weights becomes a single entry. The file is checked by installing it through the renderer's font seam before any bytes move, so what lands is what a preview and an export can draw with, and the family name comes off the font's own metadata. That same moment draws the specimen the shelf keeps as the file's cover, so a font card shows the alphabet in its own face whether or not the page looking at it has that face installed. A new account starts with an empty Fonts folder to say the shelf takes them; it is an ordinary folder and can be deleted. A render job reaches the cloud shelf alone, which is what those rules are for. A font filed into a folder belongs to that folder's shelf like anything else, and a full account keeps its font on the shelf it was working from: it draws in the tab, is marked in the font menu as living on this device, and falls back to the base face in a render job. A title set in a font that is later deleted falls back too, so nothing in a document has to be rewritten.
-
-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. 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. Every asset that lands at rest — a drop, a generation, a freeze frame, a conversion, a template copy — takes its address from one resolver: this browser's own copy when the store holds one, else a signed link on the media origin, else the route URL. A blob URL that fails to read mid-session is re-resolved through the same resolver and the store swap repoints every reader, so a new kind of asset inherits both the address and the healing.
-
-The cache runs the other way too: opening a cloud project pulls in the assets this browser is missing, nearest timeline use first. Video caches as fixed-size chunks keyed to the stored object: playback serves the pieces it holds from disk and fetches the rest as byte ranges, so scrubbing warms the exact regions being worked, a half-fetched file keeps every chunk that landed, and the cache carries across the hourly re-signing of media links. Images and audio stream in whole and swap onto local bytes as they land. When the origin's storage quota runs short, chunked video goes first — a lost chunk costs one ranged re-fetch — then the least recently opened projects' whole-file caches; pinned uploads and browser-resident projects are never evicted.
-
-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.
-
-A cloud project can be shared read-only, Google-Docs style: the editor's Share dialog invites specific emails (viewers sign in) or opens the link to anyone (no sign-in), and switches opt extra surfaces in — chat, media, AI generations, subtitles, details — on top of the always-shared preview and timeline. The share row's id is the link token, so revoking deletes the link. Viewers ride a third backend driver against `/api/cut-shared/<token>/*`, a deliberately public API surface (the one exception to session auth on the cloud side): the server resolves access per request, filters the doc to the shared surfaces before it leaves, and refuses media outside that filter, so hiding is enforced by the backend rather than the client. A public share's reads are cached at the edge for a lifetime that tracks how long the owner has been idle — a doc saved seconds ago is served near-live, one untouched for an hour is served from cache for minutes — and the same number is handed back as the viewer's poll interval, so a link a crowd opens costs a handful of origin requests rather than one per viewer per tick. A restricted share's reads depend on the viewer's session, so they are never cached. A shared project's media is served from Cloudflare's edge rather than presigned against R2's S3 endpoint, which nothing caches: a Worker holding a private bucket binding checks a short token the hosted API mints, then answers from cache keyed on the object alone. Dropping the token from the cache key is what makes the token affordable to keep short — every viewer and every re-mint share one cached copy — and a short token is what makes unsharing mean something, since a presigned URL is a bearer credential nothing can withdraw before it expires. Owner-side editing still presigns R2 directly, where the URLs are minted on fixed windows so a browser can reuse bytes across reloads. A shared link unfurls with the project's own card: the render worker derives a first-frame still and a five-second animation from the opening of the cut, the page's metadata points at them through a URL carrying the doc version, and a project with no card yet gets a drawn one. Viewers poll the doc version on an interval the server picks — shared views trail live edits, they don't stream them — and a "Copy project" action duplicates everything the share exposes — the filtered doc, its media, and the chat threads when chat is shared — server-side into the viewer's own account and quota. Copies queue rather than run in the request: each request writes a job row and publishes it to a Cloudflare Queue whose serial consumer executes one copy at a time, so a burst of copy requests can't stampede storage; the client polls the job for the outcome. An owner duplicating their own cloud project from the dashboard rides the same queue. A cloud project's export renders in the browser. The tab already draws the whole cut for the preview, so it can draw it again frame by frame into an MP4 and upload the finished file — no round trip that pulls the media back out of storage into a container, no waiting behind someone else's render, and a file that matches the preview because the same compositor drew both. A browser that can't carry the render — no scratch storage, no encoder at the requested frame size — sends it to the worker, and so does everything the editor renders on its own behalf: hover-preview proxies, share cards, streaming ladders, and URL imports. That worker is a pool of containers (`site/src/cut/worker/`) that claim job rows from Postgres, reuse the engine's exact ffmpeg pipeline against R2, and report progress back through the rows the client polls. The hosted API wakes as many replicas as there are jobs waiting, and a replica with nothing left to claim exits within a minute, so the pool bills for renders and little else. Each replica takes one job at a time, so a render has the whole machine to itself, and the queue is claimed by what someone is watching first: an export or a URL import goes ahead of the background artwork. The artwork waits for a lull too — a project's hover proxy and share card rebuild when the editor closes or the tab goes to the background, so a session of editing spends the pool on the renders the user asked for. Transcription and mic dictation prefer this Mac: with the app running they use on-device speech even for a cloud project, and fall back to a hosted, credit-metered route — a Gemini speech model reading word timings off browser-rendered audio — when it isn't. That split between where a project's data lives and where its work runs is its own guide: [Local compute](local-compute.md). The assistant offers its Gemini models (which already run entirely in the page); the Claude/Codex CLI providers stay app-only because they are the user's local logins.
-
-A share link opened on a phone plays rather than edits. The editor composites a project live — a video decoder per clip, painted onto a canvas — which is the right design on a desktop and an impossible one on a phone, where the decoders alone exhaust what a tab is given. So below the width the editor needs, the share serves a player instead: the cut as a single adaptive stream with the platform's own controls, and whichever surfaces the share opted in — chat, media, subtitles, details — as sheets that rise over it. The desktop share is untouched. The choice is made in code rather than in styling, because hiding the editor with a class would still have mounted it and started every decode.
-
-That stream is an adaptive ladder the render worker builds and stores in R2 beside the project's media. A single flattened file is the wrong answer once a cut can run long or land in 4K, for two reasons. The edge declines to cache any object past half a gigabyte, so the file that most needs caching is exactly the one that never gets it, while segments of a few megabytes always do. And one bitrate cannot serve both a phone on a weak cellular link and a desktop on a 4K panel; a ladder lets the player choose, and change its mind mid-watch. Rungs are capped at the source so nothing is upscaled, and the low ones publish first, which is what makes a share watchable well before the slowest rung finishes. Each render writes a new version of the tree, so a viewer already watching keeps playing off the old one while the next is built, and the superseded version is swept a day later. Access is the same short-token scheme as the rest of a share's media, with one difference: the token covers the whole tree and rides in the path, because a player reaches segments by following relative links out of a playlist and a query string does not survive that hop.
-
-A ladder is the one thing in the bucket that is neither the user's media nor charged to them. It is a delivery format the product picked, rebuilt whenever a shared project settles, and the footage it was built from is already paid for — so it carries no media rows and never counts against a storage quota. That is also why it needs an index of its own: with no rows, a tree nothing points at is a leak nothing can find. So a Workers KV record, not the database, tracks every version a project has ever *started* — claimed before the first byte uploads, so a render that dies partway still leaves a trail — along with the one it serves and the ones it has replaced, each stamped with when it was replaced. The sweep runs off those stamps: a replaced ladder gets a day before its segments go, counted from the moment it stopped being current rather than from whenever its bytes were written, and a claim whose render never finished is collected once it is too old to still be running. Work scales with the garbage rather than the project count, so no project waits behind a fixed number of others.
-
-Rebuilding waits for the same lull the hover proxy does — the editor closing, or the tab going to the background — because unlike the five-second card it re-encodes the whole cut once per rung, and an interaction like opening a dialog is the wrong thing to hang that on. At most one ladder renders while one waits, and the waiting one is replaced rather than kept, so an edit made mid-render is never the thing that gets dropped.
-
-What a viewer sees is answered in their favour: until a ladder exists, and while one is still rendering, the phone plays the project's flattened proxy and swaps in the real stream when it appears — though never mid-playback, since replacing a video someone is watching would restart the cut at zero. So a link shared before any of this existed still plays.
-
-Both renders are subject to the same content boundary as the doc. Captions are burned into pixels, which no later filter can undo, so a share that hides Subtitles is rendered without them and the record remembers what each ladder actually burned in; if the owner turns Subtitles off afterwards, the existing ladder is withheld rather than served, and the next render replaces it.
-
-## One API surface, one router
-
-Every Donkey Cut API route is a framework-free handler (web-standard request in, response out) registered once in a route table (`matchCutRoute`), namespaced under `/api/cut/*` to keep it clear of Donkey's own APIs. Both surfaces dispatch through that one table: the packaged engine mounts it directly, and the Next dev server reaches it through a single optional-catch-all route (`/api/cut/[[...slug]]`). They are the same router — static-over-dynamic precedence, HEAD, and 405s behave identically, and there is nowhere for the two to drift. The hosted 404 is applied once, in that shared dispatch.
-
-Local data belongs to the Mac user: every account that signs in on the Mac sees the same projects and library. The page still appends the signed-in account id to engine URLs because engines released before 2026-08 refuse requests without it; the current dispatch ignores it.
-
-## The engine
-
-The engine is a single compiled binary built from the site's `cut/` code and version-locked to the app: the app's dev run script and release packaging build and bundle it automatically (no separate step), and the app stamps its own release version into the engine's environment, so updates ride app releases. The Donkey app spawns it at launch — regardless of sign-in, since Donkey Cut is free and standalone — restarts it with backoff if it dies, and stops it on quit. The engine's lifetime is tied to the app process: the engine watches the pid that spawned it and exits when that process is gone, and at launch the app replaces an engine on the port stamped with a different version, so engine fixes always ship with the app update. An engine matching the app's version (another instance) or a developer-run "dev" engine is left alone. Its data lives in the user's Movies folder (`~/Movies/DonkeyCut`), shared by every Donkey account that signs in on the Mac, so projects and exports are visible in Finder and openable by other apps; each project's folder is named after the project and follows renames. Its logs live under the user's Logs folder.
-
-Because a GUI-spawned process inherits a bare PATH, the engine rebuilds it: tools shipped beside the engine binary first (they version with the app), then the app's bundled tools (bundled tool always wins), then the user's login-shell PATH and common install dirs. That is how it finds the speech tool, ffmpeg, and the user's `claude` and `codex`.
-
-## Boundary with Donkey
-
-| Concern | Donkey | Donkey Cut |
-| --- | --- | --- |
-| 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 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; browser and cloud projects need no install |
-
-The only shared code runs one way: Donkey 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 Donkey Cut. Its database models live in their own schema file (`site/prisma/Cut.prisma`) and carry plain user ids.
-
-## Local resources
-
-Missing tools disable the matching feature; they never affect the rest of the site or app.
-
-| Feature | Needs |
-| --- | --- |
-| Encode, probe, thumbnails | the app's bundled `ffmpeg`/`ffprobe` |
-| Transcription, subtitles, and voice dictation in prompt inputs (assistant, image/video/audio generation) | prebuilt `cut-stt` shipped beside the engine binary (the plain dev server falls back to compiling it); dictation streams live mic audio through its `--live` mode |
-| AI assistant | the user's own `claude` and `codex` CLI logins; its Gemini models use a Donkey sign-in and credits instead |
-| AI generation (image / video / voiceover) | a Donkey sign-in and credits |
-| Projects, library, exports | writable local disk (the user's Movies folder when run as the engine) |
+The 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.
-## The assistant's knowledge
+## The export
-The AI assistant knows the editor through three surfaces: the catalog — tool definitions, the skills library, and the system prompt, shared by every provider — the browser-side tool implementations that run those tools against the live editor store, and the per-turn context snapshot sent with each message. The catalog lives with the engine's AI code; the implementations and snapshot live with the editor client code. How a chat turn actually runs — providers, the tool bridge, context budgets — is its own guide: [Donkey Cut's AI Assistant](ai-assistant.md).
+An export is the preview drawn again frame by frame into an MP4 by the same compositor and mixer, so the file matches what the person saw. The finished file goes to the project's home: the app's project folder for a Mac project, storage for a cloud one, the page's store for a browser one. A browser that cannot carry the render hands it to the machine behind the project, and the ffmpeg pipeline stays for ProRes, headless renders, share cards, and streaming ladders. The local-compute guide covers where each kind of work runs.
-**Teach the assistant in the same change.** When an editor feature lands, changes, or goes away, update those surfaces with it — usually by adding, updating, or deleting the matching tools and skills, and by extending the context snapshot when the feature adds user-visible state. A feature the catalog omits is invisible to the assistant, and a stale tool or skill is worse: the assistant confidently acts on behavior that no longer exists.
+## Sharing
-**Everything the user can point at is referenceable.** Every entity the editor lets a user select or create — a clip, a keyframe, a mask, a sticker, a title, an effect, a generated asset, a library item, a phone recording — carries a stable id and joins the editor's one reference model. The ref is how an entity leaves its home surface: drag it onto a drop zone, copy it with ⌘C and paste it into the chat composer, or type its @handle in a prompt, and chat resolves it back to the live entity — "tighten @c2" reaches the real clip and the tools that edit it.
+A cloud project can be shared read-only by link, with the owner choosing which surfaces a viewer sees. The server filters the doc and its media to that set before anything leaves, and a viewer can copy the shared project into their own account.
-The catalogs are referenceable too: an effect, a transition style or a shape copied out of its panel pastes as a mention that carries the catalog id and the tool that places it, so "put a @"Cross fade transition" on that cut" names the exact treatment the user pointed at.
+## The assistant
-⌘C is one keystroke with one implementation behind it. A card or tile says what it stands for, the copy handler picks whatever the pointer is on (falling back to what has focus), and it writes that ref's mention token — so what a tile's copy button copies and what the keystroke copies are the same string, on the library page, in the editor's panels, and in chat. When a feature adds a new kind of entity, wire its ref in the same change: a scope and handle among the mention candidates, copy and drag affordances where the entity renders, and tools that accept its id. An entity without a ref is invisible to chat.
+The chat drives everything the editor can do through typed tools, and every tool's schema and prompt text derive from the same constants the UI uses, so the catalog stays true. The assistant guide covers the harness, the tools, and the evals that hold the line.
## Where it lives
-The editor, its handlers, and the engine entry sit under the site app's `cut/` folder; host routing, the hosted API shut-off, and the CORS grant live in the site's proxy file (`src/proxy.ts`, the Next 16 successor to middleware). The app-side supervisor lives with the Donkey runtime code, and the packaging scripts stage the engine binary into the app bundle.
+The editor, its stores, and the backend seam live under the site's `cut` folder; the engine and worker share its server code; the Mac app is a menu bar shell that ships the engine and screen recording.