Skip to content

Open source CapCut alternative.

TypeScript

docs: no trailing caveats, and the guide covers text-driven cuts

David Leababd3d413bf
diff --git a/AGENTS.md b/AGENTS.md
index df038558..bd2a4768 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -38,6 +38,7 @@ Every Cut change has to hold on all four surfaces, and the plan for it says how:
- When writing or editing any engineering doc under `docs/`, follow `docs/guides/eng-doc-style.md`.
- Write straight up — in prompts, docs, commits, code comments, summaries, and UI copy. State what a thing is, once, and stop. Never frame it against what it is not: no "X, not Y", no "X rather than Y", no "instead of Z", no "…, which is exactly what not to do". Cut filler.
- Keep replies short and action-oriented. For implementation questions, give the recommendation first, then one to three short bullets on why; when the answer is obvious, just say what to do. Skip long explanations, caveats, and "one last thing" sections; flag a real blocker or risk with "One issue:" and explain it briefly.
+- Never end a reply with a caveat, limit, bound, or "worth knowing" addendum. A problem gets fixed in the same turn it is found; anything that changes what the user does belongs in the body of the summary, said once.
- Make the decision and do it. Implement the obvious next step; never end with "if you want, I can…" or ask the user to say the word. Save questions for genuine scope forks and destructive actions.
- Update guides in `docs/guides/` only for major features or durable supported-behavior changes. Do not update guide docs for small styling tweaks, layout adjustments, copy changes, or implementation-only refactors.
- Keep guides explanatory. They should teach what the system is, how it works, and which boundaries matter; do not turn guides into feature inventories, implementation logs, duplicated code, or long file lists.
diff --git a/CLAUDE.md b/CLAUDE.md
index df038558..bd2a4768 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -38,6 +38,7 @@ Every Cut change has to hold on all four surfaces, and the plan for it says how:
- When writing or editing any engineering doc under `docs/`, follow `docs/guides/eng-doc-style.md`.
- Write straight up — in prompts, docs, commits, code comments, summaries, and UI copy. State what a thing is, once, and stop. Never frame it against what it is not: no "X, not Y", no "X rather than Y", no "instead of Z", no "…, which is exactly what not to do". Cut filler.
- Keep replies short and action-oriented. For implementation questions, give the recommendation first, then one to three short bullets on why; when the answer is obvious, just say what to do. Skip long explanations, caveats, and "one last thing" sections; flag a real blocker or risk with "One issue:" and explain it briefly.
+- Never end a reply with a caveat, limit, bound, or "worth knowing" addendum. A problem gets fixed in the same turn it is found; anything that changes what the user does belongs in the body of the summary, said once.
- Make the decision and do it. Implement the obvious next step; never end with "if you want, I can…" or ask the user to say the word. Save questions for genuine scope forks and destructive actions.
- Update guides in `docs/guides/` only for major features or durable supported-behavior changes. Do not update guide docs for small styling tweaks, layout adjustments, copy changes, or implementation-only refactors.
- Keep guides explanatory. They should teach what the system is, how it works, and which boundaries matter; do not turn guides into feature inventories, implementation logs, duplicated code, or long file lists.
diff --git a/docs/guides/cut/README.md b/docs/guides/cut/README.md
index 84c97057..4ecbcdf6 100644
--- a/docs/guides/cut/README.md
+++ b/docs/guides/cut/README.md
@@ -28,6 +28,10 @@ browser (the editor)
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.
+
+**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 that decides the frame color, the card colors it cycles line to line, the type, and how each line arrives. The looks live in one registry the tools and the skill 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 and can light each word as it is sung, or elements, which give each line its own card, color and motion. 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.
+
## 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.