Keyframeable mask geometry on a PIP layer (stroke-following local retouch)

[renezander030]

Tracks the feature requested in discussion #43 (beauty-ad local retouch that follows the product on the face).

Gap: mask writes static mask geometry and keyframe animates segment transform (position/scale/rotation/alpha/volume), but mask geometry itself is not keyframeable today.

Scope: mask geometry as keyframeable properties, via keyframe --batch:

• mask position (x, y)
• mask width and height
• mask rotation
• mask feather

Split out to follow-ups, so this issue stays one reviewable piece: the PIP duplicate helper is #77, the validation report is #78. Both get easier once the mask side is settled.

Acceptance criteria:

• Mask geometry keyframes round-trip through write then read with no drift.
• Interpolation between two mask keyframes is verified against what CapCut actually renders, not only against our own writer. This is the part with the unknowns in it: the interpolation curve and the property key names are what the issue turns on.
• No change to existing keyframe behaviour for transform properties.
• Durations stay on the frame grid, per docs/draft-schema/01-tracks-and-segments.md.
• Test under test/, per CONTRIBUTING.md.

Notes: direct draft editing only (encrypted JianYing 6.0+ out of scope, already flagged by decrypt/version). The requester offered a sample draft, source video and screenshots in #43 but has not posted since 2026-07-03, so assume a self-built fixture. If bundles are shared here, generate them on v0.18.0 or later, which redacts device identifiers (#59).

[Sufiyan-MSA]

Hi, can u pls assign this to me.

[renezander030]

Hi @Sufiyan-MSA, yes. Your lint --fix work in #42 is why I am comfortable handing this one over.

One change before you start: I have split the issue rather than assigning all three bullets at once. This one now covers the first slice only, the mask geometry keyframes. The PIP duplicate helper moved to #77 and the validation report to #78, both marked as depending on this. That is the part with the real unknowns in it, and I would rather review 200 lines that answer the hard question than 600 that mix it with plumbing.

Two things worth knowing before you write code:

1. The original requester offered a sample draft and source video in Local beauty retouch with frame-by-frame mask tracking #43 but has not posted since early July, so build against a fixture you construct yourself. If the assets turn up I will attach them here.
2. v0.18.0 changed capcut fixture to redact device identifiers (fixture: bundles are not safe to share — device_id / mac_address are never redacted #59). If you share a bundle in this thread, generate it on 0.18.0 or later, since older bundles carry device_id and mac_address in the clear.

Acceptance criteria are on the issue now. The one I would start with is the second: verifying interpolation between two mask keyframes against what CapCut actually renders, not just against our own writer. The property key names and the curve are what this whole thing turns on, and finding those out early tells you whether the rest is straightforward.

Assigning you now. Shout if the split cuts across how you wanted to approach it.