NextFrame: Instructions file for Claude Code

NextFrame · AI Entry

NextFrame is an AI-native video editor/runtime: structured JSON compositions render in the desktop editor and export to MP4.

Run

# First-time setup · build the frontend bundle (gitignored · webview loads it at runtime)
cd frontend/nf-components && npm install && npm run build && cd -

cargo build -p nf-shell -p nf-cli
target/debug/nf-shell
target/debug/nf open --project v2-showcase --composition showreel-clip-first

Example projects live under examples/; runtime projects are copied to ~/.nextframe/.

Black preview gotcha · if the desktop window shows the idle "NextFrame · AI-FIRST CLI-DRIVEN" hero instead of your composition, frontend/nf-components/dist/index.js is missing — re-run the npm build above. The webview silently falls back to idle when the bundle isn't loaded; nf devtools --eval='document.querySelectorAll("[data-nf-component]").length' returning 0 confirms it.

AI 验证接口

target/debug/nf open --project=<slug> --composition=<slug> — open a composition in the desktop editor. target/debug/nf screenshot --project=<slug> --episode=<slug> --region=editor --out=<png> — probe a desktop editor region and write a size stub PNG; use capture for visual evidence. target/debug/nf capture --project=<slug> --episode=<slug> --out=<png> — capture the native macOS window PNG for real visual verification. target/debug/nf click --project=<slug> --episode=<slug> --selector=<css> — simulate a real desktop click, including shadow DOM selectors. target/debug/nf devtools --project=<slug> --episode=<slug> --query=<css> --get=<prop> — inspect live DOM, including shadow DOM selectors. target/debug/nf devtools --project=<slug> --episode=<slug> --query=<css> --fill=<value> [--get=<prop>] — fill a live input through the same input/change path as human editing. target/debug/nf devtools --project=<slug> --episode=<slug> --eval=<js> — evaluate JavaScript in the live desktop webview and return {eval,value,error} JSON. target/debug/nf-shell 2>&1 | grep NFCONSOLE — watch forwarded webview console.log/warn/error/info lines from the shell process. target/debug/nf cue --timeline=<vox.json> [--max-chars=18] [--min-pause-ms=250] [--out=<json>] — use an LLM to cut a vox word-level timeline into validated cue list JSON. target/debug/nf composition show --project=<slug> --composition=<slug> [--clip=<id>] [--track=<id>] [--item=<id>] [--field=<path>] — read raw composition JSON or one clip/track/item field. target/debug/nf composition patch --project=<slug> --composition=<slug> [--clip=<id>] --track=<id> [--item=<id>] --field=<path> --value=<json-or-string> — patch one track or clip item field such as params.title, style.x, or time.start. target/debug/nf composition validate --project=<slug> --composition=<slug> — validate component registry, files, mount/update exports, import-free ABI, used tracks, and observed params. target/debug/nf composition compile --project=<slug> --composition=<slug> --out=<render_source.json> — compile AI-authored composition JSON into stable nf.render_source.v1 recorder input. target/debug/nf verify --project=<slug> --composition=<slug> [--out=<json>] [--screenshot-dir=<dir>] — verify AI-authored composition JSON: component ABI, compiled source, overlap intent, anchor guide, ASCII timeline, layout/text checks, and typical screenshot commands. target/debug/nf-recorder validate-source --source=<render_source.json> — validate recorder input contract without reading project storage or desktop state. target/debug/nf-recorder export --source=<render_source.json> --profile=draft|standard|final|final-fast --output=<mp4> [--diagnostics=<json>] — export directly from render source through the recorder module. target/debug/nf-recorder snapshot-source --source=<render_source.json> --t-ms=<ms> --output=<png> — sample one render-source frame through the same recorder HTML/runtime path. target/debug/nf export --project=<slug> --composition=<slug> --profile=draft|standard|final|final-fast --out=<mp4> — export a composition to MP4 with a named quality/speed profile. target/debug/nf export --project=<slug> --composition=<slug> --profile=draft --diagnostics --out=<mp4> — export and write a sibling diagnostics JSON with frame timings, slow spans, and top slow frames. target/debug/nf export --project=<slug> --composition=<slug> --fps=30|60 --resolution=720p|1080p|4k --parallel=<1-8> --events --out=<mp4> — override export settings and stream recorder progress JSONL before the final summary JSON. target/debug/nf verify-export --source=<render_source.json> --video=<mp4> --out=<report.json> — sample exported MP4 clip frames and fail on magenta-background or blank-frame regressions. target/debug/nf export-status --job-id=<id> — read desktop export job status, including progress and diagnostics summary/path when available. target/debug/nf export-cancel --job-id=<id> — cancel a running desktop export job and stop its recorder process group. ./scripts/check-structure.sh — verify repository skeleton: root allowlist, no nested spec git, no tracked generated artifacts.