greenlight-motion 0.1.5 → 0.2.1

package/skill/SKILL.md

@@ -18,12 +18,19 @@ You never write UI or animation code. If something is not in the format, it is n
 ## Setup (once per machine)
 
 ```
-npx greenlight-motion@0.1.5 doctor
+npx greenlight-motion@0.2.1 doctor
 ```
 
 It checks Node 18+, Chrome or Edge, WebGPU and H.264 encoding, and prints a fix for anything missing. Do not install
 anything globally without asking the user. Always pin the version in every command you run.
 
+## First, a direction
+
+Before any JSON, decide in a few lines what the video LOOKS like: one visual idea from the subject's own world carried
+through every scene, the palette, the type, and what each scene shows besides its words. Presets make a video move;
+the direction makes it look designed. `skill/references/scene-script.md` opens with how. Then build to it, and judge
+every contact sheet against it.
+
 ## The fast way: a scene script
 
 For a new video, start with a **scene script** instead of a whole project: a short JSON file — scenes, their texts and
@@ -32,23 +39,47 @@ animation presets (the same converter the GreenLight Motion connector uses in Cl
 keyframes rarely look as good. The format, the design rules and the catalogues: `skill/references/scene-script.md`.
 
 ```
-npx greenlight-motion@0.1.5 script <folder> --from scenes.json   # or write <folder>/script.json, then: script <folder>
+npx greenlight-motion@0.2.1 script <folder> --from scenes.json   # or write <folder>/script.json, then: script <folder>
 ```
 
-Then `check` and `stills` (below), fix the SCRIPT and run `script` again — it rewrites `project.json`. For what a
-script can't say (3D, particles, motion paths, masks, text animators by hand), go on from `project.json` with the
+Then `check` and `stills` (below), fix the SCRIPT and run `script` again — it rewrites `project.json`. A scene's
+`camera` can be a real 3D camera (the editor's camera moves and rigs, zooms on spots, depth of field, layers in depth with
+`z`). For what a script can't say (3D models, particles, motion paths, masks, text animators by hand), go on from `project.json` with the
 workflow below and stop running `script` (it refuses to overwrite a project edited since, unless `--force`).
 
+## Beyond the script: the signature visual
+
+The script gives structure; the picture that makes the video THIS product's usually needs the engine's full format.
+Build it with `apply` on the project `script` wrote (the item ids are the script's element ids):
+
+- **A material of its own**: a custom GLSL shader on a shape or the whole background (water, light through glass,
+  paper, heat): `shapeBackground` / `background` `{ "type": "shader", "shaderId": "custom", "shaderCode": "void
+  mainImage(out vec4 o, in vec2 fc) { … }" }`, Shadertoy-style, `iTime` from the timeline
+  (`references/video-backgrounds.md`, Custom GLSL shaders).
+- **Layers that interact**: a track matte, so words dip under a surface or show only through a shape
+  (`"trackMatte": { "sourceId": "<item>", "mode": "alpha" | "alphaInverted" | "luma" | "lumaInverted" }` on the layer
+  that is cut; the source is hidden from the output; `references/video-shapes.md`). Clipping masks and Layer Mask
+  (`references/video-effects.md`) for reveals.
+- **Your own drawing and motion**: SVG you write (`{ "type": "image", "svg": "…" }` in the script), shapes with
+  keyframes, motion paths (`references/video-paths.md`), particles (`references/video-particles.md`), 3D
+  (`references/video-3d.md`), Text Animators by hand (`references/video-text.md`).
+- **Sound when nothing may be downloaded**: write it in code. A short Node script can write a 48 kHz WAV (a soft bed, a
+  click, a noise whoosh) into `assets/`, then use it as the script's `music` or as an audio clip. Keep the bed quiet
+  under the hits.
+
+Keep the build repeatable: put your edits in a file you `apply` again after each `script` run (`script --force`, then
+`apply`), so the script and the hand-made layers never drift apart.
+
 ## Workflow
 
-1. `npx greenlight-motion@0.1.5 init <folder>` — starts from a working example (title, subtitle, accent line, four
+1. `npx greenlight-motion@0.2.1 init <folder>` — starts from a working example (title, subtitle, accent line, four
    options). `--from file.json` starts from a project you have (for example one exported from GreenLight Dash).
 2. Edit `<folder>/project.json` — for changes to an EXISTING project prefer `apply` (below): it checks every edit and
    applies all or nothing. Put pictures, video, sound and fonts in `<folder>/assets/` and refer to them as
    `"asset:<file>"` (e.g. `"url": "asset:product.png"`).
-3. `npx greenlight-motion@0.1.5 check <folder>` — fix everything it lists (missing files, template mistakes, blank
+3. `npx greenlight-motion@0.2.1 check <folder>` — fix everything it lists (missing files, template mistakes, blank
    frames, page errors). `--json` for machine output.
-4. `npx greenlight-motion@0.1.5 stills <folder>` — renders frames and **a labelled contact sheet**. Open and look at
+4. `npx greenlight-motion@0.2.1 stills <folder>` — renders frames and **a labelled contact sheet**. Open and look at
    it before you go on: layout, readability, timing. Fix and repeat. `--at 0.5,1.2,3` for exact times.
 5. Hand it over: tell the user to open `<folder>/index.html` (Chrome or Edge), or `pack` it into one file, or
    `render` the MP4 yourself (`--fps 60 --motion-blur` for fast motion).
@@ -113,7 +144,7 @@ editor's own normalizer), so write only what you mean.
 Full references (generated from the editor's own docs; ignore the `/api/` routes they mention):
 `skill/references/` — video-design, scene-script, video-projects, video-text, video-text-kinetic, video-text-presets, video-shapes, video-keyframes,
 video-camera, video-3d, video-effects, video-transitions, video-particles, video-paths, video-backgrounds, video-grid.
-Machine-readable lists: `npx greenlight-motion@0.1.5 schema effects | transitions | easings | paths | expressions`.
+Machine-readable lists: `npx greenlight-motion@0.2.1 schema effects | transitions | easings | paths | expressions`.
 
 ## Template
 
@@ -160,7 +191,7 @@ an absolute moment; `align` `sync` (default) / `start` / `end`; `offset` seconds
 
 The library is 77 hand-picked sounds in categories (whooshes and swooshes, transitions, clicks, pop-ups and
 notifications, data blips, typing and writing, foley, bubbles, impacts and bass drops, camera, gears, voice clips).
-`npx greenlight-motion@0.1.5 schema sounds` lists every one with its `category`, `use` (what it is for), `duration`
+`npx greenlight-motion@0.2.1 schema sounds` lists every one with its `category`, `use` (what it is for), `duration`
 and `sync`. Pick by `category` and `use`, then by name.
 
 - **Where the files come from:** the GreenLight sound CDN. `build` downloads each sound a cue uses into
@@ -176,7 +207,7 @@ The page has **Notes**: the user marks what should change right on the frame (a
 and writes a note for each mark. Every note carries the moment (seconds and frame), the mark in composition pixels
 and the layers under it (item ids in project.json), so you change exactly that and nothing else.
 
-- **They review on this computer:** run `npx greenlight-motion@0.1.5 review <folder>` and give them the URL it prints
+- **They review on this computer:** run `npx greenlight-motion@0.2.1 review <folder>` and give them the URL it prints
   (it keeps running; `--open` opens their browser, only when they ask). Their notes land in `<folder>/review/`: read
   `review/NOTES.md`, look at the `at-<t>s.png` pictures (the marks are numbered), make the changes (`apply`), `build`
   again and tell them to reload the page.
@@ -205,11 +236,11 @@ that fails (`plugin`); look at `stills` for the look. A package that carries its
 
 The same project opens in GreenLight Dash (the desktop editor this engine comes from) for full editing: the page's
 edit note offers **Open in GreenLight Dash** (it imports the folder as a new project on the open board; a page with
-changes saves a `.glvideo`). `npx greenlight-motion@0.1.5 pack <folder> --glvideo` writes that file yourself: ONE
+changes saves a `.glvideo`). `npx greenlight-motion@0.2.1 pack <folder> --glvideo` writes that file yourself: ONE
 `.glvideo` (the project + its files) that opens in GreenLight Dash on a double-click, or dropped on its board. Hand it
 over when the user wants to keep editing in the app. A
 GreenLight Dash project comes the other way through the app's **Export for agents** — a ready folder like the one
-`init` makes, with the options the author ticked. `npx greenlight-motion@0.1.5 init <folder> --from <its project.json>`
+`init` makes, with the options the author ticked. `npx greenlight-motion@0.2.1 init <folder> --from <its project.json>`
 starts from one too. Never tell the user they must install it: the page plays, changes options and renders on its own.
 
 ## Files

package/skill/references/scene-script.md

@@ -13,6 +13,19 @@ works too (it has to stay reachable). SVG you write: `{ "type": "image", "svg":
 
 ## The scene script
 
+**Before the script, a direction.** Presets make a video move; they don't give it an idea. Decide in a few lines first,
+and keep them next to the script:
+- **The idea**: ONE picture from the subject's own world (its object, place or action: a coffee shop's steam and cup rim,
+  a budgeting app's receipt printing line by line, a running app's track the scenes run along), carried through every scene.
+- **The palette**: background, text, one accent, plus only the colours that carry meaning (good / bad, before / after).
+  Light or dark on purpose.
+- **The type**: a big headline against a small support line; aligned left or centred on purpose, not by default.
+- **Each scene**: what it SHOWS besides its words, built from shapes, lines, `svg` you write, keyframes and the camera.
+The same line centred on a gradient in every scene reads as a template. Judge the stills against the direction, not
+only for mistakes.
+What a script can't say (a custom GLSL shader on a shape or the background, words dipping under a surface with a track
+matte, masks, particles, 3D) goes on from `project.json`: SKILL.md, "Beyond the script".
+
 ```json
 {
   "title": "Bean There — opening day",
@@ -29,8 +42,10 @@ works too (it has to stay reachable). SVG you write: `{ "type": "image", "svg":
         { "type": "pill", "w": 560, "h": 116, "color": "accent", "start": 0.15 },
         { "type": "text", "text": "Opening day: 2 for 1", "role": "body", "color": "#1b120d", "start": 0.3, "enter": "pop-overshoot", "sound": "data-1" } ] },
     { "name": "Close", "duration": 2.4, "transition": "Gradient Glow Stack", "background": { "shader": "silk", "look": "sunset" },
+      "camera": { "move": "cm-quiet-push", "dof": { "focus": "street", "aperture": 50 } },
       "elements": [
-        { "type": "text", "text": "12 Elm Street", "role": "headline", "textAnimation": "word-swing" },
+        { "type": "circle", "w": 420, "color": "#fff3e0", "opacity": 0.3, "at": [330, -60], "z": -700 },
+        { "id": "street", "type": "text", "text": "12 Elm Street", "role": "headline", "textAnimation": "word-swing" },
         { "type": "text", "text": "OPEN 7 – 7", "role": "label", "at": [0, 130], "start": 0.8, "letterSpacing": 6 } ] }
   ]
 }
@@ -44,15 +59,36 @@ works too (it has to stay reachable). SVG you write: `{ "type": "image", "svg":
 - **line**: from `at` to `to`, `width`, drawn on (`draw`: false to skip).
 - **image · video**: `src` (a file in the folder's assets/ as `asset:<name>`, or an https link) or, for an image, `svg` (SVG markup you write); `w` or `h`
   (px; the other follows the file's shape) or `fit` cover | contain
-  (default: a video covers the frame, a picture sits at 70 % of contain), `rotate` (deg), `opacity` (0–1). A video also takes
+  (default: a video covers the frame, a picture sits at 70 % of contain), `rotate` (deg). A video also takes
   `startAt` (s into the file) and `volume` (0–100, default muted). No entrance unless you set `enter`.
 - **Keyframes on any element** — your own motion: `"keyframes": { "x": [[0, -400], [0.8, 0, "Smooth Glide"]], "scale": [[0, 0.9], [2, 1.05]] }`
   — tracks x, y (px offsets from `at`), scale, rotate (deg), opacity (0–1); each key [seconds into the element, value, easing of the
   segment after it — Smooth Glide, AE Smooth, Expo Out, Back Out, Elastic, Linear …]. They replace an entrance's keys on the same track.
 - **Every element**: `start` / `end` (s within its scene; default: staggered 0.12 s, to the scene's end), `enter` / `exit` (keyframe presets, `direction` up | down | left | right
-  for directional ones), `effects`: [{ "id", "params"? }], `sound` (played at its start), `id`, `label` (its name in the page's options).
-- **Scene**: `duration` (s), `transition` into it (default Cross Fade, 0.6 s; `transitionDuration`), `camera` none | push-in | pull-out | drift-left | drift-right | drift-up (default push-in),
+  for directional ones), `effects`: [{ "id", "params"? }], `sound` (played at its start), `id`, `label` (its name in the page's options), `opacity` (0–1),
+  `z` (px of depth, + toward the viewer, default 0: a real camera's dolly, orbit and depth of field separate layers by it), `locked`: true
+  (the scene's camera doesn't move it: a logo, a caption). Keyframes also take a `z` track.
+- **Scene**: `duration` (s), `transition` into it (default Cross Fade, 0.6 s; `transitionDuration`), `camera` (below; default push-in),
   `background` (overrides style), `sounds`: [{ "sfx", "at" }]. Script-level `sound`: auto (default: a whoosh on each transition and on the first headline) | none.
+  **A transition overlaps the scenes on both sides**, so the video lasts the scenes' durations added up MINUS every
+  transition: five 3 s scenes with the default 0.6 s transitions run 15 − 4 × 0.6 = 12.6 s. To hit a length, add the
+  transitions back to the scenes (`script` prints the total).
+- **camera** — a quick move of the whole scene: none | push-in | pull-out | drift-left | drift-right | drift-up. Or a REAL camera that films the scene's elements in 3D (the
+  Video Editor's own camera layer; the scene's backdrop stays put, so its edge never shows). One of:
+  - `{ "move": id }` — a camera move from the catalogue (or just `"camera": "cm-quiet-push"`), spread over the scene;
+  - `{ "rig": id }` or `{ "rig": { "preset"?: id, "type"?, …fields } }` — an orbit, crane, push-in, truck, spiral, handheld or follow move
+    (`"camera": "heroOrbit"` works too). A `follow` rig rides elements: `"targets": [element ids]`. Layers are flat: keep an orbit within about
+    ±70° of the front (heroOrbit, slowReveal) or they turn edge-on and read mirrored;
+  - `{ "zooms": [{ "start", "end", "at"?, "zoom"? }], "feel"? }` — zoom in on spots and back out, like a screen recording's Smart Zoom: `at` as for
+    elements (the spot to frame, clamped so the view stays inside the frame), `zoom` 1.05–4 (default the feel's, about 1.45), each zoom at least
+    0.4 s and none overlapping; `feel` studio | calm | precise | lively | follow (the spring). Put a screen recording in as a video element (or the
+    scene's video background) and zoom on what it shows;
+  - `{ "keyframes": { zoom | x | y | roll | dolly | tiltX | tiltY | focusZ: [[seconds, value, easing?], …] } }` — your own move: zoom (×, 1 = none),
+    x / y (px the camera pans right / down), roll / tilt (deg), dolly (px toward the scene: it changes perspective, so layers at different `z` part).
+    With a `move` they replace its track; a rig drives x, y, roll, dolly and tilt itself and zooms drive zoom, x and y, so key only the others there.
+  - plus `"dof": { "focus": element id | "focusZ": px, "aperture"?: 40, "blur"?: 100 }` (or `true`) — depth of field: what sits at another `z` blurs;
+    the focus stays on its subject while the camera dollies or rides a rig. `focusZ` keys are a rack focus (measured from where the camera starts).
+  - `start` / `end` (s in the scene; default the whole scene; outside them the camera rests). Keys and zooms count seconds into the camera.
 - **background**: a colour, a CSS gradient, { "shader": id, "look"? } — shaders: silk, glowblobs, waves, plasma, mesh, fire, spacetravel, glitters, blueplanet, auroraridge, emberpool, neonvignette, electricvignette, spectrumdrift, emberfacet, silkdrift, eclipseprism, glassreeds, staticfringe, ripplefold, nightaurora, pixelbeams, petalgrid, amberblinds, icehalo, windowhaze (looks: references/video-backgrounds.md) — or { "image": src } / { "video": src } (covers the frame; b-roll behind the scene).
 - **music** (script level): `"music": { "src": file, "volume": 80, "fadeIn": 0.3, "fadeOut": 1.2, "startAt": 0 }` — one track under the video.
 
@@ -63,7 +99,7 @@ the first version and check every version against it.
 
 ## Catalogues
 
-**Text animations** (`textAnimation`; ★ = preferred): ★ `glide-text` Glide Text · `glide-continuous` Glide Continuous · `glide-soft-stop` Glide Soft Stop · ★ `ember-type` Ember Type · `molten-edge` Molten Edge · `focus-type` Focus Type · `tumble-type` Tumble Type · `flap-down` Flap Down · `drop-swell` Drop Swell · `rain-type` Rain Type · `counter-sweep` Counter Sweep · `sunset-shrink` Sunset Shrink · `boomerang` Boomerang · ★ `swing-pop` Swing Pop · ★ `word-swing` Word Swing · ★ `letter-vortex` Letter Vortex · `center-burst` Center Burst · ★ `pendulum` Pendulum · `spin-pop` Spin Pop · `domino` Domino · `flip-pop` Flip Pop · `card-turn` Card Turn · `slam-zoom` Slam Zoom · `orbit` Orbit · ★ `fan-deal` Fan Deal · ★ `whip` Whip · `rubber-letters` Rubber Letters · `pop-letters` Pop Letters · `drop-swing` Drop Swing · `coin-spin` Coin Spin · `converge` Converge · `roll-in` Roll In · `door-swing` Door Swing · `pill-type` Pill Type · `card-type` Card Type · `word-bars` Word Bars · `line-stack` Word Stack · `marker-type` Marker Type · `card-erase` Card Erase · `colour-sweep` Colour Sweep · `glow-pass` Glow Pass · `wave-pass` Wave Pass · `pop-through` Pop Through · `shine` Shine · ★ `marker` Marker · ★ `outline-pass` Outline Pass · ★ `neon-flow` Neon Flow · `rainbow` Rainbow · `gradient-flow` Gradient Flow · `jitter` Jitter · `float` Float · `flicker` Flicker · `breathe` Breathing Wave · `shimmer` Shimmer · `decode` Decode · `binary` Binary Decode · `alphabet-roll` Alphabet Roll · ★ `glitch` Glitch · `classic-fade-up` Fade Up · `classic-fade-down` Fade Down · `classic-rise-mask` Rise (Mask) · `classic-blur-in` Blur In · `classic-slide-in` Slide In · `classic-side-mask` Side Mask · `classic-tilt-drop` Tilt Drop · `classic-flip-up` Flip Up · `classic-typewriter` Typewriter · `classic-wave-rise` Wave Rise · `classic-bounce-letters` Bounce Letters · `classic-materialize` Materialize · `classic-neon-runner` Neon Runner · `classic-ink-highlight` Ink Highlight · `classic-flash-type` Flash Type · `classic-karaoke-sweep` Karaoke Sweep · `classic-chase-loop` Chase Loop · `classic-sung-words` Sung Words · `classic-marker-lines` Marker Words · `classic-pill-grow` Pill Grow · `classic-lower-third` Lower Third · `classic-drop-bar` Drop Bar · `classic-outline-tag` Outline Tag · `classic-prompt-field` Prompt Field · `classic-random-pop` Random Pop · `classic-chaos-letters` Chaos Letters · `classic-random-rise` Random Rise · `classic-ransom-note` Ransom Note · `classic-editorial-typer` Editorial Typer
+**Text animations** (`textAnimation`; ★ = preferred): ★ `glide-text` Glide Text · `glide-continuous` Glide Continuous · `smart-overshoot` Smart Overshoot · `glide-soft-stop` Glide Soft Stop · ★ `ember-type` Ember Type · `molten-edge` Molten Edge · `focus-type` Focus Type · `tumble-type` Tumble Type · `flap-down` Flap Down · `drop-swell` Drop Swell · `rain-type` Rain Type · `counter-sweep` Counter Sweep · `sunset-shrink` Sunset Shrink · `boomerang` Boomerang · ★ `swing-pop` Swing Pop · ★ `word-swing` Word Swing · ★ `letter-vortex` Letter Vortex · `center-burst` Center Burst · ★ `pendulum` Pendulum · `spin-pop` Spin Pop · `domino` Domino · `flip-pop` Flip Pop · `card-turn` Card Turn · `slam-zoom` Slam Zoom · `orbit` Orbit · ★ `fan-deal` Fan Deal · ★ `whip` Whip · `rubber-letters` Rubber Letters · `pop-letters` Pop Letters · `drop-swing` Drop Swing · `coin-spin` Coin Spin · `converge` Converge · `roll-in` Roll In · `door-swing` Door Swing · `pill-type` Pill Type · `card-type` Card Type · `word-bars` Word Bars · `line-stack` Word Stack · `marker-type` Marker Type · `card-erase` Card Erase · `colour-sweep` Colour Sweep · `glow-pass` Glow Pass · `wave-pass` Wave Pass · `pop-through` Pop Through · `shine` Shine · ★ `marker` Marker · ★ `outline-pass` Outline Pass · ★ `neon-flow` Neon Flow · `rainbow` Rainbow · `gradient-flow` Gradient Flow · `jitter` Jitter · `float` Float · `flicker` Flicker · `breathe` Breathing Wave · `shimmer` Shimmer · `decode` Decode · `binary` Binary Decode · `alphabet-roll` Alphabet Roll · ★ `glitch` Glitch · `classic-fade-up` Fade Up · `classic-fade-down` Fade Down · `classic-rise-mask` Rise (Mask) · `classic-blur-in` Blur In · `classic-slide-in` Slide In · `classic-side-mask` Side Mask · `classic-tilt-drop` Tilt Drop · `classic-flip-up` Flip Up · `classic-typewriter` Typewriter · `classic-wave-rise` Wave Rise · `classic-bounce-letters` Bounce Letters · `classic-materialize` Materialize · `classic-neon-runner` Neon Runner · `classic-ink-highlight` Ink Highlight · `classic-flash-type` Flash Type · `classic-karaoke-sweep` Karaoke Sweep · `classic-chase-loop` Chase Loop · `classic-sung-words` Sung Words · `classic-marker-lines` Marker Words · `classic-pill-grow` Pill Grow · `classic-lower-third` Lower Third · `classic-drop-bar` Drop Bar · `classic-outline-tag` Outline Tag · `classic-prompt-field` Prompt Field · `classic-random-pop` Random Pop · `classic-chaos-letters` Chaos Letters · `classic-random-rise` Random Rise · `classic-ransom-note` Ransom Note · `classic-editorial-typer` Editorial Typer
 
 **Entrances** (`enter`): `slide` Slide · direction · `glide` Glide (in and out) · direction · `glide-stop` Glide Stop (in and out) · direction · `glide-floaty` Glide Floaty (in and out) · direction · `glide-endless` Glide Endless (in and out) · direction · `glide-diagonal` Glide Diagonal (in and out) · direction · `glide-arc` Glide Arc (in and out) · direction · `glide-close-pass` Glide Close Pass (in and out) · direction · `glide-fade-drift` Glide Fade Drift (in and out) · direction · `glide-bank` Glide Bank (in and out) · direction · `glide-swing-3d` Glide Swing 3D (in and out) · direction · `glide-linger` Glide Linger (in and out) · direction · `glide-soft-entry` Glide Soft Entry (in and out) · direction · `glide-blur` Glide Blur (in and out) · direction · `glide-spin-through` Glide Spin Through (in and out) · direction · `glide-depth-pass` Glide Depth Pass (in and out) · direction · `glide-tilt` Glide Tilt (in and out) · direction · `zoom-in` Zoom In · `mockup-close-up` Mockup Close-Up · `mockup-orbit-left` Orbit Left · `deck-drift` Deck Drift · `hero-punch` Hero Punch · `dark-spotlight` Dark Spotlight · `phone-app-swipe` Phone Swipe Reveal · `phone-app-punch` Phone App Punch In · `phone-app-tilt-drift` Phone Tilt Drift · `phone-app-cta-hold` CTA Hold Focus · `button-press` Button Press · `button-tap-flash` Tap Flash · `pop-overshoot` Pop Overshoot · `spring-in` Spring In · `rubber-wobble` Rubber Wobble · `tap-nudge` Tap Nudge · `whip-swing` Whip Swing · `flick-drop` Flick Drop · `jelly-shake` Jelly Shake · `heartbeat` Heartbeat · `impact-punch` Impact Punch · `pendulum-swing` Pendulum Swing · `loose-wiggle` Loose Wiggle · `shiver` Shiver · `float` Float · `flicker-in` Flicker In · `earthquake` Earthquake · `tumble-drop` Tumble Drop · `rubber-band` Rubber Band · `spring-twist` Spring Twist · `slingshot` Slingshot · `pendulum-in` Pendulum In · `smooth-overshoot-rise` Smooth Overshoot Rise · `spin-in` Spin In · `twist-in` Twist In · `roll-in` Roll In · `tilt-settle` Tilt Settle · `wind-up-spin` Wind-Up Spin
 
@@ -71,9 +107,15 @@ the first version and check every version against it.
 
 **Transitions** (★ = preferred): None · ★ Cross Fade · Push · Parallax · Wipe · Zoom In · Zoom Out · ★ Advanced Zoom · ★ Advanced Movement · 3D Carousel · Louver Flip · ★ Circular Wipe · ★ Pixel Blocks · ★ Camera Whip · ★ Zoom Ruler · ★ Gradient Glow Stack · ★ Gradient Map · Scale Swap · Side by Side · Dip to Black · Radial Wipe
 
+**Camera moves** (`camera.move`; spread over the camera's length): `cm-quiet-push` Quiet Push (Cinematic) · `cm-swoop-dive` Swoop Dive (Cinematic) · `cm-corkscrew` Corkscrew (Cinematic) · `cm-fast-orbit` Fast Orbit (Cinematic) · `cm-lateral-glide` Lateral Glide (Cinematic) · `cm-parallax-arc` Parallax Arc (Cinematic) · `cm-arc-closeup` Arc Close-Up (Cinematic) · `cm-slingshot` Slingshot (Editorial) · `cm-step-zoom` Step Zoom (Editorial) · `cm-handheld-breath` Handheld Breath (Editorial) · `cm-soft-land` Soft Land (Editorial) · `cm-documentary-follow` Documentary Follow (Editorial) · `cm-weave-run` Weave Run (Energy) · `cm-s-curve-drift` S-Curve Drift (Energy) · `cm-macro-sweep` Macro Sweep (Energy) · `cm-punch-through` Punch Through (Energy) · `cm-orbit-pulse` Orbit Pulse (Loops) · `cm-float` Float (Loops) · `cm-figure-eight` Figure Eight (Loops) · `cm-rack-to-near` Rack to Near (Focus) · `cm-rack-to-far` Rack to Far (Focus) · `cm-focus-chase` Focus Chase (Focus) · `cm-macro-bloom` Macro Bloom (Focus) · `cm-grand-reveal` Grand Reveal (Cinematic)
+
+**Camera rigs** (`camera.rig`; the fields you can override: type orbit | dolly | crane | pushIn | truck | spiral | handheld | follow, aim center | path, radius 100–20000, height -8000–8000, startAngle -360–360, sweep -720–720, rise -8000–8000, distance -20000–20000, turns 0.25–8, tilt -80–80, roll -180–180, amplitude 0–2000, frequency 0–40): `heroOrbit` Hero Orbit (orbit) · `slowReveal` Slow Reveal (orbit) · `turntable` Turntable (orbit) · `craneDown` Crane Down (crane) · `riseReveal` Rise & Reveal (crane) · `pushIn` Push In (pushIn) · `pullBack` Pull Back (dolly) · `truckLeft` Truck Left (truck) · `productSpiral` Product Spiral (spiral) · `handheldDrift` Handheld Drift (handheld) · `droneFollow` Drone Follow (follow) · `chaseCam` Chase Cam (follow)
+
+**Zoom feels** (`camera.feel`): `studio` Studio · `calm` Calm · `precise` Precise · `lively` Lively · `follow` Follow. Full camera layers (paths, Smart Zoom on a recording's clicks, the drawn cursor): references/video-camera.md.
+
 **Overlay effects** (`effects`): `glow`, ★ `bloom`, `auraBlur`, `gradientBeam`, ★ `gradientSweep`, `fractalNoise`, ★ `rgbSplit`, `glitch`, `scanlines`, `flashBlink`, `vhs`, `fisheye`, `opticsCompensation`, `vignette`, ★ `echo`, `timeshift`, `radialBlur`, ★ `radialFastBlur`, `sharpen`, `mirror`, `waveWarp`, `warpStyles`, `shockwave`, `waveLines`, `waveRipple`, `fill`, `shapeRulers`, `copyColor`, `curves`, `turbulentDisplace`, `alphaChoker`, `extract`, ★ `colorama`, `posterize`, ★ `halftone`, ★ `fastCameraWiggle`, ★ `lightRays`, `longShadow`, `outlineBands`, `kaleidoscope`, `crtMatrix`, `pixelate`, `vectorFieldWarp`, `pixelStretch`, `neonGlow`, `edgeDetect`, `doubleExposure`, ★ `filmStock`, `fastBlur`, `gridLines`, `strip`, `ascii`, `objectDither`, `objectIsolines`, `objectWindow`, `objectSlitScan`, `objectCurtain`, `objectGrid`, `objectContour`, `objectNodes`, `objectLinks`, `objectFacets`, `objectMeasure`
 
-**Layer effects** (`effects`): `mockupFrame`, ★ `runningGlow`, `depthMap`, `depth3d`, `depthScan`, `fresnelRim`, ★ `motionBlur`, ★ `motionTrail`, `autoFill`, ★ `repetile`, `regionDistort`, `bend`, `cornerPin`, `meshWarp`, `bezierWarp`, `rig`, ★ `droste`, `pryzm`, ★ `glass`, `chromaKey`, `layerMask`
+**Layer effects** (`effects`): `mockupFrame`, ★ `runningGlow`, `depthMap`, `depth3d`, `depthScan`, `fresnelRim`, ★ `motionBlur`, `posterizeTime`, ★ `motionTrail`, `autoFill`, ★ `repetile`, `regionDistort`, `bend`, `cornerPin`, `meshWarp`, `bezierWarp`, `rig`, ★ `droste`, `pryzm`, ★ `glass`, `chromaKey`, `layerMask`
 
 Effect params: references/video-effects.md.
 

package/skill/references/video-camera.md

@@ -9,6 +9,9 @@
 ## Contents
 
 - [Camera layers (`mediaType: "camera"`) — a virtual camera over the whole stack](video-camera.md#camera-layers-mediatype-camera--a-virtual-camera-over-the-whole-stack)
+- [A sequence's own camera](video-camera.md#a-sequences-own-camera)
+- [Smart Zoom — the camera's Zoom mode](video-camera.md#smart-zoom--the-cameras-zoom-mode)
+- [Drawn cursor](video-camera.md#drawn-cursor--a-screen-recording-with-no-cursor-in-its-picture)
 - [Camera presets (save & load reusable camera moves)](video-camera.md#camera-presets-save--load-reusable-camera-moves)
 - [Camera Rig — a parametric camera move](video-camera.md#camera-rig--a-parametric-camera-move)
 
@@ -18,7 +21,7 @@ A camera clip draws nothing. While the playhead is inside it, it poses a virtual
 
 Rules:
 
-- The camera lives on a channel marked `"kind": "camera"`. **A project may have at most one camera channel, and it must be LAST in the `channels` array** (channel order is z-order; last renders highest). The editor re-pins it on every write and on load, so a project authored with the camera elsewhere is silently reordered — emit it last to avoid surprising diffs. Put several camera clips on it to chain moves; the clip under the playhead wins, and outside every camera clip the camera is neutral.
+- The camera lives on a channel marked `"kind": "camera"`. **A timeline may have at most one camera channel, and it must be LAST in its `channels` array** (the project's, and each sequence's for its own camera — see below) (channel order is z-order; last renders highest). The editor re-pins it on every write and on load, so a project authored with the camera elsewhere is silently reordered — emit it last to avoid surprising diffs. Put several camera clips on it to chain moves; the clip under the playhead wins, and outside every camera clip the camera is neutral.
 - Camera clips are synthetic (no `url`) and are keyframed with their own property registry, using the ordinary `propertyKeyframes` shape (positions 0–100 % of the clip).
 - Any channel can opt out with `"cameraLocked": true` — it renders exactly as if there were no camera (watermarks, fixed captions).
 - A camera-locked layer is a 2D layer, as in After Effects: it composites in STACK order and never depth-tests against 3D. Above a model layer in the stack it draws over the model (a flash, a title at the comp plane needs no pulling toward the camera); at the very bottom of the stack (a full-frame backdrop) it stays behind everything, the Scene Rig's cyclorama included. 3D layers on either side of a locked layer still occlude each other by depth.
@@ -105,9 +108,106 @@ A camera item can ride a saved 3D bezier spline. It uses the same world-pixel po
 
 Animating `camDolly` and `camZoom` in opposite directions is the vertigo effect.
 
-**Depth of field** is physical and per layer: each layer's circle of confusion comes from its own distance to the camera (`aperture · |focusDistance − layerDistance| / layerDistance · blurLevel/100`), so a rack focus is just keyframed `camFocusDistance`. All the DOF fields above may be set either as a **base value on the camera item** (`item.camAperture = 40`) or as a keyframe track in `propertyKeyframes` — tracks win at the playhead. `camAperture: 0` or `camBlurLevel: 0` renders byte-identically to DOF off. There are no per-layer `dof*` fields — a project still carrying them animates nothing. Rendered by **`/render-onserver`** and the desktop render; the fast `/render` ignores camera layers along with everything else non-trivial.
+**Depth of field** is physical and per layer: each layer's circle of confusion comes from its own distance to the camera (`aperture · |focusDistance − layerDistance| / layerDistance · blurLevel/100`), so a rack focus is just keyframed `camFocusDistance`. Both distances are **view depth from the camera**, so a camera that moves carries the sharp plane with it: under a dolly the subject at depth `z` (its `panZ`) sits at `perspectiveDistance − camDolly − z` (`perspectiveDistance = (H/2)/tan(14°)`, ≈ 2166 on a 1080-tall frame). To keep a subject sharp through a move, key `camFocusDistance` on the dolly's own keys with that value; under a rig, with the subject's depth along the rig's view at a few points of the move (the scene script does both for `dof.focus`). All the DOF fields above may be set either as a **base value on the camera item** (`item.camAperture = 40`) or as a keyframe track in `propertyKeyframes` — tracks win at the playhead. `camAperture: 0` or `camBlurLevel: 0` renders byte-identically to DOF off. There are no per-layer `dof*` fields — a project still carrying them animates nothing. Rendered by **`/render-onserver`** and the desktop render; the fast `/render` ignores camera layers along with everything else non-trivial.
 
-**Screen-recording auto-zoom emits one of these** (a clip named `Auto-zoom` on the camera channel), so an agent asked to "make the zoom less aggressive" edits `camZoom` keys on that clip rather than hunting for an adjustment layer.
+**Screen recordings get a camera clip on the camera channel.** A new recording gets a **Smart Zoom** camera, a clip named `Smart Zoom`; see the Smart Zoom section below. Projects made before it carry a clip named `Auto-zoom` with baked `camZoom`/`camX`/`camY` keys. So for "make the zoom less aggressive", change the Smart Zoom preset, or edit `camZoom` keys on an `Auto-zoom` clip. Never hunt for an adjustment layer.
+
+### A sequence's own camera
+
+A sequence (`mediaType: "sequence"`) can carry its own camera: a camera clip on a `"kind": "camera"` channel, LAST in
+`sequence.channels`, timed in the sequence's own seconds. It films that sequence's layers exactly as the project camera
+films the top level — its move, its rig, Smart Zoom, depth of field per layer, and `cameraLocked` channels inside the
+sequence stay put. The project camera, if any, then films the sequence as a whole. Each scene of a film can so have its
+own camera while a cross transition still blends the whole scenes. A GreenLight Motion scene script's real camera
+(a scene's `camera` with `move`, `rig`, `zooms`, `keyframes` or `dof`) is built this way, with the scene's backdrop
+channel camera-locked so a zoom or an orbit never shows its edge.
+
+### Smart Zoom — the camera's Zoom mode
+
+The Movement tab **Zoom** zooms the camera in over **zoom ranges** on the camera layer. They are automatic from a
+screen recording's clicks, or added by hand. Nothing is baked into keyframes:
+
+```jsonc
+"cameraMoveMode": "smartZoom",            // the Zoom tab (the stored id keeps its first name)
+"smartZoom": {
+  "clipId": "<the recording's CLIP id>",  // null: no recording, the ranges are placed by hand
+  "preset": "studio",                     // studio|calm|precise|lively|follow
+  "ranges": [                             // optional. Absent = automatic, from the recording's clicks
+    { "id": "r1", "startMs": 2700, "endMs": 5580, "mode": "follow" },
+    { "id": "z2", "startMs": 9000, "endMs": 11400, "mode": "fixed", "point": { "x": 0.3, "y": 0.7 }, "zoom": 2 }
+  ]
+}
+```
+
+- **Ranges:**
+  - `startMs`/`endMs` are in the **recording's own time** (source ms, so trims and moves keep a zoom on its moment).
+    With no recording they are the camera clip's own time.
+  - `zoom` is 1–4; absent = the preset's (Studio 1.45).
+  - `mode: "follow"` aims at the clicks inside the range. `mode: "fixed"` centres the view exactly on `point` (0..1 of
+    the frame).
+  - `disabled: true` keeps a range but skips it.
+  - Writing `ranges` replaces the automatic list. Copy the automatic ones first (ids `r1`, `r2`…) to keep them.
+- **In the editor:**
+  - **Add Zoom** (a timeline toolbar toggle, shown while a camera is in Zoom): with it ON, hovering the camera layer
+    shows a ghost zoom with a + and a click adds one there; a block drags to move it. With it OFF (the default) the
+    camera layer drags, trims and selects like any clip, and only the blocks answer: a click picks one.
+  - Either way, dragging a block's end resizes it and × removes it.
+  - With a block picked, dragging the preview moves the zoomed view and scroll or pinch zooms; both make the range
+    fixed. Delete removes it.
+  - The panel has the Feel (preset), the picked zoom's value, Follow the clicks again, and Back to automatic zooms.
+
+- **How it decides:**
+  - It reads the recording clip's `recordingMeta` (its clicks and cursor track).
+  - It zooms in from 0.3 s before a click until 2.5 s after the last one, and moves part of the way toward each group of clicks.
+  - Every move is a spring, so the camera never stops and restarts between clicks.
+- **It follows the recording's items on the timeline.** Trims, splits, moves and speed changes re-aim it on their own. Outside the recording's items, the camera rests at zoom 1, centred. It only acts inside its own camera clip's span.
+- **Presets** (`smartZoom.js` `PRESETS`; an unknown id reads as `studio`):
+
+  | Preset | Look |
+  |---|---|
+  | `studio` | Default, like Screen Studio: 1.45×, aims part-way |
+  | `calm` | 1.35×, slow; the clicked spot stays put |
+  | `precise` | 1.6×, clicks near the middle |
+  | `lively` | 1.7×, quick |
+  | `follow` | 1.5×, follows the cursor, not only clicks |
+
+  The recorder's setup panel picks one before the take. Its **No zoom** choice makes no camera at all.
+- **Precedence:** it drives `camZoom`, `camX` and `camY`, so keys on those three render as nothing. `camRoll`, `camDolly`, tilt and depth of field compose as usual. A motion preset that animates zoom or pan flips the mode to `"free"`.
+- **Changing it:**
+  - Patch `smartZoom.preset` on the live project to change the look, or `smartZoom.ranges` to place zooms.
+  - Set `"cameraMoveMode": "free"` to drive the camera by hand. `smartZoom` stays on the item, so setting the mode
+    back (the Zoom tab) restores it.
+  - A recording clip without `recordingMeta` (no Input Monitoring) has no automatic zooms, but ranges you add still
+    work.
+
+### Drawn cursor — a screen recording with no cursor in its picture
+
+The macOS recorder (Full screen / Area) and the agent template (`CURSOR=drawn`, its default) record the screen
+**without** the cursor. The editor draws a smooth one back onto the recording's own picture, so effects, masks,
+mockups, transitions and the camera treat it like a recorded cursor. Three fields make it:
+
+```jsonc
+// the recording CLIP
+"recordingMeta": { /* clicks + a light path */ "cursorInVideo": false },
+"recordingTrackUrl": "/media/<board folder>/screen_….glcursor",   // the hand's full path + cursor shapes, beside the video
+// its timeline ITEM (absent = drawn with the Studio look)
+"recordingCursor": { "enabled": true, "preset": "studio" }
+```
+
+- **`recordingCursor`** fields; any set field overrides the preset's:
+  - `enabled`: false hides the cursor.
+  - `preset`: `studio`, `calm`, `precise`, `lively` or `follow`. The same ids as Smart Zoom; each sets a cursor look.
+  - `size`: 0.25–6, a multiple of the real cursor. Studio is 1.5.
+  - `smoothing`: `off`, `spring`, `zerolag` or `spline`.
+  - `clickEffect`: `press`, `ring` or `none`.
+  - `hideIdleMs`: fade after this long still; 0 = never.
+  - `tilt`: 0–40.
+  - `motionBlur`: 0–2; 0 = none.
+- **Only for `recordingMeta.cursorInVideo === false`.** A recording that has the cursor in its picture (Windows,
+  Linux, Window capture, older takes) ignores `recordingCursor`; the cursor it has can't be removed.
+- The cursor lands exactly on each click, presses on mouseDown and takes the real shape (hand over links, I-beam
+  over text) from the track. A missing or failed `.glcursor` falls back to the light path in `recordingMeta`.
+- To change it, edit the live project: GET, set the item's `recordingCursor`, PUT with `expected_version`.
 
 ### Camera presets (save & load reusable camera moves)
 
@@ -149,7 +249,7 @@ An entry may set `sparse: true`, which drops the usual "seed every motion prop"
 
 ### Camera Rig — a parametric camera move
 
-A camera item's `cameraMoveMode` picks one of three exclusive modes: `"free"` (position/rotation keyframes, the default), `"path"` (the hand-drawn motion path), `"rig"` (`item.cameraRig`). **A rig writes no path**, so switching modes never destroys a drawn curve.
+A camera item's `cameraMoveMode` picks one of four exclusive modes: `"free"` (position/rotation keyframes, the default), `"path"` (the hand-drawn motion path), `"rig"` (`item.cameraRig`) and `"smartZoom"` (the Movement tab **Zoom**: zoom ranges, from a screen recording's clicks or placed by hand — see Smart Zoom above). **A rig writes no path**, so switching modes never destroys a drawn curve.
 
 ```jsonc
 "cameraMoveMode": "rig",
@@ -204,6 +304,8 @@ Keys use the same shape as every other track: `position` is 0–100 % of the cam
 
 **`aim` picks what the camera faces.** `"center"` (the default, also when the key is absent) aims at the point the rig is built around — the comp centre, or the followed layer for `follow`. `"path"` faces the direction of travel (orient along path). It suits moves that travel toward or past the subject (`pushIn`, `dolly`, `crane`, `truck`); on an `orbit` or `spiral` it looks along the circle, roughly 90° away from the subject. A rig that does not move (zero `sweep`/`distance`, a `handheld` with `amplitude` 0) keeps the centre aim. `aim` is a choice about the shot's framing, not part of a preset: keep the current value when emitting a preset over an existing rig, as with `targets`.
 
+**Flat layers have a front.** Text, shapes, pictures and video are flat cards: an orbit that swings more than about 75° off the front (`startAngle` + `sweep` past ±75°, with `startAngle: 0` = straight ahead) turns them edge-on, and past 90° the camera sees their backs and they read mirrored. Keep orbits of flat layers within about ±70° (`heroOrbit`, `slowReveal`); `turntable`'s full circle is for 3D models.
+
 **`tilt` moves the AIM POINT, not the camera's own rotation**, so the subject stays framed as the rig travels. With `"aim": "path"` the same lift tips the gaze above or below the direction of travel. `handheld` jitter is a pure function of `seed` and progress — never wall-clock — so preview and export match frame for frame.
 
 **Rendering.** Model layers render in the editor preview, the desktop Download, **`/render-onserver`** / **`/render-onserver-job`**, and **`/render-still`**. The fast `/render` does **not** support them (video/image only). Very heavy assets (≳900 k triangles) render slowly enough that an export can look hung — prefer decimated models.

package/skill/references/video-design.md

@@ -57,6 +57,11 @@ and check every version against them.
 - Vary two or three kinds of transition across a video: one kind everywhere looks like a template, a new one at
   every cut looks random.
 - Camera moves are slow and small unless they are the point. Fast motion looks best at 60 fps with motion blur.
+- A real 3D camera earns its place on one or two moments, not every scene: a zoom onto the one thing a scene is about
+  (a number, the button a screen recording clicks; 1.3–2×, then back out), or a slow orbit or push that shows depth.
+- Depth needs layers at different distances: a soft shape or picture far behind, the words at the front. Depth of
+  field reads only then; keep the words sharp.
+- Keep an orbit in front of flat layers (within about ±70°): text turned further goes edge-on, then mirrored.
 
 ## Sound
 

package/skill/references/video-effects.md

@@ -26,6 +26,7 @@
   - [3D Depth entry](#3d-depth-entry)
   - [Depth Scan entry](#depth-scan-entry)
   - [Motion Blur entry](#motion-blur-entry)
+  - [Posterize Time entry](#posterize-time-entry)
   - [Motion Trail entry](#motion-trail-entry)
   - [Grow Fill entry](#grow-fill-entry)
   - [Rig (Puppet) entry](#rig-puppet-entry)
@@ -844,6 +845,23 @@ Rim light from the subject's SHAPE. Authored from the DEPTH EFFECTS section.
 - Keyframe with `propertyKeyframes.mblurShutter`, `propertyKeyframes.mblurAmount`, and (velocity mode) `propertyKeyframes.mblurMaxBlur` / `propertyKeyframes.mblurFalloff`. `mblurSamples` is not keyframable — an animated tap count steps the kernel per integer.
 - It cannot see motion INSIDE the clip's pixels (a person walking through a static video stays sharp) and does nothing on `model3d` layers.
 
+### Posterize Time entry
+
+```json
+{ "id": "posterizeTime", "eid": "layer-posterize", "enabled": true, "params": { "ptFps": 12 } }
+```
+
+- The layer updates only `ptFps` times a second (1–60) while the project plays at full rate — the stop-motion /
+  "on twos" look. It is the layer's CLOCK, not a pixel pass: its video or GIF frame, every keyframe (transform,
+  effect params, masks, the motion path and Path Progress), text animators, a nested sequence's whole inner
+  timeline, models and particles all hold on each step. Preview (paused and playing), `/render-still` and every
+  export agree.
+- **Not posterized:** the layer's sound, the timeline itself (which clip is active, cross transitions), layers
+  parented to it or following it, and a camera clip.
+- Keyframe the rate with `propertyKeyframes.ptFps`. The rate is INTEGRATED, so a ramp from 6 to 24 speeds the steps
+  up smoothly and time never steps backwards.
+- Costs nothing per frame beyond reading the time; a layer without it pays one array scan.
+
 ### Motion Trail entry
 
 ```json

package/skill/references/video-paths.md

@@ -109,17 +109,48 @@ A **text** item with a motion path can lay its glyphs out along the curve instea
   "textPathTrimStart": 0,            // % of curve length — usable window start
   "textPathTrimEnd": 100,            // % — window end
   "textPathOffsetY": 0,              // px perpendicular (baseline) offset; rows stack along the normal
-  "textPathRotate": true             // align each unit with the curve tangent
+  "textPathRotate": true,            // align each unit with the curve tangent
+  "textPathCorners": "smooth"        // 'smooth' = units turn with the curve | 'sharp' = a unit never straddles a bend
 }
 ```
 
 - Placement is arc-length parameterised (kerning survives corners) and shares `evaluateObjectMotionPath`, so preview, WebCodecs export and `/render-onserver` agree.
-- **Progress reuses `motionPathT` + its Path Progress track** and moves every glyph along the curve (not the block as one object). A closed untrimmed loop wraps like a marquee; an open or trimmed path extrapolates straight past its end tangents, so text can slide onto/off the curve. Keying `textPathTrimEnd` 0→100 is a write-on.
+- **Progress reuses `motionPathT` + its Path Progress track** and moves every glyph along the curve (not the block as one object). A closed untrimmed loop wraps like a marquee; an open or trimmed path extrapolates straight past its end tangents, so text can slide onto/off the curve. The trims move the WINDOW the run is laid out in — they do NOT hide letters (those run on past the window's ends), so keyed trims are not a write-on: use a Text Animator reveal for that. Letters that run past the path's own ends are cut at the text plate's edge — extend the path to run text off the frame.
 - `textPathDirection` decides where the run rests at 0% and which way progress carries it: `forward` parks the text ON the first point and travels to the last, `backward` ends it on the last point and travels back to the first, `center` (default) keeps the legacy middle anchor and follows `textAlign` (start/centre/end of the trimmed window). Multi-line text stacks rows along the curve normal at line-height steps.
 - `textPathTravel` sets how far 100% carries a forward/backward run: `fit` (default) stops when the run's far end reaches the far point, so the whole text stays on the path; `through` keeps going until the leading unit gets there, sliding the text off the end. Travel is computed per row (each row's run has its own length), and a run longer than the trimmed window has nowhere to travel under `fit`. Ignored by `center` (which always slides the full window) and by a wrapping closed loop (always a whole lap).
+- `textPathCorners: "sharp"` treats bends as corners (a turn of 20°+ within ¾ of the type size, or half the unit if wider): a unit never takes an in-between angle on a bend — it belongs wholly to ONE side, turned to that side and laid on that side's straight line carried through the bend. The side is the one it RESTS on (Path Progress 0), so a glide or drift shorter than half a unit never turns a letter at a corner; a unit carried further (a marquee round a square) moves across when its centre passes the middle of the bend. Use it for text running or gliding round a square / ∩ path (rounded corners included); keep `smooth` for curves (an outline, a wave).
 - While `textPathEnabled` is live (path has ≥2 points), `follow` is ignored — the glyph run owns the curve and the layer's own transform stays put. The caption background bar (`textBgEnabled`) is suppressed on a path; split/in-out animations, highlight, randomizer and word timings all compose per unit on the curve.
 - `follow` is NOT required: draw a path, leave `follow: false`, set `textPathEnabled: true`.
 
+#### Animated motion path (`motionPathPoints`)
+
+The path ITSELF can be keyframed, like a Layer Mask outline: `propertyKeyframes.motionPathPoints` holds snapshots of the
+points, and Follow Path and Text on Path both ride the snapshot at the current frame — so text can follow a tracked
+(RotoScope) outline frame by frame.
+
+```json
+"propertyKeyframes": {
+  "motionPathPoints": [
+    { "position": 0,   "value": "[{\"x\":-520,\"y\":0,\"z\":0,\"hIn\":{\"x\":0,\"y\":0,\"z\":0},\"hOut\":{\"x\":0,\"y\":0,\"z\":0},\"manual\":true}, …]", "easing": "Linear" },
+    { "position": 100, "value": "[…the same points, moved…]", "easing": "Linear" }
+  ]
+}
+```
+
+- **Value:** a JSON string of the points in the WORLD space of `motionPath` (pixels, origin at the comp centre, +y up,
+  z toward the viewer, handles as offsets, optional `rx/ry/rz`). `closed`, `follow`, `aim` stay on `item.motionPath`.
+- **Same point count in every key**, as for mask paths; the shorter list wins if they differ. Dense (per-frame) tracks
+  use LINEAR keys.
+- **Keep `item.motionPath`** with the same points (any key's): the track is only kept while the layer has a path of
+  2+ points, and point counts / Text on Path liveness read it.
+- **In the editor:** MOTION PATH ▸ **Animate path** keys the path at the playhead; from then on every canvas, 3D-view
+  or panel edit keys it where the playhead is (adding or deleting an anchor changes every key, split at the same spot
+  of the curve). **Copy path** from an ANIMATED source — a RotoScope mask, a keyed shape path or another animated
+  motion path (the menu shows `n◆`) — brings all its keys, at their absolute times on this layer's span, cut with an
+  interpolated key where the source runs past either end.
+- **Text on Path:** the text plate is sized from the reach of ALL keys once, so the outline can move without the
+  texture being reallocated.
+
 ### Motion-track follow (`motionTracks` + `motionFollow`)
 
 A video layer the user has motion-tracked in the editor carries the result on the item as `motionTracks: []` — each track `{ id, name, mode, refTime, region, sourceFps, sourceAspect, segments, samples }`, where `samples` rows are `[tSourceSeconds, cx, cy, scale, rotDeg, confidence]` in the clip's **source** seconds, normalised to the source frame (so a track survives trims, splits and speed changes). **The editor's own analysis has no endpoint** — it runs on decoded frames inside the app. Treat a track the USER made as read-only: preserve it verbatim when copying items, and never hand-edit its samples. An agent can, however, compute tracking data itself (OpenCV in Python) and write a NEW track into the project — the sample layout, the coordinate spaces and a worked recipe are in [tracking-data.md](tracking-data.md).

package/skill/references/video-projects.md

@@ -224,6 +224,8 @@ If you need to build the editor state by hand instead of using `/from-clips`, th
 
 **Preview source.** `"previewOriginal": true` on a clip makes the editor preview play the full-res original instead of its `proxyUrl` — sharper when scale/crop keyframes zoom in, at a heavier decode cost. Preview-only: every render path already uses the original.
 
+**Screen recordings.** A recording clip carries `recordingMeta` (its clicks and a light cursor path, in seconds of the file) and may carry `recordingTrackUrl` (the full-rate `.glcursor` beside it) and `recordingMeta.cursorInVideo: false` (no cursor in its picture: the editor draws one). Its camera is a Smart Zoom item, and its item's `recordingCursor` sets the drawn cursor's look. Both are in [video-camera.md](video-camera.md) ("Smart Zoom" and "Drawn cursor").
+
 **Layer scale is three fields.** `zoom` is the uniform scale (0.1–20, default 1), and `scaleX` / `scaleY` (same range, both default 1) are per-axis multipliers on top of it — so a layer's drawn width is `zoom × scaleX` and its height `zoom × scaleY`. Use `zoom` alone for an ordinary resize; reach for the other two only to stretch or squash one axis (a wide title bar, a squash-and-stretch bounce). All three are the panel's Transform → Scale row (X / Y / XY) and all three inherit through layer parenting. Every one of them also has a keyframe track (`scale`, `scaleX`, `scaleY` — see [video-keyframes.md](video-keyframes.md)), which multiplies the base field rather than replacing it. Projects written before these existed load unchanged: a missing `scaleX`/`scaleY` is 1.
 
 **Layer grade — the static `filter*` fields.** Every visual item carries a CSS-style grade applied to the layer before it composites: `filterBlur` (px, 0–10, default 0), `filterBrightness` / `filterContrast` / `filterSaturation` (%, 0–200, default 100), `filterHueRotate` (deg, 0–360, default 0), `filterGrayscale` / `filterSepia` / `filterInvert` (%, 0–100, default 0; Invert at 100 is a full negative). These are the layer's own base values; the matching keyframe tracks (`blur`, `brightness`, `contrast`, `hue-rotate`, `saturate`, `grayscale`, `sepia`, `invert`) **override** the static field while the track exists rather than multiplying it, so key one or set the other, not both. They are a cheap per-layer grade and independent of the Overlay Effects chain — reach for `effects[]` when you need a real grade (curves, LUT, colour balance).
@@ -254,13 +256,37 @@ Agent rules: when the user asks for "the project's colours", "brand colours" or
 { "colorTokens": ["#8b5cf6", "#0ea5e9", "rgba(0, 0, 0, 0.6)"] }
 ```
 
+**Photo slots (pictures people may replace).** A picture layer (an item whose clip is `mediaType: "image"`) can carry
+`"photoSlot": { "fill": "cover" | "fit", "focus": [x, y], "takes": "image" | "media", "series": true | false, "note": "…" }`
+— a MARK only: no render path reads it. `fill` = cover the layer's box (edges may be cut) or show all of the photo;
+`focus` = the point (0–1 inside the photo) a Cover crop keeps in view; `takes` = a photo, or a photo or a video;
+`series: true` = one of the project's numbered slots, filled in PLAY order (by start time, not track order), `false` = a
+slot on its own (a logo); `note` (≤ 300 chars) = what belongs there, for an agent. The box is the layer's own frame, so
+moving or resizing the layer moves the slot. Optional `"photoSlotSettings": { "label": "Photos", "ifFewer": "reuse" | "keep" }`
+at the `data` root names the series and says what slots with no photo show when people bring fewer photos than slots
+(omitted while default). The timeline marks slot layers `SLOT n`; the user sets them in Export for agents ▸ Photo slots.
+Agent rules: to let people put their own photo in a picture, add `photoSlot` to its item (`{}` is enough — every field
+has a default); keep the user's existing marks when you rebuild a layer; a slot is never empty — its current picture is
+the example until someone replaces it.
+
 **Project background.** Set `"background": { …backgroundConfig… }` at the `data` root to fill the stage behind every channel — a solid colour, gradient, GLSL shader, pattern, or image. It takes the same `backgroundConfig` object as shape backgrounds; the full schema, the gradient/shader preset ids, and the shader authoring rules live in the **Backgrounds (project & shape)** section below. Omit it (or use `"type": "transparent"`) for a transparent stage. Baked by **`/render-onserver`**; the fast `/render` ignores it. A bare colour string (`"background": "#3366cc"`) is coerced to `{"type": "solid", "solidColor": …}`; prefer the explicit object.
 
 **One live item per channel.** Treat every channel as one timeline track, not as a container of simultaneously composited layers. At any timeline time, a channel may have at most one active item. If two items' visible windows overlap, only one is guaranteed to render (the later-starting item commonly wins) and the save API does not reject the project. For an unsnapped item, its ordinary visible window is `[freeStart, freeStart + (trimEnd - trimStart))`; validate these windows before `PUT`. Put every simultaneously visible image, shape, text block, motion layer, or other visual on a separate channel. This rule also applies inside sequence timelines. Reuse one channel for consecutive, non-overlapping captions or shots only.
 
 **Keep unsnapped items sorted by `freeStart`.** On an `unsnapped` channel the editor treats the item BEFORE a clip in the `items` array as "the clip before it" — cross transitions, the seam button and the layout's overlap all read array neighbours, not time neighbours. The editor re-sorts on every insert, move and paste; an API write does not. After adding or moving items, sort each unsnapped channel's `items` by `freeStart` before `PUT`. An out-of-order array looks fine until the user adds a cross transition: the clip is then snapped against the wrong neighbour and jumps elsewhere on the timeline (e.g. past the end), so it appears to vanish.
 
-**Motion blur (render-only).** Set `"motionBlurEnabled": true` at the `data` root — a project-wide switch, not per layer — to bake cinematic motion blur into full renders. Frames whose motion comes from **keyframed transforms** (incl. camera-layer moves and adjustment-layer pan/zoom) or **speed-ramped video** are rendered as a multi-sample shutter accumulation; still frames are untouched, so cost only grows where motion exists.
+**Motion blur (render-only).** Set `"motionBlurEnabled": true` at the `data` root — a project-wide switch, not per layer — to bake cinematic shutter blur into full renders. The choice is made per output **frame**, not per layer: a frame where motion is detected is rendered as a multi-sample accumulation of the **whole composition** across a shutter window centred on the frame, so every layer that changes inside that window blurs (keyframed layers, text animators, motion layers, transitions, particles), not only the one that triggered it. A frame with no detected motion renders once and stays sharp, so cost only grows where motion exists.
+
+A frame is accumulated when any of these change across its shutter window:
+
+- the camera layer's pose (any camera track), or the frame enters or leaves a camera clip;
+- a keyframed layer's resolved pose: its position, rotation or scale as drawn, from any track that places it (`translateX/Y/Z`, `xPercent`/`yPercent`, `rotate`, `rotateX/Y`, `scale`, `scaleX`/`scaleY`), and a live motion path's `motionPathT`, `motionPathOffsetX/Y/Z` or keyed path shape (adjustment-layer pan/zoom included);
+- the parent of a parented layer, or the tracked point of a `motionFollow` layer;
+- a `video` item with a speed curve (any `speedPoints` value other than 1): every frame of that item, the 1× stretches included;
+- a particle system, or an `html` clip drawn live (the render default): every frame they are on screen;
+- the inner timeline of a `sequence` clip, by the same rules, down to the 4-level nesting limit (parenting and `motionFollow` links inside a sequence are not read).
+
+Nothing else triggers a frame by itself: text animators, MotionFast `motion` layers, 3D model animation, enter/exit and cross transitions, keyed opacity or effect params, and movement inside footage at normal speed. They blur on frames something in the list triggers and are sharp everywhere else.
 
 **Strength** is `"motionBlurShutter"` — a **shutter angle in degrees** alongside `motionBlurEnabled`. Only these four values are meaningful; anything else (missing, non-numeric, an off-table angle) snaps to the nearest level, so `180` is the effective default:
 
@@ -271,7 +297,7 @@ Agent rules: when the user asks for "the project's colours", "brand colours" or
 | `270` | Strong | 24 | ~24× |
 | `360` | Max | 32 | ~32× |
 
-The angle is how much of each frame interval the exposure covers, so wider = more blur *and* proportionally slower. The field is only written when blur is on, so projects that never enabled it round-trip unchanged. Table lives in `frontend/src/components/videoEditor/motionBlurLevels.js`. Honored by **`/render-onserver`**, **`/render-onserver-job`** and the desktop Download/Render — **ignored by the fast `/render`** and never applied in the editor preview (render-only by design). Worth enabling for projects with fast zooms/pans that would otherwise strobe. Motion inside `sequence` clips counts too (a sequence's own camera clip, its layers' keys, speed ramps and live HTML), down to the 4-level nesting limit; parenting links inside a sequence are not read. Renders get proportionally slower on moving segments (~16× per moving frame).
+The angle is how much of each frame interval the exposure covers, so wider = more blur *and* proportionally slower. The field is only written when blur is on, so projects that never enabled it round-trip unchanged. Table lives in `frontend/src/components/videoEditor/motionBlurLevels.js`. Honored by **`/render-onserver`**, **`/render-onserver-job`** and the desktop Download/Render — **ignored by the fast `/render`** and never applied in the editor preview (render-only by design). Worth enabling for projects with fast zooms/pans that would otherwise strobe. Renders get proportionally slower on accumulated frames (~16× each at the default), and a speed-ramped clip, a particle system or a live html clip makes every frame it covers an accumulated one.
 
 **Renderer.** Every project renders on the engine the app is set to — one app-wide setting, not a project field. Read it with `GET /api/video-editor/engine` (`engine`: `"webgl"`, the default, or `"webgpu"`). Preview and the desktop Download use it; the headless renders (`/render-onserver`, `/render-onserver-job`, `/render-still`) take it as the request's `"renderer"` field, which defaults to `"webgl"`, so pass the engine there to render what the editor shows. It matters wherever shading is written by hand rather than picked from a list: an uploaded Advanced Transition package is authored for one engine and is refused on the other, and a **custom** adjustment/layer effect (`"id": "custom"`) cannot run on WebGPU at all — its body is compiled at runtime, so the effect is skipped with a reason. Building a new template or transition: [custom-builds.md](custom-builds.md).
 
@@ -387,6 +413,9 @@ GET  /api/moodboards/{board_id}/video-projects/{project_id}/glvideo?models=<JSON
   project) or to a chat: the GreenLight Motion connector's `open_video` page reads it in the user's browser, and
   `get_video` / `edit_video` change it there.
 
+- The window's **Photo slots** strip writes each picture's `photoSlot` mark into the project (one undo step, saved before
+  the export), and every slot becomes an `image` field of the template (its clip's `url` + `proxyUrl`); the marks travel
+  inside `project.json` with their layers.
 - `template.fields[]` = `{ key, label, type: text|color|image|number|select|toggle, targets: [{ itemId | clipId | (neither = project), path }] }`
   — e.g. `{ "key": "headline", "label": "Headline", "type": "text", "targets": [{ "itemId": "<item id>", "path": "textContent" }] }`,
   a shape colour `path: "shapeFillColor"`, the background `{ "path": "background.solidColor" }`. Omit `template` to keep
@@ -403,7 +432,7 @@ GET  /api/moodboards/{board_id}/video-projects/{project_id}/glvideo?models=<JSON
 
 ### Interface scenes (built-in animated scenes — "the UI kit")
 
-The editor's **Presets** tab also lists the **Interface scenes** library (called GL Motion before 14.0.25): 275 ready-made animated scenes (controls, cards, charts, checkout, coupons, countdowns, galleries…) in one style, all transparent (they sit over the video). Search and category chips filter them; Light / Dark and an accent recolour them. A card's **HTML clip** button inserts the scene as one standalone transparent HTML page, saved into the board's media (`ui-kit/<id>.html`) and placed as an HTML clip (`mediaType: "html"`) at the scene's own length.
+The editor's **Presets** tab also lists the **Interface scenes** library (called GL Motion before 14.0.25): 172 ready-made animated scenes (controls, cards, charts, checkout, coupons, countdowns, galleries…) in one style, all transparent (they sit over the video). Search and category chips filter them; Light / Dark and an accent recolour them. A card's **HTML clip** button inserts the scene as one standalone transparent HTML page, saved into the board's media (`ui-kit/<id>.html`) and placed as an HTML clip (`mediaType: "html"`) at the scene's own length.
 
 For a **whole film** — a story and its shots with the user's copy and pictures, a scenario card on the board, a voice-over, sound design and a render; with a GLEA delivery the film finished in a Video Editor project (a tutorial's interface as HTML scene clips, other films built with the editor's own layers) and rendered from it — use the `motion-film` workflow on the `greenlight` MCP server ([SKILL.md](../SKILL.md#ai-workflows-the-greenlight-mcp-server)) instead of inserting scenes one by one.