Merge branch 'worktree-agent-a5b25d366383f4675'

# Conflicts:
#	docs/parity.md

docs/agents.md

@@ -105,11 +105,18 @@ effectcraft-cli run clip.ecproj track.motion '{"layer":"#2"}' \
 
 `track.mask` follows the pixels inside a mask and keys its Mask Path on every frame (vertices and
 tangents move with the fitted motion). `method` is `position`, `positionScale`,
-`positionScaleRotation` (the default, also kept as the Tracker panel's Method), `positionScaleRotationSkew`
-or `perspective`; `direction` is `forward|backward|frameForward|frameBackward` from the current
+`positionScaleRotation` (the default, also kept as the Tracker panel's Method), `positionScaleRotationSkew`,
+`perspective`, `faceOutline` (Face Tracking (Outline Only): the mask, drawn around a face, becomes
+the face outline on every frame) or `faceDetailed` (Face Tracking (Detailed Features): also keys a
+Face Track Points effect with one point per landmark — eyebrows, eyes, pupils, nose tip,
+nostrils, mouth corners and lips, chin, jaw); `direction` is `forward|backward|frameForward|frameBackward` from the current
 time (or `start` / `end` in seconds). Like `track.analyze` it runs in the background in the app
 (progress in `track.status` under `mask`, `track.stop` cancels and keeps what was tracked) and is
-one undo step; `"wait": true` blocks.
+one undo step; `"wait": true` blocks. `track.extractFaceMeasurements {layer?}` (Extract & Copy Face
+Measurements) keys a Face Measurements effect from the Face Track Points (head position, scale and
+orientation X/Y/Z, eye openness, eyebrow distance from eye, mouth openness, width and offset), puts
+those keys on the keyframe clipboard and returns them per frame plus a tab-separated `clipboard`
+text.
 
 `mask.interpolate` (Window ▸ Mask Interpolation ▸ Apply) adds in-between Mask Path keys between
 each pair of selected Mask Path keys (or the existing keys at `times`, in seconds), giving both
@@ -138,7 +145,11 @@ the app re-analyses automatically (headless: run `warp.analyze` again). Settings
 properties under the instance's groups, e.g. `effects/#1/stabilization/result` (0 Smooth Motion,
 1 No Motion), `effects/#1/stabilization/smoothness`, `effects/#1/stabilization/method`,
 `effects/#1/borders/framing` (0 Stabilize Only … 3 Stabilize, Synthesize Edges),
-`effects/#1/borders/autoScale/maximumScale`, `effects/#1/advanced/showTrackPoints`.
+`effects/#1/borders/autoScale/maximumScale`, `effects/#1/advanced/showTrackPoints`. Method 3
+(Subspace Warp, the default) bends a mesh per frame to the smoothed feature trajectories, so
+scenes with depth stabilise where one perspective transform cannot;
+`effects/#1/advanced/rollingShutterRipple` (0 Automatic Reduction, 1 Enhanced Reduction: a finer,
+softer mesh) tunes it.
 
 ```sh
 effectcraft-cli run shaky.ecproj track.warpStabilizer '{"layer":"#1","wait":true}' \
@@ -150,13 +161,17 @@ effectcraft-cli exec warp.status '{"layer":"#1"}' shaky.ecproj --json
 ### 3D Camera Tracker
 
 Animation ▸ Track Camera and the Tracker panel's button (`track.camera {layer?, shotType?:
-fixed|variable|specify, aov?, solveMethod?: auto|typical|flat|tripod, detailed?, wait?}`) apply
+fixed|variable|specify, aov?, solveMethod?: auto|typical|flat|tripod, detailed?, lensDistortion?,
+undistort?, wait?}`) apply
 Effect ▸ Perspective ▸ 3D Camera Tracker (or reuse the layer's) and analyse it in the background:
 "Analyzing in background (step 1 of 2)" tracks features, "Solving camera" solves.
 `camera.analyze {layer?, effect?, wait?}` re-runs it, `camera.cancel` stops it without writing
 anything. `camera.solveStatus` reports `progress`/`banner`, `analyzed`, `solved`, `methodUsed`,
 `averageError` (pixels), `focalLength`, `horizontalAngleOfView`, the current frame's `camera`
-(position, orientation, zoom) and `groundPlane`. `camera.points {time?}` lists the solved points
+(position, orientation, zoom), `groundPlane` and the solved `lensDistortion` (`k1`, `k2`, normalised by
+half the frame diagonal) when Solve Lens Distortion (`effects/#1/advanced/lensDistortion`, also on
+with Detailed Analysis) is on; `effects/#1/advanced/undistort` renders the footage undistorted so
+the solved camera's 3D layers line up. `camera.points {time?}` lists the solved points
 visible now with their `id`, `comp` position, `depth`, `world` position and `error`.
 
 Select points with `camera.selectPoints {points, add?, toggle?}` (the viewer's click / Shift-click /

docs/architecture.md

@@ -229,6 +229,13 @@ tracks them with pyramidal Lucas–Kanade and fits the chosen model (position
 RANSAC; the motion moves the Mask Path's vertices and tangents and is keyed per frame. **Mask
 Interpolation** (`mask.interpolate`) uses `effectcraft-path`'s smart interpolation (arc-length
 vertex insertion, shape-context matching, rigid in-betweens) to key in-between shapes.
+The two **Face Tracking** methods (`effectcraft_track::face`) fit a face inside the mask instead:
+a skin colour model from the first frame, the face outline along rays from the skin component's
+centre (an area-moment ellipse gives centre, size and roll), facial features as the non-skin
+components inside it, and an active-shape point distribution model trained on synthetic face
+shapes (our own generator, no external weights) that fills and checks the landmarks. The outline
+keys the Mask Path; Detailed Features keys a Face Track Points effect, and
+`track.extractFaceMeasurements` derives a keyed Face Measurements effect (and copies its keys).
 
 **Warp Stabilizer** (`effects::warp_stab`, `engine::warp`): `warp.analyze` renders the layer's
 input to the effect (`Renderer::layer_input`: source, masks and the effects above it) for every
@@ -237,7 +244,10 @@ translation / similarity / homography fits) as JSON in the effect's hidden Analy
 with a key of the layer's source, In/Out, start, stretch and Time Remap. `Session::edit` clears
 analyses whose key no longer matches and queues them; the desktop app re-analyses them in the
 background. Rendering derives the stabilization plan (smoothed camera path or No Motion, framing,
-auto-scale; cached per analysis and settings) and warps each frame; Synthesize Edges fills the
+auto-scale; cached per analysis and settings) and warps each frame. Subspace Warp also stores long
+feature trajectories in the analysis, smooths them in a low-rank subspace (Liu et al. 2011) and
+warps each frame with a content-preserving mesh (Liu et al. 2009) fitted to the smoothed
+positions, rendered as a per-pixel mesh lookup; Synthesize Edges fills the
 borders from neighbouring frames read with `EffectHost::self_at`. The effect lives in the
 effects crate, hence the `effects → track` edge.
 
