fablecut 1.13.0 → 1.14.0

package/CLAUDE.md

@@ -177,8 +177,10 @@ Reusable assets, visible in the editor's left-panel tabs and never copied:
 | `library/elements/` | **Elements** | overlay art: alpha PNGs, light leaks, textures, stickers |
 | `library/svg/`      | **SVG**      | animated vector graphics **you author** (convention below) |
 | `library/fonts/`    | font editor  | `.ttf/.otf/.woff/.woff2`, auto-registered, family name = file name; a variable font draws every `weight` |
+| `library/presets/`  | Inspector → Motion → Presets | saved animation presets, one `.json` each (see "Presets and templates") |
+| `library/templates/`| **Templates** | saved templates, one `.json` each, listed after the built-in ones |
 
-- List via `GET /api/library?dir=sfx|elements|svg|fonts` (recursive; subfolders OK).
+- List via `GET /api/library?dir=sfx|elements|svg|fonts|presets|templates` (recursive; subfolders OK).
 - To use one in the timeline, add a media entry whose `src` is its library path,
   e.g. `{ "id":"m_x", "name":"whoosh.mp3", "kind":"audio", "src":"/library/sfx/whoosh.mp3" }`
   — then reference it from clips like any other media.
@@ -266,6 +268,8 @@ Examples in `library/svg/`: `sparkles.svg` (loop), `lower-third.svg`,
     { "id": "A4", "kind": "audio" }
   ],
   "buses": [ { "id": "B1", "name": "Dialogue", "gain": -2, "fx": [ { "type": "compressor" } ] } ],
