Merge pull request #792 from vangel76/gap-object-matte

# Conflicts:
#	crates/ui-egui/src/i18n/ui.rs
#	docs/gaps.md
#	docs/target-app-parity.md

docs/agents.md

@@ -483,6 +483,26 @@ effectcraft-cli run clip.ecproj roto.stroke '{"layer":"#1","points":[[300,200],[
   roto.propagate '{"layer":"#1","wait":true}' roto.freeze '{"layer":"#1","wait":true}' --save
 ```
 
+### Object Matte
+
+The Object Matte tool (third in the Alt+W slot) works in the Composition viewer: click an object,
+or drag a box around it; Shift adds another Object Matte instead of re-prompting the layer's.
+Agents use `objectMatte.apply {layer, point: [x, y], box?: [x0, y0, x1, y1], frame?, track?,
+before?, after?, effect?}` (layer pixels, layer frames; `effect` re-prompts that instance), one
+undo step each. With a trained model installed (Settings ▸ Roto Brush) the box is the model's box
+prompt. `objectMatte.propagate {layer, effect?, direction?, wait?}` tracks the matte over the
+frames around the reference frame in the background (`roto.cancel` stops it; edits to the prompt
+or the layer's frames queue it again), `objectMatte.freeze {wait?}` / `objectMatte.unfreeze`
+store or drop the final mattes, and `objectMatte.status {layer, effect?}` reports the job's
+progress, the frozen state, the tracked frames and which are computed. With the disk cache on (Settings ▸
+Media & Disk Cache), computed Object Matte and Roto Brush segmentations are also kept there, keyed
+by what they are made of, so reopening a project reuses them.
+
+```sh
+effectcraft-cli run clip.ecproj objectMatte.apply '{"layer":"#1","point":[320,200],"box":[250,120,400,300]}' \
+  objectMatte.propagate '{"layer":"#1","wait":true}' objectMatte.freeze '{"layer":"#1","wait":true}' --save
+```
+
 ### Text: styles and editing
 
 Source Text holds character style runs and per-paragraph settings. CR (`\r`), LF (`\n`) and

docs/effects.md

@@ -3,11 +3,11 @@
 <!-- Generated from the effect registry (crates/effects/src/catalog.rs); do not edit by hand.
      Regenerate: UPDATE_DOCS=1 cargo test -p effectcraft-effects --lib effects_doc_is_current -->
 
-EffectCraft ships 306 effects with 3017 parameters in total, grouped into the same categories as the Effects & Presets panel. Every effect is our own implementation, written from public behaviour descriptions and standard image-processing literature. Parameter names, order, popup options, units, defaults and ranges follow the reference application so that projects, expressions and muscle memory carry over.
+EffectCraft ships 307 effects with 3032 parameters in total, grouped into the same categories as the Effects & Presets panel. Every effect is our own implementation, written from public behaviour descriptions and standard image-processing literature. Parameter names, order, popup options, units, defaults and ranges follow the reference application so that projects, expressions and muscle memory carry over.
 
 - **GPU**: 280 effects also run on the GPU compositor with identical results.
-- **32**: 306 effects process 32-bit float (HDR, overbright) pixels without clamping.
-- **Status**: 306 implemented in full, 0 partial (what is missing is listed).
+- **32**: 307 effects process 32-bit float (HDR, overbright) pixels without clamping.
+- **Status**: 307 implemented in full, 0 partial (what is missing is listed).
 
 Effects are addressed by id (`ec.<category>.<name>`) or display name in commands, scripts and the control channel, and every parameter by its id (`effects/#1/blurriness`).
 
@@ -255,6 +255,7 @@ Effects are addressed by id (`ec.<category>.<name>`) or display name in commands
 |---|---|---:|:-:|:-:|---|
 | Matte Choker | `ec.matte.mattechoker` | 7 | GPU | 32 | Implemented |
 | Mocha shape | `ec.obsolete.mochashape` | 6 |  | 32 | Implemented |
+| Object Matte | `ec.matte.objectmatte` | 13 |  | 32 | Implemented |
 | Refine Hard Matte | `ec.matte.refinehard` | 16 | GPU | 32 | Implemented |
 | Refine Soft Matte | `ec.matte.refinesoft` | 18 | GPU | 32 | Implemented |
 | Roto Brush & Refine Edge | `ec.matte.rotobrush` | 24 |  | 32 | Implemented |

docs/fidelity/README.md