@@ -268,7 +278,10 @@ the essential matrix (normalised 8-point in RANSAC) or a planar homography decom
 resection and triangulation; a sparse Levenberg–Marquardt bundle adjustment (Schur complement over
 the points, Huber loss) with the focal length fixed, shared, or per frame; a log-spaced and
 golden-section focal search for Fixed Angle of View / Variable Zoom; a rotation-only model for tripod
-pans, chosen by Auto Detect when it explains the tracks as well. Tracks and solve are stored as JSON
+pans, chosen by Auto Detect when it explains the tracks as well; with Solve Lens Distortion (or
+Detailed Analysis) radial distortion `k1, k2` is adjusted jointly in a final bundle adjustment on
+the raw tracks and the solve repeated on tracks undistorted with that estimate; Undistort Footage
+renders the input through the inverse model. Tracks and solve are stored as JSON
 in hidden effect parameters with keys: changing the layer's frames clears both, changing Shot Type,
 Angle of View, Solve Method or deleting points only re-solves. The solve's canonical frame maps to
 comp space so the first frame's camera is the default comp camera (or so a chosen ground plane is

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 304 effects with 2446 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 306 effects with 2488 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**: 59 effects also run on the GPU compositor with identical results.
-- **32**: 304 effects process 32-bit float (HDR, overbright) pixels without clamping.
-- **Status**: 262 implemented in full, 42 partial (what is missing is listed).
+- **32**: 306 effects process 32-bit float (HDR, overbright) pixels without clamping.
+- **Status**: 264 implemented in full, 42 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`).
 
@@ -302,7 +302,7 @@ Effects are addressed by id (`ec.<category>.<name>`) or display name in commands
 
 | Effect | Id | Params | GPU | 32 | Status |
 |---|---|---:|:-:|:-:|---|
-| 3D Camera Tracker | `ec.perspective.cameratracker` | 10 |  | 32 | Implemented |
+| 3D Camera Tracker | `ec.perspective.cameratracker` | 12 |  | 32 | Implemented |
 | 3D Glasses | `ec.perspective.3dglasses` | 8 |  | 32 | Implemented |
 | Bevel Alpha | `ec.perspective.bevelalpha` | 4 |  | 32 | Implemented |
 | Bevel Edges | `ec.perspective.beveledges` | 4 |  | 32 | Implemented |
@@ -416,6 +416,8 @@ Effects are addressed by id (`ec.<category>.<name>`) or display name in commands
 | CC Overbrights | `ec.utility.ccoverbrights` | 2 |  | 32 | Implemented |
 | Cineon Converter | `ec.utility.cineon` | 7 |  | 32 | Implemented |
 | Color Profile Converter | `ec.utility.colorprofileconverter` | 7 |  | 32 | Implemented |
+| Face Measurements | `ec.utility.facemeasurements` | 14 |  | 32 | Implemented |
+| Face Track Points | `ec.utility.facetrackpoints` | 26 |  | 32 | Implemented |
 | Grow Bounds | `ec.utility.growbounds` | 1 |  | 32 | Implemented |
 | HDR Compander | `ec.utility.hdrcompander` | 3 |  | 32 | Implemented |
 | HDR Highlight Compression | `ec.utility.hdrcompression` | 1 |  | 32 | Implemented |

docs/parity.md

@@ -17,12 +17,12 @@ How close EffectCraft is to After Effects 2026, feature by feature, and how much
 
 By area: Layers 98%, Output 95%, Compositions 95%, Automation 96%, Paint 95%, Text 95%, Import 96%,
 Animation 94%, Masks 94%, Preview 94%, Interface 93%, Shapes 93%, 3D 91%, Audio 90%, Project 90%,
-Tracking 88%, Effects 85%, Web 65%.
+Tracking 96%, Effects 85%, Web 65%.
 
 What is left, in priority order: the web app's depth (threads, storage, audio, non-blocking
 renders); stroke taper/wave and multi-segment dashes; variable mask feather points; camera iris/bokeh and focus-link commands; Render Queue field render, crop/resize and templates;
-approximated effects (Subspace Warp, Key Cleaner) and Liquify's viewer brush; text in imported
-PDF/AI files and Illustrator procset EPS; more codecs; 59 preferences not yet wired; ScriptUI; face tracking; and the "better than After Effects" items (a plug-in API, branching history; GPU particles landed in M12.7).
+approximated effects (Key Cleaner) and Liquify's viewer brush; text in imported
+PDF/AI files and Illustrator procset EPS; more codecs; and the remaining "better than After Effects" items (ScriptUI, the plug-in API and branching history landed in M13.1; face tracking and Subspace Warp in M13.3; GPU particles in M12.7).
 
 The sections below are the original audit (morning of 2 October, ≈ 64%) and its updates, kept for
 history.
@@ -122,7 +122,7 @@ the disk cache in the formats wave; the 3D Camera Tracker in M12.6.)
 | Project | ≈ 68% | 5.5 | auto-save, folder moves, OCIO displays beyond the built-in tone map (Color Engine with OCIO/ACES working spaces, HDR compand/tone mapping, Rec. 2100 PQ/HLG output, Feet + Frames, display colour management, Simulate Output and the locked viewer landed in M7.7; proxies and Interpret Footage fields / pixel aspect / alpha guess landed: PRJ-8, PRJ-3) |
 | Masks & roto | 74% | 5.0 | Roto Brush's learned (3.0) segmentation model (variable-width mask feather points with the Mask Feather tool landed in M13.5; 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 | 66% | 4.0 | GPU bokeh depth of field, wireframes and Advanced 3D compositing (Classic 3D runs and adjustment layers composite on the GPU since M12.7; persistent disk cache with the blue cache bar landed; region of interest, snapshots, exposure and Fast Previews landed in M0.13) |
-| Tracking | ≈ 85% | 2.5 | face tracking, Subspace Warp's mesh warp, lens distortion in the camera solve (Rolling Shutter Repair landed in M9.11; point tracker, mask tracking, Warp Stabilizer and the 3D Camera Tracker landed in M6.x / M12.5 / M12.6) |
+| Tracking | ≈ 96% | 0.3 | face tracking is a classical (skin model + feature components + shape model) fitter, not a learned detector: profile views and occluded faces are weak; Rolling Shutter Ripple is approximated by Subspace Warp's mesh density (face tracking (Outline Only / Detailed Features with Face Track Points and Extract & Copy Face Measurements), Subspace Warp's content-preserving mesh warp on subspace-smoothed trajectories, and radial lens distortion (k1, k2) in the camera bundle adjustment with Undistort Footage landed in M13.3; Rolling Shutter Repair in M9.11; point tracker, mask tracking, Warp Stabilizer and the 3D Camera Tracker in M6.x / M12.5 / M12.6) |
 | Paint | 0% | 4.0 | Brush, Clone Stamp, Eraser |
 
 ## Effects still missing