Update to Picsart
Snapshot Nov 7, 2026 · 00:09 UTC · version 2.4.0
Collection source: downloaded plugin package.
Instructions updated for custom-transitions
Skill instructions — Now says: ported-from: transition-authoring 1.0 at 55.75.0 admits **`min`, `max`, `abs`, `floor`, `ceil`, `round`, `sqrt`, `sin`, `cos`, `atan2(y, x)`** (angles in...
Observed in instructions or declared skills. Runtime behavior has not been tested.
Up to 3 plugins free · no card required.
All fields and original values.
Skill instructions
Nov 3, 2026 · 18:14 UTC
admits **`min`, `max`, `abs`, `floor`, `ceil`, `round`, `sqrt`** and nothing else. There is no `hypot` and no ternary; `and`/`or`/`not` exist for `$when` gates. (`min max abs floor ceil round sqrt and or not true false`), the firing-supp...
Nov 7, 2026 · 00:09 UTC
ported-from: transition-authoring 1.0 at 55.75.0 admits **`min`, `max`, `abs`, `floor`, `ceil`, `round`, `sqrt`, `sin`, `cos`, `atan2(y, x)`** (angles in radians) and nothing else. There is no `hypot` and no ternary; `and`/`or`/`not` e...
Compare saved observations
Download comparison JSONSKILL.md text changes
− removed · + added
--- before +++ after @@ -4,6 +4,7 @@ metadata: category: authoring version: '1.0' + ported-from: transition-authoring 1.0 at 55.75.0 --- # Writing a transition @@ -82,13 +83,13 @@ | The selected variant's row | `scene.variants.table.<row>` | `{"$eval":"sweep"}` | `{"$eval": "..."}` computes over all three. The grammar is small on purpose — it -admits **`min`, `max`, `abs`, `floor`, `ceil`, `round`, `sqrt`** and nothing -else. There is no `hypot` and no ternary; `and`/`or`/`not` exist for `$when` gates. +admits **`min`, `max`, `abs`, `floor`, `ceil`, `round`, `sqrt`, `sin`, `cos`, +`atan2(y, x)`** (angles in radians) and nothing else. There is no `hypot` and no ternary; `and`/`or`/`not` exist for `$when` gates. The frame diagonal is `sqrt(width * width + height * height)`, so a circle that must cover the frame from its centre needs a diameter of exactly that. Names that are refused rather than shadowed: the grammar's own -(`min max abs floor ceil round sqrt and or not true false`), the firing-supplied +(`min max abs floor ceil round sqrt sin cos atan2 and or not true false`), the firing-supplied three, and a variant row's own selector. The check covers EVERY row, not the selected one — a clean row does not excuse a broken sibling. @@ -158,9 +159,15 @@ star and bar read 1.1 / 26.9 / 97.0, 1.8 / 45.5 / 100, 1.0 / 26.5 / 100 at t = 2.7 / 3.0 / 3.3 through a 1s window. -`shape_reveal` is the larger worked example: sixteen choreographies, with the +`shape_reveal` is the larger worked example: twenty-one choreographies, with the geometry written as fractions of `width`/`height` so a circle stays a circle at -every aspect. Each variant's row declares its shape tree ONCE, and three layers +every aspect. Its five `wipe_*` rows are the exception: an edge at any `angle` +is drawn in units of the frame diagonal inside a group that rotates by `angle` +and scales by `diagonal / 100`, so it covers every aspect at every angle. Those +rows also supply `lineShape` and `panelShape` for the `accent` layers (a divider +stroke drawn over the blur band, a colour panel under the destination); every +other row supplies them empty, because a body may only read a row key every row +carries. Each variant's row declares its shape tree ONCE, and three layers draw it with `"items": {"$eval": "shape"}` (the sharp mask, the blur band, and the band's lagged cut). The lagged copy is that same tree on a later clock: `"start": {"$eval": "0.22 * duration"}, "timeMode": "layer"`. A later `start` @@ -174,6 +181,15 @@ copies to land by `0.9 * duration` left the last frames clean at 0.4s, 1s and 2s, and at 24 fps. +**Repeat a mask piece with `$each` over a number.** In a definition, `$each` +may name a whole number N (a parameter or a row field) and makes N copies whose +item is the copy's index. `tile_mosaic` nests `{"$each": "rows", "as": "r"}` +and `{"$each": "columns", "as": "c"}` inside the mask's shape `items`, one +group per tile, each with its own `opacity` keyframes timed from `r` and `c`. +The variant picks the order through numeric row weights (`byRow`, +`byDiagonal`, `byRandom`): a row field is filled at the definition's top scope, +so it cannot read `r` or `c` itself. A fraction or a negative count is refused with `invalid_each`. + The shape vocabulary is `ellipse`, `rect`, `polystar`, `path`, `fill`, `stroke`, `gradientFill`, `gradientStroke`, `group`, `trim`, `repeater`, `roundCorners`, `offsetPaths`, `zigZag`, `merge`.
Full technical diff · 1 changed fields
changed /skill_md_contents
"---\nname: custom-transitions\ndescription: How to write a new scene transition as an inline JSON definition — the slot contract, the token vocabulary a definition may read, the four mechanisms a transition can be built from, and the frictions that make a plausible-looking definition render wrong. Every rule here was rendered, and the numbers are what was drawn. Use when authoring or reviewing a transition definition, or when a transition renders at the wrong speed, cuts, or is refused by the validator.\nmetadata:\n category: authoring\n version: '1.0'\n---\n\n# Writing a transition\n\nA transition is DATA: a JSON definition, declared inline as a `type: \"transition\"`\nasset. This is what the definition has to say, and what goes wrong.\n\n**Check what already exists first.** `picsart_scene_capabilities({sections:\n[\"transitions\"]})` returns every built-in transition with its id, description\nand parameters; if one of them does what you need, apply it by id and stop\nhere. Authoring is for the case where none of them does.\n\n## Incoming continuity contract\n\nThis skill defines an already-decided seam; it does not decide what two beats should mean together.\nBefore writing a definition, require four inputs:\n\n1. the semantic relationship — continuation, replacement, reveal, arrival, interruption, or reset;\n2. the intended travel vector, or an explicit decision that this boundary resets it;\n3. the visual carrier, when the viewer should be able to follow one;\n4. the concrete reason no shipped catalog transition expresses that relationship.\n\nIf any of these is still undecided, return to\nmotion-scene-continuity (fetch with `picsart_scene_recipe`, name `motion-scene-continuity`). Do not invent a custom transition merely\nbecause the adjacent scenes feel disconnected; the representation may instead be one persistent\nlayer, a hard cut, or an existing crossfade or directional transition.\n\n## The shape of a definition\n\nTwo parts: `meta` identifies it, `scene` IS a scene — the same document model as\nanywhere else, with two extra powers.\n\n```json\n{ \"meta\": { \"id\": \"crossfade\", \"displayName\": \"Crossfade\",\n \"description\": \"Linear dissolve from source to destination: the two weights always sum to one, so the background never shows through an opaque pair.\" },\n \"scene\": {\n \"version\": \"1.0\",\n \"composition\": { \"width\": {\"$eval\":\"width\"}, \"height\": {\"$eval\":\"height\"},\n \"fps\": 30, \"duration\": {\"$eval\":\"duration\"} },\n \"layers\": [\n { \"id\": \"source\", \"start\": 0, \"duration\": {\"$eval\":\"duration\"},\n \"content\": { \"kind\": \"slot\", \"role\": \"source\" },\n \"animations\": { \"opacity\": { \"keyframes\": [\n { \"time\": 0, \"value\": 1 }, { \"time\": {\"$eval\":\"duration\"}, \"value\": 0 } ] } } },\n { \"id\": \"destination\", \"start\": 0, \"duration\": {\"$eval\":\"duration\"}, \"blendMode\": \"add\",\n \"content\": { \"kind\": \"slot\", \"role\": \"destination\" },\n \"animations\": { \"opacity\": { \"keyframes\": [\n { \"time\": 0, \"value\": 0 }, { \"time\": {\"$eval\":\"duration\"}, \"value\": 1 } ] } } } ] } }\n```\n\nThat is a complete, shipping transition. The destination ADDS onto the fading\nsource inside the firing's own canvas, so the weights are t and 1 − t and sum to\none. Two `normal` fades would each let the composition background through: at\nthe midpoint a red→red crossfade over green read G = 132, a 25% background\nshare.\n\nThe two extra powers:\n\n**`content: { \"kind\": \"slot\", \"role\": \"source\" | \"destination\" }`** — a hole\nfilled at render time with the outgoing clip's last frame or incoming clip's first frame. A\ndefinition never names a clip; it arranges two boundary-frame slots. Exactly one of each role. The\ndefinition animates those supplied frames on its own clock; neighboring clip animation does not\ncontinue live through the transition window. If the seam needs a genuinely live shared object,\nkeep that object alive outside this slot contract.\n\n**Firing-supplied tokens.** `width`, `height` and `duration` are handed in by the\ncall site and are NOT declared in `parameters`. Read them as `{\"$eval\":\"width\"}`\nor inside an expression as `{\"$eval\": \"width / 2\"}`.\n\n## What a definition may read\n\n| Source | Declared where | Read as |\n|---|---|---|\n| `width`, `height`, `duration` | nowhere — the firing supplies them | `{\"$eval\":\"duration\"}` |\n| Your own knobs | `scene.parameters` | `{\"$eval\":\"softness\"}` |\n| The selected variant's row | `scene.variants.table.<row>` | `{\"$eval\":\"sweep\"}` |\n\n`{\"$eval\": \"...\"}` computes over all three. The grammar is small on purpose — it\nadmits **`min`, `max`, `abs`, `floor`, `ceil`, `round`, `sqrt`** and nothing\nelse. There is no `hypot` and no ternary; `and`/`or`/`not` exist for `$when` gates.\nThe frame diagonal is `sqrt(width * width + height * height)`, so a circle that\nmust cover the frame from its centre needs a diameter of exactly that.\n\nNames that are refused rather than shadowed: the grammar's own\n(`min max abs floor ceil round sqrt and or not true false`), the firing-supplied\nthree, and a variant row's own selector. The check covers EVERY row, not the\nselected one — a clean row does not excuse a broken sibling.\n\n## Variants\n\nOne definition, many looks. `by` names the selector param; each row's fields join\nthe scope for that firing.\n\n```json\n\"parameters\": { \"variant\": { \"type\": \"text\", \"default\": \"circle\",\n \"enum\": [\"circle\", \"star\", \"bar\"] } },\n\"variants\": { \"by\": \"variant\", \"table\": {\n \"circle\": { \"isCircle\": true, \"isStar\": false, \"isBar\": false },\n \"star\": { \"isCircle\": false, \"isStar\": true, \"isBar\": false } } }\n```\n\nGate whole layers or shape items on a row field with `\"$when\": \"isStar\"`. A row\nfield beats a firing param of the same name.\n\n## The four mechanisms, and what each costs\n\n| Built from | Example | Needs an asset | Fits any `duration` |\n|---|---|---|---|\n| **Opacity** | `crossfade` | no | yes, by construction |\n| **Transform** | `slide`, `diagonal_slide` | no | yes, by construction |\n| **Effect** | `blur_dissolve` | no | yes, by construction |\n| **Mask — shape layer** | `iris`, `shape_reveal` | **no** | **yes, by construction** |\n| **Mask — video/lottie matte** | none shipped (`push`, `splatter` were) | yes, remote | **no — see below** |\n\nThe first four animate on the DEFINITION's own clock. Their keyframes are written\nat `{\"$eval\":\"duration\"}`, so whatever window the author asks for is the window\nthey fill. Nothing else is needed.\n\n**Prefer a shape mask over a video matte.** It needs no asset, no network,\nno external renderer, and it cannot drift out of time with its window. **Never\nship a `.webm` matte:** iOS (AVFoundation) cannot decode WebM, so the incoming\nclip just cut in there — which is why `push`, `bubble`, `cubes`, `free_fall`,\n`kaleida` and `splatter` were removed from the catalogue. The matte notes below\nare kept for a matte in a format supported by the intended playback environment.\n\n**Keep a definition cheap enough to play in real time on a phone.** A blur's cost\ngrows with its radius times the area it covers, and a firing pays it on every frame\nof the window. `movement_camera` peaked at a full-frame whip blur, 260 px at 720p,\nwhich cost up to ~180 ms a frame at the cut and stalled playback, so it was removed\nfrom the catalogue too. Blur a small layer, or keep the radius low.\n\n`iris` does a circle, a six-point star and a widening bar from one definition:\n\n```json\n\"mask\": { \"invert\": false, \"clip\": {\n \"id\": \"iris_mask\",\n \"transform\": { \"position\": [{\"$eval\":\"width / 2\"}, {\"$eval\":\"height / 2\"}] },\n \"content\": { \"kind\": \"shape\", \"items\": [\n { \"$when\": \"isCircle\", \"type\": \"ellipse\",\n \"size\": [{\"$eval\":\"width * 1.6\"}, {\"$eval\":\"width * 1.6\"}], \"position\": [0,0] },\n { \"$when\": \"isStar\", \"type\": \"polystar\", \"starType\": \"star\", \"points\": 6,\n \"position\": [0,0], \"outerRadius\": {\"$eval\":\"max(width, height) * 1.45\"},\n \"innerRadius\": {\"$eval\":\"max(width, height) * 0.80\"} },\n { \"type\": \"fill\", \"color\": \"#ffffffff\" } ] },\n \"animations\": { \"scale\": { \"keyframes\": [\n { \"time\": 0, \"value\": [0.001, 0.001], \"easing\": \"ease_in\" },\n { \"time\": {\"$eval\":\"duration\"}, \"value\": [1, 1] } ] } } } }\n```\n\nMeasured on a 640×480 frame, `iris`/`circle` at `duration` 0.4, 1.0 and 2.0 gave\nthe SAME progression every time — 0% / ~5% / 66% / 100% across the window. Circle,\nstar and bar read 1.1 / 26.9 / 97.0, 1.8 / 45.5 / 100, 1.0 / 26.5 / 100 at\nt = 2.7 / 3.0 / 3.3 through a 1s window.\n\n`shape_reveal` is the larger worked example: sixteen choreographies, with the\ngeometry written as fractions of `width`/`height` so a circle stays a circle at\nevery aspect. Each variant's row declares its shape tree ONCE, and three layers\ndraw it with `\"items\": {\"$eval\": \"shape\"}` (the sharp mask, the blur band, and\nthe band's lagged cut). The lagged copy is that same tree on a later clock:\n`\"start\": {\"$eval\": \"0.22 * duration\"}, \"timeMode\": \"layer\"`. A later `start`\nalone does NOT delay it, because keyframe times are composition seconds by\ndefault. The lagged copy then moved in lockstep and the blur band disappeared.\nOne more friction it measured:\n\n- **Land the motion before the window ends.** A track keyed to end exactly at\n `duration` on an ease-out is still short of its end pose on the last frame at\n short windows (0.4s). Its blurred band then cleared in one frame. Keying both\n copies to land by `0.9 * duration` left the last frames clean at 0.4s, 1s and 2s,\n and at 24 fps.\n\nThe shape vocabulary is `ellipse`, `rect`, `polystar`, `path`, `fill`, `stroke`,\n`gradientFill`, `gradientStroke`, `group`, `trim`, `repeater`, `roundCorners`,\n`offsetPaths`, `zigZag`, `merge`.\n\n## Frictions\n\n**A shape item discriminates on `type`, not `kind`.** Content is `kind`, shape\nitems are `type` — they mirror Lottie's own item vocabulary. Getting it wrong fails\nwith `missing_field` on the item's `type`, listing every tag it could have been. Their\nnames are also camelCase (`gradientFill`, `roundCorners`, `zigZag`) while the\nrest of the format is snake_case.\n\n**The window is CENTRED on the cut and eats `duration/2` out of EACH neighbouring\nclip.** A 7.25s transition needs 3.625s of both. Too long for the clips and the\nvalidator refuses the whole document with `transition_window_exceeds_clip`. Size a\ntransition against the shortest clip it sits between, not against the composition.\n\n**A time-based matte does not fit the window by itself.** A `.webm` or a lottie\nplays at 1× from its own zero. Too long a window and the wipe finishes early and\nthen the matte runs out before the window ends. Too short and it is a hard cut: `splatter`/`blood_drop_1` in a 1.0s\nwindow reached 9.8% and then gained 90 points in a single frame. The fix, which\nevery matte family carries, is\nto map the window onto the matte's own travel time. `lead` is a second row field:\nthe last source second at which the matte still equals its first frame, so the\nwindow does not spend its opening standing still (`cubes`/`style10` holds for\n1.08s of a 1.63s matte, and without `lead` moved only in the last third):\n\n```json\n\"trim\": { \"in\": { \"$eval\": \"lead\" }, \"out\": { \"$eval\": \"sweep\" } },\n\"speed\": { \"$eval\": \"(sweep - lead) / duration\" }\n```\n\n`sweep` is a variant-row field holding the matte's active source extent in source\nseconds — measure it as the first frame where no more than ~1.16% of the\nmatte's pixels remain above 0.5 alpha, the rule every shipped matte row\nfollows. **`speed` is refused\nwithout an explicit `trim`**: time remapping needs a known source extent, and the\nrenderer cannot probe for one. A matte definition with no `sweep` is refused the same way.\n\n**A matte whose edge travels the full frame in one direction (push) must `fill`;\na shaped matte keeps `cover`; verify at 9:16 as well as 16:9.** `cover` crops a\n16:9 matte to its middle 32% on a portrait frame, so `push`'s left/right edge\ncrossed the visible strip in one matte frame and rendered as a hard cut; `fill`\nmaps the whole travel onto any frame. A shaped matte (a splatter, a bubble)\nwould distort under `fill`.\n\nA shaped matte that keeps `cover` pays for it in time instead. A portrait frame\ncrops the 16:9 matte to its centre, which clears first, so a single `sweep`\nfinished `splatter`/`blood_splatter_1` at 45% of a 9:16 window and held. Cover-fit\nrows therefore carry `sweep_tall` (9:16) and `sweep_square` (1:1) next to\n`sweep` (16:9), and the trim end interpolates between them on the frame's aspect:\n\n```json\n\"out\": { \"$eval\": \"sweep_tall + (sweep_square - sweep_tall) * min(1, max(0, (width / height - 0.5625) * 16 / 7)) + (sweep - sweep_square) * min(1, max(0, (width / height - 1) * 9 / 7))\" }\n```\n\n`speed` is that same expression, minus `lead`, over `duration`. Measure each\nvalue with the same residue rule as `sweep`: the first frame where no more than\nthe row's 16:9 residue remains, rendering the matte under its own `cover` fit on\na 9:16 frame for `sweep_tall` and on a 1:1 frame for `sweep_square`.\n\n**A splatter matte leaves an edge residue on 16:9.** Stopping at the ~1.16%\nthreshold leaves ~1–1.6% of the outgoing clip at the frame edges, which drops\nout on the window's last frame. That is accepted: holding the matte until it is\nfully clear would spend most of the window on an almost-empty tail, and `cover`\ncrops the residue away on 9:16.\n\n**A mask is an owned clip.** `mask.clip` spans the host layer's window, and its\nkeyframes count from the host's start. It carries its own `transform`,\n`transforms[]` and `animations`, so an animated shape mask animates. A mask that\nstarts later than its host (a lag matte) puts a `composition` in the clip's\ncontent, with the delayed layer inside it — see `shape_reveal`'s lag mask.\n\n**The non-active part of a clip is its first or last frame.** A transition shows\nthe outgoing clip's last frame and the incoming clip's first, not live playback\nof both. Design the beat around that.\n\n## Verifying one\n\nThe definition is data, so the only question worth asking is what the renderer\ndrew. Validate it with `picsart_scene_validate`, then render full-resolution stills at the\nsample times below in ONE call per `duration`:\n`picsart_scene_contact_sheet` with `times: [t1, t2, …]` and `resolution` set to the scene's `composition.width` and `composition.height`. Without `resolution` the sheet returns downscaled thumbnails, which are not for judging position. The sheet image scales every frame to fit one picture; to judge full-resolution detail, open a frame's `url`.\n\nSample ACROSS the window, not at its midpoint: the failures above all look fine\nat 50%. For a window `[c - d/2, c + d/2]` take at least `0.0, 0.25, 0.5, 0.75,\n1.0` of it, and measure coverage rather than eyeballing — the incoming clip's\nshare of the frame, frame by frame, is what tells you whether it swept or cut.\n\nIf the definition claims duration independence, render the SAME definition at two materially\ndifferent `duration` values. If it claims aspect independence, render at 16:9 and 9:16. A\ntransition tested at one duration or one frame shape may still be useful, but scope the claim to\nthat tested case. A matte authored for one frame shape is fit onto every other, and a crop can hide\nthe travel that makes it a transition.\n""---\nname: custom-transitions\ndescription: How to write a new scene transition as an inline JSON definition — the slot contract, the token vocabulary a definition may read, the four mechanisms a transition can be built from, and the frictions that make a plausible-looking definition render wrong. Every rule here was rendered, and the numbers are what was drawn. Use when authoring or reviewing a transition definition, or when a transition renders at the wrong speed, cuts, or is refused by the validator.\nmetadata:\n category: authoring\n version: '1.0'\n ported-from: transition-authoring 1.0 at 55.75.0\n---\n\n# Writing a transition\n\nA transition is DATA: a JSON definition, declared inline as a `type: \"transition\"`\nasset. This is what the definition has to say, and what goes wrong.\n\n**Check what already exists first.** `picsart_scene_capabilities({sections:\n[\"transitions\"]})` returns every built-in transition with its id, description\nand parameters; if one of them does what you need, apply it by id and stop\nhere. Authoring is for the case where none of them does.\n\n## Incoming continuity contract\n\nThis skill defines an already-decided seam; it does not decide what two beats should mean together.\nBefore writing a definition, require four inputs:\n\n1. the semantic relationship — continuation, replacement, reveal, arrival, interruption, or reset;\n2. the intended travel vector, or an explicit decision that this boundary resets it;\n3. the visual carrier, when the viewer should be able to follow one;\n4. the concrete reason no shipped catalog transition expresses that relationship.\n\nIf any of these is still undecided, return to\nmotion-scene-continuity (fetch with `picsart_scene_recipe`, name `motion-scene-continuity`). Do not invent a custom transition merely\nbecause the adjacent scenes feel disconnected; the representation may instead be one persistent\nlayer, a hard cut, or an existing crossfade or directional transition.\n\n## The shape of a definition\n\nTwo parts: `meta` identifies it, `scene` IS a scene — the same document model as\nanywhere else, with two extra powers.\n\n```json\n{ \"meta\": { \"id\": \"crossfade\", \"displayName\": \"Crossfade\",\n \"description\": \"Linear dissolve from source to destination: the two weights always sum to one, so the background never shows through an opaque pair.\" },\n \"scene\": {\n \"version\": \"1.0\",\n \"composition\": { \"width\": {\"$eval\":\"width\"}, \"height\": {\"$eval\":\"height\"},\n \"fps\": 30, \"duration\": {\"$eval\":\"duration\"} },\n \"layers\": [\n { \"id\": \"source\", \"start\": 0, \"duration\": {\"$eval\":\"duration\"},\n \"content\": { \"kind\": \"slot\", \"role\": \"source\" },\n \"animations\": { \"opacity\": { \"keyframes\": [\n { \"time\": 0, \"value\": 1 }, { \"time\": {\"$eval\":\"duration\"}, \"value\": 0 } ] } } },\n { \"id\": \"destination\", \"start\": 0, \"duration\": {\"$eval\":\"duration\"}, \"blendMode\": \"add\",\n \"content\": { \"kind\": \"slot\", \"role\": \"destination\" },\n \"animations\": { \"opacity\": { \"keyframes\": [\n { \"time\": 0, \"value\": 0 }, { \"time\": {\"$eval\":\"duration\"}, \"value\": 1 } ] } } } ] } }\n```\n\nThat is a complete, shipping transition. The destination ADDS onto the fading\nsource inside the firing's own canvas, so the weights are t and 1 − t and sum to\none. Two `normal` fades would each let the composition background through: at\nthe midpoint a red→red crossfade over green read G = 132, a 25% background\nshare.\n\nThe two extra powers:\n\n**`content: { \"kind\": \"slot\", \"role\": \"source\" | \"destination\" }`** — a hole\nfilled at render time with the outgoing clip's last frame or incoming clip's first frame. A\ndefinition never names a clip; it arranges two boundary-frame slots. Exactly one of each role. The\ndefinition animates those supplied frames on its own clock; neighboring clip animation does not\ncontinue live through the transition window. If the seam needs a genuinely live shared object,\nkeep that object alive outside this slot contract.\n\n**Firing-supplied tokens.** `width`, `height` and `duration` are handed in by the\ncall site and are NOT declared in `parameters`. Read them as `{\"$eval\":\"width\"}`\nor inside an expression as `{\"$eval\": \"width / 2\"}`.\n\n## What a definition may read\n\n| Source | Declared where | Read as |\n|---|---|---|\n| `width`, `height`, `duration` | nowhere — the firing supplies them | `{\"$eval\":\"duration\"}` |\n| Your own knobs | `scene.parameters` | `{\"$eval\":\"softness\"}` |\n| The selected variant's row | `scene.variants.table.<row>` | `{\"$eval\":\"sweep\"}` |\n\n`{\"$eval\": \"...\"}` computes over all three. The grammar is small on purpose — it\nadmits **`min`, `max`, `abs`, `floor`, `ceil`, `round`, `sqrt`, `sin`, `cos`,\n`atan2(y, x)`** (angles in radians) and nothing else. There is no `hypot` and no ternary; `and`/`or`/`not` exist for `$when` gates.\nThe frame diagonal is `sqrt(width * width + height * height)`, so a circle that\nmust cover the frame from its centre needs a diameter of exactly that.\n\nNames that are refused rather than shadowed: the grammar's own\n(`min max abs floor ceil round sqrt sin cos atan2 and or not true false`), the firing-supplied\nthree, and a variant row's own selector. The check covers EVERY row, not the\nselected one — a clean row does not excuse a broken sibling.\n\n## Variants\n\nOne definition, many looks. `by` names the selector param; each row's fields join\nthe scope for that firing.\n\n```json\n\"parameters\": { \"variant\": { \"type\": \"text\", \"default\": \"circle\",\n \"enum\": [\"circle\", \"star\", \"bar\"] } },\n\"variants\": { \"by\": \"variant\", \"table\": {\n \"circle\": { \"isCircle\": true, \"isStar\": false, \"isBar\": false },\n \"star\": { \"isCircle\": false, \"isStar\": true, \"isBar\": false } } }\n```\n\nGate whole layers or shape items on a row field with `\"$when\": \"isStar\"`. A row\nfield beats a firing param of the same name.\n\n## The four mechanisms, and what each costs\n\n| Built from | Example | Needs an asset | Fits any `duration` |\n|---|---|---|---|\n| **Opacity** | `crossfade` | no | yes, by construction |\n| **Transform** | `slide`, `diagonal_slide` | no | yes, by construction |\n| **Effect** | `blur_dissolve` | no | yes, by construction |\n| **Mask — shape layer** | `iris`, `shape_reveal` | **no** | **yes, by construction** |\n| **Mask — video/lottie matte** | none shipped (`push`, `splatter` were) | yes, remote | **no — see below** |\n\nThe first four animate on the DEFINITION's own clock. Their keyframes are written\nat `{\"$eval\":\"duration\"}`, so whatever window the author asks for is the window\nthey fill. Nothing else is needed.\n\n**Prefer a shape mask over a video matte.** It needs no asset, no network,\nno external renderer, and it cannot drift out of time with its window. **Never\nship a `.webm` matte:** iOS (AVFoundation) cannot decode WebM, so the incoming\nclip just cut in there — which is why `push`, `bubble`, `cubes`, `free_fall`,\n`kaleida` and `splatter` were removed from the catalogue. The matte notes below\nare kept for a matte in a format supported by the intended playback environment.\n\n**Keep a definition cheap enough to play in real time on a phone.** A blur's cost\ngrows with its radius times the area it covers, and a firing pays it on every frame\nof the window. `movement_camera` peaked at a full-frame whip blur, 260 px at 720p,\nwhich cost up to ~180 ms a frame at the cut and stalled playback, so it was removed\nfrom the catalogue too. Blur a small layer, or keep the radius low.\n\n`iris` does a circle, a six-point star and a widening bar from one definition:\n\n```json\n\"mask\": { \"invert\": false, \"clip\": {\n \"id\": \"iris_mask\",\n \"transform\": { \"position\": [{\"$eval\":\"width / 2\"}, {\"$eval\":\"height / 2\"}] },\n \"content\": { \"kind\": \"shape\", \"items\": [\n { \"$when\": \"isCircle\", \"type\": \"ellipse\",\n \"size\": [{\"$eval\":\"width * 1.6\"}, {\"$eval\":\"width * 1.6\"}], \"position\": [0,0] },\n { \"$when\": \"isStar\", \"type\": \"polystar\", \"starType\": \"star\", \"points\": 6,\n \"position\": [0,0], \"outerRadius\": {\"$eval\":\"max(width, height) * 1.45\"},\n \"innerRadius\": {\"$eval\":\"max(width, height) * 0.80\"} },\n { \"type\": \"fill\", \"color\": \"#ffffffff\" } ] },\n \"animations\": { \"scale\": { \"keyframes\": [\n { \"time\": 0, \"value\": [0.001, 0.001], \"easing\": \"ease_in\" },\n { \"time\": {\"$eval\":\"duration\"}, \"value\": [1, 1] } ] } } } }\n```\n\nMeasured on a 640×480 frame, `iris`/`circle` at `duration` 0.4, 1.0 and 2.0 gave\nthe SAME progression every time — 0% / ~5% / 66% / 100% across the window. Circle,\nstar and bar read 1.1 / 26.9 / 97.0, 1.8 / 45.5 / 100, 1.0 / 26.5 / 100 at\nt = 2.7 / 3.0 / 3.3 through a 1s window.\n\n`shape_reveal` is the larger worked example: twenty-one choreographies, with the\ngeometry written as fractions of `width`/`height` so a circle stays a circle at\nevery aspect. Its five `wipe_*` rows are the exception: an edge at any `angle`\nis drawn in units of the frame diagonal inside a group that rotates by `angle`\nand scales by `diagonal / 100`, so it covers every aspect at every angle. Those\nrows also supply `lineShape` and `panelShape` for the `accent` layers (a divider\nstroke drawn over the blur band, a colour panel under the destination); every\nother row supplies them empty, because a body may only read a row key every row\ncarries. Each variant's row declares its shape tree ONCE, and three layers\ndraw it with `\"items\": {\"$eval\": \"shape\"}` (the sharp mask, the blur band, and\nthe band's lagged cut). The lagged copy is that same tree on a later clock:\n`\"start\": {\"$eval\": \"0.22 * duration\"}, \"timeMode\": \"layer\"`. A later `start`\nalone does NOT delay it, because keyframe times are composition seconds by\ndefault. The lagged copy then moved in lockstep and the blur band disappeared.\nOne more friction it measured:\n\n- **Land the motion before the window ends.** A track keyed to end exactly at\n `duration` on an ease-out is still short of its end pose on the last frame at\n short windows (0.4s). Its blurred band then cleared in one frame. Keying both\n copies to land by `0.9 * duration` left the last frames clean at 0.4s, 1s and 2s,\n and at 24 fps.\n\n**Repeat a mask piece with `$each` over a number.** In a definition, `$each`\nmay name a whole number N (a parameter or a row field) and makes N copies whose\nitem is the copy's index. `tile_mosaic` nests `{\"$each\": \"rows\", \"as\": \"r\"}`\nand `{\"$each\": \"columns\", \"as\": \"c\"}` inside the mask's shape `items`, one\ngroup per tile, each with its own `opacity` keyframes timed from `r` and `c`.\nThe variant picks the order through numeric row weights (`byRow`,\n`byDiagonal`, `byRandom`): a row field is filled at the definition's top scope,\nso it cannot read `r` or `c` itself. A fraction or a negative count is refused with `invalid_each`.\n\nThe shape vocabulary is `ellipse`, `rect`, `polystar`, `path`, `fill`, `stroke`,\n`gradientFill`, `gradientStroke`, `group`, `trim`, `repeater`, `roundCorners`,\n`offsetPaths`, `zigZag`, `merge`.\n\n## Frictions\n\n**A shape item discriminates on `type`, not `kind`.** Content is `kind`, shape\nitems are `type` — they mirror Lottie's own item vocabulary. Getting it wrong fails\nwith `missing_field` on the item's `type`, listing every tag it could have been. Their\nnames are also camelCase (`gradientFill`, `roundCorners`, `zigZag`) while the\nrest of the format is snake_case.\n\n**The window is CENTRED on the cut and eats `duration/2` out of EACH neighbouring\nclip.** A 7.25s transition needs 3.625s of both. Too long for the clips and the\nvalidator refuses the whole document with `transition_window_exceeds_clip`. Size a\ntransition against the shortest clip it sits between, not against the composition.\n\n**A time-based matte does not fit the window by itself.** A `.webm` or a lottie\nplays at 1× from its own zero. Too long a window and the wipe finishes early and\nthen the matte runs out before the window ends. Too short and it is a hard cut: `splatter`/`blood_drop_1` in a 1.0s\nwindow reached 9.8% and then gained 90 points in a single frame. The fix, which\nevery matte family carries, is\nto map the window onto the matte's own travel time. `lead` is a second row field:\nthe last source second at which the matte still equals its first frame, so the\nwindow does not spend its opening standing still (`cubes`/`style10` holds for\n1.08s of a 1.63s matte, and without `lead` moved only in the last third):\n\n```json\n\"trim\": { \"in\": { \"$eval\": \"lead\" }, \"out\": { \"$eval\": \"sweep\" } },\n\"speed\": { \"$eval\": \"(sweep - lead) / duration\" }\n```\n\n`sweep` is a variant-row field holding the matte's active source extent in source\nseconds — measure it as the first frame where no more than ~1.16% of the\nmatte's pixels remain above 0.5 alpha, the rule every shipped matte row\nfollows. **`speed` is refused\nwithout an explicit `trim`**: time remapping needs a known source extent, and the\nrenderer cannot probe for one. A matte definition with no `sweep` is refused the same way.\n\n**A matte whose edge travels the full frame in one direction (push) must `fill`;\na shaped matte keeps `cover`; verify at 9:16 as well as 16:9.** `cover` crops a\n16:9 matte to its middle 32% on a portrait frame, so `push`'s left/right edge\ncrossed the visible strip in one matte frame and rendered as a hard cut; `fill`\nmaps the whole travel onto any frame. A shaped matte (a splatter, a bubble)\nwould distort under `fill`.\n\nA shaped matte that keeps `cover` pays for it in time instead. A portrait frame\ncrops the 16:9 matte to its centre, which clears first, so a single `sweep`\nfinished `splatter`/`blood_splatter_1` at 45% of a 9:16 window and held. Cover-fit\nrows therefore carry `sweep_tall` (9:16) and `sweep_square` (1:1) next to\n`sweep` (16:9), and the trim end interpolates between them on the frame's aspect:\n\n```json\n\"out\": { \"$eval\": \"sweep_tall + (sweep_square - sweep_tall) * min(1, max(0, (width / height - 0.5625) * 16 / 7)) + (sweep - sweep_square) * min(1, max(0, (width / height - 1) * 9 / 7))\" }\n```\n\n`speed` is that same expression, minus `lead`, over `duration`. Measure each\nvalue with the same residue rule as `sweep`: the first frame where no more than\nthe row's 16:9 residue remains, rendering the matte under its own `cover` fit on\na 9:16 frame for `sweep_tall` and on a 1:1 frame for `sweep_square`.\n\n**A splatter matte leaves an edge residue on 16:9.** Stopping at the ~1.16%\nthreshold leaves ~1–1.6% of the outgoing clip at the frame edges, which drops\nout on the window's last frame. That is accepted: holding the matte until it is\nfully clear would spend most of the window on an almost-empty tail, and `cover`\ncrops the residue away on 9:16.\n\n**A mask is an owned clip.** `mask.clip` spans the host layer's window, and its\nkeyframes count from the host's start. It carries its own `transform`,\n`transforms[]` and `animations`, so an animated shape mask animates. A mask that\nstarts later than its host (a lag matte) puts a `composition` in the clip's\ncontent, with the delayed layer inside it — see `shape_reveal`'s lag mask.\n\n**The non-active part of a clip is its first or last frame.** A transition shows\nthe outgoing clip's last frame and the incoming clip's first, not live playback\nof both. Design the beat around that.\n\n## Verifying one\n\nThe definition is data, so the only question worth asking is what the renderer\ndrew. Validate it with `picsart_scene_validate`, then render full-resolution stills at the\nsample times below in ONE call per `duration`:\n`picsart_scene_contact_sheet` with `times: [t1, t2, …]` and `resolution` set to the scene's `composition.width` and `composition.height`. Without `resolution` the sheet returns downscaled thumbnails, which are not for judging position. The sheet image scales every frame to fit one picture; to judge full-resolution detail, open a frame's `url`.\n\nSample ACROSS the window, not at its midpoint: the failures above all look fine\nat 50%. For a window `[c - d/2, c + d/2]` take at least `0.0, 0.25, 0.5, 0.75,\n1.0` of it, and measure coverage rather than eyeballing — the incoming clip's\nshare of the frame, frame by frame, is what tells you whether it swept or cut.\n\nIf the definition claims duration independence, render the SAME definition at two materially\ndifferent `duration` values. If it claims aspect independence, render at 16:9 and 9:16. A\ntransition tested at one duration or one frame shape may still be useful, but scope the claim to\nthat tested case. A matte authored for one frame shape is fit onto every other, and a crop can hide\nthe travel that makes it a transition.\n"Full snapshot data
{
"description": "How to write a new scene transition as an inline JSON definition — the slot contract, the token vocabulary a definition may read, the four mechanisms a transition can be built from, and the frictions that make a plausible-looking definition render wrong. Every rule here was rendered, and the numbers are what was drawn. Use when authoring or reviewing a transition definition, or when a transition renders at the wrong speed, cuts, or is refused by the validator.",
"included_files": [],
"name": "custom-transitions",
"skill_md_contents": "---\nname: custom-transitions\ndescription: How to write a new scene transition as an inline JSON definition — the slot contract, the token vocabulary a definition may read, the four mechanisms a transition can be built from, and the frictions that make a plausible-looking definition render wrong. Every rule here was rendered, and the numbers are what was drawn. Use when authoring or reviewing a transition definition, or when a transition renders at the wrong speed, cuts, or is refused by the validator.\nmetadata:\n category: authoring\n version: '1.0'\n ported-from: transition-authoring 1.0 at 55.75.0\n---\n\n# Writing a transition\n\nA transition is DATA: a JSON definition, declared inline as a `type: \"transition\"`\nasset. This is what the definition has to say, and what goes wrong.\n\n**Check what already exists first.** `picsart_scene_capabilities({sections:\n[\"transitions\"]})` returns every built-in transition with its id, description\nand parameters; if one of them does what you need, apply it by id and stop\nhere. Authoring is for the case where none of them does.\n\n## Incoming continuity contract\n\nThis skill defines an already-decided seam; it does not decide what two beats should mean together.\nBefore writing a definition, require four inputs:\n\n1. the semantic relationship — continuation, replacement, reveal, arrival, interruption, or reset;\n2. the intended travel vector, or an explicit decision that this boundary resets it;\n3. the visual carrier, when the viewer should be able to follow one;\n4. the concrete reason no shipped catalog transition expresses that relationship.\n\nIf any of these is still undecided, return to\nmotion-scene-continuity (fetch with `picsart_scene_recipe`, name `motion-scene-continuity`). Do not invent a custom transition merely\nbecause the adjacent scenes feel disconnected; the representation may instead be one persistent\nlayer, a hard cut, or an existing crossfade or directional transition.\n\n## The shape of a definition\n\nTwo parts: `meta` identifies it, `scene` IS a scene — the same document model as\nanywhere else, with two extra powers.\n\n```json\n{ \"meta\": { \"id\": \"crossfade\", \"displayName\": \"Crossfade\",\n \"description\": \"Linear dissolve from source to destination: the two weights always sum to one, so the background never shows through an opaque pair.\" },\n \"scene\": {\n \"version\": \"1.0\",\n \"composition\": { \"width\": {\"$eval\":\"width\"}, \"height\": {\"$eval\":\"height\"},\n \"fps\": 30, \"duration\": {\"$eval\":\"duration\"} },\n \"layers\": [\n { \"id\": \"source\", \"start\": 0, \"duration\": {\"$eval\":\"duration\"},\n \"content\": { \"kind\": \"slot\", \"role\": \"source\" },\n \"animations\": { \"opacity\": { \"keyframes\": [\n { \"time\": 0, \"value\": 1 }, { \"time\": {\"$eval\":\"duration\"}, \"value\": 0 } ] } } },\n { \"id\": \"destination\", \"start\": 0, \"duration\": {\"$eval\":\"duration\"}, \"blendMode\": \"add\",\n \"content\": { \"kind\": \"slot\", \"role\": \"destination\" },\n \"animations\": { \"opacity\": { \"keyframes\": [\n { \"time\": 0, \"value\": 0 }, { \"time\": {\"$eval\":\"duration\"}, \"value\": 1 } ] } } } ] } }\n```\n\nThat is a complete, shipping transition. The destination ADDS onto the fading\nsource inside the firing's own canvas, so the weights are t and 1 − t and sum to\none. Two `normal` fades would each let the composition background through: at\nthe midpoint a red→red crossfade over green read G = 132, a 25% background\nshare.\n\nThe two extra powers:\n\n**`content: { \"kind\": \"slot\", \"role\": \"source\" | \"destination\" }`** — a hole\nfilled at render time with the outgoing clip's last frame or incoming clip's first frame. A\ndefinition never names a clip; it arranges two boundary-frame slots. Exactly one of each role. The\ndefinition animates those supplied frames on its own clock; neighboring clip animation does not\ncontinue live through the transition window. If the seam needs a genuinely live shared object,\nkeep that object alive outside this slot contract.\n\n**Firing-supplied tokens.** `width`, `height` and `duration` are handed in by the\ncall site and are NOT declared in `parameters`. Read them as `{\"$eval\":\"width\"}`\nor inside an expression as `{\"$eval\": \"width / 2\"}`.\n\n## What a definition may read\n\n| Source | Declared where | Read as |\n|---|---|---|\n| `width`, `height`, `duration` | nowhere — the firing supplies them | `{\"$eval\":\"duration\"}` |\n| Your own knobs | `scene.parameters` | `{\"$eval\":\"softness\"}` |\n| The selected variant's row | `scene.variants.table.<row>` | `{\"$eval\":\"sweep\"}` |\n\n`{\"$eval\": \"...\"}` computes over all three. The grammar is small on purpose — it\nadmits **`min`, `max`, `abs`, `floor`, `ceil`, `round`, `sqrt`, `sin`, `cos`,\n`atan2(y, x)`** (angles in radians) and nothing else. There is no `hypot` and no ternary; `and`/`or`/`not` exist for `$when` gates.\nThe frame diagonal is `sqrt(width * width + height * height)`, so a circle that\nmust cover the frame from its centre needs a diameter of exactly that.\n\nNames that are refused rather than shadowed: the grammar's own\n(`min max abs floor ceil round sqrt sin cos atan2 and or not true false`), the firing-supplied\nthree, and a variant row's own selector. The check covers EVERY row, not the\nselected one — a clean row does not excuse a broken sibling.\n\n## Variants\n\nOne definition, many looks. `by` names the selector param; each row's fields join\nthe scope for that firing.\n\n```json\n\"parameters\": { \"variant\": { \"type\": \"text\", \"default\": \"circle\",\n \"enum\": [\"circle\", \"star\", \"bar\"] } },\n\"variants\": { \"by\": \"variant\", \"table\": {\n \"circle\": { \"isCircle\": true, \"isStar\": false, \"isBar\": false },\n \"star\": { \"isCircle\": false, \"isStar\": true, \"isBar\": false } } }\n```\n\nGate whole layers or shape items on a row field with `\"$when\": \"isStar\"`. A row\nfield beats a firing param of the same name.\n\n## The four mechanisms, and what each costs\n\n| Built from | Example | Needs an asset | Fits any `duration` |\n|---|---|---|---|\n| **Opacity** | `crossfade` | no | yes, by construction |\n| **Transform** | `slide`, `diagonal_slide` | no | yes, by construction |\n| **Effect** | `blur_dissolve` | no | yes, by construction |\n| **Mask — shape layer** | `iris`, `shape_reveal` | **no** | **yes, by construction** |\n| **Mask — video/lottie matte** | none shipped (`push`, `splatter` were) | yes, remote | **no — see below** |\n\nThe first four animate on the DEFINITION's own clock. Their keyframes are written\nat `{\"$eval\":\"duration\"}`, so whatever window the author asks for is the window\nthey fill. Nothing else is needed.\n\n**Prefer a shape mask over a video matte.** It needs no asset, no network,\nno external renderer, and it cannot drift out of time with its window. **Never\nship a `.webm` matte:** iOS (AVFoundation) cannot decode WebM, so the incoming\nclip just cut in there — which is why `push`, `bubble`, `cubes`, `free_fall`,\n`kaleida` and `splatter` were removed from the catalogue. The matte notes below\nare kept for a matte in a format supported by the intended playback environment.\n\n**Keep a definition cheap enough to play in real time on a phone.** A blur's cost\ngrows with its radius times the area it covers, and a firing pays it on every frame\nof the window. `movement_camera` peaked at a full-frame whip blur, 260 px at 720p,\nwhich cost up to ~180 ms a frame at the cut and stalled playback, so it was removed\nfrom the catalogue too. Blur a small layer, or keep the radius low.\n\n`iris` does a circle, a six-point star and a widening bar from one definition:\n\n```json\n\"mask\": { \"invert\": false, \"clip\": {\n \"id\": \"iris_mask\",\n \"transform\": { \"position\": [{\"$eval\":\"width / 2\"}, {\"$eval\":\"height / 2\"}] },\n \"content\": { \"kind\": \"shape\", \"items\": [\n { \"$when\": \"isCircle\", \"type\": \"ellipse\",\n \"size\": [{\"$eval\":\"width * 1.6\"}, {\"$eval\":\"width * 1.6\"}], \"position\": [0,0] },\n { \"$when\": \"isStar\", \"type\": \"polystar\", \"starType\": \"star\", \"points\": 6,\n \"position\": [0,0], \"outerRadius\": {\"$eval\":\"max(width, height) * 1.45\"},\n \"innerRadius\": {\"$eval\":\"max(width, height) * 0.80\"} },\n { \"type\": \"fill\", \"color\": \"#ffffffff\" } ] },\n \"animations\": { \"scale\": { \"keyframes\": [\n { \"time\": 0, \"value\": [0.001, 0.001], \"easing\": \"ease_in\" },\n { \"time\": {\"$eval\":\"duration\"}, \"value\": [1, 1] } ] } } } }\n```\n\nMeasured on a 640×480 frame, `iris`/`circle` at `duration` 0.4, 1.0 and 2.0 gave\nthe SAME progression every time — 0% / ~5% / 66% / 100% across the window. Circle,\nstar and bar read 1.1 / 26.9 / 97.0, 1.8 / 45.5 / 100, 1.0 / 26.5 / 100 at\nt = 2.7 / 3.0 / 3.3 through a 1s window.\n\n`shape_reveal` is the larger worked example: twenty-one choreographies, with the\ngeometry written as fractions of `width`/`height` so a circle stays a circle at\nevery aspect. Its five `wipe_*` rows are the exception: an edge at any `angle`\nis drawn in units of the frame diagonal inside a group that rotates by `angle`\nand scales by `diagonal / 100`, so it covers every aspect at every angle. Those\nrows also supply `lineShape` and `panelShape` for the `accent` layers (a divider\nstroke drawn over the blur band, a colour panel under the destination); every\nother row supplies them empty, because a body may only read a row key every row\ncarries. Each variant's row declares its shape tree ONCE, and three layers\ndraw it with `\"items\": {\"$eval\": \"shape\"}` (the sharp mask, the blur band, and\nthe band's lagged cut). The lagged copy is that same tree on a later clock:\n`\"start\": {\"$eval\": \"0.22 * duration\"}, \"timeMode\": \"layer\"`. A later `start`\nalone does NOT delay it, because keyframe times are composition seconds by\ndefault. The lagged copy then moved in lockstep and the blur band disappeared.\nOne more friction it measured:\n\n- **Land the motion before the window ends.** A track keyed to end exactly at\n `duration` on an ease-out is still short of its end pose on the last frame at\n short windows (0.4s). Its blurred band then cleared in one frame. Keying both\n copies to land by `0.9 * duration` left the last frames clean at 0.4s, 1s and 2s,\n and at 24 fps.\n\n**Repeat a mask piece with `$each` over a number.** In a definition, `$each`\nmay name a whole number N (a parameter or a row field) and makes N copies whose\nitem is the copy's index. `tile_mosaic` nests `{\"$each\": \"rows\", \"as\": \"r\"}`\nand `{\"$each\": \"columns\", \"as\": \"c\"}` inside the mask's shape `items`, one\ngroup per tile, each with its own `opacity` keyframes timed from `r` and `c`.\nThe variant picks the order through numeric row weights (`byRow`,\n`byDiagonal`, `byRandom`): a row field is filled at the definition's top scope,\nso it cannot read `r` or `c` itself. A fraction or a negative count is refused with `invalid_each`.\n\nThe shape vocabulary is `ellipse`, `rect`, `polystar`, `path`, `fill`, `stroke`,\n`gradientFill`, `gradientStroke`, `group`, `trim`, `repeater`, `roundCorners`,\n`offsetPaths`, `zigZag`, `merge`.\n\n## Frictions\n\n**A shape item discriminates on `type`, not `kind`.** Content is `kind`, shape\nitems are `type` — they mirror Lottie's own item vocabulary. Getting it wrong fails\nwith `missing_field` on the item's `type`, listing every tag it could have been. Their\nnames are also camelCase (`gradientFill`, `roundCorners`, `zigZag`) while the\nrest of the format is snake_case.\n\n**The window is CENTRED on the cut and eats `duration/2` out of EACH neighbouring\nclip.** A 7.25s transition needs 3.625s of both. Too long for the clips and the\nvalidator refuses the whole document with `transition_window_exceeds_clip`. Size a\ntransition against the shortest clip it sits between, not against the composition.\n\n**A time-based matte does not fit the window by itself.** A `.webm` or a lottie\nplays at 1× from its own zero. Too long a window and the wipe finishes early and\nthen the matte runs out before the window ends. Too short and it is a hard cut: `splatter`/`blood_drop_1` in a 1.0s\nwindow reached 9.8% and then gained 90 points in a single frame. The fix, which\nevery matte family carries, is\nto map the window onto the matte's own travel time. `lead` is a second row field:\nthe last source second at which the matte still equals its first frame, so the\nwindow does not spend its opening standing still (`cubes`/`style10` holds for\n1.08s of a 1.63s matte, and without `lead` moved only in the last third):\n\n```json\n\"trim\": { \"in\": { \"$eval\": \"lead\" }, \"out\": { \"$eval\": \"sweep\" } },\n\"speed\": { \"$eval\": \"(sweep - lead) / duration\" }\n```\n\n`sweep` is a variant-row field holding the matte's active source extent in source\nseconds — measure it as the first frame where no more than ~1.16% of the\nmatte's pixels remain above 0.5 alpha, the rule every shipped matte row\nfollows. **`speed` is refused\nwithout an explicit `trim`**: time remapping needs a known source extent, and the\nrenderer cannot probe for one. A matte definition with no `sweep` is refused the same way.\n\n**A matte whose edge travels the full frame in one direction (push) must `fill`;\na shaped matte keeps `cover`; verify at 9:16 as well as 16:9.** `cover` crops a\n16:9 matte to its middle 32% on a portrait frame, so `push`'s left/right edge\ncrossed the visible strip in one matte frame and rendered as a hard cut; `fill`\nmaps the whole travel onto any frame. A shaped matte (a splatter, a bubble)\nwould distort under `fill`.\n\nA shaped matte that keeps `cover` pays for it in time instead. A portrait frame\ncrops the 16:9 matte to its centre, which clears first, so a single `sweep`\nfinished `splatter`/`blood_splatter_1` at 45% of a 9:16 window and held. Cover-fit\nrows therefore carry `sweep_tall` (9:16) and `sweep_square` (1:1) next to\n`sweep` (16:9), and the trim end interpolates between them on the frame's aspect:\n\n```json\n\"out\": { \"$eval\": \"sweep_tall + (sweep_square - sweep_tall) * min(1, max(0, (width / height - 0.5625) * 16 / 7)) + (sweep - sweep_square) * min(1, max(0, (width / height - 1) * 9 / 7))\" }\n```\n\n`speed` is that same expression, minus `lead`, over `duration`. Measure each\nvalue with the same residue rule as `sweep`: the first frame where no more than\nthe row's 16:9 residue remains, rendering the matte under its own `cover` fit on\na 9:16 frame for `sweep_tall` and on a 1:1 frame for `sweep_square`.\n\n**A splatter matte leaves an edge residue on 16:9.** Stopping at the ~1.16%\nthreshold leaves ~1–1.6% of the outgoing clip at the frame edges, which drops\nout on the window's last frame. That is accepted: holding the matte until it is\nfully clear would spend most of the window on an almost-empty tail, and `cover`\ncrops the residue away on 9:16.\n\n**A mask is an owned clip.** `mask.clip` spans the host layer's window, and its\nkeyframes count from the host's start. It carries its own `transform`,\n`transforms[]` and `animations`, so an animated shape mask animates. A mask that\nstarts later than its host (a lag matte) puts a `composition` in the clip's\ncontent, with the delayed layer inside it — see `shape_reveal`'s lag mask.\n\n**The non-active part of a clip is its first or last frame.** A transition shows\nthe outgoing clip's last frame and the incoming clip's first, not live playback\nof both. Design the beat around that.\n\n## Verifying one\n\nThe definition is data, so the only question worth asking is what the renderer\ndrew. Validate it with `picsart_scene_validate`, then render full-resolution stills at the\nsample times below in ONE call per `duration`:\n`picsart_scene_contact_sheet` with `times: [t1, t2, …]` and `resolution` set to the scene's `composition.width` and `composition.height`. Without `resolution` the sheet returns downscaled thumbnails, which are not for judging position. The sheet image scales every frame to fit one picture; to judge full-resolution detail, open a frame's `url`.\n\nSample ACROSS the window, not at its midpoint: the failures above all look fine\nat 50%. For a window `[c - d/2, c + d/2]` take at least `0.0, 0.25, 0.5, 0.75,\n1.0` of it, and measure coverage rather than eyeballing — the incoming clip's\nshare of the frame, frame by frame, is what tells you whether it swept or cut.\n\nIf the definition claims duration independence, render the SAME definition at two materially\ndifferent `duration` values. If it claims aspect independence, render at 16:9 and 9:16. A\ntransition tested at one duration or one frame shape may still be useful, but scope the claim to\nthat tested case. A matte authored for one frame shape is fit onto every other, and a crop can hide\nthe travel that makes it a transition.\n"
}SHA-256 of public snapshot: b3cd42757bc9042f8d0fa52fbf9581d0fe849a6a64e4d718a2abbe12cd930491