Skip to content

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

docs(decisions): bring both logs up to date with the code

Jareerbc4af20ab089
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
index 632120fd..229daccb 100644
--- 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
@@ -5,6 +5,11 @@ 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.
diff --git a/desktop/docs/decisions/0006-multiple-timelines.md b/desktop/docs/decisions/0006-multiple-timelines.md
index e07d5495..958eb0d0 100644
--- a/desktop/docs/decisions/0006-multiple-timelines.md
+++ b/desktop/docs/decisions/0006-multiple-timelines.md
@@ -1,5 +1,11 @@
# 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
diff --git a/desktop/docs/decisions/0007-preview-approximation-layer.md b/desktop/docs/decisions/0007-preview-approximation-layer.md
index a933afa8..aa03bec5 100644
--- a/desktop/docs/decisions/0007-preview-approximation-layer.md
+++ b/desktop/docs/decisions/0007-preview-approximation-layer.md
@@ -32,8 +32,10 @@ The first step of the engine presentation path shipped: the reader pool and
frame cache exist (`relay_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. What remains for full retirement is
-streaming presentation against the transport clock.
+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
diff --git a/engine/docs/decisions/0001-rust-over-cpp.md b/engine/docs/decisions/0001-rust-over-cpp.md
deleted file mode 100644
index 84624623..00000000
--- a/engine/docs/decisions/0001-rust-over-cpp.md
+++ /dev/null
@@ -1,25 +0,0 @@
-# 0001 - Rust, not C++
-
-## Decision
-The engine is written in Rust.
-
-## Why
-- The render path is a fan-out across cores sharing a frame cache. Data races and
- use-after-free on frame buffers are *the* bug class here, and they are compile
- errors in Rust instead of a corrupt frame three hours into a render.
-- This project is maintained by one person, intermittently. Rust's payoff is that
- you debug at compile time, alone, from the error text. No exceptions unwinding
- through the render loop, no implicit conversions, no surprise copy constructors.
-- One build system, one formatter, one linter, one doc generator. Re-entering a
- C++ codebase cold means re-learning whatever build archaeology it invented.
-- `wgpu` gives one GPU backend across Vulkan/Metal/DX12. In C++ that portability
- is a permanent tax.
-
-## What it costs
-- OpenFX / VST plugin hosting is a C ABI and will need `unsafe extern "C"` shims.
-- Some vendor encoder SDKs are C++-first.
-- Lifetime and trait-bound errors on generic code can be opaque - mitigated by
- keeping generics shallow.
-
-## What would change our mind
-A hard dependency that only ships a C++-template-only API.
diff --git a/engine/docs/decisions/0002-ffmpeg-over-a-pipe.md b/engine/docs/decisions/0002-ffmpeg-over-a-pipe.md
index c204a409..d7d4cd03 100644
--- a/engine/docs/decisions/0002-ffmpeg-over-a-pipe.md
+++ b/engine/docs/decisions/0002-ffmpeg-over-a-pipe.md
@@ -92,6 +92,18 @@ consumers are live: `relay-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
diff --git a/engine/docs/decisions/0004-cpu-compositor-first.md b/engine/docs/decisions/0004-cpu-compositor-first.md
index 8bcbffc0..8dbbf1d0 100644
--- a/engine/docs/decisions/0004-cpu-compositor-first.md
+++ b/engine/docs/decisions/0004-cpu-compositor-first.md
@@ -1,5 +1,14 @@
# 0004 - CPU compositor first, GPU behind the same trait
+> **Status: the sequencing completed as planned.** `WgpuCompositor` exists
+> behind relay-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
`relay-render` ships a correct, dependency-free `CpuCompositor`. The GPU path
(`wgpu`) will be a second implementation of the same `Compositor` trait.
diff --git a/engine/docs/decisions/0005-license-mpl-2.md b/engine/docs/decisions/0005-license-mpl-2.md
index b7fde598..25d17901 100644
--- a/engine/docs/decisions/0005-license-mpl-2.md
+++ b/engine/docs/decisions/0005-license-mpl-2.md
@@ -9,8 +9,7 @@ repository root is the canonical text; every crate and package manifest names
- 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 (decision 0001)
- stays possible.
+ 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.
diff --git a/engine/docs/decisions/0007-engine-owns-the-project.md b/engine/docs/decisions/0007-engine-owns-the-project.md
index 92be01d8..f90b3583 100644
--- a/engine/docs/decisions/0007-engine-owns-the-project.md
+++ b/engine/docs/decisions/0007-engine-owns-the-project.md
@@ -1,5 +1,10 @@
# 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
`relay-project` is the model of record for the edit: the document types,
every operation as a serialisable `Command`, whole-state undo, and the
diff --git a/engine/docs/decisions/README.md b/engine/docs/decisions/README.md
index a76b2724..a41df7e6 100644
--- a/engine/docs/decisions/README.md
+++ b/engine/docs/decisions/README.md
@@ -4,3 +4,7 @@ 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.