@@ -3,6 +3,9 @@
 The [AE 2026 replacement acceptance gates](ae-2026-acceptance.md) define the broader
 target across workflows, rendered output, work-project compatibility, performance and platforms.
 
+[Object Matte](object-matte.md) has a comparison plan (clips, prompt, per-frame IoU and the other
+metrics) but no measurement yet.
+
 The first G1 comparison measures eight original scalar Rotation cases against a live After Effects
 2026 session through AEsync 2.0.4: Easy Ease, overlapping influences, asymmetric ease, overshoot,
 descending values, equal endpoints, 100%/100% influence and 0.1%/100% influence. Each case has

docs/fidelity/object-matte.md

@@ -0,0 +1,73 @@
+# Object Matte: comparison plan (not measured yet)
+
+**Status: untested.** There is no After Effects 26.2+ comparison of Object Matte yet. Nothing on
+this page is a measurement. It lists what to compare once an After Effects reference session
+is available, so the first run can be repeated and scored without guesswork.
+
+EffectCraft side, as of #783: the Object Matte effect (`ec.matte.objectmatte`), the Object Matte
+tool in the Composition viewer, `objectMatte.apply` / `.propagate` / `.freeze` /
+`.status`, and segmentations kept in the disk cache. The point (and an optional box) is
+segmented by Roto Brush's engine: MobileSAM when it is installed (Settings ▸ Roto Brush, with
+the box as the model's box prompt), otherwise the classical graph cut. The result is tracked
+frame by frame with optical flow, and the model re-prompts each frame from the carried matte.
+Record which engine was active, because the two are separate cases.
+
+## Test clips
+
+All original, generated or openly licensed; none of them goes into the repository.
+
+1. **Synthetic disk**: the moving textured disk over a textured background from
+   `crates/engine/src/tests_roto.rs` (`draw(center(f))`, 320×240, 25 fps, 25 frames, radius
+   40 px, about 4 px a frame to the right). Export it as a PNG sequence. Its ground truth is
+   analytic (`gt(center(f))`).
+2. **Synthetic disk with a jump**: the same disk with `jumping(f)` (it jumps at frame 8). This
+   checks how each tool handles losing the object.
+3. **Two objects**: the disk plus a second still, differently coloured square that touches it
+   on some frames, prompted once with a point only and once with a box around the disk. This
+   checks the box prompt.
+4. **Real footage**: one openly licensed clip (CC0 or CC BY) with a person or object moving
+   against clutter, at least 1080p and 5 s long. Record its URL, licence and SHA-256 next to the
+   results, and keep the clip itself out of the repository.
+
+## Prompt and settings
+
+- Reference frame 0. The point at the object's centre, in layer pixels (clip 1: `[90, 110]`).
+  The box, where used, is `[centre − 55, centre + 55]` on each axis.
+- Track forward to the last frame (Frames After = clip length − 1, Frames Before = 0).
+- Matte refinement at its defaults on both sides: Feather 0, Contrast 0, Shift Edge 0, no
+  Invert. Output the matte itself (View ▸ Matte in EffectCraft, the alpha channel in After
+  Effects) as a full-resolution PNG sequence.
+- Record the After Effects build, the OS, the GPU, and the exact click position in After
+  Effects. It is a viewer click, so convert it to layer pixels with the comp's zoom.
+
+Keep the After Effects mattes in gitignored `plan/aftereffects/ref/object-matte/`. Only an
+aggregate results file (like `keyframe-ease.json`) and the comparison script may be committed.
+
+## Metrics (per frame, then mean / worst)
+
+- **IoU against After Effects**: binarize both mattes at alpha 0.5, then intersection over
+  union. This is the headline number. `effectcraft_track::roto::iou` computes it, and
+  `roto.status` already reports it for Roto Brush through `compareTo`; Object Matte needs the
+  same for exported mattes.
+- **IoU against ground truth** for the synthetic clips, for both applications. It tells
+  "differs from After Effects" apart from "worse than After Effects".
+- **Boundary error**: the mean and 95th-percentile distance (px) between the two mattes' 0.5
+  contours, which shows edge disagreement that IoU dilutes on large objects.
+- **Soft-edge error**: the mean absolute alpha difference inside a 3 px band around the After
+  Effects contour.
+- **Temporal stability**: the frame-to-frame IoU change of each matte on clip 1, where the
+  object moves rigidly, so jitter shows.
+- **Drift**: the frame where IoU against ground truth first drops below 0.9 (clips 1 and 2).
+- **Time**: seconds per frame to track the clip, warm and cold, on the same machine, with the
+  disk cache on and off.
+
+Proposed pass bar (a maintainer decision, not yet agreed): mean IoU against After Effects
+≥ 0.95 and worst ≥ 0.90 on clips 1 and 3, with MobileSAM. With the classical engine the numbers
+are reported but not gated.
+
+## Reproduce (to write)
+
+The script does not exist yet. It should: generate the synthetic clips; run EffectCraft
+headless (`effectcraft-cli run … objectMatte.apply … objectMatte.propagate {"wait":true}`, then
+render the matte); drive After Effects through ExtendScript or AEsync to apply Object Matte with
+the same prompt and render its alpha; then compute the metrics above into a JSON results file.