+  "comps": [ { "id": "lt", "name": "Lower third", "width": 1280, "height": 720, "duration": 5, "clips": [ /* … */ ] } ],
+  // ^ optional — compositions (nested sequences), placed with kind:"comp" clips; see "Compositions (nested sequences)"
   // ^ optional — submix buses B1…B8: name, gain (dB), pan, mute, fx; tracks route in with `out`
   "media": [
     { "id": "m_abc", "name": "intro.mp4", "kind": "video",  // video|audio|image|svg
@@ -278,8 +282,9 @@ Examples in `library/svg/`: `sparkles.svg` (loop), `lower-third.svg`,
   "clips": [
     {
       "id": "c_xyz",             // unique string
-      "mediaId": "m_abc",        // null for kind:"text" and kind:"adjust"
-      "kind": "video",           // video | audio | image | svg | text | adjust
+      "mediaId": "m_abc",        // null for kind:"text", "adjust", "shape", "null" and "comp"
+      "kind": "video",           // video | audio | image | svg | text | adjust | shape | null | comp
+      // kind:"comp" also has "compId" (a comps[] entry) — see "Compositions (nested sequences)"
       "track": "V1",             // Vn…V1 (video) | A1…An (audio); extras via UI +V/+A or tracks[]
       "start": 0,                // timeline position, seconds
       "in": 2.5,                 // offset into source media, seconds (0 for image/svg/text)
@@ -289,10 +294,13 @@ Examples in `library/svg/`: `sparkles.svg` (loop), `lower-third.svg`,
       "locked": true,            // OPTIONAL — locked by the user: leave it alone (MCP patch refuses edits)
       "disabled": true,          // OPTIONAL — stays on the timeline, hidden from preview / audio / export
       "unlinked": true,          // OPTIONAL — the user unlinked this clip; never auto-relinked on load
+      "parent": "c_null",        // OPTIONAL — moves, turns and scales with that clip (see "Shapes, nulls and parenting")
       "props": { /* all optional — see the props reference below */ },
       // OPTIONAL — keyframe animation. Times are seconds RELATIVE TO CLIP START.
       // "ease" sits on the DESTINATION keyframe of each segment:
       // linear | ease-in | ease-out | ease-in-out (default ease-in-out).
+      // x and y keys at the same time are a position key; pin / pout on them (px)
+      // are motion-path curve handles (see "Motion paths, motion blur and text on a path").
       "keyframes": {
         "scale":   [ { "t": 0, "v": 1 }, { "t": 5, "v": 1.25, "ease": "linear" } ],
         "opacity": [ { "t": 0, "v": 0 }, { "t": 0.8, "v": 1 } ]
@@ -316,6 +324,9 @@ Examples in `library/svg/`: `sparkles.svg` (loop), `lower-third.svg`,
 | `scale` | 1 | |
 | `rotation` | 0 | degrees |
 | `opacity` | 1 | 0–1 |
+| `anchorX`, `anchorY` | 0 | anchor point, px from the picture's centre: the point `x`/`y` place and `rotation`/`scale` turn around |
+| `autoOrient` | false | turn the clip with its direction of travel along its motion path (`rotation` adds on top) |
+| `motionBlur` · `motionBlurSamples` | 0 · 8 | motion blur: shutter angle in degrees (0 = off, 180 = film look, up to 720) · sub-frame samples 2–32 |
 | `blend` | "normal" | how the clip lays over what is under it (see Track mattes and blending) |
 | `matte` · `matteTrack` | — | a track matte (see Track mattes and blending) |
 
@@ -390,6 +401,8 @@ These are quick looks. For real grading use `props.grade` (see "Color" below).
 | `bgColor` `bgOpacity` | "#000", 0 | rounded pill behind each line |
 | `textAnim` | "none" | typewriter · word-pop · word-slide · karaoke · **letter-pop** (per-character entrance; Arabic/Indic auto-fallback to per-word clusters so joined letters shape correctly) · **wave** (looping per-character ride; same shaping fallback) · **bounce** (looping per-word hop) · **shake** (looping jitter) · **clip-reveal** (wipe-mask sweep, per line) · **zoom-in** (scale + opacity settle) · **font-cut** (rhythmically swaps typeface, then settles — see `fontCutSet`) · **rise-mask** (line rises from behind its baseline, lower-third reveal) |
 | `wordRate` | 0.15 | seconds per word (typewriter: /4, letter-pop: /3 per character); also staggers `clip-reveal`/`zoom-in`/`rise-mask` per line |
+| `textPath` | — | set the title along a path: one shape item (`path`, `line`, `ellipse`, `rect`, `polygon`, `star`) whose outline is the baseline; more lines follow on parallel curves below it. See "Motion paths, motion blur and text on a path" |
+| `pathOffset` · `pathAlign` | 0 · "start" | where along the path the text sits (% of its length, keyframable, wraps on closed paths) · which end of the text sits there: start · center · end |
 | `fontCutSet` | (curated) | array of font family names cycled by `font-cut`, e.g. `["Anton","Bebas Neue","Archivo Black","Oswald"]`; each is auto-loaded |
 
 **Title styles (one-tap cohesive looks).** Text clips created in the UI now
@@ -432,7 +445,16 @@ footage. Example: 0.3 s impact shake over everything =
 shows — rect, ellipse, bezier, free-hand; feather, expand, invert, add /
 subtract / intersect, keyframes. See "Masks" below.
 
-**Animatable props** (usable in `keyframes`): x, y, scale, rotation, opacity,
+**Shape layers** (`kind:"shape"`): `props.shapes` (rectangles, ellipses,
+polygons, stars, lines, bezier paths, groups) and `trimStart` / `trimEnd` /
+`trimOffset` (%, a draw-on of every path). **Null objects** (`kind:"null"`)
+never render; other clips are parented to them. See "Shapes, nulls and parenting".
+
+**Comp clips** (`kind:"comp"`, `compId`): a composition placed as one clip — it
+draws like a picture of the comp's size (`fit` defaults to `none`) and its media
+plays and exports. See "Compositions (nested sequences)".
+
+**Animatable props** (usable in `keyframes`): x, y, scale, rotation, opacity, anchorX, anchorY, trimStart, trimEnd, trimOffset, pathOffset,
 volume, pan, duck, speed, brightness, contrast, saturation, hue, blur, grayscale, sepia,
 invert, temperature, tint, vignette, cornerRadius, shake, rgbSplit, grain,
 fontSize, letterSpacing, glow.
@@ -925,6 +947,405 @@ track the screen with Scale and Rotate on and attach the new picture, cropped
 to fit; **a highlight that stays on a UI element** in a screen recording —
 track the button, attach a rect svg.
 
+### Shapes, nulls and parenting
+
+Motion graphics are built from three pieces: **shape layers** (vector shapes
+drawn by the editor, crisp at any size), **null objects** (invisible layers that
+carry a transform) and **parenting** (a clip moves, turns and scales with
+another clip). Every visual clip also has an **anchor point**. All of it runs
+the same in preview and export.
+
+**Shape layers.** A clip with `kind:"shape"` (no `mediaId`) draws
+`props.shapes`, a list drawn bottom-up (first = bottom):
+
+```jsonc
+{ "id": "c_lt", "kind": "shape", "mediaId": null, "track": "V2", "start": 0, "duration": 5,
+  "props": { "x": -300, "y": 220, "shapes": [
+    { "type": "rect", "name": "Bar", "w": 520, "h": 90, "radius": 12, "fill": "#ffd166",
+      "keys": [ { "t": 0, "w": 0 }, { "t": 0.6, "w": 520, "ease": "ease-out" } ] },
+    { "type": "line", "y": 60, "points": [[-260, 0], [260, 0]], "stroke": "#ffffff", "strokeWidth": 6,
+      "keys": [ { "t": 0.3, "trimEnd": 0 }, { "t": 1.1, "trimEnd": 100 } ] },
+    { "type": "group", "x": 300, "items": [
+      { "type": "star", "sides": 5, "inner": 0.45, "w": 80, "h": 80, "fill": "#ff7ac8" },
+      { "type": "ellipse", "w": 120, "h": 120, "fill": "none", "stroke": "#ff7ac8", "strokeWidth": 4 } ],
+      "keys": [ { "t": 0, "rotation": 0 }, { "t": 5, "rotation": 360, "ease": "linear" } ] }
+  ] } }
+```
+
+| key | default | does |
+|---|---|---|
+| `type` | `rect` | `rect` · `ellipse` · `polygon` · `star` · `line` · `path` · `group` |
+| `x` · `y` | 0 | position in layer px, from the layer's origin (the clip's `x`/`y`, y down) |
+| `rotation` · `scale` · `opacity` | 0 · 1 · 1 | about the item's own `x, y` |
+| `w` · `h` | 200 | size, px (rect, ellipse, polygon, star) |
+| `radius` | 0 | rect corner radius, px |
+| `sides` · `inner` | 6 / 5 · 0.5 | polygon / star point count (3–64); a star's inner radius as a fraction of the outer |
+| `points` | — | line: exactly 2 · path: 2–128 points `[x, y]` or `[x, y, inX, inY, outX, outY]` (curve handles relative to the point), px around the item's `x, y` |
+| `closed` | true | path only; `false` leaves it open (lines are always open) |
+| `fill` · `stroke` | `#ffffff` · `none` | `"#rrggbb"`, `"#rrggbbaa"` or `"none"`; lines and open paths default to a white stroke and no fill |
+| `strokeWidth` | 6 (8 open) | px; set with `stroke` |
+| `lineCap` · `lineJoin` | `round` · `round` | `butt` · `round` · `square` / `miter` · `round` · `bevel` |
+| `dash` | — | `[on, off, …]` px, e.g. `[24, 12]` |
+| `trimStart` · `trimEnd` | 0 · 100 | the part of the outline drawn, % — key `trimEnd` 0→100 to draw a path on |
+| `trimOffset` | 0 | % of the outline the drawn part is shifted round by (key it to make a dash run round a loop) |
+| `items` | — | group only: its items. A group moves, turns, scales, fades and trims them together (groups nest 4 deep) |
+| `name` · `on` | — | a label (agents address items by it); `on:false` hides it |
+| `keys` | — | `[{t, ease?, …}]`, `t` in seconds from the clip's start. Keyable: `x y rotation scale opacity w h radius inner strokeWidth trimStart trimEnd trimOffset fill stroke points`. Each value eases between the keys that set it (`ease` on the arriving key); colours blend; `points` keys morph the path and need its point count |
+
+At most 64 items per layer (group children included). The layer itself is a
+normal visual clip: its `x`, `y`, `scale`, `rotation`, `opacity`, `blend`,
+masks, transitions and keyframes all work, as do `blur` and `shake`. Its own
+`trimStart` / `trimEnd` / `trimOffset` (clip props, keyframable) trim every
+path in it at once. A trimmed shape fills the part that is drawn.
+
+**Null objects.** `kind:"null"` (no `mediaId`) is a clip that never renders.
+Give it `x`, `y`, `rotation`, `scale` (and keyframes), and parent clips to it to
+move them as one. The monitor shows it as a red square while it is on screen.
+
+**Parenting.** `"parent": "<clip id>"` (top-level, next to `track`) makes a
+clip move, turn and scale with that clip. Its own `x`/`y` are then measured
+in the parent's space: from the parent's centre, turned and scaled with it.
+Parents chain (a parent can have a parent), and loops are refused. Only the
+transform follows: the parent's opacity, transitions, shake and effects do
+not, and the parent's keyframes are read even outside its time range (held
+at its first or last value). Splitting a parent leaves the children on the
+left half.
+
+**Anchor point.** `anchorX` / `anchorY` (px from the picture's centre, for any
+visual clip) pick the point that `x`/`y` place and that `rotation` and `scale`
+turn around: `anchorY: 200` on a 400 px tall shape spins it about its bottom
+edge. Moving the anchor without moving the picture means changing `x`/`y`
+with it (the editor's anchor tool does that).
+
+In the editor: the bin's **Shapes** tab adds a rectangle, ellipse, polygon,
+star, line or pen-path layer, or a null object, at the playhead. The **Shape layer** section lists the
+items; pick one to edit it — the sliders, Fill / Stroke (colour or **None**),
+ends and joins, trim, **Group** / **Ungroup** / **Out**, ↑ ↓, **Copy**,
+**Delete** — and on the monitor drag it to move, the knob to turn it (Shift:
+15°) and the corners to resize it. On a line or path, drag points and their
+handles (Alt breaks the pair, Alt-drag pulls new handles); on a path,
+Ctrl-click the outline to add a point and double-click one to remove it.
+**Pen** draws a new path: click points (drag to curve), click the first point
+to close it or press Enter to keep it open. Each value has its own **◆**: key
+it at the playhead, and from then on changing it keys it. Every visual clip's
+Transform section has **Anchor** (**✥ Move**: drag on the monitor to move the
+anchor point while the picture stays put, Shift snaps to the centre;
+**Centre** puts it back) and **Parent**. Right-click clips → **Parent to a
+new null** groups them under a fresh null at their centre.
+
+**Agents:**
+
+- Add a layer with `addClip {kind:"shape", track, start, duration, props:{shapes:[…]}}`,
+  a null with `addClip {kind:"null", track, start, duration, props:{x, y}}`.
+- `{op:"setShape", id, set:{type:"rect", w:400, h:80, fill:"#ffd166"}}` adds an
+  item (no `shape`, an index one past the end or a new name adds one; a new
+  item needs `type`). `{op:"setShape", id, shape:"Bar", set:{fill:"#22d3ee"}}`
+  edits one — by index (0 = first), name, or a path into groups like `"2.0"`
+  (item 0 of group 2; `"2.3"` with 3 items adds one there) — merging key by
+  key (`null` resets a key; a new `type` keeps the position and paint).
+  `replace:true` starts it over. `keys` in `set` replaces its keys.
+  `{op:"removeShape", id, shape}` deletes one. `ids:[…]` edits several clips.
+- `{op:"setParent", id | ids, parent:"c_null"}` parents clips and keeps them
+  where they are on screen (at time `at`, default each clip's start; keyed
+  channels are left as they are). `keep:false` keeps the numbers instead.
+  `parent:null` unparents. Removing a parent clip unparents its children
+  where they stand.
+- `props.shapes` and `parent` written through `addClip` / `updateClip` are
+  validated the same way; bad input refuses the whole patch. The compact
+  view lists a layer as `[3 shapes: rect #ffd166 2 keys, line stroke #ffffff/6, group(star(5) #ff7ac8)]`
+  and a child as `parent:c_null`.
+
+Recipes: **draw-on logo** — the logo as `path` items with a stroke and no fill,
+`trimEnd` keyed 0→100 (stagger the items' keys), then `fill` keyed from
+`"#ffffff00"` to `"#ffffff"`; **lower third** — a `rect` bar whose `w` keys
+from 0, a `line` drawn on under it, a title on the track above parented to the
+shape layer so they slide out together; **loading ring** — an ellipse with a
+stroke, `trimEnd: 25`, `trimOffset` keyed 0→100 with `ease:"linear"`;
+**orbit** — a null at the centre with `rotation` keyed 0→360, a shape parented
+to it with `x: 300`; **swing from the top** — `anchorY` at the top edge
+(minus half the height) and `rotation` keyed −10↔10; **burst** — a group of
+lines at different `rotation`s with `scale` keyed 0→1 and `opacity` 1→0.
+
+### Motion paths, motion blur and text on a path
+
+**Motion paths.** When `keyframes.x` and `keyframes.y` both have a key at the
+same time, that is a **position key**. Give position keys curve handles and
+the clip travels along a bezier path between them instead of a straight line.
+The handles are `pin` (arriving) and `pout` (leaving) on the x and y keys,
+in px relative to the key's position, in the clip's `x`/`y` space:
+
+```jsonc
+"keyframes": {
+  "x": [ { "t": 0, "v": -450, "pout": 250 }, { "t": 2, "v": 0, "pin": -250, "pout": 250 }, { "t": 4, "v": 450, "pin": -250 } ],
+  "y": [ { "t": 0, "v": 150, "pout": -300 }, { "t": 2, "v": 0 },                        { "t": 4, "v": 150, "pin": -300 } ]
+}
+```
+
+Between two position keys the clip moves along the curve at the pace of the
+arriving key's `ease`, measured along the curve, so a `linear` key gives an
+even speed around a bend. A segment with an extra x or y key inside it, or
+with no handles, runs the channels as before. `autoOrient: true` turns the
+clip to face its direction of travel, and its `rotation` adds on top. A
+parent on a curved path carries its children along it.
+
+**Motion blur.** `motionBlur` is a shutter angle: the clip is drawn at
+`motionBlurSamples` moments across `motionBlur / 360` of a frame, centred on
+the frame, and the samples are averaged. 180 is the film look; 360 smears a
+whole frame. It blurs whatever changes: position, scale, rotation, a parent's
+motion, keyed shapes and trims. A clip that does not move draws once. During
+playback the preview uses as many samples as fit in the frame time (all of them
+on a fast machine); a paused frame and export always use them all. It works on
+video, image, svg, text and shape clips.
+
+**Text on a path.** `textPath` on a text clip is one shape item (`path`, `line`,
+`ellipse`, `rect`, `polygon` or `star`, with the same geometry keys and
+`keys` as in "Shapes, nulls and parenting", but no paint or trim) whose
+outline is the baseline, in the title's own px. The first line of text runs
+along it, each letter turned with the path; each further line (`\n`) runs on a
+parallel curve one line-height below, so its letters space by that curve's own
+length. `pathOffset` (% of the path's length, keyframable) is where the text
+sits, and `pathAlign` says which end of each line sits there. On a closed path
+the text wraps around; keying `pathOffset` 0 → 100 sends it once around a
+circle. Every text animation plays along the path. Font, size, colour,
+gradient, stroke, glow, shadow, `lineHeight` and `letterSpacing` all apply;
+text boxes and `align` do not (`pathAlign` takes their place).
+
+```jsonc
+{ "kind": "text", "props": { "text": "AROUND AND AROUND • ", "font": "Anton", "fontSize": 40, "letterSpacing": 4,
+  "textPath": { "type": "ellipse", "w": 300, "h": 300 }, "pathAlign": "start" },
+  "keyframes": { "pathOffset": [ { "t": 0, "v": 0 }, { "t": 6, "v": 100, "ease": "linear" } ] } }
+```
+
+In the editor: when the selected clip has two or more position keys, its path
+shows on the monitor: the curve, a dot per frame (their spacing is the speed),
+a square per key and the keys' handles. Drag a key to move it, drag a handle to
+bend the path (Alt breaks the pair), Alt-drag a key to pull new handles, and
+double-click a key to make it a corner again. Moving the clip on the monitor
+or typing X / Y keys both channels together. The Inspector's **Motion**
+section has **Smooth** (handles through every position key), **Straight**,
+**Auto-orient**, **Motion blur** and **Blur samples**. A title's **Text path**
+section sets it on a **Line**, **Arc**, **Circle**, **Wave** or a **Pen** path
+(click points, drag to curve, Enter to finish, click the first point to close
+it). **Edit path** shows the path's points on the monitor, and **Offset** and
+**Align** place the text along it.
+
+**Agents:**
+
+- Write `pin` / `pout` on x / y keys directly, or
+  `{op:"setMotionPath", id | ids, path:"smooth" | "straight", autoOrient?: true}`.
+  `"smooth"` needs the position keys first (x and y keyed together at two or more times).
+- Motion blur: `updateClip` with `props:{motionBlur:180, motionBlurSamples:12}`.
+- `{op:"setTextPath", id | ids, path:"line" | "arc" | "circle" | "wave" | {type:"path", points:[…], closed:false, …} | null, offset?, align?}`
+  sets, replaces or removes (`null`) a title's path; animate `pathOffset` with
+  keyframes.
+- These are validated on `addClip` / `updateClip` too. The compact view shows
+  `path:curved` after a clip's keyframes, and a title's `"textPath":"ellipse 300×300"`.
+
+Recipes: **fly-in on a curve** — two position keys, `setMotionPath` smooth,
+`autoOrient:true`, `motionBlur:180`; **orbiting label** — circle `textPath`,
+`pathOffset` keyed 0 → 100 linear; **stamp along a road** — an open `path`
+textPath that follows the shape in the footage, `pathAlign:"center"`,
+`textAnim:"letter-pop"`; **whip without the transition** — a fast `x` move over
+4–6 frames with `motionBlur:360`.
+
+### Compositions (nested sequences)
+
+A **composition** (comp) is a timeline of its own, with its own size, length,
+tracks and clips, that is placed on the main timeline (or inside another comp)
+as one clip. Build a lower third, a logo sting or a whole scene once, then use
+it as many times as you like: every clip that shows the comp changes when the
+comp is edited. Comps live in `project.comps`:
+
+```jsonc
+"comps": [
+  { "id": "lt", "name": "Lower third", "width": 1280, "height": 720, "duration": 5,
+    "background": "#00000000",   // optional; leave it out for transparent
+    "tracks": [ { "id": "V2", "kind": "video" }, { "id": "V1", "kind": "video" }, { "id": "A1", "kind": "audio" } ],
+    "clips": [
+      { "id": "bar", "kind": "shape", "track": "V1", "start": 0, "duration": 5, "props": { "shapes": [ … ] } },
+      { "id": "name", "kind": "text", "track": "V2", "start": 0.3, "duration": 4.7, "props": { "text": "Ada Lovelace" } },
+      { "id": "whoosh", "kind": "audio", "mediaId": "m_whoosh", "track": "A1", "start": 0, "in": 0, "duration": 0.6 }
+    ] }
+],
+"clips": [
+  { "id": "c_lt1", "kind": "comp", "compId": "lt", "mediaId": null, "track": "V3", "start": 4, "in": 0, "duration": 5,
+    "props": { "fit": "none", "y": 220 } }
+]
+```
+
+| key | default | does |
+|---|---|---|
+| `id` · `name` | — · the id | how clips and agents refer to it · the label shown on its clips and in the bin |
+| `width` · `height` | the project's | the comp's frame, px (16…8192) |
+| `duration` | — | seconds; what the comp shows past its clips is transparent (or its `background`) |
+| `background` | none | a colour behind the comp's clips; leave it out for transparent |
+| `tracks` | V3…V1, A1, A2 | the comp's own lanes, like the project's `tracks` |
+| `clips` | [] | ordinary clips of any kind (comp clips too), with times inside the comp |
+| `template` | — | set on a placed template: `{id, hold, fields}` (see "Presets and templates") |
+
+**A comp clip** (`kind:"comp"`, `compId`, no `mediaId`) shows the comp from its
+`in` (comp seconds) for its `duration`, at speed 1. It draws like a picture of
+the comp's size: `fit` defaults to `none` (the comp's own pixels), and its
+transform, keyframes, opacity, transitions, masks, track matte, blend, grade and
+filters all apply to the comp's frame as a whole. Trims and splits move its
+`in` like a video clip's; the window can't run past the comp's length.
+
+The media inside a comp **plays and exports as if it were on the timeline**:
+its video frames, and its audio, which goes through the main timeline's audio
+track of the same name (its fader, effects and bus). A comp clip that is
+disabled, or sits on a disabled track, silences the comp's audio too. Comps
+nest up to 4 deep, and a comp can never contain itself.
+
+In the editor: the bin's **Project** tab lists the comps; drag one onto the
+timeline to place it, and double-click it (or a comp clip, or **Open** in the
+Inspector's **Composition** section) to open it. An open comp takes over the
+timeline: every tool, shortcut and inspector works on its clips, and the
+breadcrumb above the timeline (or **Esc**, once nothing is selected) goes back
+out. Right-click clips → **Precompose** moves them into a new comp and puts a
+comp clip in their place; right-click the Project tab → **New composition**
+starts an empty one. The Composition section also sets the comp's name, size,
+length and background.
+
+**Agents:**
+
+- `{op:"addComp", comp:{id?, name, duration, width?, height?, background?, tracks?, clips?:[…]}}`
+  adds one (its clips go through the same checks as `addClip`).
+  `{op:"updateComp", id, set:{name?, width?, height?, duration?, background?, tracks?}}`
+  changes it; `{op:"removeComp", id}` is refused while a clip still uses it.
+- Place it with `addClip {kind:"comp", compId, track, start, duration, in?}`.
+- `{op:"inComp", comp, ops:[…]}` runs clip and timeline ops on the comp's own
+  clips: `addClip`, `updateClip`, `removeClip`, `split`, `rippleDelete`, the
+  trims, `setShape`, `setMask`, `setGrade`, `setParent`, `setMotionPath`,
+  `setTextPath`, clip `setFx`, `precompose`, and `inComp` for a comp inside it.
+- `{op:"precompose", ids:[…], name?, id?}` moves those clips (here, or in the
+  comp an `inComp` is running in) into a new comp that starts at the earliest
+  of them; a comp clip of the same length takes their place.
+- The compact view shows a comp clip as `comp(lt in:1.5)` and lists every comp
+  under `COMPS` with its clips.
+
+Recipes: **reusable lower third** — a template (next section) gives every
+speaker their own copy with their own name; a plain comp suits a graphic that
+is the same every time; **logo sting** — a draw-on logo comp at the head and tail of the edit;
+**picture in picture of a whole scene** — precompose the scene's clips, then
+scale the comp clip down and move it into a corner;
+**one grade for a sequence** — precompose it and grade the comp clip once.
+
+### Presets and templates
+
+Two ways to reuse motion: an **animation preset** keys a named animation onto a
+clip, and a **template** is a ready-made comp (lower third, logo animation,
+social layout) whose text, colours and pictures are **fields** you fill in.
+
+**Presets.** A preset keys the clip's own channels, relative to where the clip
+already is: `scale` and `opacity` multiply the clip's value and everything else
+adds to it, so "Slide up" works wherever the clip sits and however big it is.
+Each has an anchor: **in** plays from the clip's start and settles on its
+values, **out** starts from them and ends at the clip's end, **at** is an
+emphasis at a time you pick (the playhead, or `at`), and **loop** spans the
+whole clip. Keys already in the window a preset covers are replaced; the rest
+stay, so an In, an Out and a loop on another channel live side by side.
+
+| group | presets |
+|---|---|
+| In | `fade-in` · `pop-in` · `slide-up-in` · `slide-down-in` · `slide-left-in` (from the right) · `slide-right-in` (from the left) · `drop-in` · `zoom-in` · `spin-in` · `whip-in` (with motion blur) · `rise-blur` · `draw-on` (shape layers) |
+| Out | `fade-out` · `pop-out` · `slide-up-out` · `slide-down-out` · `slide-left-out` · `slide-right-out` · `zoom-out` · `spin-out` · `whip-out` · `sink-blur` · `draw-off` |
+| At (emphasis) | `pulse` · `shake` · `wobble` · `bounce` · `flash` |
+| Loop | `float` · `breathe` · `sway` · `spin` · `wiggle` |
+
+Every In / Out / At preset is 0.35–1 s long; `length` stretches it (a clip
+shorter than the preset squeezes it in). A saved preset is a JSON file in
+`library/presets/`, shared by every project:
+
+```jsonc
+{ "id": "fly-in", "name": "Fly in", "group": "Saved", "anchor": "in", "length": 0.6,
+  "keys": { "x": [ { "t": 0, "v": -500 }, { "t": 0.6, "v": 0, "ease": "ease-out" } ],
+            "opacity": [ { "t": 0, "v": 0 }, { "t": 0.3, "v": 1 } ] },
+  "props": { "motionBlur": 180 } }   // optional: motionBlur, motionBlurSamples
+```
+
+`t` is seconds into the preset (for a loop, 0…1 of the clip). Channels: `x y
+scale rotation opacity blur anchorX anchorY trimStart trimEnd trimOffset
+brightness saturation hue grayscale shake rgbSplit glow fontSize letterSpacing
+pathOffset`.
+
+**Templates.** Placing one adds its own comp (so two lower thirds can show two
+names) and a comp clip showing it with `fit:"contain"`; a template made for
+another shape than the canvas sits inside it, letterboxed. The comp carries
+what makes it a template:
+
+```jsonc
+{ "id": "comp_x1", "name": "Lower third — Bar", "width": 1920, "height": 1080, "duration": 5, "clips": [ … ],
+  "template": { "id": "lower-third-bar", "hold": 4.5, "fields": [
+    { "key": "name", "label": "Name", "type": "text", "targets": [ "name:props.text" ], "value": "Ava Moreno" },
+    { "key": "accent", "label": "Accent", "type": "color", "targets": [ "bar:props.shapes.1.fill" ], "value": "#ffd166" } ] } }
+```
+
+| template | name | size | length | fields |
+|---|---|---|---|---|
+| `lower-third-bar` | Lower third — Bar | 1920×1080 | 5 s | `name` `title` `accent` `panel` |
+| `lower-third-underline` | Lower third — Underline | 1920×1080 | 5 s | `name` `title` `accent` |
+| `lower-third-boxes` | Lower third — Boxes | 1920×1080 | 5 s | `name` `title` `accent` `box` |
+| `logo-ring` | Logo — Ring reveal | 1920×1080 | 4 s | `logo` `brand` `accent` |
+| `logo-slam` | Logo — Slam | 1920×1080 | 3.5 s | `logo` `accent` |
+| `logo-lines` | Logo — Lines | 1920×1080 | 4 s | `logo` `tagline` `lines` |
+| `social-story` | Story — Headline (9:16) | 1080×1920 | 6 s | `headline` `subline` `button` `accent` `background` |
+| `social-quote` | Post — Quote (1:1) | 1080×1080 | 6 s | `quote` `author` `accent` `background` |
+| `social-end-card` | End card — Follow (16:9) | 1920×1080 | 6 s | `heading` `button` `accent` `background` |
+
+Field types: `text` (a string), `color` (`#rgb`, `#rrggbb` or `#rrggbbaa`) and
+`media` (a media id of a picture: image, svg or video; the clip's kind follows
+it). A target is `"<clip id>:<path>"` inside the comp (`props.text`,
+`props.shapes.1.fill`, `mediaId`, …) or `"comp:background"`; one field can set
+several. The logo templates start with a placeholder,
+`/library/elements/logo-placeholder.svg`, until the `logo` field gets a
+picture. **`hold`** is when the exit starts: changing a template's length
+keeps everything after it at the same distance from the end, so a longer lower
+third just holds longer (it can't get shorter than its entrance needs).
+
+A saved template (`library/templates/<id>.json`) is a template object:
+`{id, name, group, width, height, duration, hold, background?, tracks?, clips,
+media?, fields}`; `media` lists the `{id, name, kind, src}` entries its clips
+use (`/library/…` or `/media/…`), matched by `src` when it is placed. A saved
+preset or template whose name a built-in already has is saved as
+"<name> (saved)".
+
+In the editor: the bin's **Templates** tab lists them by group (Lower thirds,
+Logo animations, Social, then Saved); drag one onto the timeline or click ＋.
+The Inspector's **Template** section on its clip edits the fields, its
+**Length**, and offers **Use W×H canvas** when the template was made for
+another shape. Right-click a comp in the Project tab → **Save as template**
+keeps it (every title's text and every picture become fields). The
+**Motion** section's **Presets** menus (In, Out, At playhead, Loop) put a
+preset on the selected clips, and **Save as preset** keeps this clip's
+keyframes (In: from its start to its last key; Out: from its first key to its
+end; Loop: the whole clip).
+
+**Agents:**
+
+- `{op:"applyPreset", id | ids, preset, length?, at?}` — `preset` is a name,
+  a saved one's id, or an inline preset object; `at` is timeline seconds (for
+  an At preset; default the clip's start). Visual clips only.
+- `{op:"addTemplate", template, start?, track?, duration?, fields?:{key: value}, id?, compId?, name?}`
+  places one (default track V2, at 0, its own length).
+- `{op:"setTemplate", id, fields?:{key: value}, duration?}` — `id` is its comp
+  clip or its comp; a new `duration` retimes it, and clips that showed it to
+  its end keep doing so.
+- `{op:"savePreset", id, name, anchor?, from?, to?}` (`from`/`to` in clip
+  seconds) or `{op:"savePreset", preset:{…}}`; `{op:"saveTemplate", comp,
+  name?, fields?, hold?}` or `{op:"saveTemplate", template:{…}}`. Files are
+  written once the patch is saved, and later ops in the same patch can use them.
+- `applyPreset`, `addTemplate` and `setTemplate` also run inside `inComp`.
+- The compact view prints a placed template's fields under its comp:
+  `template lower-third-bar — fields (setTemplate): name="Ava Moreno" …`.
+
+Recipes: **name every speaker** — `addTemplate lower-third-bar` once per
+speaker with `fields:{name, title}`; **branded intro** — `addTemplate logo-ring`
+with `fields:{logo:"<your logo's media id>", brand, accent}` at 0;
+**vertical teaser** — set the canvas to 1080×1920, `addTemplate social-story`;
+**house style** — build a comp the way you like it, `saveTemplate`, then place
+it in every project; **titles that arrive and leave the same way** —
+`applyPreset` an In and an Out on every title in one patch.
+
 ### Semantics
 
 - Rendering order: V1 is drawn first, then V2, V3, … on top. SVG/image/text clips
@@ -1074,7 +1495,10 @@ obvious cuts were missed, raise it if motion is being misread as cuts.
   Append `?force=1` to overwrite unconditionally. Writes are atomic (tmp file +
   rename), so a crashed write never corrupts the file.
 - `GET  /api/media`   — list files in ./media (name, src, size)
-- `GET  /api/library?dir=sfx|elements|svg|fonts` — list library assets
+- `GET  /api/library?dir=sfx|elements|svg|fonts|presets|templates` — list library assets
+- `GET  /api/presets` · `GET /api/templates` — the saved presets / templates, validated (bad files skipped);
+  `POST /api/presets {preset}` · `POST /api/templates {template}` — validate one and save it as
+  `library/presets/<id>.json` / `library/templates/<id>.json`, returning `{id, name, file}`
 - `POST /api/upload?name=foo.mp4` — raw body saved into ./media, returns `{src}`.
   MP4/MOV/M4V uploads are auto-remuxed with `+faststart` (needs ffmpeg on PATH).
   Files copied straight into ./media by external tools skip this — remux big ones

package/README.md

@@ -194,6 +194,27 @@ same time.
   difference, each with feather, expansion, invert and opacity, all
   keyframable (outlines morph). Draw and edit them on the monitor, with a
   matte view. Agents use the `setMask` patch op and measure with `fablecut_scopes`
+- **Shapes and motion graphics** — shape layers of rectangles, ellipses,
+  polygons, stars, lines and pen-drawn bezier paths in groups, with fill,
+  stroke, dashes and trim paths for draw-ons; null objects, parenting and an
+  anchor point on every clip; every value keyframes, edited right on the
+  monitor. Agents use the `setShape` and `setParent` patch ops
+- **Motion paths, motion blur and text on a path** — bend a clip's travel into
+  a curve with handles on the monitor, turn it along the way, blur fast moves
+  with a shutter angle (preview and export), and set titles along lines, arcs,
+  circles or drawn paths. Agents use the `setMotionPath` and `setTextPath`
+  patch ops
+- **Compositions** — nested sequences: build a lower third, a logo sting or a
+  scene once and place it anywhere as one clip that moves, masks, grades and
+  blends like a picture, while its video and audio play and export as usual.
+  Open one to edit it on the timeline, or precompose a selection. Agents use
+  the `addComp`, `inComp` and `precompose` patch ops
+- **Animation presets and templates** — 33 ready-made entrances, exits,
+  emphases and loops that fit any clip where it sits, and templates (lower
+  thirds, logo animations, 9:16 / 1:1 / 16:9 social layouts) whose text,
+  colours and logo you fill in, each placed as its own comp. Save your own
+  animations and comps to the library for every project. Agents use the
+  `applyPreset`, `addTemplate` and `setTemplate` patch ops
 - **Motion tracking** — follow a point or a region (with its scale and
   rotation) through a video clip, then make a mask follow it or pin a title,
   sticker or any clip to it; the result is ordinary editable keys. Agents use
@@ -323,8 +344,8 @@ you choose. Leave it unset and everything stays in the repo, exactly as before.
 /plugin install fablecut@fablecut
 ```
 
-That registers the MCP server for you and adds two skills — `edit-video` and
-`remake-reel`. Your timeline and footage live in the plugin's own data
+That registers the MCP server for you and adds three skills — `edit-video`,
+`remake-reel` and `motion-graphics`. Your timeline and footage live in the plugin's own data
 directory, so an update never touches them. Node 18+ and (optionally) ffmpeg
 still need to be on your machine.