M6.7: refine edge + freeze + UI

Refine Edge tool (Alt+W cycles Roto Brush / Refine Edge), Layer panel
roto strokes with matte overlays (Alpha Boundary in pink, Alpha, Alpha
Overlay, View Search Region), segmentation span bar, Freeze/Propagate in
the Layer panel and Effect Controls, background propagation polling,
docs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/agents.md

@@ -146,6 +146,28 @@ effectcraft-cli exec warp.analyze '{"layer":"#1","wait":true}' shaky.ecproj --sa
 effectcraft-cli exec warp.status '{"layer":"#1"}' shaky.ecproj --json
 ```
 
+### Roto Brush & Refine Edge
+
+The Roto Brush tool (Alt+W cycles Roto Brush / Refine Edge) paints in the Layer panel; agents use
+`roto.stroke {layer, kind: fg|bg|refine|refineErase, points: [[x, y], …], frame?, radius?}`
+(layer pixels, layer frames). The first foreground stroke applies the Roto Brush & Refine Edge
+effect and sets the base frame with a span of 20 frames each side. `roto.propagate {layer,
+direction?: forward|backward|both, to?, wait?}` segments the span (in the background unless
+`wait`); strokes on any other frame correct it and propagation restarts from there.
+`roto.span {start?, end?}`, `roto.freeze {wait?}` / `roto.unfreeze`, `roto.clearStrokes {frame?,
+kind?}`, `roto.cancel` and `roto.options {diameter?, refineDiameter?, view?: alphaBoundary|alpha|
+alphaOverlay|none}` complete the set; every edit is one undo step. `roto.status {layer, frame?,
+matte?, compute?, compareTo?}` reports the base frame, span, computed and stroked frames, frozen
+state, job progress and, for a frame, the matte's area, centroid, RLE matte and IoU against a
+reference. Matte settings are ordinary properties (`effects/#1/rotoBrushMatte/searchRadius`,
+`effects/#1/refineEdgeMatte/decontaminateEdgeColors`, …).
+
+```sh
+effectcraft-cli run clip.ecproj roto.stroke '{"layer":"#1","points":[[300,200],[360,230]],"radius":10}' \
+  roto.stroke '{"layer":"#1","kind":"bg","points":[[40,40],[600,40]],"radius":12}' \
+  roto.propagate '{"layer":"#1","wait":true}' roto.freeze '{"layer":"#1","wait":true}' --save
+```
+
 ### Text: styles and editing
 
 Source Text holds character style runs and per-paragraph settings. `layer.setText` changes the

docs/architecture.md

@@ -176,6 +176,19 @@ auto-scale; cached per analysis and settings) and warps each frame; Synthesize E
 borders from neighbouring frames read with `EffectHost::self_at`. The effect lives in the
 effects crate, hence the `effects → track` edge.
 
+**Roto Brush & Refine Edge** (`effectcraft_track::roto`, `effects::roto`, `engine::roto`):
+strokes (foreground, background, Refine Edge) are stored as JSON in the effect's hidden Strokes
+parameter with the base frame and segmentation span. Each frame is segmented by graph cut
+(Boykov–Jolly hard constraints, GrabCut colour mixtures, our own Boykov–Kolmogorov max-flow,
+coarse to fine) and propagated to the next frame by warping the matte with block optical flow and
+re-cutting in a Search Radius band; frames with correction strokes are re-cut with the warped
+matte as a soft prior. Refine Edge bands get guided-filter + closed-form matting and
+foreground-colour decontamination. Segmentations are derived data: each frame's chain key (Input
+Key, settings, strokes from the base frame out) indexes a process-wide cache that renders fill on
+demand (`self_at`) and `roto.propagate` fills in the background; `Session::edit` keeps the Input
+Key in step with the layer's source, masks and upstream effects. Freeze stores final 8-bit mattes
+in the effect.
+
 ## 5. Expressions
 
 Expressions are JavaScript, run by boa, with After Effects' object model (`thisComp`, `thisLayer`,

docs/parity.md

@@ -73,7 +73,7 @@ library groundwork for mask tracking and Warp Stabilizer.
 | Remaining (audit-scale agent-hours) | ≈ 167 | ≈ 100 |
 | Wall clock, five parallel agents | 42–50 h | **≈ 8–10 h at today's measured pace; ≈ 25 h by the audit's conservative figures** |
 
-What is left is concentrated in large systems: Roto Brush and Refine Edge, the 3D camera tracker,
+What is left is concentrated in large systems (Roto Brush and Refine Edge landed in M6.7): the 3D camera tracker,
 Advanced 3D (models, PBR, image-based lighting), the Warp Stabilizer and mask-tracking UI on top of
 the new tracking library, a JavaScript scripting object model, SVG/PSD import, WebM, a disk cache,
 the missing effect categories (3D Channel, Immersive Video, OCIO), native macOS menus, and
@@ -97,7 +97,7 @@ wasm threads.
 | Effects | 58% | 13.6 | Effect Controls widgets (angle dial, point crosshair, eyedropper, curves), GPU versions of more effects, 41 missing effects |
 | Interface | 55% | 10.4 | drag-to-dock and floating panels, preferences, native macOS menus (viewer rulers/snapping/channels/snapshots landed in M0.13) |
 | Project | 53% | 8.1 | 8/16/32-bit pipeline and colour management, auto-save, proxies, folder moves |
-| Masks & roto | 52% | 10.0 | Roto Brush, variable-width mask feather points (mask tracking and Mask Interpolation landed in M6.6) |
+| Masks & roto | 68% | 6.0 | variable-width mask feather points, Roto Brush's learned (3.0) segmentation model (mask tracking and Mask Interpolation landed in M6.6; Roto Brush & Refine Edge with graph-cut segmentation, flow propagation, edge matting, decontamination and Freeze in M6.7) |
 | Preview | 55% | 6.1 | GPU 3D and adjustment layers, disk cache (region of interest, snapshots, exposure and Fast Previews landed in M0.13) |
 | Tracking | ≈ 70% | 4.0 | 3D camera tracker, face tracking, Subspace Warp's mesh warp and rolling-shutter repair (point tracker, mask tracking and Warp Stabilizer landed in M6.x / M12.5) |
 | Paint | 0% | 4.0 | Brush, Clone Stamp, Eraser |