Skip to content

The truly free, open-source, local-first, cross-platform CapCut replacement. Scriptable through a JSON-RPC API & MCP.

docs: drop the decision logs

Jareer36168accaad2
diff --git a/desktop/docs/decisions/0001-tauri-over-electron.md b/desktop/docs/decisions/0001-tauri-over-electron.md
deleted file mode 100644
index 0357137f..00000000
--- a/desktop/docs/decisions/0001-tauri-over-electron.md
+++ /dev/null
@@ -1,27 +0,0 @@
-# 0001 - Tauri, not Electron
-
-## Decision
-The desktop shell is Tauri v2. React 19 and Tailwind v4 render the UI inside
-the platform's own webview.
-
-## Why
-- Electron ships a whole Chromium per app: ~150 MB of installer and ~100 MB of
- idle RSS before the editor has done anything. A video editor needs that
- memory for frame caches.
-- The host process is already Rust, so the engine links straight into it. With
- Electron the engine would sit behind a native module or a subprocess, and
- every frame would cross a language boundary that does not need to exist.
-- Tauri v2's IPC is a normal function call into Rust, not a second process.
-- The bundle is an ordinary signed installer on all three platforms.
-
-## What it costs
-- Three webview engines instead of one: WebView2 on Windows, WKWebView on
- macOS, WebKitGTK on Linux. Their CSS support differs at the edges, and
- WebKitGTK is the one that will surprise you.
-- No Node APIs in the front end. Anything touching the filesystem is a command.
-- A smaller ecosystem of desktop-specific examples to copy from.
-
-## What would change our mind
-Needing a Chromium-only capability in the UI itself. Note that this does *not*
-include video decode or GPU compositing - those belong to the engine, not the
-webview, so the webview's media support is close to irrelevant here.
diff --git a/desktop/docs/decisions/0002-the-hot-surfaces-are-not-the-dom.md b/desktop/docs/decisions/0002-the-hot-surfaces-are-not-the-dom.md
deleted file mode 100644
index 229daccb..00000000
--- a/desktop/docs/decisions/0002-the-hot-surfaces-are-not-the-dom.md
+++ /dev/null
@@ -1,43 +0,0 @@
-# 0002 - The timeline and the preview are not made of DOM
-
-## Decision
-The timeline is one `<canvas>` drawn from a `requestAnimationFrame` loop. The
-preview is a placeholder that will become a native GPU surface. Neither renders
-through React.
-
-> The preview half has moved twice since: 0007 promoted its approximation
-> layer to the plan of record, and 0009 streams the engine's true composite
-> against the transport clock. The native surface stays the endgame; those two
-> notes are the path to it.
-
-## Why
-- A real edit is thousands of clips, keyframes and waveform segments. As DOM
- nodes that is thousands of elements, restyled and re-laid-out on every scrub.
- React reconciliation is not the bottleneck there - layout and paint are, and
- no amount of memoisation avoids them.
-- One canvas is one draw call per frame, and the draw cost scales with what is
- *visible* rather than with what exists.
-- Frames must never be paced by React state. Playback is a clock, and the clock
- belongs to the engine.
-
-## Consequences
-- The canvas has to handle its own hit-testing, scrolling and device pixel
- ratio. That is real work, and it is why `Timeline.tsx` is longer than the
- panels around it.
-- Accessibility does not come free on a canvas. Keyboard editing operations
- must be first-class rather than an afterthought bolted onto mouse handlers.
-- The draw loop reads its inputs through a ref, so changing a prop never tears
- down and rebuilds the loop.
-
-## The preview specifically
-Pushing decoded frames to the webview over IPC means copying every frame into
-JSON-adjacent plumbing and through the browser compositor. That is acceptable
-for a still and hopeless at 60 fps. The plan is a native child window that the
-GPU compositor draws into directly, positioned to the preview element's
-bounding box - which is why that element keeps a strict aspect box even while
-it is empty.
-
-## What would change our mind
-Nothing for the timeline. For the preview, a zero-copy path from a GPU texture
-into the webview would remove the reason for a separate surface - worth
-re-checking when the `wgpu` backend lands.
diff --git a/desktop/docs/decisions/0003-csp.md b/desktop/docs/decisions/0003-csp.md
deleted file mode 100644
index a4598910..00000000
--- a/desktop/docs/decisions/0003-csp.md
+++ /dev/null
@@ -1,21 +0,0 @@
-# 0003 - Content Security Policy
-
-*Previously an open question; decided alongside the MPL-2.0 licensing pass.*
-
-## Decision
-Release builds run under a strict CSP set in `tauri.conf.json`: same-origin
-scripts only, media and images additionally allowed from the asset protocol
-plus `blob:`/`data:` (poster frames, waveform tiles, the grain overlay),
-inline styles permitted (component `style={{...}}` attributes are everywhere),
-and IPC endpoints named explicitly. Dev builds use a permissive `devCsp` so
-Vite's injected HMR scripts and websocket keep working.
-
-## What stays open
-The asset protocol scope is still `["**"]` - a video editor opens arbitrary
-user files, so a narrower scope would be a lie. The CSP now bounds what a
-compromised page could *do* with that reach (no foreign script, no exfil
-targets beyond IPC), which was the actual risk the old note deferred.
-
-## What would change our mind
-Rendering anything remote or user-authored beyond media files - templates, a
-plugin UI, an update notice - forces this list open again, item by item.
diff --git a/desktop/docs/decisions/0004-audio-preview-in-the-webview.md b/desktop/docs/decisions/0004-audio-preview-in-the-webview.md
deleted file mode 100644
index 2c85a508..00000000
--- a/desktop/docs/decisions/0004-audio-preview-in-the-webview.md
+++ /dev/null
@@ -1,68 +0,0 @@
-# 0004 - Audio and video preview run in the webview, for now
-
-> **Superseded in part by [0005](0005-audio-playback-in-the-engine.md)** and
-> **amended by [0007](0007-preview-approximation-layer.md):** the "No effects"
-> claim below no longer holds - the monitor now draws every effect and
-> transition live through an approximation layer, and 0007 makes that layer
-> the plan of record rather than scaffolding.
->
-> **Superseded in part by [0005](0005-audio-playback-in-the-engine.md):**
-> audio playback now lives in the engine - decoded, mixed and clocked in
-> `src-tauri/src/playback.rs`, with the UI following the engine's position
-> events. `lib/audio.ts` and the blob-URL fallback described below were
-> deleted with that move, exactly as "What replaces it" planned. What remains
-> true here is the *video* half: the monitor picture is still the webview's
-> `<video>` element, muted, until the engine can present frames.
-
-## Decision
-Playback preview - both the picture in the monitor and the sound - uses the
-webview's own `<video>` and `<audio>` elements, fed through Tauri's asset
-protocol. The engine is not involved.
-
-## Why
-Decision 0002 in this folder says the hot surfaces are not the DOM, and that is
-still the plan. But the engine cannot currently present a frame or open an
-output device, and an editor where pressing play does nothing is not an editor.
-The webview already has a demuxer, a decoder, a video output and an audio
-device. Using them is the difference between an editor you can use today and a
-screenshot.
-
-## What this is not
-It is a preview, not the program output. Specifically:
-
-- **No compositing.** The monitor shows the top-most video clip under the
- playhead and nothing else. Two stacked clips do not blend; the lower one is
- invisible.
-- **No mixing.** Overlapping audio clips play at once and will clip if loud.
- There is no gain staging, no pan, no fades.
-- **Sync is corrective, not sample-accurate.** Each element is nudged back into
- step when it drifts past a tolerance - 300 ms while playing, 30 ms while
- paused. A correction while playing is audible and visible.
-- **No effects.** Nothing in the render graph is applied.
-- **Scrubbing repositions audio, it does not scrub it.** There is no
- granular playback.
-- **Frame stepping is approximate.** The transport computes an exact frame
- boundary, but a media element seeks to the nearest frame *it* can decode.
-
-## The asset protocol, and the fallback
-`convertFileSrc` produces an `asset:` URL that streams and seeks, which is what
-you want. It requires `assetProtocol.enable` plus a scope in
-`tauri.conf.json`, and the scope is currently `["**"]` - a video editor opens
-arbitrary user files, so a narrower scope would be a lie. Note this widens what
-a compromised front end could read; it should be revisited alongside the CSP
-(decision 0003).
-
-If the protocol is unavailable for any reason, `lib/audio.ts` falls back to
-pulling the whole file through the `read_media_bytes` command and playing a
-blob URL. Slower and memory-hungry, but it degrades to working audio rather
-than to silence. The video path has no such fallback.
-
-## What replaces it
-The engine growing a presentation path: a frame cache and reader pool first
-(so scrubbing is possible at all), then a native surface for picture and a
-cpal-based mixer for sound. At that point the elements in `Preview.tsx` and
-`lib/audio.ts` are deleted outright rather than adapted - they share no code
-with what replaces them, which is the point of keeping them this small.
-
-## What would change our mind
-Nothing. This is scaffolding with a known demolition date.
diff --git a/desktop/docs/decisions/0005-audio-playback-in-the-engine.md b/desktop/docs/decisions/0005-audio-playback-in-the-engine.md
deleted file mode 100644
index 72d70a4c..00000000
--- a/desktop/docs/decisions/0005-audio-playback-in-the-engine.md
+++ /dev/null
@@ -1,51 +0,0 @@
-# 0005 - Audio playback lives in the engine
-
-## Decision
-
-All audible playback is decoded, mixed and clocked by the Rust host
-(`src-tauri/src/playback.rs`). The webview no longer owns any part of the
-audio path: it describes the audible clip set (`audio_set_clips`), drives the
-transport (`transport_play` / `transport_pause` / `transport_seek`), and
-follows the engine's `transport` position events. The monitor's `<video>`
-element is permanently muted - it is a picture surface, nothing more.
-
-## Why
-
-The webview mixer (decision 0004) was built on `HTMLMediaElement` routed
-through `createMediaElementSource`, corrected against a wall-clock transport.
-That design hit its ceiling in practice, not in theory: WebKit's
-element-through-graph pipeline drops out audibly even on a three-second file,
-corrective reseeks are audible clicks, filtered clips required rendering a
-whole WAV per slider adjustment, and there were three clocks - wall clock,
-media element, audio context - that could only ever agree approximately.
-
-The engine path has exactly one clock: the audio device's sample counter.
-
-## How it works
-
-- **Decode once, mix forever.** Each audible clip's source span is decoded by
- FFmpeg to raw 48 kHz stereo PCM, with the clip's filter chain and speed
- baked in using the same filters the exporter uses - preview and export
- cannot disagree. Volume and fades apply at mix time (the gain law mirrors
- `clipGainAt`), so gain edits never re-decode.
-- **Disk-backed, memory-mapped.** PCM lands in `<project>/cache/audio/` keyed
- by everything that changes the samples, and is memory-mapped rather than
- loaded - memory stays bounded on long material, and a reopened project
- replays instantly.
-- **A lock-free mix callback.** The cpal callback owns its state and drains a
- message channel; no locks are taken on the audio thread. Clip-set changes,
- play, pause and seek are messages.
-- **The clock flows outward.** The callback publishes its position; a 30 Hz
- event stream carries it to the UI, which interpolates on the wall clock
- between events. The UI never tells the engine what time it is while playing.
-
-## What this is not, yet
-
-- **Not video presentation.** The picture is still the muted webview element
- showing the top-most clip (decision 0004's video half stands). When the
- engine can decode and present frames, the same transport already drives it.
-- **Not streaming decode.** A clip's span is decoded whole before it joins
- the mix. New material is silent for the decode's duration (cached
- thereafter). Fine for editing; a capture monitor would need a ring buffer.
-- **Not an undo boundary.** The mixer is a pure function of the clip set it
- is sent; it holds no editing state at all.
diff --git a/desktop/docs/decisions/0006-multiple-timelines.md b/desktop/docs/decisions/0006-multiple-timelines.md
deleted file mode 100644
index d47f4dff..00000000
--- a/desktop/docs/decisions/0006-multiple-timelines.md
+++ /dev/null
@@ -1,34 +0,0 @@
-# 0006 - Multiple timelines, and the shelf that made them cheap
-
-> **Status: the exit was taken.** The shelf died with `lib/project.ts` when
-> the UI flipped onto the engine model (engine decision 0007), exactly as
-> planned below - no `shelved` map exists anywhere in the tree. What
-> survives of this note is the feature itself and the document-format
-> compatibility reasoning.
-
-## Decision
-A project holds several timelines (tabs above the timeline tray). In the
-frozen UI model the active timeline's tracks and clips stay at the top of the
-project - exactly where they always were - and inactive timelines park their
-content in a `shelved` map. Switching swaps content in and out at one seam.
-
-## Why the shelf
-Every edit operation and every reader (the canvas draw loop included) already
-worked on `project.tracks`/`project.clips`. The shelf made "which timeline am
-I editing" a fact decided in exactly one place, and no other code had to
-learn timelines exist. Thirty operations, zero changes.
-
-## Its known ugliness, and the exit
-Two homes for the same kind of data is a real smell - which is why the
-engine model (`wolfcut-project`, engine decision 0007) has **no shelf**: it
-stores a plain list of timelines and an active id, and operations address the
-active one. The shelf dies with `lib/project.ts` when the UI flips. The
-*document* format never had a shelf either; both models read and write the
-same `timelines` array.
-
-## Rules that hold either way
-- New timelines mint fresh track ids - reusing `T1..T4` across timelines
- would make duplicate-id repair orphan clips.
-- Deleting is confirmed (no undo existed when this shipped), floors at one
- timeline, and switches to a neighbour first when the active one dies.
-- Per-timeline playhead positions are window state, never saved.
diff --git a/desktop/docs/decisions/0007-preview-approximation-layer.md b/desktop/docs/decisions/0007-preview-approximation-layer.md
deleted file mode 100644
index 05ae0b8d..00000000
--- a/desktop/docs/decisions/0007-preview-approximation-layer.md
+++ /dev/null
@@ -1,43 +0,0 @@
-# 0007 - The monitor is an approximation layer, and that is the plan
-
-## Decision
-The webview monitor draws every effect and transition live, through per-effect
-preview mechanisms declared next to their FFmpeg chains in `lib/effects.ts`:
-CSS filters where CSS is faithful, SVG filters for matrices and convolutions,
-overlay layers (vignette, grain), a canvas redraw pass for geometry (pixelate,
-mirror, fisheye), deterministic playhead-clocked jitter (shake), and a second
-ghost video element for cross-fades. This layer is the **plan of record**, not
-scaffolding: it stays until the engine can present frames, and it is allowed
-to grow with the effect catalogue.
-
-## What this supersedes
-Decision 0004 called the monitor "scaffolding with a known demolition date."
-That story is dead - deliberately. Users evaluate an editor by what they see
-while editing, and "export only" effects tested as a retention killer. We
-traded single-renderer purity for a live monitor, with eyes open.
-
-## The drift risk, and its containment
-This is a second implementation of effect *appearance* - exactly the shape
-the architecture doctrine warns about. Containment:
-
-- Both renderings read the **same parameters** from the same clip; there is
- no preview-only knob anywhere.
-- The export chain is ground truth; the preview is documented as its
- approximation, never the reverse.
-- Every effect's chain and preview live in **one catalogue entry**, so adding
- or changing an effect touches one place.
-
-## Status: the retirement clock is running
-The first step of the engine presentation path shipped: the reader pool and
-frame cache exist (`wolfcut_media::pool`), and the paused monitor already shows
-the engine's true composite through `preview_frame` - real multi-track
-stacking and exact effect chains, with the approximation layer doing motion
-and the truth taking over on dwell. Streaming presentation against the
-transport clock has since begun where the approximation is wrong - stacked
-layers stream the true composite during playback (decision 0009). Full
-retirement still waits on the native surface.
-
-## What would change our mind
-The engine presentation path completing. When the engine can show its own
-frames at interactive rates, this layer retires bottom-up: composite first,
-effects last.
diff --git a/desktop/docs/decisions/0008-bundled-ffmpeg-and-releases.md b/desktop/docs/decisions/0008-bundled-ffmpeg-and-releases.md
deleted file mode 100644
index 976418b7..00000000
--- a/desktop/docs/decisions/0008-bundled-ffmpeg-and-releases.md
+++ /dev/null
@@ -1,28 +0,0 @@
-# 0008 - Releases bundle static FFmpeg, staged by CI
-
-## Decision
-Every packaged build ships its own `ffmpeg`/`ffprobe` pair in the app's
-resources; `build.rs` refuses a release build without them staged, because a
-packaged app without FFmpeg ships broken (no PATH to fall back on from
-Finder). CI stages the pair before building: BtbN static GPL builds on
-Windows, Martin Riedl static builds on macOS (arm64), both verified runnable
-and - on macOS - verified present and executable inside the bundle after
-packaging.
-
-Tags matching `v*` additionally publish the installers to a GitHub release;
-a hyphen in the tag marks a pre-release. The release body links
-`THIRD_PARTY_NOTICES.md` for the FFmpeg licensing story (the builds are GPL;
-we invoke, never link - see engine decisions 0002 and 0005).
-
-## Why download static builds instead of our trimmed workflow's output
-The `ffmpeg.yml` workflow builds a cut-down FFmpeg whose feature list is
-matched to exactly what the app invokes, but it is Windows-only today and its
-output must be staged by hand. Full static builds are ~100 MB heavier and
-always sufficient; correctness beats size for the alpha. When the trimmed
-build graduates (both platforms, automated staging), its enable-filter list
-already tracks the effect catalogue - keep it that way.
-
-## What would change our mind
-Nothing about bundling. The source of the binaries flips to the trimmed
-build when it covers both platforms; the guard in `build.rs` and the CI
-verification step stay regardless.
diff --git a/desktop/docs/decisions/0009-the-monitor-streams-the-true-frame.md b/desktop/docs/decisions/0009-the-monitor-streams-the-true-frame.md
deleted file mode 100644
index 842a69e8..00000000
--- a/desktop/docs/decisions/0009-the-monitor-streams-the-true-frame.md
+++ /dev/null
@@ -1,50 +0,0 @@
-# 0009 - The monitor streams the true frame where the approximation is wrong
-
-## Decision
-While the transport runs, the monitor pulls the engine's real composite -
-the exporter's own plan, pool and compositor via `preview_frame` - in a loop:
-request the frame at the transport's current position, present it, request
-the next the moment it lands. The loop engages only while **two or more
-visual layers** sit under the playhead; single-layer stretches keep the
-webview element's smooth playback, exactly as before. Streamed frames are
-capped at 640 px on the long edge; the paused dwell still re-fetches at 960
-the moment the transport stops.
-
-This is the presentation half that 0007 left open ("presenting pooled frames
-continuously against the transport clock"), built on the seam that already
-existed rather than a new one.
-
-## Why this shape
-- **Pull, not push.** The UI asks for one frame at the *current* position and
- does not ask again until it arrives. Backpressure is structural: a slow
- machine gets a lower rate, never a growing queue of stale frames, and the
- host's pool mutex serialises requests in order - which is also what makes
- consecutive requests warm roll-forwards instead of seeks.
-- **Only where the element is wrong.** The `<video>` element is exact for one
- layer and *cannot composite* a stack. Streaming everywhere would trade the
- common case's 60 fps smoothness for uniform choppiness; streaming only on
- stacks buys truth precisely where the approximation lies.
-- **The IPC budget holds.** 640-wide RGBA is ~1 MB a frame as an ArrayBuffer
- response; at the 15-30 fps the pool sustains for warm readers that is well
- inside what Tauri's IPC moves locally, and it degrades by rate, not by
- failure.
-
-## What this is not
-- **Not a vsync-locked presentation.** Frames display one fetch-latency
- behind the transport and at whatever rate decoding sustains. It is honest
- compositing, not final playback smoothness.
-- **Not the native surface.** Decision 0002's endgame - a GPU surface
- positioned to the frame box, engine-presented - still stands. When it
- arrives it replaces the *transport* of pixels (IPC → surface); the plan,
- pool and compositor this loop exercises are exactly what it will present
- from, which is why building this first is not throwaway.
-
-## What it costs
-- Streamed frames are visibly softer than the element (640 upscaled) and
- arrive a beat late. Acceptable on stacks, which previously showed
- something *wrong* rather than something soft.
-- A failed frame drops back to the approximation silently (logged host-side).
-
-## What would change our mind
-The native surface landing - at which point this loop is deleted, not
-adapted, the same clean demolition 0004 got.
diff --git a/desktop/docs/decisions/0010-the-app-installs-its-own-tools.md b/desktop/docs/decisions/0010-the-app-installs-its-own-tools.md
deleted file mode 100644
index 48f0d1d1..00000000
--- a/desktop/docs/decisions/0010-the-app-installs-its-own-tools.md
+++ /dev/null
@@ -1,36 +0,0 @@
-# 0010 - The app installs its own tools
-
-## Decision
-No feature may arrive as a setup chore. Every binary WolfCut needs ships
-inside the bundle or installs itself behind a single button with progress.
-Concretely, as of this note:
-
-- `whisper-cli` is staged at build like FFmpeg (`src-tauri/whisper/`,
- declared in the bundle's resources) and the release guard in `build.rs`
- refuses to build without it - a release that would ask the user to "locate
- whisper-cli" does not get to exist. CI builds it from source on macOS and
- Linux (cached by version) and takes the official binary on Windows.
-- Models remain downloads, because half a gigabyte of weights someone may
- never use does not belong in every installer - but the download is one
- button in Settings with a progress bar, which is the ceiling for what a
- feature may ask.
-- The Settings "Locate..." picker survives only as a dev-build escape hatch
- and is hidden whenever the bundled copy is in use.
-
-## Why
-The product's one-line promise is "install it and start cutting, no setup".
-The transcriber shipped as the opposite: a feature that greeted its user
-with a binary hunt. The user's words, verbatim, now policy: "never offload
-technical jobs to the user... At most, the user should do some basic config
-and have to click a 'Install' button, AT MOST."
-
-## What it costs
-- CI builds whisper.cpp once per platform per version bump (~4 minutes cold,
- then cached), and installers grow by a few megabytes.
-- The bundled copy is CPU/Metal only; exotic accelerators mean the escape
- hatch in a dev build.
-
-## What would change our mind
-Nothing about the principle. The mechanics move if the engine grows an
-audio-analysis seam (this note's staging follows the runner there, per the
-note in `transcribe.rs`).
diff --git a/engine/docs/decisions/0002-ffmpeg-over-a-pipe.md b/engine/docs/decisions/0002-ffmpeg-over-a-pipe.md
deleted file mode 100644
index 11e77668..00000000
--- a/engine/docs/decisions/0002-ffmpeg-over-a-pipe.md
+++ /dev/null
@@ -1,113 +0,0 @@
-# 0002 - FFmpeg as a subprocess now, FFI where the pipe cannot reach
-
-*Revised. The first version of this note claimed the pipe was fine until 4K
-playback. That was too generous: two of its limits are correctness problems,
-not performance ones, and they bite much earlier. The revised trigger is at the
-bottom.*
-
-## Decision
-Split by use case rather than picking one backend for everything.
-
-| Path | Backend | Status |
-|---|---|---|
-| Probe (`ffprobe`) | subprocess | Permanent. Runs once per import; robustness beats latency. |
-| Export / render | subprocess | Permanent unless throughput demands otherwise. |
-| Playback and scrubbing | **FFI** (`rusty_ffmpeg`) | Built and tested (`FfiDecoder`, `ffi` feature); not yet wired to the app. |
-
-The subprocess backends run everything today; the FFI decoder exists and waits
-on the frame cache and reader pool before playback can use it.
-
-## Why the subprocess path is genuinely right for probe and export
-- A crashing decoder on malformed input kills a child process, not the editor.
- We are parsing arbitrary user media; every serious video app has a CVE
- history in its demuxers.
-- The boundary is trivially debuggable: print the argv, paste it into a shell,
- read what FFmpeg says.
-- It builds anywhere `ffmpeg` is on `PATH`. No headers, no import libs, no
- bindgen, no `FFMPEG_DIR` to keep correct on every machine and CI runner
- forever. For a project maintained by one person intermittently, that is worth
- a great deal.
-
-## What the pipe cannot do, in order of severity
-
-1. **No timestamps.** `rawvideo` is a naked pixel stream with no PTS. Frame time
- is inferred from ordinal position, which is only true for constant-frame-rate
- material. Variable-frame-rate footage - screen recordings, phone video -
- silently desyncs. There is no way to fix this over a pipe; the information
- simply is not in the stream.
-2. **No frame-accurate seek.** `-ss` lands on a keyframe. Seeking to an exact
- frame means decode-from-keyframe-and-discard, per request, which the pipe
- cannot express.
-3. **No hardware decode into GPU textures.** Frames must land in system memory
- and be uploaded again, which defeats the point of the `wgpu` compositor.
-4. **Bandwidth.** 1080p60 RGBA is roughly 500 MB/s through the pipe.
-5. **A process spawn per media open.** A twenty-clip timeline being scrubbed
- means spawning and killing processes continuously.
-
-Items 1 and 2 are correctness. Items 3 to 5 are performance. That ordering is
-the whole reason this note was rewritten.
-
-## Containment
-Everything process-shaped hides behind `FrameSource` and `FrameSink` in
-`wolfcut-media`. The FFI backend is one new type implementing `FrameSource`;
-`wolfcut-core`, `wolfcut-render` and every caller stay untouched. The subprocess
-decoder stays as a fallback for formats the linked build was not compiled with.
-
-## What the FFI work will actually cost
-Not "add a crate". As of writing, the development machine has FFmpeg 8.1 from
-Chocolatey - binaries only, no `libavcodec/avcodec.h` and no import libs, and
-`pkg-config` has nothing FFmpeg-shaped to find. So the work is:
-
-- source a `-shared` dev build (gyan.dev) or `vcpkg install ffmpeg`,
-- set and document `FFMPEG_DIR`, and keep it true on every machine and CI runner,
-- get bindgen agreeing with the installed MSVC toolchain,
-- then write the wrapper: roughly 500 lines of `unsafe extern "C"` behind a safe
- `FrameSource`.
-
-Budget for the build plumbing, not the Rust. The Rust is the easy half.
-
-## Status: the FFI half now exists
-
-`wolfcut-media`'s `ffi` feature builds a linked decoder, `FfiDecoder`, which
-implements `FrameSource` and `SeekableSource`. Both correctness gaps above are
-closed in it and covered by `tests/ffi_decode.rs`:
-
-- real presentation timestamps, exact rationals straight from the container
-- frame-accurate seeking, verified by landing between keyframes
-
-It is **off by default and unused by the app.** The subprocess backend is still
-what runs, and probe and export are staying on it permanently.
-
-The seam held: adding it required one new type implementing an existing trait,
-one new trait for the capability the pipe genuinely lacks, and no change to
-`wolfcut-core`, `wolfcut-render`, or any caller.
-
-## Status: the reader pool exists too
-
-`wolfcut_media::pool` is the per-media reader pool with a byte-budgeted LRU
-frame cache that playback was waiting on: warm readers roll forward for near
-requests and seek for far ones - frame-accurately through `FfiDecoder` when
-the `ffi` feature is on, by respawn on the pipe otherwise. Its first two
-consumers are live: `wolfcut-cli render` (whose founding "deliberate shortcut"
-comment is finally deleted) and the host's `preview_frame` command, which
-composites the true frame for the paused monitor.
-
-## Status: streaming presentation has begun, and the FFI half is portable now
-
-The "what remains" below is half done: the desktop monitor now pulls pooled
-frames continuously against the transport clock wherever its approximation
-cannot composite - see desktop decision 0009 for the shape and its
-native-surface exit. And the FFI build plumbing this note budgeted for is
-paid on macOS too: the feature builds and passes every test against a
-package-manager FFmpeg via `FFMPEG_PKG_CONFIG_PATH` (after two portability
-fixes - a committed Windows vendor path, and `AVERROR(EAGAIN)` being -35,
-not -11, on macOS and the BSDs). It stays off in shipped builds; linking
-FFmpeg is the licensing tripwire decision 0005 records.
-
-## What would change our mind
-Nothing left to decide about *whether*. What remains is streaming playback -
-presenting pooled frames continuously against the transport clock rather than
-one paused frame at a time.
-
-Do **not** migrate probe or export along with it - for those, the tradeoff
-never flips.
diff --git a/engine/docs/decisions/0003-arena-handles-not-pointers.md b/engine/docs/decisions/0003-arena-handles-not-pointers.md
deleted file mode 100644
index 4a3fecbb..00000000
--- a/engine/docs/decisions/0003-arena-handles-not-pointers.md
+++ /dev/null
@@ -1,22 +0,0 @@
-# 0003 - Timeline and graph objects are arena handles, not `Rc<RefCell<..>>`
-
-## Decision
-Clips, tracks and graph nodes live in a `wolfcut_core::arena::Arena<T>` and are
-referred to by a `Copy` handle, `Id<T>`.
-
-## Why
-- Editor data is a graph: clips reference media, effects reference clips, nodes
- reference other nodes. Expressing that with owning pointers fights the borrow
- checker forever; expressing it with `Rc<RefCell<T>>` moves the fight to runtime
- and hands you cycles, leaks and `already borrowed` panics.
-- Handles are `Copy`, `Eq` and `Hash`. They go into undo records, serialized
- projects, and across thread boundaries without ceremony.
-- The generation counter turns "stale reference to a deleted clip" from a
- use-after-free into `arena.get(id) == None`.
-
-## What it costs
-- One indirection and one `Option` unwrap at every access.
-- You pass `&Arena` around instead of following a pointer.
-
-## What would change our mind
-Nothing. This is the standard shape for this problem in Rust.
diff --git a/engine/docs/decisions/0004-cpu-compositor-first.md b/engine/docs/decisions/0004-cpu-compositor-first.md
deleted file mode 100644
index a6b294a6..00000000
--- a/engine/docs/decisions/0004-cpu-compositor-first.md
+++ /dev/null
@@ -1,29 +0,0 @@
-# 0004 - CPU compositor first, GPU behind the same trait
-
-> **Status: the sequencing completed as planned.** `WgpuCompositor` exists
-> behind wolfcut-render's `gpu` feature, diff-tested against the CPU reference
-> with deliberate parity choices (non-sRGB target, premultiplied source-over),
-> and the desktop app exports through it (`best_compositor()` in the host's
-> `export.rs`, CPU fallback for machines with no usable adapter). The CPU
-> compositor kept exactly the role this note gave it: the reference the GPU
-> output is diffed against, and the backend the paused/streaming preview
-> composites with, where at preview sizes it is fast enough.
-
-## Decision
-`wolfcut-render` ships a correct, dependency-free `CpuCompositor`. The GPU path
-(`wgpu`) will be a second implementation of the same `Compositor` trait.
-
-## Why
-- The interesting design work is the *plan*: given a timeline and a timestamp,
- which layers are visible, at what source time, with what opacity. That is pure
- logic, testable with zero IO, and the GPU backend consumes the same plan.
-- A CPU compositor is the reference implementation. When GPU output looks wrong,
- you diff against this.
-- `wgpu` is a large dependency tree and a long compile. Not worth paying before
- the plan is settled.
-
-## What it costs
-Playback performance until the GPU path lands. Acceptable - nothing ships yet.
-
-## What would change our mind
-Nothing; this is sequencing, not a fork in the road.
diff --git a/engine/docs/decisions/0005-license-mpl-2.md b/engine/docs/decisions/0005-license-mpl-2.md
deleted file mode 100644
index 25d17901..00000000
--- a/engine/docs/decisions/0005-license-mpl-2.md
+++ /dev/null
@@ -1,27 +0,0 @@
-# 0005 - License: MPL-2.0
-
-## Decision
-WolfCut is licensed under the Mozilla Public License 2.0. `LICENSE` at the
-repository root is the canonical text; every crate and package manifest names
-`MPL-2.0`.
-
-## Why
-- File-level copyleft: changes to WolfCut's own files must be shared, which
- keeps improvements flowing back without capturing everything they touch.
-- A proprietary plugin, integration, or vendor SDK can link against the engine
- without inheriting the license - the future OpenFX/VST story stays possible.
-- Compatible with the dependency tree in use (MIT/Apache Rust crates), and
- with distributing GPL-built FFmpeg *alongside* the app as a separate
- program.
-
-## The FFmpeg constraint, restated
-The bundled `ffmpeg`/`ffprobe` binaries are GPL builds (x264). Because they are
-invoked as child processes and never linked (decision 0002), their license does
-not propagate to this code - but distributing them makes the *bundle* subject
-to FFmpeg's source-availability terms. `THIRD_PARTY_NOTICES.md` names the
-builds we ship and where their sources live, and every release links it.
-
-## What would change our mind
-Linking FFmpeg into the shipped app (the `ffi` feature graduating from
-dev-only) would force the bundle question open again: a GPL libavcodec linked
-into an MPL binary is a licensing decision, not a build flag.
diff --git a/engine/docs/decisions/0006-transitions-in-the-exporter.md b/engine/docs/decisions/0006-transitions-in-the-exporter.md
deleted file mode 100644
index bf705a0d..00000000
--- a/engine/docs/decisions/0006-transitions-in-the-exporter.md
+++ /dev/null
@@ -1,37 +0,0 @@
-# 0006 - Transitions resolve in the exporter, ramps live in the core
-
-## Decision
-A transition is stored on the *incoming* clip of a cut (`transitionIn`), and
-is turned into things the renderer already understands at export time, by
-`resolve_transitions` in the host's `export.rs`:
-
-- **Cross-fade**: the incoming clip is extended backwards over the outgoing
- one - consuming its source handle, clamped to what exists - moved onto a
- synthetic lane directly above it (every track index is doubled; incoming
- clips take the odd lane), and given a `video_fade_in` opacity ramp.
-- **Fade to black/white**: frame-exact `fade` filters appended to each side's
- decode chain. Nothing moves.
-
-`wolfcut-core::Clip` grew exactly one concept: `video_fade_in`/`video_fade_out`
-ramps, multiplied into the frame plan's layer opacity. The compositor never
-learns transitions exist.
-
-## Why this shape
-- Binding a transition to the cut by *adjacency* (a clip ends where this one
- starts) means moving the clips apart orphans it into a plain cut - no
- dangling entity, no repair pass.
-- Resolving in the exporter keeps the engine timeline free of a transition
- type it would only ever lower into overlaps anyway.
-- The handle rule (a dissolve consumes source before the in-point) is what
- every NLE does, and the clamp means "no handle, shorter dissolve" instead
- of frozen frames.
-
-## What it costs
-- Chained cross-fades within one dissolve window degrade (the synthetic-lane
- trick assumes one incoming clip per cut). Pathological, documented in code.
-- The motion transitions (wipe, push, zoom) need animated transforms in the
- engine and stay "Soon" until it has them.
-
-## What would change our mind
-Animated transforms landing in `wolfcut-core` - at which point wipes arrive and
-cross-fade could become a first-class engine op instead of an export lowering.
diff --git a/engine/docs/decisions/0007-engine-owns-the-project.md b/engine/docs/decisions/0007-engine-owns-the-project.md
deleted file mode 100644
index 85019169..00000000
--- a/engine/docs/decisions/0007-engine-owns-the-project.md
+++ /dev/null
@@ -1,55 +0,0 @@
-# 0007 - The engine owns the project
-
-> **Status: the migration is complete.** Every step below is done;
-> `lib/project.ts` and `lib/persist.ts` are deleted, and the freeze language
-> in the decision is historical. This crate has since grown the template
-> commands (decision 0008) on exactly the seam this note built.
-
-## Decision
-`wolfcut-project` is the model of record for the edit: the document types,
-every operation as a serialisable `Command`, whole-state undo, and the
-tolerant `wolfcut.json` reader/writer - all ported semantics-for-semantics from
-the UI's provisional `lib/project.ts`. The host exposes it as the `editor_*`
-commands (open / apply / undo / redo / save / state / close).
-
-`lib/project.ts` is **frozen**: bug fixes only, mirrored into `wolfcut-project`
-in the same commit, until the UI has flipped onto the engine API and the file
-is deleted.
-
-## Why now
-The provisional model was meant to be scaffolding, but it was accreting
-features faster than the engine grew an API - multiple timelines, effects and
-transitions all landed UI-side, and every one raised the migration bill. The
-audit that preceded this decision called it the repo's biggest strategic
-debt; this crate is the answer.
-
-## Shape choices worth recording
-- **A separate crate, not part of wolfcut-core.** The document model needs
- serde; wolfcut-core's zero-dependency rule is worth more than adjacency.
-- **String ids and f64 seconds in the document model.** These match the
- on-disk format and the ten projects that already exist. The arena-handled,
- rational-time `wolfcut-core::Timeline` remains the *render* model; the
- exporter converts, as it always has. Moving the document itself to exact
- time is a format decision to make once, deliberately, later.
-- **Undo is whole-state snapshots**, capped at 200. A heavy project is a few
- hundred kilobytes; cloning per edit is cheaper than inverse operations and
- impossible to get wrong.
-- **Compatibility is tested**, both ways: a document written by the TS side
- loads here (fixture test), and this crate's writer produces the same
- structure - including the flat active-timeline mirror for old builds.
-
-## The migration plan
-1. *(done)* Crate, commands, undo, document IO, host API, freeze.
-2. *(done)* UI flipped: App state is the `EditorView` the host returns; every
- mutation is a serialised command; drags echo locally with the engine's own
- arithmetic (`lib/editor.ts`) and commit one command on release, so undo
- means "undo the drag"; Ctrl+Z / Ctrl+Shift+Z and the Edit menu drive the
- engine's history.
-3. *(done)* `lib/project.ts` and `lib/persist.ts` are deleted. What remains
- in the UI is `lib/editor.ts`: type mirrors, read-only selectors, and the
- echo - view logic, not model ownership.
-
-## What would change our mind
-Nothing about ownership. IPC round-trip cost could force a finer-grained
-state-sync protocol (patches instead of full snapshots) if profiling demands
-it - that changes the wire format, not who owns the model.
diff --git a/engine/docs/decisions/0008-templates-are-documents-plus-slots.md b/engine/docs/decisions/0008-templates-are-documents-plus-slots.md
deleted file mode 100644
index 493209de..00000000
--- a/engine/docs/decisions/0008-templates-are-documents-plus-slots.md
+++ /dev/null
@@ -1,49 +0,0 @@
-# 0008 - A template is a document plus slots, not a new format
-
-## Decision
-A template (the CapCut-style "drop your clips into a finished edit" feature)
-is an ordinary wolfcut document with one new fact and one new operation:
-
-- `MediaItem.placeholder: bool` marks a media item as a *slot* - a stand-in
- whose metadata says what belongs there. Skipped when false, so documents
- without templates stay byte-identical. In the creator's own project the
- path stays real and everything previews; only a packed bundle blanks it.
-- `Command::FillSlot { media_id, item }` replaces the identity behind the
- media id - path, duration, codecs, kind - and leaves every clip that
- references it untouched, except that in-points reset (they referred to the
- old footage) and clip kind follows the new media. Slot timing is the
- template's: start, duration and speed stay put, which is what keeps cuts
- on the beat. A clip shorter than its slot freeze-frames, which is the
- renderer's existing behaviour for a trim past the media's end.
-- `Command::Batch { commands }` applies a list all-or-nothing (staged clone,
- committed on success) as one undo step. Filling eleven slots is one edit.
-
-The *bundle* - `template.json` with `assets/` for the music and overlays
-that are part of the design, paths relative to the bundle - is host territory
-(`desktop/src-tauri/src/templates.rs`), not engine territory. The host packs
-and unpacks; instantiation opens the document in a `wolfcut_project::Editor`
-and applies a batch of fills, so what a fill *means* lives in exactly one
-place. The editor never opens on a slot with a dead path: the launch screen
-collects every slot's media first, and instantiation refuses a partial set.
-
-## Why this shape
-- The document model, tolerant reader, undo and command wire all exist; a
- template format that was not the document format would mean porting every
- future feature twice, which is the exact debt decision 0007 paid off.
-- Binding fills to the media id rather than to clips means one slot can cut
- to the beat many times and fill once - and the engine's "clips reference
- media" indirection was already the right join point.
-- Relative asset paths stay confined to the bundle boundary. The engine
- still never sees anything but ordinary paths, so `wolfcut-media`,
- `wolfcut-render` and the exporter needed no changes at all.
-
-## What it costs
-- Slot metadata rides in every document, invisible until used.
-- A bundle copies its design media in full; big soundtracks make big
- templates. Acceptable - a template that references files it does not own
- breaks the moment it travels, which is the whole point of having one.
-
-## What would change our mind
-Sharing templates between machines at scale (a gallery, a marketplace) would
-want a zipped single-file form and a manifest version - packaging concerns,
-which change the host's bundle code and nothing in this crate.
diff --git a/engine/docs/decisions/0009-the-engine-owns-the-render-path.md b/engine/docs/decisions/0009-the-engine-owns-the-render-path.md
deleted file mode 100644
index 73a296ef..00000000
--- a/engine/docs/decisions/0009-the-engine-owns-the-render-path.md
+++ /dev/null
@@ -1,54 +0,0 @@
-# 0009 - The engine owns the render path
-
-## Decision
-
-Rendering moves into the engine as `wolfcut-export`: transition resolution
-(decision 0006's semantics, unchanged), the flat-clip-list-to-`Timeline`
-conversion, the frame loop, audio mix orchestration, and the paused-monitor
-composite. The desktop host's `export.rs` shrinks to a wire shim - deserialise
-the request, forward progress as `export://progress` events.
-
-This lands the standing doctrine as structure, not comments: **the Tauri and
-TypeScript sides are interface; everything important exists in the engine.**
-A piece of editing or rendering semantics found in `desktop/` is debt to be
-moved, not a home to be extended.
-
-## Why now
-
-The 2026-08 audit found the "engine owns the model" doctrine true for editing
-and persistence but false for rendering: what actually exported was a clip
-list flattened by the UI, re-interpreted by a hundred lines of dissolve
-semantics living in the host - in a file whose own header said editing
-semantics must not live there. Three definitions of "a clip" existed
-(`wolfcut-core` rational, `wolfcut-project` f64, host `ExportClip`), and any
-drift between them was invisible to every test in the workspace, because the
-host was the only place they met.
-
-## Shape choices worth recording
-
-- **A separate crate, not part of wolfcut-render.** `wolfcut-render` turns a
- timeline plus a timestamp into one frame and depends only on core; the
- export path also needs media (decoders, the audio graph) and orchestrates
- whole files. Folding that tree into wolfcut-render would make every
- render-only consumer pay for it.
-- **The GPU stays behind a feature gate** (`gpu`, forwarding to
- wolfcut-render's), for the same reason it is one there: engine-only work
- never pays for the wgpu tree.
-- **The flattened `ExportClip` remains, for now, produced by the UI.** Moving
- the code was step one; making the engine's own `Editor` session the source
- the flattener reads - so export and preview stop trusting UI JSON at all -
- is the follow-on step, along with the FFmpeg effect/filter chain builders
- (today mirrored between `lib/effects.ts`/`lib/filters.ts` and
- `wolfcut-export::chains`, pinned to byte-identical output by tests on both
- sides).
-
-## Consequences
-
-- The CLI and any future frontend can render a timeline identically to the
- app, from the engine alone.
-- `resolve_transitions` and the conversion seam are tested where they live;
- a change to dissolve semantics fails an engine test, not a user's export.
-- The host no longer compiles any code that decides what pixels mean. What
- remains in `desktop/src-tauri` is process supervision (playback's device
- babysitting, whisper, single-flight job slots) and wire conversion - the
- things a host is for.
diff --git a/engine/docs/decisions/README.md b/engine/docs/decisions/README.md
deleted file mode 100644
index a41df7e6..00000000
--- a/engine/docs/decisions/README.md
+++ /dev/null
@@ -1,10 +0,0 @@
-# Decision log
-
-One file per decision that would otherwise be invisible in the code. Short.
-Written for whoever opens this repo after a long gap - usually you.
-
-Format: what we decided, why, what it costs, and what would change our mind.
-
-Numbering is append-only. A note that stops earning its place is deleted, its
-number is never reused, and git history keeps the text - which is why the log
-can start past 0001.