docs/gaps.md

@@ -70,7 +70,7 @@ are grouped by area; the issue tracker has the rest.
 | 11 | **Text rendering and layout** | Open: #453 CJK text in comps, #316 paragraph alignment inverted (maintainers' tests show Left/Right correct; asked for a project), #417 soft at Fit (mostly fixed by #444), #550 toolbar font options. Closed: #483, #583 | Text is in almost every motion graphic | 10–20 h | G2 · [ui-parity.md](ui-parity.md) |
 | 12 | **3D interaction and depth** | No 3D transform gizmos (#392, #347); camera aperture (#260); reflections (#261); extruded surface materials beyond Front / Bevel / Side / Back Color (fb5a5e9a; #315 closed); #307 reopened (the viewer's renderer button now shows and switches the renderer, #645); Z position (#489) closed | Advanced 3D is After Effects' growth area since 2023 | 20–35 h | G2 · [ui-parity.md](ui-parity.md) |
 | 13 | **3D model formats and materials** | After Effects 26 imports FBX, USD/USDZ, STL besides glTF and OBJ (`usd_plugins`), and Substance 3D materials with mesh displacement (26.0–26.2); we read glTF, OBJ, STL (binary and ASCII, with facet colours) and FBX 7.x (binary and ASCII: meshes, hierarchy, Lambert/Phong materials and textures; no FBX animation or skinning yet) | Product shots and 3D scenes come as FBX/USDZ | 25–45 h | — · [file-format-parity.md](file-format-parity.md) |
-| 14 | **Object Matte** (26.2, disk cache in 26.5) | Not present; MobileSAM is already in `effectcraft-segment` and could back it | The new one-click roto; Roto Brush covers part of it | 15–30 h | G7 · [target-app-parity.md](target-app-parity.md) |
+| 14 | **Object Matte** (26.2, disk cache in 26.5) | First slice (#783): the Object Matte effect (Effect ▸ Matte) and `objectMatte.apply` turn a point (and optional box) on a reference frame into a matte and follow the object up to 600 frames each way, or segment every frame on its own; Roto Brush's engine, cache and model (MobileSAM from Settings ▸ Roto Brush, classical graph cut without it). Since then: the Object Matte tool in the viewer (click / drag a box, hover crosshair), the box as the model's box prompt, background tracking with progress and cancel, Freeze, and segmentations kept in the disk cache (26.5). Missing: a comparison with After Effects ([plan](fidelity/object-matte.md)) | The new one-click roto | 10–20 h | G7 · [target-app-parity.md](target-app-parity.md) |
 | 15 | **Hardware video decode and encode** | No VideoToolbox, NVENC, Quick Sync or VA-API; #498 asks for it (answered: CUDA / NVENC need Nvidia's proprietary SDK through FFI, which the no-`unsafe` rule forbids); open PR #819 adds hardware decoding via `filmcraft-platform`; FilmCraft has VideoToolbox / NVENC / VA-API paths to borrow | 4K playback and export speed | 25–45 h | G5/G6 · [hardware-parity.md](hardware-parity.md) |
 | 16 | **Localization depth** | Menus in 10 languages (ja, zh-hans, zh-hant, uk, es, pt-br, ru, fr, de, cs: 624 rows each); panels in 6 (ja, zh-hans, zh-hant, uk, pt-br, cs); effect names and ~1,650 effect parameter names untranslated; Korean and Italian (After Effects ships them) absent; Hangul probe added (#599 closed) | After Effects is used heavily in Japan, China, Korea, Brazil, Europe | 60–110 h + native review | G9 · [localization-parity.md](localization-parity.md) |
 | 17 | **Media Browser lists files import refuses** | `media_browser.rs` lists AVI; `media::is_importable` has none of them (Targa and Radiance HDR import since #745; DPX and Cineon since #756, log shown as stored: no Cineon Settings conversion yet; MXF OP1a / OP-Atom since #767; FilmCraft has no AVI demuxer); #431 and #324 closed | Confusing failures on common VFX formats | 15–30 h | G6 · [file-format-parity.md](file-format-parity.md) |

docs/target-app-parity.md

@@ -122,7 +122,7 @@ compositing and effects dominate; audio is light). Hours are to full parity for
 | Text and typography | 7% | 94% | 50% | 20–35 | CJK text in comps renders wrongly (#453); paragraph alignment inverted (#316); soft text at Fit (#417, mostly fixed by #444); toolbar font options (#550); #483 and #583 are closed; variable-font filter landed (#741) |
 | Effects and animation presets | 14% | 85% | 40% | 70–130 | All 306 effects exist, but rendered output is unmeasured against After Effects; 54 built-in presets (text, Transitions, Backgrounds) against After Effects' 621 ([effects-parity.md](effects-parity.md)); open effect bugs (#580 crash, #463, #369, #473, #474; #514 and #526 are closed); effect colour labels (26.5); see [effects-parity.md](effects-parity.md) |
 | 3D (Classic and Advanced) | 6% | 82% | 35% | 35–65 | No FBX/USD/STL models, no Substance materials, mesh displacement unverified; no 3D transform gizmos (#392, #347); reflections (#261); camera aperture (#260); #489 and #315 are closed |
-| Tracking and AI-assisted tools | 5% | 80% | 35% | 35–70 | No Object Matte (26.2); Roto Brush (MobileSAM) and face tracking (MediaPipe) unmeasured against After Effects; camera-tracker view (#505) |
+| Tracking and AI-assisted tools | 5% | 80% | 35% | 35–70 | Object Matte (26.2) has the effect, the viewer tool (click / box), background tracking, Freeze and the 26.5 disk cache, not yet compared with After Effects; Roto Brush (MobileSAM) and face tracking (MediaPipe) unmeasured against After Effects; camera-tracker view (#505) |
 | Preview and cache | 7% | 92% | 40% | 25–50 | Playback stutters on cached frames (#595, #304); late audio (#504, #335); #329 and #554 are closed; no benchmark against After Effects |
 | Render queue and export | 7% | 85% | 55% | 25–45 | No hardware encoding; ProRes 4444 colour tag (#340); rendering over an existing file (#325); #446 and #372 (8-bit uncompressed QuickTime, #778) are closed; HEVC/AV1 without B-frames |
 | Audio | 2% | 85% | 45% | 6–12 | Audio sync and crackle (#335); audio to keyframes depth |
@@ -144,7 +144,7 @@ Feature depth (≈ 50%) feeds the overall *ready* number with the other dimensio
 | Stability | 45% | 40–80 | Open crash reports #580, #501, #426, #341, #234, #879 (#591, #306 and #511 are closed); no CI runs the tests on pull requests | [gaps.md](gaps.md#g3-stability-and-a-green-main) |
 | Platforms | 65% | 30–60 | Releases for macOS, Windows x64/x86/ARM64, Linux, FreeBSD and the web (more than After Effects), but Linux and Windows users hit basic bugs | [gaps.md](gaps.md#g2-real-user-reliability-on-every-platform) |
 | Ecosystem and plug-ins | 20% | 40–80 | After Effects scripts and expressions mostly carry over; no After Effects SDK plug-ins, `.ffx` presets or `.mogrt`; our WebAssembly plug-in API has no third-party plug-ins yet | [plugins.md](plugins.md) |
-| AI features | 35% | 40–80 (overlaps Tracking) | Roto Brush (MobileSAM) and face tracking (MediaPipe) as optional downloads; no Object Matte; the After Effects bundle ships Whisper, BERT and Marian tokenizers and a shot-cut model we have no equivalent of | [gaps.md](gaps.md) |
+| AI features | 35% | 40–80 (overlaps Tracking) | Roto Brush (MobileSAM) and face tracking (MediaPipe) as optional downloads; Object Matte (point / box prompt, same model; viewer tool, background tracking, Freeze, disk cache) unmeasured against After Effects; the After Effects bundle ships Whisper, BERT and Marian tokenizers and a shot-cut model we have no equivalent of | [gaps.md](gaps.md) |
 | Agent control (beyond After Effects) | ahead | — | Every command is drivable over MCP, the control channel and the CLI | [agents.md](agents.md) |
 
 **Totals.** Summing the rows double-counts: AI overlaps Tracking, performance overlaps Preview,