filmcraft/CLAUDE.md

FilmCraft — instructions for agents

FilmCraft is a clean-room, open-source, pure-Rust non-linear video editor targeting Adobe Premiere Pro parity (and beyond). Native on macOS, Windows, Linux; web via WASM. Sibling of ../photocraft (Photoshop), ../pdfcraft (Acrobat) and ../vectorcraft (Illustrator; formerly DrawCraft), with the same conventions.

Start every session here

plan/ is maintainer-local (gitignored, not in the repo). Each step names the public equivalent to use if you don't have it.

1. Read plan/STATUS.md (current milestone, next unchecked task, blockers). Public: ROADMAP.md, then docs/gaps.md (ranked shortfalls) and docs/roadmap.md (current focus).
2. Read the task in plan/execution-plan.md §3, the relevant section of plan/architecture.md, and the README/docs of the crate you touch. Public: docs/architecture.md, docs/contributing.md, docs/testing.md. Visual/behaviour reference: plan/premiere/ (local only, never committed).
3. Follow the autonomous operation protocol (plan/execution-plan.md §7; public summary: docs/agents.md §5–7). Don't stop to ask unless it lists the decision as the user's.

Non-negotiables

Read AGENTS.md first; its rules override everything here.

• Never crash (AGENTS.md §0, standard: craftrules/standards/never-crash.md). People depend on FilmCraft; a crash loses their work, so this outranks feature work. No unwrap/expect/panic!/unreachable!/todo!/unimplemented! or unsafe outside tests: return Result<T, E> and propagate with ? (ok_or, let … else, if let). Treat every number from media, project files, presets or CLI/MCP/control params as hostile: get() instead of [i], checked/saturating math, no division by possibly-zero values, capped allocations, bounded recursion. lock().unwrap_or_else(PoisonError::into_inner); background jobs run under catch_unwind. The panic hook + UI catch_unwind (crates/ui-egui/src/crash.rs) are the last-resort guard, not a licence. Every crash fix gets a regression test that panicked before. In particular (§1): never use Adobe iconography, images or any other Adobe asset. Every asset must be openly licensed (OSS / public domain / Creative Commons, or original work by a contributor) and must have a <file>.attribution sidecar plus an entry in ATTRIBUTION.md. cargo xtask assets enforces this.
• Fonts live in storytold/craft-fonts, never in this repo (no new font files here; AGENTS.md §1.9, standard: craftrules/standards/fonts.md). Build with them: git clone https://github.com/storytold/craft-fonts ../craft-fonts && CRAFT_FONTS_DIR="$PWD/../craft-fonts" cargo run -p filmcraft (crates/text/build.rs embeds them as filmcraft_text::fonts::CRAFT_FONTS, used for Japanese in the UI and titles). Unset, CRAFT_FONTS is empty and everything must still build, test and run; never add craft-fonts to a Cargo.toml. Tests on its glyphs skip when it is empty, so run the gates with and without CRAFT_FONTS_DIR when you touch fonts.
• Clean-room. Never read/disassemble anything inside Adobe app bundles (names/listings only). Never copy Adobe icons, presets, LUTs, fonts. Never copy GPL/LGPL/AGPL code (FFmpeg, x264, x265, MLT, Kdenlive, Shotcut, Olive, LAME…). ffmpeg/ffprobe run only as external test oracles / fixture generators — never linked or shipped.
• Pure Rust in the product. OS media APIs only via Rust bindings in crates/platform (hardware decoding; the one crate allowed unsafe, see AGENTS.md §0.3 and docs/adr/0001-platform-ffi.md), optional, behind traits, with our decoders as the fallback.
• Layering (docs/architecture.md §1, enforced by cargo xtask layers): nothing below L5 depends on egui/eframe/winit/rfd/cpal. L0 codec/container crates depend only on filmcraft-bitstream.
• Exact time: all time is filmcraft_time::Tick (254 016 000 000/s). Never use f64 seconds for edit math.
• Everything is a command (crates/engine): id, label, menu path, shortcut, params, enabled(), run(). UI, CLI, control channel and MCP all dispatch by id.
• Everything is agent-drivable: every interactive widget registers an automation id; UI state is serde so the control channel can read/set it.
• Quality gates before every commit: cargo fmt --check, cargo clippy --workspace --all-targets -- -D warnings, cargo test --workspace, cargo xtask layers, cargo xtask assets, cargo xtask wasm (checks L0–L4 crates). cargo xtask ci runs them all.
• Commits: one task id per commit (M2.4: CABAC residual decoding). Only green states. End messages with the attribution line required by the environment.

Running and looking at the app

• cargo run -p filmcraft -- --control 9876 opens the desktop app with the JSON-lines control server (see docs/control-protocol.md).
• For UI work, look at the result: drive via the control channel and take ui.screenshot, compare with plan/premiere/screenshots/ (maintainer-local; see docs/agents.md §3).
• Parallel agents: separate git worktrees and CARGO_TARGET_DIR=target/agent-<name>; keep every Cargo.toml valid at all times (the crates/* glob means one broken manifest breaks everyone).
• Test fixtures: generate with ffmpeg into target/fixtures/ (never commit media). See docs/testing.md.