greenlight-motion 0.3.4 → 0.4.0

package/skill/references/video-shapes.md

@@ -10,23 +10,46 @@
 
 ## Contents
 
-- [Shape layers (`mediaType: "shape"`)](video-shapes.md#shape-layers-mediatype-shape)
-- [Rounded rectangles — buttons, pills, cards](video-shapes.md#rounded-rectangles--buttons-pills-cards)
+- [Shape layers (`mediaType: "shape"`)](#shape-layers-mediatype-shape)
+  - [Sizing (`shapeSizeUnit`)](#sizing-shapesizeunit)
+  - [Rounded rectangles — buttons, pills, cards](#rounded-rectangles--buttons-pills-cards)
+  - [Fill, opacity and framing on shapes](#fill-opacity-and-framing-on-shapes)
+  - [Editable paths (`shapeType: "path"`, `shapePath`)](#editable-paths-shapetype-path-shapepath)
+  - [Writing the handles](#writing-the-handles) — the tangent rule for every path in the app
+  - [Lines and strokes](#lines-and-strokes)
+  - [Shape background (`shapeBackground`)](#shape-background-shapebackground)
+  - [Clipping masks (`shapeClipMask` / `textClipMask` / `clipMaskInvert`)](#clipping-masks-shapeclipmask--textclipmask--clipmaskinvert)
+  - [Track matte (`trackMatte`)](#track-matte-trackmatte)
+  - [Card framing on every visual layer](#card-framing-on-every-visual-layer) — rounded corners, borders and shadows on video, image, text and sequences
+  - [Backdrop blur and glass](#backdrop-blur-and-glass)
+  - [Traced vectors (`shapeType: "vector"`)](#traced-vectors-shapetype-vector)
 
 ### Shape layers (`mediaType: "shape"`)
 
-A solid-color rectangle / ellipse / arrow / triangle — or a custom SVG silhouette — with the full photo-layer option set (transforms, filters, keyframes, layer transitions, blend modes). Like text, the clip is synthetic (no `url`) and the LOOK lives on the timeline item:
+A solid-colour rectangle / ellipse / arrow / triangle — or a custom SVG silhouette — with the full photo-layer option set (transforms, filters, keyframes, layer transitions, blend modes). Like text, the clip is synthetic (no `url`) and the LOOK lives on the timeline item:
 
-```json
+```jsonc
 // clip
 { "id": "shp1", "source": "LOCAL", "mediaType": "shape", "url": "", "proxyUrl": null, "name": "Shape", "duration": 5 }
 // item fields (on the timeline item referencing shp1; defaults shown)
-{ "shapeType": "rectangle" | "ellipse" | "circle" | "arrow" | "triangle" | "path" | "line" | "custom", "shapeFillColor": "#8b5cf6", "shapeSizeUnit": "pct" | "px", "shapeWidthPct": 40, "shapeHeightPct": 40, "shapeWidthPx": null, "shapeHeightPx": null, "shapeRadiusPct": 20, "shapeRadiusPx": null, "shapeSvgUrl": null, "shapePath": null, "shapeClipMask": false, "clipMaskInvert": false }
+{ "shapeType": "rectangle", "shapeFillColor": "#8b5cf6", "shapeSizeUnit": "pct", "shapeWidthPct": 40, "shapeHeightPct": 40, "shapeWidthPx": null, "shapeHeightPx": null, "shapeRadiusPct": 20, "shapeRadiusPx": null, "shapeSvgUrl": null, "shapePath": null, "shapeClipMask": false, "clipMaskInvert": false }
 ```
 
-`shapeType` is one of `rectangle` | `ellipse` | `circle` | `arrow` | `triangle` | `path` | `line` | `custom`. Triangles take `shapeTriDirection` (`up`|`down`|`left`|`right`, default `up`) and `shapeTriApexPct` (0–100, default 50 — where the tip sits along the opposite edge; 0/100 gives a right triangle). Arrows take `shapeArrowHeadPct` (head length as % of width, 5–90, default 45) and `shapeArrowShaftPct` (shaft thickness as % of height, 2–100, default 42). `custom` renders a user-provided SVG silhouette: set `shapeSvgUrl` to an SVG **data URI** (`data:image/svg+xml;base64,…` or URL-encoded) — the SVG's alpha is the shape and it is recolored with `shapeFillColor`, so it travels inside the project JSON with no media file. Stills and exports load every `shapeSvgUrl` in the project before the first frame, so an icon whose clip starts mid-timeline appears on its first frame (the live preview loads it on first display). `shapeWidthPct`/`shapeHeightPct` are % of the frame and may exceed 100; the pixel size fields may likewise exceed the composition dimensions. The size is keyframable in the unit the shape uses: tracks `shapeWidthPx`/`shapeHeightPx` or `shapeWidthPct`/`shapeHeightPct` (a circle: `shapeRadiusPx` or `shapeRadiusPct`), each overriding the field of the same name — a track for the unit not in use does nothing.
+`shapeType` is one of `rectangle` | `ellipse` | `circle` | `arrow` | `triangle` | `path` | `line` | `custom` | `vector`; an unknown value loads as `rectangle`.
+
+- **Triangles** take `shapeTriDirection` (`up`|`down`|`left`|`right`, default `up`) and `shapeTriApexPct` (0–100, default 50 — where the tip sits along the opposite edge; 0/100 gives a right triangle).
+- **Arrows** take `shapeArrowHeadPct` (head length as % of width, 5–90, default 45) and `shapeArrowShaftPct` (shaft thickness as % of height, 2–100, default 42).
+- **`custom`** renders a user-provided SVG silhouette: set `shapeSvgUrl` to an SVG **data URI** (`data:image/svg+xml;base64,…` or URL-encoded) — the SVG's alpha is the shape and it is recoloured with `shapeFillColor`, so it travels inside the project JSON with no media file. Stills and exports load every `shapeSvgUrl` in the project before the first frame, so an icon whose clip starts mid-timeline appears on its first frame (the live preview loads it on first display).
+- **`vector`** is a traced image: see [Traced vectors](#traced-vectors-shapetype-vector).
+- **`path`** and **`line`** are editable bezier outlines: see [Editable paths](#editable-paths-shapetype-path-shapepath) and [Lines and strokes](#lines-and-strokes).
+
+The size is keyframable in the unit the shape uses: tracks `shapeWidthPx`/`shapeHeightPx` or `shapeWidthPct`/`shapeHeightPct` (a circle: `shapeRadiusPx` or `shapeRadiusPct`), each overriding the field of the same name — a track for the unit not in use does nothing. Shapes render in `/render-onserver` (not the fast `/render`). Put shapes on their own `unsnapped` channel above the footage, like captions.
+
+#### Sizing (`shapeSizeUnit`)
 
-**Sizing (`shapeSizeUnit`).** `"pct"` (the default) reads `shapeWidthPct` as % of the composition **width** and `shapeHeightPct` as % of its **height** — two different bases, so equal percentages are only square on a square composition: `40`/`40` on 1920×1080 is a 768×432 oval. `"px"` reads `shapeWidthPx`/`shapeHeightPx` as absolute composition pixels instead (a `null` px value falls back to the %). **To draw a circle, size it in px, never in matching percentages**: either `shapeType: "circle"`, which takes a single radius (`shapeRadiusPx` with `shapeSizeUnit: "px"`; its `shapeRadiusPct` fallback is % of the *shorter* composition side, default 20, so it stays round but changes size with the aspect ratio), or an `ellipse` with `shapeSizeUnit: "px"` and equal `shapeWidthPx`/`shapeHeightPx`. The same applies to any shape that must keep its proportions across compositions (a square, a 1:1 badge): use px.
+`"pct"` (the default) reads `shapeWidthPct` as % of the composition **width** and `shapeHeightPct` as % of its **height** — two different bases, so equal percentages are only square on a square composition: `40`/`40` on 1920×1080 is a 768×432 oval. Both may exceed 100. `"px"` reads `shapeWidthPx`/`shapeHeightPx` as absolute composition pixels instead (a `null` px value falls back to the %), and may exceed the composition size.
+
+**To draw a circle, size it in px, never in matching percentages**: either `shapeType: "circle"`, which takes a single radius (`shapeRadiusPx` with `shapeSizeUnit: "px"`; its `shapeRadiusPct` fallback is % of the *shorter* composition side, default 20, so it stays round but changes size with the aspect ratio), or an `ellipse` with `shapeSizeUnit: "px"` and equal `shapeWidthPx`/`shapeHeightPx`. Do the same for any shape that must keep its proportions across compositions (a square, a 1:1 badge).
 
 #### Rounded rectangles — buttons, pills, cards
 
@@ -34,7 +57,9 @@ For anything with rounded corners — a button, pill, badge, tag, card, chat bub
 
 - `borderRadiusUnit`: `"px"` (default; composition pixels — a fixed corner) or `"pct"` (% of the shape's **shorter** side, 0–50). `50` is a full pill/capsule at any aspect ratio. Any radius larger than half the shorter side clamps there, so `borderRadius: 9999` in px is also a pill.
 - `borderRadius` is the radius for all four corners (default 0 = square). For different corners set `borderRadiusLinked: false` and `borderRadiusTL` / `borderRadiusTR` / `borderRadiusBR` / `borderRadiusBL`, in the same unit (a corner left out falls back to `borderRadius`) — e.g. a tab with only its top corners rounded.
-- Animate it with the `borderRadius` property-keyframe track (`borderRadiusTL` … `borderRadiusBL` when unlinked). Values are in the item's `borderRadiusUnit`; `"0"` is square, so `0 → 50` in `pct` morphs a square box into a pill.
+- **Animate it** with the `borderRadius` property-keyframe track (`borderRadiusTL` … `borderRadiusBL` when unlinked). Values are in the item's `borderRadiusUnit`; `"0"` is square, so `0 → 50` in `pct` morphs a square box into a pill. Changing `borderRadiusUnit` through the API does not convert existing keys, so rewrite them in the new unit.
+- When the layer itself must scale (a tile that grows to fill the frame, a card that punches in on a `scale` track), set `borderRadiusScaleLock: true`. Every radius is then divided by the layer's scale (`zoom`, the `scale`/`scaleX`/`scaleY` tracks and its parents), so the corner keeps its size on screen instead of growing with the tile. Without it (the default) the corner scales with the layer.
+- Only `rectangle` shapes take a `pct` radius. Every other layer (video, image, text, sequence) takes the radius in px, and its `borderRadius` tracks too (see [Card framing](#card-framing-on-every-visual-layer)); `shapeRadiusPct`/`shapeRadiusPx` are a `circle`'s size, not a corner amount.
 - `borderWidth`/`borderColor`/`borderStyle` stroke the rounded outline, and `shadows` and `backdropBlur` follow it.
 
 A pill button — the label is a text layer on the channel above, at the same `panX`/`panY`:
@@ -50,24 +75,25 @@ A pill button — the label is a text layer on the channel above, at the same `p
 
 A 12 px-corner card is `"borderRadius": 12` with no unit field.
 
-**Shape fill opacity comes from the alpha of `shapeFillColor`** — use an rgba/8-digit-hex value (e.g. `rgba(139,92,246,0.5)` or `#8b5cf680`) for a semi-transparent fill; there is no separate fill-opacity field. Position/scale/rotation come from the standard item fields (`panX`, `panY`, `zoom`, `rotateZ`, keyframes…). For whole-layer fade (any layer type, not just shapes) use the standard item `opacity` (0–100). On shape layers the framing fields follow the **shape outline**, not the bounding box: `borderWidth`/`borderColor`/`borderStyle` stroke the path (all four styles; not available on `custom` SVG shapes), `borderRadius` (incl. per-corner, px or `borderRadiusUnit: "pct"` — see [Rounded rectangles](#rounded-rectangles--buttons-pills-cards)) rounds `rectangle` shapes only (`shapeRadiusPct`/`shapeRadiusPx` are the `circle` radius, not a corner amount), and drop `shadows` hug the silhouette (shadow `spread` and `inset` are ignored for shapes). Shapes render in `/render-onserver` (not the fast `/render`). Put shapes on their own `unsnapped` channel above the footage, like captions.
+#### Fill, opacity and framing on shapes
 
-**Editable paths (`shapeType: "path"`, `shapePath`).** A freeform bezier outline instead of a parametric one. `shapePath` is `{ "points": [ … ], "closed": true }`; each point is `{ "x", "y", "hIn": {"x","y"}, "hOut": {"x","y"}, "manual": true }`. Coordinates are **fractions of the shape's own box, centred on it** — `-0.5` is the left/top edge and `0.5` the right/bottom — so `shapeWidthPct`/`shapeHeightPct` still size the whole path (points may go outside ±0.5; the render surface grows to fit). `hIn`/`hOut` are the cubic-bezier control handles stored as **offsets from their own anchor**, not absolute control points — the segment A→B is the cubic `A → A+A.hOut → B+B.hIn → B`.
+- **Fill opacity comes from the alpha of `shapeFillColor`** — use an rgba/8-digit-hex value (e.g. `rgba(139,92,246,0.5)` or `#8b5cf680`) for a semi-transparent fill; there is no separate fill-opacity field.
+- Position/scale/rotation come from the standard item fields (`panX`, `panY`, `zoom`, `rotateZ`, keyframes…). For a whole-layer fade use the standard item `opacity` (0–100; its keyframe track is 0–1).
+- On shape layers the framing fields follow the **shape outline**, not the bounding box: `borderWidth`/`borderColor`/`borderStyle` stroke the outline (all four styles; not on `custom`/`vector` SVG shapes or stroked paths and lines, which use the [line stroke](#lines-and-strokes) instead), and drop `shadows` hug the silhouette (shadow `spread` and `inset` are ignored for shapes).
 
-⚠️ **Handles are not optional.** A missing or zero-length handle is a hard **corner**, and nothing fills one in for you: the auto-tangent pass runs only when a human adds or drags a point in the editor, while load, save, preview, export and `/render-onserver` all draw the stored handles verbatim. An outline written as bare `x`/`y` points renders as a straight-line **polygon**, not the smooth shape it looks like on paper. Set `manual: true` on every anchor too, or the next point a user adds in the UI re-smooths the whole outline out from under the design. The tangents to write:
+#### Editable paths (`shapeType: "path"`, `shapePath`)
 
-- **Smooth anchor** — the editor's own Catmull-Rom tangent: `hOut = (P[next] − P[prev]) / 6`, `hIn = −hOut`. On a `closed` path the neighbours wrap; on an open one the first anchor uses `hOut = (P[1] − P[0]) / 3` and the last `hIn = −(P[last] − P[last−1]) / 3`.
-- **Corner** — `hIn` and `hOut` both `{ "x": 0, "y": 0 }`.
-- **Cusp with curvature on both sides** — break the mirror: give `hIn` and `hOut` directions that are not opposite.
-- **Circular arc** — a quarter-arc wants handles of `0.5523 × radius` laid **perpendicular** to the anchor's radius, following the winding: `0.2761` in the ±0.5 box (that is the Circle preset). Longer handles bulge the arc (Squircle uses 1.34×), shorter ones flatten it.
+A freeform bezier outline instead of a parametric one. `shapePath` is `{ "points": [ … ], "closed": true }`; each point is `{ "x", "y", "hIn": {"x","y"}, "hOut": {"x","y"}, "manual": true }`. Coordinates are **fractions of the shape's own box, centred on it** — `-0.5` is the left/top edge and `0.5` the right/bottom (+y down) — so `shapeWidthPct`/`shapeHeightPct` still size the whole path (points may go outside ±0.5; the render surface grows to fit). Anchors **and** handles are clamped to **±8** box units on load. Write the handles as described in [Writing the handles](#writing-the-handles).
 
-Anchors **and** handles are clamped to **±8** box units on load. `closed: false` draws the path as a **stroked line** using `borderWidth`/`borderColor`/`borderStyle` (falling back to 4px + `shapeFillColor` when the border width is 0) instead of a filled shape — an open path cannot be a clipping mask. Ready-made outlines come from `GET /api/video-editor/capabilities` → **`paths`**: `paths.shapePresets` holds 11 closed shapes (Circle, Rectangle, Rounded, Triangle, Diamond, Pentagon, Hexagon, Star, Burst, Blob, Squircle) and `paths.linePresets` 6 open ones (Straight, Arc, S-curve, Wave, Zigzag, Corner), each as a complete point list with handles already resolved and `manual: true` set — paste one and it renders exactly as published. `paths.anchor` / `paths.spaces` / `paths.tangents` restate the contract above for every path kind. Take the points from there rather than approximating a shape by hand (the generator reads `SHAPE_PATH_PRESETS`/`LINE_PATH_PRESETS` in `frontend/src/components/videoEditor/shapePath.js`); on a keyframed outline, write the resampled points into a key instead of the base field.
+`closed: false` (or `shapePathRenderMode: "stroke"`) draws the path as a **stroked line** with the [line stroke fields](#lines-and-strokes) instead of a filled shape; an open path cannot be a clipping mask.
 
-**Reusing another curve as an outline.** A motion path or camera path can become a shape outline: world-pixel curves are fitted into **this** shape's box with a single scale for both axes (keeping proportions rather than stretching to the box), centred on it, and flattened — `z` is dropped, since a shape draws its XY footprint. `worldPointsToShapePoints` in `frontend/src/components/videoEditor/pathCopy.js` is the conversion.
+**Ready-made outlines** come from `GET /api/video-editor/capabilities` → **`paths`**: `paths.shapePresets` holds 11 closed shapes (Circle, Rectangle, Rounded, Triangle, Diamond, Pentagon, Hexagon, Star, Burst, Blob, Squircle) and `paths.linePresets` 6 open ones (Straight, Arc, S-curve, Wave, Zigzag, Corner), each as a complete point list with handles already resolved and `manual: true` set — paste one and it renders exactly as published. Take the points from there rather than approximating a shape by hand; on a keyframed outline, write the resampled points into a key instead of the base field.
 
-The outline is keyframable as a whole under the `shapePath` **property-keyframe track** — one of only two track kinds whose `value` is not a number or colour but a JSON array of points (the other is a layer mask's `msk:<mid>:path`; see `video-effects.md`). Every key must hold the **same number of points**, since they morph one-to-one:
+**Reusing another curve as an outline.** A motion path or camera path can become a shape outline: world-pixel curves are fitted into **this** shape's box with a single scale for both axes (keeping proportions rather than stretching to the box), centred on it, and flattened — `z` is dropped, since a shape draws its XY footprint, and y flips (world +y is up, the box's +y is down).
 
-```json
+The outline is keyframable as a whole under the `shapePath` **property-keyframe track** — one of the track kinds whose `value` is a JSON array of points rather than a number or colour (the others are a layer mask's `msk:<mid>:path`, see [Layer Mask entry](video-effects.md#layer-mask-entry), and `motionPathPoints`, see [video-paths.md](video-paths.md#animated-motion-path-motionpathpoints)). Every key must hold the **same number of points**, since they morph one-to-one:
+
+```jsonc
 "propertyKeyframes": { "shapePath": [
   { "position": 0,   "value": "[{\"x\":-0.5,\"y\":-0.5,\"hIn\":{\"x\":0,\"y\":0},\"hOut\":{\"x\":0,\"y\":0},\"manual\":true}, …]", "easing": "Smooth" },
   { "position": 100, "value": "[…same length…]", "easing": "Smooth" }
@@ -76,7 +102,20 @@ The outline is keyframable as a whole under the `shapePath` **property-keyframe
 
 The track is only kept on load when the item's `shapeType` is `path` or `line`.
 
-**Lines and strokes (`shapeType: "line"`, or `"path"` with `closed: false`).** A `line` is an editable path that renders as a **stroke** rather than a fill (its `closed` flag is ignored — a line is always open). Stroke fields, all on the item: `lineWidth` (px, default 8), `lineCap` (`butt`|`round`|`square`, default `round`), `lineJoin` (`round`|`miter`|`bevel`, default `round`), `lineDash` (`solid`|`dashed`|`dotted`|`custom`, default `solid`). The stroke is painted with the shape's own fill, so `shapeFillColor` **and** a full `shapeBackground` (gradient / shader / pattern / image) both work on a line. The card `borderWidth`/`borderStyle` do **not** apply — the stroke is the outline.
+#### Writing the handles
+
+One rule covers every bezier path in the app: `shapePath`, line outlines and Layer Mask paths (unit box, `x`/`y`), and `motionPath`, `cameraPath` and `motionPathPoints` keys (world pixels, `x`/`y`/`z` — every handle carries `z` too). `GET /api/video-editor/capabilities` → `paths.anchor` / `paths.spaces` / `paths.tangents` restate it.
+
+`hIn`/`hOut` are the cubic-bezier control handles stored as **offsets from their own anchor**, not absolute control points — the segment A→B is the cubic `A → A+A.hOut → B+B.hIn → B`. **Write both handles on every anchor.** A missing or zero-length handle is a hard **corner**, and nothing fills one in: the auto-tangent pass runs only on a hand edit in the editor, while load, save, preview, export and `/render-onserver` draw the stored handles verbatim. An outline written as bare points renders as a straight-line **polygon**, not the smooth shape it looks like on paper. Set **`manual: true` on every anchor** too, or the next hand edit in the editor re-smooths the whole outline out from under the design.
+
+- **Smooth anchor** — the editor's own Catmull-Rom tangent, componentwise: `hOut = (P[next] − P[prev]) / 6`, `hIn = −hOut`. On a `closed` path the neighbours wrap; on an open one the first anchor uses `hOut = (P[1] − P[0]) / 3` and the last `hIn = −(P[last] − P[last−1]) / 3`.
+- **Corner** — `hIn` and `hOut` both `{ "x": 0, "y": 0 }` (plus `"z": 0` in world space).
+- **Cusp with curvature on both sides** — break the mirror: give `hIn` and `hOut` directions that are not opposite.
+- **Circular arc** — a quarter-arc wants handles of `0.5523 × radius` laid **perpendicular** to the anchor's radius, following the winding: `0.2761` in the ±0.5 box (that is the Circle preset). Longer handles bulge the arc (Squircle uses 1.34×), shorter ones flatten it.
+
+#### Lines and strokes
+
+A `line` is an editable path that renders as a **stroke** rather than a fill (its `closed` flag is ignored — a line is always open). A `path` is stroked the same way when `closed: false` or when `shapePathRenderMode` is `"stroke"` (default `"fill"`) — what you want for a signature, a route line or any figure where a fill would close the curve. Stroke fields, all on the item: `lineWidth` (px, 0–400, default 8), `lineCap` (`butt`|`round`|`square`, default `round`), `lineJoin` (`round`|`miter`|`bevel`, default `round`), `lineDash` (`solid`|`dashed`|`dotted`|`custom`, default `solid`). The stroke is painted with the shape's own fill, so `shapeFillColor` **and** a full `shapeBackground` (gradient / shader / pattern / image) both work on a line. The card `borderWidth`/`borderStyle` do **not** apply — the stroke is the outline.
 
 **Trim Paths (`lineTrimStart` / `lineTrimEnd` / `lineTrimOffset`).** Draw only part of the outline, measured by arc length: `lineTrimStart` and `lineTrimEnd` are 0–100 (default 0 and 100), `lineTrimOffset` is −100…100 (default 0) and slides the span along the path, wrapping on a closed one. Keyframing `lineTrimEnd` 0 → 100 is the "write the line on" move. Trim applies to any stroked shape.
 
@@ -122,28 +161,52 @@ A tapered arrow that writes itself on:
 - Flat fields: `lineWidth`, `lineTrimStart`, `lineTrimEnd`, `lineTrimOffset`, `lineDashOffset`, `lineDashSpeed`, `lineOutlineWidth`, `lineGhost`, and the custom dash pattern as `lineDashLength1`, `lineDashGap1`, `lineDashLength2`, `lineDashGap2`.
 - `lineStroke` numbers: a track named `line` + card key + field, both capitalised — `lineBrushNibAngle`, `lineWarpZigzagRidges`, `lineCopiesRotate`, `lineStampsSpacing`, `linePaintRepeat` … — except these, which keep their own names: `lineTaperStartLength`, `lineTaperEndLength`, `lineTaperStartWidth`, `lineTaperEndWidth`, `lineProfileOffset`, `lineWidthWaveAmount`, `lineWidthWavePhase`, `lineWarpOffset`, `lineZigzagSize`, `lineWiggleSize`, `lineWarpWaveAmplitude`, `lineCopySpacing`, `lineEndsSize`, `lineStampOffset`, `lineGradientOffset`, `lineFadeIn`, `lineFadeOut`.
 - `lineStroke` colours (key `value`s are CSS colours, interpolated as colours): `linePaintColor1`–`3` and `lineCopiesColor1`–`3` (the entries of `colors`), `linePaintCoreColor`, and `lineStampsColor` (only recolours stamps that have their own `color`).
+
 A track overrides its field only while that card is on the layer; values use the field's units and are clamped to its range.
 
 Running Glow on a stroked shape should set `glowTraceThin: 1` and a `glowEdgeWidth` near the line's own thickness (in @1080 px) — the default filled-shape tracing finds no contour on a thin stroke and the effect is invisible.
 
-**Shape background (`shapeBackground`).** Beyond the flat `shapeFillColor`, a shape can take a full **background** via `shapeBackground` — the same `backgroundConfig` object as the project background (solid, gradient, GLSL shader, pattern, or image; full schema, preset ids and the shader rules are in the **Backgrounds (project & shape)** section above). It fills the shape's silhouette; when `shapeBackground` is `null` (the default) the shape falls back to the flat `shapeFillColor`. Shader and animated-gradient shape backgrounds render only in the Video Editor.
+#### Shape background (`shapeBackground`)
 
-**Clipping masks (`shapeClipMask` / `textClipMask` / `clipMaskInvert`).** A shape can act as a **clipping mask**: set `shapeClipMask: true` and the layers below the shape's channel show only where the shape has coverage (the fill itself isn't drawn; the fill's alpha sets mask strength, and the shape's transforms/keyframes move the mask). **Text layers** take the same treatment with `textClipMask: true` — the glyph coverage is the matte, so footage plays inside the letters, and typography plus the split/stagger animation fields animate it. While a text layer masks, its own text shadow (`textShadowX/Y/Blur/Spread`) and caption bar (`textBgEnabled`) are ignored, as is card framing (`borderWidth`, `shadows`) — that alpha would leak into the matte; use the `blur` filter to feather instead. Either kind accepts `clipMaskInvert: true` to flip the matte (knockout: the layers below are hidden inside the shape/letters and shown everywhere else). A mask affects **all** channels below it in the same stack, masks stack, and they composite both at the top level and inside a sequence's inner timeline. A frame with an active mask skips the global Depth of Field.
+Beyond the flat `shapeFillColor`, a shape can take a full **background** via `shapeBackground` — the same `backgroundConfig` object as the project background (solid, gradient, GLSL shader, pattern, or image; the schema, preset ids and shader rules are in [video-backgrounds.md](video-backgrounds.md)). It fills the shape's silhouette; when `shapeBackground` is `null` (the default) the shape falls back to the flat `shapeFillColor`. Shader and animated-gradient shape backgrounds render only in the Video Editor.
 
-**Track matte (`trackMatte`).** The After Effects analog, distinct from clipping masks: it scopes to **one consumer layer** instead of the whole stack below, and supports luma. Set on the consumer item: `trackMatte: { sourceId: "<other item id>", mode: "alpha" | "alphaInverted" | "luma" | "lumaInverted" }` — the consumer then shows only where the source layer has alpha coverage (`alpha`) or brightness (`luma`; computed premultiplied, so transparent source areas contribute nothing), inverted variants flip it. The **source layer is hidden from output** while at least one active consumer references it; its transforms/keyframes still animate the matte. Rules: the source must be another **visual** item (not audio/camera/adjustment) at the **same editing level**; the reference is by item id, not stack position; several consumers may share one source; a mutual pair (A mattes with B while B mattes with A) is auto-broken on save; if the source clip isn't under the playhead the matte is EMPTY — `alpha`/`luma` hide the consumer, inverted modes show it untouched. The matte clips the consumer's **finished** look (after its filters, glow, overlay effects and motion blur), matching AE. The **source is read finished too**: its own `effects` chain, `layerEffects`, rig warp and motion blur shape the matte, so an `extract` (histogram key) or `alphaChoker` on the source layer is the normal way to author a matte from footage rather than from a silhouette. Works at the top level and inside a sequence's inner timeline alike (inside a sequence only the layer's `effects` chain shapes the matte — glow, motion blur and the other Layer Effects are top-level stages); grids strip it on grouping.
+#### Clipping masks (`shapeClipMask` / `textClipMask` / `clipMaskInvert`)
 
-Every visual layer (video/image/shape/text/sequence) additionally supports **card framing** item fields, all in canvas px:
+A shape can act as a **clipping mask**: set `shapeClipMask: true` and the layers below the shape's channel show only where the shape has coverage (the fill itself isn't drawn; the fill's alpha sets mask strength, and the shape's transforms/keyframes move the mask). **Text layers** take the same treatment with `textClipMask: true` — the glyph coverage is the matte, so footage plays inside the letters, and typography plus the split/stagger animation fields animate it. While a text layer masks, its own text shadow (`textShadowX/Y/Blur/Spread`) and caption bar (`textBgEnabled`) are ignored, as is card framing (`borderWidth`, `shadows`) — that alpha would leak into the matte; use the `blur` filter to feather instead. Either kind accepts `clipMaskInvert: true` to flip the matte (knockout: the layers below are hidden inside the shape/letters and shown everywhere else). A mask affects **all** channels below it in the same stack, masks stack, and they composite both at the top level and inside a sequence's inner timeline. A frame with an active mask skips the global Depth of Field.
 
-- **Rounded corners** — `borderRadius` (uniform, default 0). For per-corner radii set `borderRadiusLinked: false` and use `borderRadiusTL`, `borderRadiusTR`, `borderRadiusBR`, `borderRadiusBL` (each falls back to `borderRadius`). On `rectangle` shapes the radius can also be a % of the shorter side and is keyframable ([Rounded rectangles](#rounded-rectangles--buttons-pills-cards)); on media layers it is static px.
-- **Border** — `borderWidth` + `borderColor` (default 0 / `#ffffff`) + `borderStyle` (`solid` | `dashed` | `dotted` | `double`, default `solid`). `borderWidth` and `borderColor` are also keyframe tracks (`propertyKeyframes.borderWidth` in px, `propertyKeyframes.borderColor` as CSS colours) — a focus ring that grows, an outline that turns red on an error; a track overrides its field for the frame.
-- **Shadows** — `shadows`: an array of up to 4 layers, each `{ x, y, blur, spread, color, inset }` (CSS box-shadow semantics; `inset: true` draws an inner shadow; the first entry sits on top). Legacy single-shadow fields (`shadowX`, `shadowY`, `shadowBlur`, `shadowSpread`, `shadowColor`) are still read when `shadows` is absent and migrate on load.
+#### Track matte (`trackMatte`)
 
-- **Backdrop Blur** (shape layers ONLY — matte / frosted glass) — `backdropBlur` (px, 0–200, default 0 = off) blurs whatever is rendered **behind** the shape, inside its outline; the shape's own fill then draws over the blur, so a semi-transparent fill (`shapeFillColor: "rgba(255,255,255,0.25)"`) reads as frosted glass and a tinted one as smoked glass. `backdropSaturation` (%, 0–300, default 100) re-saturates the blurred backdrop (boost it for the iOS/macOS glass look). Both are keyframable as the `backdropBlur` / `backdropSaturation` tracks. The blur covers the shape's full coverage regardless of the fill's alpha (the plate alpha is normalised by the fill's peak alpha × `opacity`), fades with a gradient fill, and is ignored on clip-mask shapes and on every non-shape layer. A fully opaque fill hides the blur entirely — always pair `backdropBlur` with a semi-transparent `shapeFillColor` (the panel thins a solid fill to 35 % when Blur is first turned on and remembers the old paint in `backdropGlassFill`; setting Blur back to 0 or the section reset restores it unless the fill was edited since. The API does neither: set `backdropBlur: 0` AND the fill you want).
+The After Effects analog, distinct from clipping masks: it scopes to **one consumer layer** instead of the whole stack below, and supports luma. Set on the consumer item: `trackMatte: { sourceId: "<other item id>", mode: "alpha" | "alphaInverted" | "luma" | "lumaInverted" }` — the consumer then shows only where the source layer has alpha coverage (`alpha`) or brightness (`luma`; computed premultiplied, so transparent source areas contribute nothing), inverted variants flip it. The **source layer is hidden from output** while at least one active consumer references it; its transforms/keyframes still animate the matte.
 
-- **Glass** (shape layers only: `rectangle`, `ellipse`, `circle`) — the `glass` Layer Effect turns the shape into a pane of real glass that refracts, frosts, tints and shadows everything rendered **behind** it; see [Glass entry](video-effects.md#glass-entry).
+- The source must be another **visual** item (not audio/camera/adjustment) at the **same editing level**; the reference is by item id, not stack position; several consumers may share one source.
+- A mutual pair (A mattes with B while B mattes with A) is auto-broken on save.
+- If the source clip isn't under the playhead the matte is EMPTY — `alpha`/`luma` hide the consumer, inverted modes show it untouched.
+- The matte clips the consumer's **finished** look (after its filters, glow, overlay effects and motion blur), matching AE. The **source is read finished too**: its own `effects` chain, `layerEffects`, rig warp and motion blur shape the matte, so an `extract` (histogram key) or `alphaChoker` on the source layer is the normal way to author a matte from footage rather than from a silhouette.
+- Works at the top level and inside a sequence's inner timeline alike (inside a sequence only the layer's `effects` chain shapes the matte — glow, motion blur and the other Layer Effects are top-level stages); grids strip it on grouping.
+
+#### Card framing on every visual layer
+
+Every visual layer (video/image/shape/text/sequence) supports **card framing** item fields, all in canvas px:
+
+- **Rounded corners** — `borderRadius` (uniform, default 0); for per-corner radii set `borderRadiusLinked: false` and use `borderRadiusTL`, `borderRadiusTR`, `borderRadiusBR`, `borderRadiusBL` (each falls back to `borderRadius`). On media layers the radius is px; only `rectangle` shapes can also take a % of the shorter side ([Rounded rectangles](#rounded-rectangles--buttons-pills-cards)). It is keyframable on every layer: `propertyKeyframes.borderRadius` (the four corner tracks while unlinked) overrides the field for the frame, so a full-frame video can round into a card. The radius is drawn before the layer's scale, so a scaled picture's corners grow with it; `borderRadiusScaleLock: true` divides every radius by the layer's scale and keeps the corner's on-screen size. Border and shadows follow the rounded outline either way. A picture tile that grows 4× with a 24 px corner the whole way:
+
+  ```json
+  { "zoom": 0.25, "borderRadius": 24, "borderRadiusScaleLock": true,
+    "propertyKeyframes": { "scale": [
+      { "position": 0, "value": "1", "easing": "AE Smooth" },
+      { "position": 100, "value": "4", "easing": "AE Smooth" }
+    ] } }
+  ```
+- **Border** — `borderWidth` + `borderColor` (default 0 / `#ffffff`) + `borderStyle` (`solid` | `dashed` | `dotted` | `double`, default `solid`). `borderWidth` and `borderColor` are also keyframe tracks (`propertyKeyframes.borderWidth` in px, `propertyKeyframes.borderColor` as CSS colours) — a focus ring that grows, an outline that turns red on an error; a track overrides its field for the frame.
+- **Shadows** — `shadows`: an array of up to 4 layers, each `{ x, y, blur, spread, color, inset }` (CSS box-shadow semantics; `inset: true` draws an inner shadow; the first entry sits on top). The single-shadow fields (`shadowX`, `shadowY`, `shadowBlur`, `shadowSpread`, `shadowColor`) are read when `shadows` is absent and are converted on load.
 
 These bake into `/render-onserver` like everything else.
 
-**Stroke instead of fill (`shapePathRenderMode`).** On `path` and `custom` shapes, `"fill"` (the default) paints the enclosed area with `shapeFillColor`; `"stroke"` draws the outline only, at `shapeStrokeWidth`, which is what you want for a signature, a route line or any open figure where a fill would close the curve. `line` shapes are always stroked regardless.
+#### Backdrop blur and glass
+
+- **Backdrop Blur** (shape layers ONLY — matte / frosted glass) — `backdropBlur` (px, 0–200, default 0 = off) blurs whatever is rendered **behind** the shape, inside its outline; the shape's own fill then draws over the blur, so a semi-transparent fill (`shapeFillColor: "rgba(255,255,255,0.25)"`) reads as frosted glass and a tinted one as smoked glass. `backdropSaturation` (%, 0–300, default 100) re-saturates the blurred backdrop (boost it for the iOS/macOS glass look). Both are keyframable as the `backdropBlur` / `backdropSaturation` tracks. The blur covers the shape's full coverage regardless of the fill's alpha (the plate alpha is normalised by the fill's peak alpha × `opacity`), fades with a gradient fill, and is ignored on clip-mask shapes and on every non-shape layer. A fully opaque fill hides the blur entirely — always pair `backdropBlur` with a semi-transparent `shapeFillColor`. (The editor thins a solid fill to 35 % when `backdropBlur` first goes above 0 and remembers the previous paint in `backdropGlassFill`; setting `backdropBlur` back to 0 there restores it unless the fill was edited since. The API does neither: set `backdropBlur: 0` AND the fill you want.)
+- **Glass** (shape layers only: `rectangle`, `ellipse`, `circle`) — the `glass` Layer Effect turns the shape into a pane of real glass that refracts, frosts, tints and shadows everything rendered **behind** it; see [Glass entry](video-effects.md#glass-entry).
+
+#### Traced vectors (`shapeType: "vector"`)
 
-**Traced-vector provenance.** A shape produced by the image → vector tracer keeps where it came from: `shapeVectorSourceUrl` (the bitmap it was traced from), `shapeVectorFileName` (that file's name, ≤240 chars), `shapeVectorPathCount` (how many sub-paths the trace produced) and `shapeVectorTrace` (the tracer settings, so the trace can be re-run at a different threshold). All four are bookkeeping — the drawn artwork is `shapePath` / `shapeSvgUrl` like any other shape — but preserve them when you edit such a layer or the user loses the ability to re-trace.
+The editor's **Image to vector** tracer makes a `vector` shape: the traced artwork is drawn from `shapeSvgUrl` in its own colours (a `custom` SVG is recoloured with `shapeFillColor`; a `vector` one is not), contain-fitted in the shape's box. The layer keeps where it came from: `shapeVectorSourceUrl` (the bitmap it was traced from), `shapeVectorFileName` (that file's name, ≤ 240 chars), `shapeVectorPathCount` (how many sub-paths the trace produced), `shapeVectorTrace` (the tracer settings, so the trace can be re-run at a different threshold) and `shapeVectorEditablePath` (an editable outline: converting the layer to a `path` in the editor uses it, drawn as a stroke). Preserve all five when you edit such a layer, or the user loses the ability to re-trace or convert it.

package/skill/references/video-text-kinetic.md

@@ -10,36 +10,38 @@
 
 ## Contents
 
-- [When to use them](video-text-kinetic.md#when-to-use-them)
-- [How every recipe works](video-text-kinetic.md#how-every-recipe-works)
-- [Writing a recipe onto a layer](video-text-kinetic.md#writing-a-recipe-onto-a-layer)
-- [The catalogue](video-text-kinetic.md#the-catalogue) and [Recipes](video-text-kinetic.md#recipes)
+- [When to use them](#when-to-use-them)
+- [How every recipe works](#how-every-recipe-works)
+- [Writing a recipe onto a layer](#writing-a-recipe-onto-a-layer)
+- [The catalogue](#the-catalogue) and [Recipes](#recipes)
 
 ## When to use them
 
-**Prefer these 21 recipes whenever text should feel energetic** — a hook, a title card, a promo or social
+**Prefer these 22 recipes whenever text should feel energetic** — a hook, a title card, a promo or social
 line, a beat-synced word, a call to action, a reveal; anything the user calls punchy, bouncy, poppy, playful,
 dynamic, kinetic, lively, "with energy" or "make it pop". They are the app's own Kinetic presets: tuned
 in-and-out motion that a hand-built animator rarely matches, so start from one instead of composing animators
 from scratch, then adjust.
 
 Not for calm or readable-first text: captions under speech, tutorials, long paragraphs, lower thirds. Use a
-plain Time fade or rise there (Fade Up in video-text.md) — a swinging paragraph is hard to read.
+plain Time fade or rise there ([Classic Fade Up](video-text-presets.md#classic-fade-up) or
+[Classic Rise (Mask)](video-text-presets.md#classic-rise-mask)) — a swinging paragraph is hard to read.
 
 Pick by the text:
 
-- **2–4 short lines** (a stacked title): a *lines* recipe. Swing Pop is the signature one.
-- **One line of 3–8 words**: a *words* recipe.
+- **2–4 short stacked lines** (one or a few words each): a *words* recipe; Swing Pop is the signature one.
+- **One line of up to ~5 words** (a hook, a title, a call to action): a *words* recipe. A longer line or a caption
+  under speech reads cheap with this much motion; use a calm preset there ([video-design.md](video-design.md#text-animation)).
 - **One short word or title, up to ~20 letters**: a *letters* recipe.
 
 Preferred recipes: when the user has not named one, choose from these first, as long as the recipe fits the text by
 the rules above: [Swing Pop](#swing-pop), [Pendulum](#pendulum), [Fan Deal](#fan-deal) and [Whip](#whip)
-(lines); [Word Swing](#word-swing) (words); [Letter Vortex](#letter-vortex)
+(words; they read well stacked); [Word Swing](#word-swing) (words); [Letter Vortex](#letter-vortex)
 (letters).
 
 ## How every recipe works
 
-Each recipe is **two Time animators** (some add a third, a quick fade) on one text layer, and nothing else:
+Each recipe is exactly **two Time animators** on one text layer, and nothing else:
 
 - the **in** animator (`"animate": "in"`): every unit arrives from its effects, `stagger` seconds apart,
   from the layer's start;
@@ -48,33 +50,36 @@ Each recipe is **two Time animators** (some add a third, a quick fade) on one te
 
 There are no keyframes, so a recipe fits any layer length: changing the layer's duration keeps the entrance at
 the start and the exit at the end. One side takes `(units − 1) × stagger + duration` seconds; keep the layer
-longer than the in and out sides together plus the time the text should rest (line recipes: 2.5 s or more;
+longer than the in and out sides together plus the time the text should rest (word recipes on 2–4 lines: 2.5 s or more;
 letter recipes on long text need more).
 
-`"around": "all"` turns every unit around the centre of the **whole** text, not its own centre, so outer lines
-and letters travel on arcs — Swing Pop's look. `textAnimatorPivotX` / `textAnimatorPivotY` (−100…100) move
-that point: Pendulum hangs from the top (`textAnimatorPivotY: -100`), Fan Deal fans from the bottom, Door
-Swing hinges on the left edge, Domino stands each line on its own bottom-left corner.
+`"around": "all"` turns every unit around the centre of the **whole** text, not its own centre, so outer words
+and letters travel on arcs — Word Swing's and Letter Vortex's look. `textAnimatorPivotX` / `textAnimatorPivotY`
+(−100…100) move each unit's turning point: Pendulum hangs each word from its top edge (`textAnimatorPivotY: -100`),
+Fan Deal fans each word from its bottom edge, Door Swing hinges each word on its left edge, Domino stands each word
+on its bottom-left corner.
 
-The curves do the energy: `Overshoot` lands past rest and settles, `Elastic` and `Bounce Out` wobble or bounce,
-`Swing` dips before it springs, and `Anticipate` (the usual exit) winds back the other way, then snaps through
+The curves do the energy: `Overshoot` lands past rest and settles, `Elastic` and `Bounce Out` wobble or bounce, and `Anticipate` (the usual exit) winds back the other way, then snaps through
 in the last frames.
 
 ## Writing a recipe onto a layer
 
-- Copy the recipe's JSON into the text item: its `textAnimators`, plus `textAnimatorPivotX` / `textAnimatorPivotY`
-  when the recipe has them. Replace the layer's existing `textAnimators`, or append with fresh unique `aid` /
-  `pid` values.
-- **Lengths are for `textFontSize` 100.** Multiply every `position` `x` / `y`, `blur` `amount` and `rotate3d`
-  `perspective` by `textFontSize / 100`. Angles, scales, opacities and timings stay as written.
+Follow [Writing a recipe onto a layer](video-text-presets.md#writing-a-recipe-onto-a-layer) in text-presets.md (replace or
+add, ids, scaling lengths to the font size). Kinetic recipes have no keyframes, so they fit any layer length as
+written. In short:
+- **Replace**: delete the old `textAnimators` and every `txa:` track, and set both pivots to the recipe's values (0
+  when it has none). Recipes reuse ids like `a1`/`p1`, so a leftover track or pivot would drive the new animator.
+- **Lengths are for a 100 px font.** Multiply every `position` `x` / `y` / `z`, `blur` `amount`, `rotate3d`
+  `perspective` and the layer's `textAnimatorPerspective` by the layer's font size in px / 100: `textFontSize`, or in pct mode
+  `textFontSizePct × videoSize.h / 100`. Angles, scales, opacities and timings stay as written.
 - Faster or slower: divide every `stagger` and `duration` by the same factor (2 = twice as fast).
 - Colour, font and size are the layer's own; the recipes only move the text.
 - To check it, render a still at the middle of the entrance and one in the middle of the layer
-  (video-rendering.md): mid-entrance the text is moving, mid-layer it rests exactly as typed.
+  (rendering.md): mid-entrance the text is moving, mid-layer it rests exactly as typed.
 
 ## The catalogue
 
-<!-- KINETIC:BEGIN (generated by tests/text-animators/skill_presets.mjs from presets.js — edit there) -->
+<!-- KINETIC:BEGIN (generated from the app's presets; do not edit by hand) -->
 
 | Recipe | What it does | Unit | Turns around | In · Out curve |
 |---|---|---|---|---|
@@ -82,14 +87,14 @@ in the last frames.
 | [Word Swing](#word-swing) | Words pop out of the middle of the text in random order and swing round into place; at the end they wind up and pop back | words | centre of the whole text | Overshoot · Anticipate |
 | [Letter Vortex](#letter-vortex) | Letters spiral out of the centre of the text one by one; at the end they spin back into it | letters | centre of the whole text | Overshoot · Anticipate |
 | [Center Burst](#center-burst) | The middle words burst out first and the others follow, wobbling into place; at the end they shrink away from the outside in | words | each word's centre | Elastic · Back In |
-| [Pendulum](#pendulum) | Words hang from their top edge and swing in like a pendulum until they settle; at the end they swing away | words | each word's centre | Elastic · Anticipate |
+| [Pendulum](#pendulum) | Words hang from their top edge and swing in like a pendulum until they settle; at the end they swing away | words | each word's top edge | Elastic · Anticipate |
 | [Spin Pop](#spin-pop) | Each word spins a full turn in place as it grows in; at the end each spins back out | words | each word's centre | Back Out · Back In |
 | [Domino](#domino) | Words stand up on their bottom-left corner and drop flat with a bounce, one after another; at the end they fall over | words | each word's bottom-left corner | Bounce Out · Ease In |
 | [Flip Pop](#flip-pop) | Words flip up into view in 3D, past flat and back; at the end they tip back and flip away | words | each word's centre | Overshoot · Anticipate |
 | [Card Turn](#card-turn) | Words turn to face you like cards, one by one, overshooting the turn; at the end they turn away | words | each word's centre | Overshoot · Anticipate |
 | [Slam Zoom](#slam-zoom) | Words slam down from huge, punch past their size and settle; at the end they fly back at the camera | words | each word's centre | Overshoot · Expo In |
 | [Orbit](#orbit) | Words turn in from a third of a turn away and ease into place; at the end they turn off | words | each word's centre | Smooth Overshoot · Anticipate |
-| [Fan Deal](#fan-deal) | Words fan up from their bottom edge like cards dealt from a hand, last word first; at the end they fan away | words | each word's centre | Overshoot · Anticipate |
+| [Fan Deal](#fan-deal) | Words fan up from their bottom edge like cards dealt from a hand, last word first; at the end they fan away | words | each word's bottom edge | Overshoot · Anticipate |
 | [Whip](#whip) | Words whip in from the left leaning into the move, snap past and settle; at the end they lean back and whip off to the right | words | each word's centre | Overshoot · Anticipate |
 | [Rubber Letters](#rubber-letters) | Letters spring out of thin slivers and wobble like rubber; at the end they stretch tall and squash flat | letters | each letter's centre | Elastic · Anticipate |
 | [Pop Letters](#pop-letters) | Letters pop up in random order, each with a little twist; at the end they swell and pop away at random | letters | each letter's centre | Overshoot · Anticipate |
@@ -97,7 +102,9 @@ in the last frames.
 | [Coin Spin](#coin-spin) | Letters spin in like coins, one after another, and rock to a stop; at the end they spin away | letters | each letter's centre | Overshoot · Anticipate |
 | [Converge](#converge) | Words shrink down from far bigger, the outer ones first, and settle; at the end they burst outward | words | each word's centre | Expo Out · Expo In |
 | [Roll In](#roll-in) | Letters roll in from the right like wheels and rock back into place; at the end they roll off to the left | letters | each letter's centre | Overshoot · Back In |
-| [Door Swing](#door-swing) | Words swing open in 3D on a hinge at their left edge, past flat and back; at the end they swing shut | words | each word's centre | Overshoot · Anticipate |
+| [Door Swing](#door-swing) | Words swing open in 3D on a hinge at their left edge, past flat and back; at the end they swing shut | words | each word's left edge | Overshoot · Anticipate |
+| [Title Push 3D](#title-push-3d) | Words fly in from depth one by one, overshoot toward the camera and settle as the line glides over to make room; at the end they rush past the camera | words | each word's centre | Back Out · Ease In |
+| [Perspective Type](#perspective-type) | Lines drive in one after another on a plane tilted toward the camera, which then swings flat; at the end they sink back into depth | lines | each line's centre | AE Smooth · Ease In |
 
 ## Recipes
 
@@ -446,4 +453,48 @@ Words swing open in 3D on a hinge at their left edge, past flat and back; at the
 }
 ```
 
+### Title Push 3D
+
+Words fly in from depth one by one, overshoot toward the camera and settle as the line glides over to make room; at the end they rush past the camera.
+
+```json
+{
+  "textAnimators": [
+    { "aid": "a1", "name": "Fly in",
+      "range": {"basedOn": "words", "drive": "time", "animate": "in", "around": "word", "stagger": 0.2, "duration": 0.75, "curve": "Back Out"},
+      "effects": [{"pid": "p1", "type": "position", "x": 0, "y": 35, "z": -2600}, {"pid": "p2", "type": "rotate3d", "x": -50, "y": 0, "perspective": 600}, {"pid": "p3", "type": "opacity", "opacity": 0}] },
+    { "aid": "a2", "name": "Push",
+      "range": {"basedOn": "lines", "drive": "time", "animate": "in", "around": "all", "stagger": 0, "duration": 1.6, "curve": "Sine Out"},
+      "effects": [{"pid": "p4", "type": "position", "x": 240, "y": 0}] },
+    { "aid": "a3", "name": "Rush out",
+      "range": {"basedOn": "words", "drive": "time", "animate": "out", "around": "word", "order": "backward", "stagger": 0.05, "duration": 0.55, "curve": "Ease In"},
+      "effects": [{"pid": "p5", "type": "position", "x": 0, "y": 0, "z": 900}, {"pid": "p6", "type": "opacity", "opacity": 0}] }
+  ],
+  "textAnimatorCamera": "layer",
+  "textAnimatorPerspective": 1300
+}
+```
+
+### Perspective Type
+
+Lines drive in one after another on a plane tilted toward the camera, which then swings flat; at the end they sink back into depth.
+
+```json
+{
+  "textAnimators": [
+    { "aid": "a1", "name": "Lines in",
+      "range": {"basedOn": "lines", "drive": "time", "animate": "in", "around": "line", "stagger": 0.5, "duration": 0.5, "curve": "AE Smooth"},
+      "effects": [{"pid": "p1", "type": "position", "x": 0, "y": 140}, {"pid": "p2", "type": "scale", "scale": 55}, {"pid": "p3", "type": "opacity", "opacity": 0}] },
+    { "aid": "a2", "name": "Tilted plane",
+      "range": {"basedOn": "lines", "drive": "time", "animate": "in", "around": "all", "delay": 1.2, "stagger": 0, "duration": 0.7, "curve": "Natural"},
+      "effects": [{"pid": "p4", "type": "rotate3d", "x": 32, "y": 25, "perspective": 300}, {"pid": "p5", "type": "rotation", "angle": -6}, {"pid": "p6", "type": "scale", "scale": 150}, {"pid": "p7", "type": "position", "x": 16, "y": -4}] },
+    { "aid": "a3", "name": "Sink out",
+      "range": {"basedOn": "lines", "drive": "time", "animate": "out", "around": "line", "order": "backward", "stagger": 0.08, "duration": 0.5, "curve": "Ease In"},
+      "effects": [{"pid": "p8", "type": "position", "x": 0, "y": 0, "z": -800}, {"pid": "p9", "type": "opacity", "opacity": 0}] }
+  ],
+  "textAnimatorCamera": "layer",
+  "textAnimatorPerspective": 300
+}
+```
+
 <!-- KINETIC:END -->