Skip to content

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

docs(project): the migration framing is history; say what survives it

Jareer56cc19edd560
diff --git a/engine/crates/wolfcut-project/src/commands.rs b/engine/crates/wolfcut-project/src/commands.rs
index ab57f5cb..f627a467 100644
--- a/engine/crates/wolfcut-project/src/commands.rs
+++ b/engine/crates/wolfcut-project/src/commands.rs
@@ -1,10 +1,10 @@
//! Every edit operation, as data.
//!
//! A [`Command`] is what the UI sends over IPC; [`apply`] is the one place
-//! its meaning lives. The semantics are ported line for line from
-//! `desktop/src/lib/project.ts` - same clamps, same tolerances, same rules -
-//! because during the migration both sides must agree about every edit, and
-//! after it this file is simply the only copy.
+//! its meaning lives. The semantics were ported line for line from the UI's
+//! provisional model (deleted; decision 0007) and this file is now the only
+//! copy - the clamps and tolerances documented on each variant are the
+//! contract the UI's gesture echo mirrors and tests against.
use std::collections::HashSet;
diff --git a/engine/crates/wolfcut-project/src/doc.rs b/engine/crates/wolfcut-project/src/doc.rs
index 2ae8b02d..41b12ef9 100644
--- a/engine/crates/wolfcut-project/src/doc.rs
+++ b/engine/crates/wolfcut-project/src/doc.rs
@@ -1,7 +1,8 @@
//! Reading and writing `wolfcut.json`.
//!
-//! The reader is a port of `desktop/src/lib/persist.ts`, tolerance rules
-//! included: every field defaults rather than being trusted, clips whose
+//! The reader began as a port of the UI's `persist.ts` (deleted; decision
+//! 0007) and its tolerance rules are the contract with every document
+//! already on disk: every field defaults rather than being trusted, clips whose
//! track or media vanished are dropped, text clips survive without media,
//! legacy flat documents load as a single timeline. A hand-edited or older
//! file must degrade to something openable, never to a load error.
diff --git a/engine/crates/wolfcut-project/src/lib.rs b/engine/crates/wolfcut-project/src/lib.rs
index 8b17566d..4e656050 100644
--- a/engine/crates/wolfcut-project/src/lib.rs
+++ b/engine/crates/wolfcut-project/src/lib.rs
@@ -1,18 +1,20 @@
//! The edit itself, owned by the engine.
//!
-//! `desktop/src/lib/project.ts` held a provisional copy of this model while
-//! the engine had no project API; this crate is that API. The model
-//! ([`model`]), every operation as a serialisable [`commands::Command`], the
-//! tolerant document reader and compatible writer ([`doc`]), and the undo
-//! stack ([`editor::Editor`]) - all headless, all testable without a window.
+//! The model ([`model`]), every operation as a serialisable
+//! [`commands::Command`], the tolerant document reader and compatible writer
+//! ([`doc`]), and the undo stack ([`editor::Editor`]) - all headless, all
+//! testable without a window.
//!
-//! Two compatibility guarantees hold while the UI migrates:
+//! The semantics began as clamp-for-clamp ports of the UI's provisional
+//! `lib/project.ts`, which is deleted (decision 0007); the migration framing
+//! that used to live here is history. What survives it, deliberately:
//!
-//! 1. **Documents are interchangeable.** A `wolfcut.json` written by either
-//! side loads in the other, tolerance rules included.
-//! 2. **Operations mean the same thing.** The command semantics are ports of
-//! the TS operations, clamp for clamp - which is what makes flipping the
-//! UI onto this crate a mechanical change rather than a behavioural one.
+//! 1. **The document format is frozen by the documents that exist.** Saved
+//! projects load forever, tolerance rules included - not because a TS
+//! twin must agree, but because users' work does not migrate on our
+//! schedule. Format changes go through `DOCUMENT_VERSION`.
+//! 2. **f64 seconds and String ids are the document's terms**, kept until a
+//! version 2 decides otherwise on purpose - not an accident of porting.
//!
//! Deliberately a separate crate rather than part of `wolfcut-core`: the
//! document model needs serde, and wolfcut-core's zero-dependency rule is worth
@@ -253,8 +255,9 @@ mod tests {
#[test]
fn a_typescript_written_document_loads() {
- // The exact shape desktop/src/lib/persist.ts toDocument produces,
- // optional fields omitted the way JSON.stringify drops undefined.
+ // The exact shape the deleted TS persist layer used to write,
+ // optional fields omitted the way JSON.stringify drops undefined -
+ // documents like this exist on disk and must load forever.
let document = json!({
"wolfcut": "0.1.0", "version": 1, "name": "TS",
"video": { "width": 1920, "height": 1080, "rateNum": 30, "rateDen": 1 },
diff --git a/engine/crates/wolfcut-project/src/model.rs b/engine/crates/wolfcut-project/src/model.rs
index 2568f0d6..0b427171 100644
--- a/engine/crates/wolfcut-project/src/model.rs
+++ b/engine/crates/wolfcut-project/src/model.rs
@@ -1,12 +1,11 @@
//! The document model: what a WolfCut project *is*.
//!
-//! This is the same shape `desktop/src/lib/project.ts` holds - deliberately,
-//! field for field, because the two must describe identical documents while
-//! the UI migrates onto this crate. Times are `f64` seconds here because that
-//! is what the on-disk format stores; the conversion to exact rationals stays
-//! at the render boundary (`export.rs`), exactly as it does today. Moving the
-//! *document* to rational time is a format decision for later, made once,
-//! here, instead of twice.
+//! Times are `f64` seconds here because that is what the on-disk format
+//! stores, and the documents that exist freeze the format (the provisional
+//! TS twin this shape once mirrored is deleted; decision 0007). The
+//! conversion to exact rationals stays at the render boundary -
+//! `wolfcut-export`'s timeline builder. Moving the *document* to rational
+//! time is a format decision for a deliberate version 2, made once, here.
//!
//! Serde names are camelCase so a document written by this crate is byte-level
//! compatible with one written by the TypeScript side.