Merge branch 'worktree-agent-a128c7366e475da55'

docs/agents.md

@@ -77,6 +77,29 @@ instead of being ignored.
 4. `execute_command {"command":"effect.apply","params":{"layer":2,"effect":"Gaussian Blur"}}`, then `set_property {"layer":2,"path":"effects/#1/blurriness","value":8}`
 5. `render_frame {"time":1.0}` lets you look at the result, and `save_project {"path":"intro.ecproj"}` saves it.
 
+### Motion tracking
+
+Trackers live on the tracked layer (`Motion Trackers ▸ Tracker n ▸ Track Point n`) and are driven
+with `track.*` commands. `track.analyze` runs in the background in the app (poll `track.status`);
+pass `"wait": true` to block until it finishes, which is what the CLI and headless MCP want.
+
+1. `execute_command {"command":"track.motion","params":{"layer":"clip.mov"}}` creates a Transform
+   tracker (Motion Target: the layer above). Use `track.stabilize` for Stabilize, or `track.new` with
+   `kind` `transform|stabilize|affine|perspective|raw` and `rotation`/`scale`.
+2. `execute_command {"command":"track.setPoint","params":{"point":1,"center":[812,440],"featureSize":[40,40],"searchSize":[96,96]}}`
+3. `execute_command {"command":"track.analyze","params":{"direction":"forward","wait":true}}` keys Feature
+   Center, Confidence and Attach Point on every frame from the current time to the layer's end.
+4. `execute_command {"command":"track.apply","params":{"dimensions":"xy"}}` keys the target's Position
+   (and Rotation/Scale), the layer's own Anchor Point and Position for Stabilize, or a Corner Pin
+   effect for `affine`/`perspective` tracks. `track.options` sets the channel, blur/enhance,
+   adapt-feature and "If Confidence is Below" behaviour; `track.status` reports the track points.
+
+```sh
+effectcraft-cli run clip.ecproj track.motion '{"layer":"#2"}' \
+  track.setPoint '{"point":1,"center":[812,440]}' \
+  track.analyze '{"wait":true}' track.apply '{}' --save
+```
+
 ## CLI
 
 Each invocation runs a headless engine with no window. It opens the demo project unless you pass

docs/architecture.md

@@ -22,6 +22,7 @@ cpal or muda. Everything in L0 to L4, the egui UI and the web app also build for
 | L2 | `project` | The document: items, compositions, layers, the property tree, render queue model, `.ecproj` serde |
 | L2 | `text` | Fonts, shaping, layout, per-glyph geometry, text animators and selectors |
 | L2 | `effects` | The effect registry (241 effects) and their CPU implementations |
+| L2 | `track` | Motion tracking: feature/search region point tracking (pyramid normalized cross-correlation, Lucas–Kanade sub-pixel refinement), confidence, homography/affine/similarity solves |
 | L3 | `render` | Evaluation and compositing: sources, masks, effects, transforms, 3D, motion blur, mattes, blending, layer cache, audio mixdown |
 | L3 | `media` | Footage decoding (FilmCraft's pure-Rust codecs), image sequences, frame cache |
 | L3 | `expr` | The expression engine (JavaScript via boa) with the After Effects object model |
@@ -92,6 +93,15 @@ layer's Blending Options and kept in step after each edit.
 
 Half, Third and Quarter resolution render proportionally fewer pixels end to end.
 
+**Motion tracking** (Animation ▸ Track Motion / Stabilize Motion, Window ▸ Tracker): a tracker
+is a `Tracker` group under the layer's Motion Trackers group, with Track Point groups (Feature
+Center, Feature Size, Search Offset, Search Size, Confidence, Attach Point, Attach Point Offset)
+keyframed per analysed frame. `track.analyze` renders the layer's source frames
+(`Renderer::layer_source`) on a background thread (`engine::tracking`, polled like the render
+queue; blocking with `wait`), and `effectcraft-track` matches each point in parallel. One undo step
+covers an analysis. `track.apply` keys the target's Position/Rotation/Scale, the tracked layer's
+Anchor Point and Position (Stabilize), or a Corner Pin effect (Parallel / Perspective).
+
 ## 5. Expressions
 
 Expressions are JavaScript, run by boa, with After Effects' object model (`thisComp`, `thisLayer`,