The truly free, open-source, local-first, cross-platform CapCut replacement. Scriptable through a JSON-RPC API & MCP.
Rust ffmpegfree-video-editormodel-context-protocolnon-linear-editoroffline-firstopen-source-video-editorself-hostedvideo-editingvideo-editing-automationvideo-editing-softwarevideo-editing-toolsvideo-editorvoice-cloningyoutube-automationyoutube-shorts
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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.