@nodetool-ai/agents 0.8.4-a24.2 → 0.8.4

package/dist/_skills/elevenlabs-audio-prompting/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: elevenlabs-audio-prompting
+description: Direct ElevenLabs speech, dialogue, sound effects and music — v3 audio tags and the voice that decides whether they land, stability as the delivery dial, punctuation for pacing, the per-line dialogue list, source-action-space sound-effect briefs, and the music composition plan. Use whenever the model id names an ElevenLabs generation endpoint (fal-ai/elevenlabs/tts/eleven-v3, fal-ai/elevenlabs/tts/multilingual-v2, fal-ai/elevenlabs/text-to-dialogue/eleven-v3, fal-ai/elevenlabs/sound-effects/v2, fal-ai/elevenlabs/music, elevenlabs/text-to-speech-multilingual-v2, elevenlabs/text-to-dialogue-v3, elevenlabs/v2-multilingual, elevenlabs/turbo-v2.5, direct eleven_v3, eleven_multilingual_v2, eleven_turbo_v2_5 and eleven_flash_v2_5) on generate_speech, generate_music, run_node or a TextToSpeech node. Not for Eleven v4, ElevenLabs Music v2 or v2.5, or the transcription, dubbing and isolation endpoints.
+---
+
+# ElevenLabs → direct the read, don't just submit the text
+
+The text is the smallest part of an ElevenLabs request. What decides whether it
+sounds directed is the voice you picked, the stability you set, and the tags
+and punctuation carrying the performance.
+
+Reach speech with `find_model` for `text_to_speech`, then `generate_speech`;
+music with `find_model` for `text_to_music`, then `generate_music`.
+`generate_speech` forwards only the text, the voice and the speed, and
+`generate_music` only the prompt, lyrics and a duration. Stability,
+`language_code`, the dialogue list, `composition_plan`, `force_instrumental` and
+every sound-effect field below exist only on the route's own node:
+`elevenlabs.TextToSpeech` for the direct `eleven_*` models, the fal, kie or
+Replicate node for the others. Find it with `search_nodes`, read its fields with
+`get_node_info`, and run it with `run_node`. Each run is a paid generation, so
+confirm the scope with the user before running several.
+
+## Voice first, then tags
+
+A tag only does what the voice can already do. `[shouts]` on a voice trained on
+soft narration produces a slightly louder narration. Pick a voice whose range
+covers the delivery you want, then direct within it.
+
+- **Emotionally varied** voices take direction across a scene.
+- **Narrow, consistent** voices are right when every line is the same register.
+- **Neutral** voices are the most stable across languages and styles.
+
+## Stability is the delivery dial
+
+The single most consequential setting. ElevenLabs names three points on it.
+The speech routes take any value from 0 to 1 (default 0.5). The dialogue routes
+take only the three named points, and fal's rounds anything else to the
+nearest of them.
+
+| Value | Behaviour | Use for |
+| :--- | :--- | :--- |
+| 0.0 — creative | Most expressive, most responsive to tags, occasional hallucination | Character work, dialogue, anything with `[whispers]` or `[laughs]` |
+| 0.5 — natural | Balanced, closest to the reference recording | Narration, most production reads |
+| 1.0 — robust | Very consistent, largely ignores directional tags | Long documents, repeated renders that must match |
+
+At 1.0 your tags stop working. If a tag is being ignored, check stability
+before rewriting the tag.
+
+## Audio tags
+
+Bracketed, inline, and they act from that point in the line. They are a v3
+feature: on multilingual-v2, turbo and flash there is nothing to act on them,
+and punctuation plus sentence structure are the only direction you have.
+
+- **Delivery**: `[whispers]`, `[shouts]`, `[sarcastic]`, `[curious]`,
+  `[excited]`, `[mischievously]`
+- **Reactions**: `[laughs]`, `[sighs]`, `[crying]`, `[clears throat]`,
+  `[snorts]`
+- **Environment**: `[applause]`, `[clapping]`, `[gunshot]`, `[explosion]`
+- **Experimental**: `[sings]`, `[strong French accent]`
+
+Punctuation carries the rest, and v3 does not support SSML break tags. Ellipses
+are pauses and hesitation, capitals are emphasis, ordinary commas and full
+stops set the rhythm:
+
+> [sighs] It was a VERY long day … nobody listens any more. [quietly] Maybe
+> that's the point.
+
+Give the model a few sentences rather than a fragment. Short isolated lines
+deliver inconsistently because there is no context to read the register from.
+`language_code` forces a language when the text alone is ambiguous.
+
+## Several speakers
+
+The dialogue endpoint takes a list of lines, each with its own text and
+voice, rather than one block of text with names in it. fal calls the list
+`inputs` and kie calls it `dialogue`. The speaker is the entry's voice, never a
+name in the text, because anything bracketed in the text is read as an audio
+tag. Tag each line for its own delivery, and write interruptions as they
+happen:
+
+```json
+[
+  {"text": "[flat] You said you'd call.", "voice": "<Ana's voice id>"},
+  {"text": "[defensive] I did — twice —", "voice": "<Ruben's voice id>"},
+  {"text": "[cutting in] Once. And you hung up.", "voice": "<Ana's voice id>"}
+]
+```
+
+Distinct voices per speaker is what makes it a conversation; the same voice
+twice reads as one person talking to themselves.
+
+## Sound effects
+
+Brief them as source, action and space: what makes the sound, what happens to
+it, and the room it happens in.
+
+> A heavy oak door swinging shut and latching in a stone corridor, long natural
+> reverb tail, close mic on the latch.
+
+- `duration_seconds` runs 0.5–22; leave it unset and the model infers a length
+  from the prompt. Impacts want 1–3 s, beds want 10–20 s.
+- `prompt_influence` defaults to 0.3. Raise it toward 1 to follow the brief
+  closely and lose variation; lower it when you want takes to choose from.
+- `loop` makes the tail blend into the head — the setting for ambience and game
+  audio, and pointless for a one-shot.
+
+## Music
+
+A prompt gets you a track: genre, instrumentation with character, tempo in bpm,
+emotional arc, and what it is for.
+
+> Fast-paced electronic chase cue for a game trailer, driving synth arpeggios,
+> punchy drums, distorted bass, rising tension with abrupt transitions,
+> 130–150 bpm.
+
+When the structure matters more than the vibe, send a `composition_plan`
+instead: an ordered list of sections, each with its own `durationMs`,
+`positiveStyles` and `negativeStyles`. That is what makes an intro stay sparse
+and a drop actually land where you wanted it. `respect_sections_durations`
+enforces those lengths; `music_length_ms` applies only to the prompt path.
+`force_instrumental` asks for no vocal. It defaults to false on fal, so a
+prompt that does not mention vocals may still come back sung, and to true on
+Replicate's `elevenlabs/music`.
+
+The vendor's guide says a prompt naming an artist, a band or copyrighted
+lyrics is rejected, with a rephrasing suggestion in the error. Describe the
+sound instead of the reference.
+
+## Symptoms
+
+| What went wrong | What to change |
+| :--- | :--- |
+| Tags do nothing | Lower stability to 0.5 or 0.0, and check the voice can do that delivery |
+| The read is flat | Add punctuation and a delivery tag; stop relying on the words alone |
+| Pauses are ignored | Use ellipses and line structure — SSML breaks are not supported |
+| Two speakers sound the same | Assign a different voice per dialogue entry |
+| The effect is too variable | Raise `prompt_influence`, and set an explicit duration |
+| A loop clicks | Set `loop` true and regenerate rather than trimming |
+| A song ignores its structure | Move from a prompt to a `composition_plan` |
+| The prompt was refused | Remove artist and band names; describe the sound |
+
+Check the result with `analyze_audio` and `detect_audio_events` rather than
+listening through it, and `transcribe_audio` when you need to prove the words
+landed as written.
+
+## Where it lands
+
+A voice or a bed from here is the "track of your own" build in
+`video-audio-continuity`: it goes on its own audio track and the generated
+clips are muted under it, which is what lets a multi-scene piece keep one
+continuous mix. For a storyboard's script, `voice_script_lines` voices every
+line in one call, each with its own voice, instead of one `generate_speech`
+per line. A bed built from a `composition_plan` has sections of known length,
+which is the grid `beat-sync-editing` cuts to; a sound-effect hit is what
+`logo-reveal` times a sting against. `motion-graphics` carries the timeline ops
+that lay the clip down.
+
+Adapted from the ElevenLabs prompting documentation for Eleven v3, sound
+effects and music:
+https://elevenlabs.io/docs/best-practices/prompting/eleven-v3
+https://elevenlabs.io/docs/overview/capabilities/sound-effects
+https://elevenlabs.io/docs/eleven-api/guides/cookbooks/music.md

package/dist/_skills/explainer-storyboard/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: explainer-storyboard
+description: Turn a confirmed product or feature brief into a shootable 30–120 second explainer storyboard with a consistent entity roster. Use for the beat structure of an explanatory product video, not workflows, pipelines, or finished renders. A narrated explainer whose shots are timed to the voiceover also loads script-video for the script, voice and timing.
+---
+
+# Explainer Storyboard → Storyboard Agent
+
+Create a complete, shootable explainer beat sheet as a NodeTool storyboard. Work directly through the storyboard and entity capability modules. Do not build a workflow or run a pipeline. Do not render stills, clips, or assemble a timeline unless the user asks.
+
+This skill is the explainer's structure. When the voiceover should time the shots, load `script-video` as well: write the VO from this beat sheet into a script, voice it, and let the linked board take each shot's length from its takes.
+
+## Truthful brief
+
+Collect these facts before creating a board: product or feature, brand and traits, category, audience, core problem, shift, 2–4 concrete mechanism steps, proof assets, CTA, runtime (30, 60, 90, or 120 seconds), platform, tone, mandatory content, and forbidden claims. The core problem, shift, and mechanism are required. Never invent a capability, integration, metric, screen, or customer. Write `[CLIENT INPUT NEEDED]` wherever proof is not confirmed.
+
+## Resolve entities before beats
+
+Every recurring person, location, product UI, device, metaphor object, brand mark, and visual style is an entity. Start with `list_entities`; reuse user-provided references and existing entities before generating anything. A real product screenshot is a `prop` reference and must never be regenerated.
+
+Resolve a style entity first. Generate only missing references, applying that style before generating each other entity. A typical 60-second explainer has 4–7 entities: style, persona, optional location, product UI prop, and metaphor prop. Label generated UI as a mock.
+
+Use `create_entity` with a dense visual descriptor. The descriptor specifies the exact recurring appearance: character features and wardrobe; location materials and lighting; UI layout, palette, typography, and content boundaries; metaphor geometry and material; or style medium, palette, lighting, and lens. An entity id is the asset id supplied to `create_entity`.
+
+## Teaching arc
+
+Compute timecodes from the selected runtime, rounded to 0.5 seconds. Use this arc:
+
+| Beat | Runtime share |
+| --- | --- |
+| Problem | 0–15% |
+| Stakes | 15–25% |
+| Shift | 25–40% |
+| Mechanism 1 | 40–55% |
+| Mechanism 2 | 55–68% |
+| Outcome / proof | 68–82% |
+| CTA | 82–93% |
+| Sign-off | 93–100% |
+
+For 30 seconds, combine problem and stakes and use one mechanism beat. For 90–120 seconds, use at most three mechanism beats. Use one concept and one literal metaphor. Put the visual aha at the shift-to-mechanism boundary and leave a deliberate half-beat of silence after it. Voice-over must be at most `runtime × 2.2` words.
+
+## Deliverables
+
+Produce, in order: three concept directions with a recommendation, the full beat sheet, and an entity roster with id, kind, descriptor summary, and referenced beats. Each direction states its entry problem, metaphor, aha, fit, risk, and referenced entities.
+
+For every beat include timecode, teaching job, framing, visual, action, visible entities, verbatim VO, on-screen text of five words or fewer, exact UI/demo input and output or `NONE`, sound, music, transition, and why it teaches. Mechanism beats must show the real UI or a labelled mock. Brand marks wait until the shift. Use verbs in VO and nouns on screen. The sign-off echoes the opening problem.
+
+## Persist the board
+
+Create the storyboard with `create_storyboard({ name, brief, style, aspect_ratio })`. Use `board.storyboard_id`. Put the complete brief, chosen direction, and entity roster into `brief` so the project can be reconstructed later. The exact call shapes and return fields — entity id equals the asset id you passed in, the fifteen `edit_storyboard` ops, what `set_board` accepts, what each prompt receives — are in `storyboard-core` § Tool contract; every board skill builds against that one section.
+
+Attach roster ids with `edit_storyboard({ storyboard_id, ops: [{ op: "set_board", entity_ids }] })` (`set_entities` is only an alias for `set_board`). Resolve the render models in the same op: `find_model` for `text_to_image` and `image_to_video`, each result's `.ref` on `image_model` / `video_model`, and each result's `prompting_skill` loaded before the shot text is written — the still model reads the shot `action` with the camera framing, angle and lens, the scene lighting and the board style appended.
+
+Add one shot per beat with `edit_storyboard` and an `add_shot` op. The dense `action` field names the teaching job, visible entity names in brackets, on-screen text, and UI demonstration. The render attaches a persona or prop entity to a shot only when its name appears in that shot's text (style and location always apply), so every visible entity must be named in `action` or `motion`, or listed on the shot's own `entity_ids`. On-screen text in `action` is a note for the cut: it goes on as a text clip after assembly (`caption-titles`), not into the render prompt.
+
+Stop after the planned board unless the user explicitly requests rendering or a cut. Report the directions, chosen board, and entity roster.
+
+## Render (only on request)
+
+Stills first with `render_storyboard_stills` — they cost less than clips, and you look at every one with `view_image` asking what is wrong, then `score_image_adherence` against the shot text. A persona or UI mock that drifts is fixed at the entity (descriptor or reference), then every shot using it re-renders; a shot that fails on composition is fixed in its `action`. Clips with `render_storyboard_clips`; a clip wrong where its still was right is one `revise_storyboard_clip`. Then `assemble_storyboard_timeline`.
+
+## When the board becomes motion
+
+When a cut is asked for, `timeline-edit-ops` carries the timeline op contract and `motion-graphics` the build loop, which routes to the craft skill for the job: `video-audio-continuity` for whether the beats render as one clip or under a narration track, `caption-titles` for the on-screen text and callouts this beat sheet already specifies, `frame-composition` for where a UI mock sits and whether it survives 9:16, `motion-direction` to hold one motion language across the mechanism beats, and `beat-sync-editing` when the cut has to sit on a music bed. The half-beat of silence after the aha is a hold, not a gap — keep it in the cut.

package/dist/_skills/flux-2-klein-prompting/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: flux-2-klein-prompting
+description: Prompt Black Forest Labs' FLUX.2 [klein] — the subject/environment/style/technical hierarchy it processes in order, guidance-scale and step choices, negative prompts aimed at real failure modes, and the seed-locked one-variable-at-a-time loop its distilled checkpoints make fast enough to run. Which dials exist depends on base versus distilled. Use whenever the model id contains flux-2/klein or flux-2-klein (fal-ai/flux-2/klein/4b, fal-ai/flux-2/klein/9b, their /base, /edit and /lora variants, fal-ai/flux-2/klein/realtime, black-forest-labs/flux-2-klein-4b, black-forest-labs/flux-2-klein-9b) on generate_image, edit_image or a TextToImage node. Not for FLUX.2 pro, flex, max or dev.
+---
+
+# FLUX.2 [klein] → structure first, then iterate fast
+
+klein is the small, fast member of the FLUX.2 family, at 4B or 9B. It ships
+two kinds of checkpoint. The distilled ones (every route without `/base`) run
+in 4 to 8 steps, which fal's guide puts under a second. The `/base` ones run
+28 steps by default and carry the guidance, negative-prompt and acceleration
+dials. The speed is the point of the distilled routes. When a generation takes
+30 seconds, prompt refinement stalls; here you can change one clause and look
+again, so the working method below is worth more than any single prompt.
+
+Reach it with `find_model` for `text_to_image` or `image_to_image`, then
+`generate_image` / `edit_image`. `generate_image` forwards only the prompt, a
+negative prompt, the size and a quality string, and `edit_image` only the
+images, the prompt, a negative prompt, a target size and a strength. Every other
+field below exists only on the route's own node: find it with `search_nodes`,
+read its fields with `get_node_info`, and run it with `run_node`. Each run is a
+paid generation, so confirm the scope with the user before a long loop.
+
+## Prompt hierarchy
+
+klein reads a prompt in this order, and content words (nouns) move the output
+more than modifiers do. Write it in the same order:
+
+1. **Subject** — concrete beats abstract. "A woman in her mid-30s with
+   shoulder-length auburn hair" over "a person".
+2. **Environment** — lighting, atmosphere, spatial relationships. "First light
+   filtering through morning mist" gives rendering cues that "morning scene"
+   does not.
+3. **Style and mood** — direction that guides without overwhelming:
+   "documentary photography", "studio lighting", "cinematic".
+4. **Technical** — composition ("rule of thirds"), depth of field ("shallow
+   focus on the foreground"), palette ("warm earth tones").
+
+> Professional headshot of a male architect in his 40s, salt-and-pepper beard,
+> black-rimmed glasses, charcoal blazer. Modern office background with
+> architectural models visible but softly blurred. Natural window light from
+> the left creating gentle shadows. Corporate photography style, sharp focus on
+> the eyes, neutral grey backdrop.
+
+## Parameters
+
+| Parameter | Where it exists | What it trades | Where to sit |
+| :--- | :--- | :--- | :--- |
+| `guidance_scale` | fal `/base` routes (default 5); Replicate `-base` calls it `guidance` (default 4) | Prompt adherence against creative freedom | 2–4 for artistic interpretation, 5–8 for product photography and technical illustration |
+| `num_inference_steps` | fal only: 4–50 on `/base` (default 28), 4–8 on distilled (default 4), 1–8 on `realtime` | Quality against time | Low while developing a prompt, high for print-ready output |
+| `acceleration` | fal `/base` routes | Detail against throughput | `regular` for production, `high` for maximum speed |
+| `negative_prompt` | fal `/base` routes | See below | Failure modes only |
+| `seed` | every route | Nothing — it removes noise from the comparison | Pin it while testing prompt variations |
+
+On a distilled route the prompt and the seed are the whole instrument, and a
+negative prompt sent through `generate_image` is dropped.
+
+Aspect ratio follows the deployment: landscape for presentations and web,
+portrait for social and mobile, square for profiles and balanced compositions.
+
+## Technique
+
+- **Emphasis is natural language, not weights.** fal's guide says there is no
+  weight syntax. "Prominently featuring", "with particular attention to" and
+  "especially detailed" are how you raise an element's priority.
+- **Negative prompts target failure modes, not quality** (`/base` only). For
+  portraits: "distorted features, unnatural proportions, extra limbs". For
+  landscapes:
+  "oversaturated colours, artificial lighting, lens distortion". A generic
+  quality list buys nothing.
+- **Text renders well when specified.** Give the copy, the font class, the
+  colour, the placement and the capitalisation: "a white coffee mug with the
+  text 'GOOD MORNING' in bold sans-serif black letters, centred on the mug".
+  Copy that belongs to the design, in other words — a title or a super on a
+  still headed for a timeline goes on as a text clip afterwards
+  (`caption-titles`), not into the render.
+- **Multi-reference conditioning is the family's edge.** "The subject from the
+  first image wearing the jacket from the second image, photographed in the
+  environment from the third image."
+
+## The five mistakes
+
+- **Overloaded prompts.** fal's guide says that past roughly 100 words the
+  model starts dropping clauses. Every word should be doing something.
+- **Vague style references.** "Make it look good" is not a direction. "Shot on
+  Hasselblad medium format" or "impressionist painting technique" is.
+- **Missing composition.** Prompts describe the subject thoroughly and never
+  say where it sits. Add "centred composition", "rule of thirds with the
+  subject on the left vertical", or "bird's eye view".
+- **Conflicting instructions.** "Photorealistic portrait" and "watercolour
+  painting style" in one prompt commits to neither.
+- **Neglected lighting.** Lighting is what makes an image dimensional. Always
+  name it: golden hour, studio softbox, rim lighting creating a silhouette.
+
+## The loop klein is for
+
+Start with subject, environment and style. Generate. Pin the seed. Change one
+element — add lighting detail, refine the subject, move the composition — and
+generate again. One variable at a time is what tells you which clause drove
+which change; a distilled route's turnaround is what makes that affordable.
+
+Keep the prompts that worked. A library of formulas per use case, with the
+guidance and step values that suited each, is the output of this loop as much
+as the images are.
+
+Adapted from fal's FLUX.2 [klein] prompt guide:
+https://fal.ai/learn/devs/flux-2-klein-prompt-guide

package/dist/_skills/frame-composition/SKILL.md

@@ -0,0 +1,291 @@
+---
+name: frame-composition
+description: Stage the frame on a NodeTool timeline — grids, focal placement, safe areas per aspect ratio, depth layers and parallax, camera moves, and where elements enter and leave. Use when placing titles, lower thirds, shapes or overlays, when a layout must survive 16:9 and 9:16, when adding a push or a parallax move, or when a frame reads flat or cramped. Not for what a clip says or when it cuts.
+---
+
+# Frame Composition → staging on the timeline
+
+Where things sit, how deep the frame is, and how the camera moves through it.
+`motion-graphics` is the build loop; `timeline-edit-ops` carries the op
+contract. This decides the coordinates you pass either.
+
+## Coordinate spaces, and mixing them is the usual bug
+
+| What | Space | Read as |
+|---|---|---|
+| `shapeStyle.x/y/width/height`, `x2/y2`, `d` | 0..1 of the **frame** | 0.5 is the frame's middle |
+| `set_mask` `x/y/width/height`, `d` | 0..1 of the **layer** | 0.5 is the clip's own middle, not the frame's |
+| `positionX` / `positionY` curves | canvas px | Absolute, and folds as `replace` |
+| `offsetX` / `offsetY` curves | canvas px, added | Composes with everything else |
+| `slide` `distance`, `kenBurns` `driftX/driftY` | fraction of frame width or height | 0.3 travels 30% of the frame |
+| `anchorX` / `anchorY` | 0..1 | The point a scale or a rotation pivots on |
+| `textStyle.fontSizePx` | sequence px | Against `height` from `get_timeline`, not the preview width |
+| `transform.depthPx`, `camera2d.position/depthPx/focalLengthPx` | sequence px | Perspective; clip depth also orders clips within one track |
+| `layout.gap`, `layout.padding` | sequence px | Flex container spacing, measured against its children's rendered boxes |
+
+Read `width`, `height` and `fps` off `get_timeline` before you compute anything.
+A layout authored against 1920×1080 and saved onto a 1080×1920 sequence is off
+by more than a crop.
+
+## Text is placed by containers
+
+Building with `@nodetool-ai/sandbox-timeline` (see `motion-graphics` for when
+code is the right surface)? **A container decides where its children sit —
+you almost never write `x`/`y` for text.** `s.stack(children, o)` and
+`s.row(children, o)` build a real Yoga flex container and reparent
+`children` onto it as its real children — nest freely, a `row` of `stack`s
+or a `stack` holding a nested `row` both resolve correctly. A text child
+reflows to whatever width Yoga offers it, not a guessed line length.
+
+The container's own placement in the frame is `o.at` (`{x, y}`, default the
+frame centre) plus `o.anchor` (default `"center"`): `anchor` names the point
+of the container's own *computed* box that lands at `at` — the name
+`"left"` puts that box's left edge at `at.x`, no measuring a sibling's width
+required. Named anchors: `"top-left"`, `"top"`, `"top-right"`, `"left"`,
+`"center"`, `"right"`, `"bottom-left"`, `"bottom"`, `"bottom-right"`, or pass
+`{x, y}` fractions directly. `o.align` (cross axis, default `"start"`) and
+`o.justify` (main axis, unset) are the Yoga `alignItems`/`justifyContent`.
+A child's own flex sizing is `o.flexItem` on that child's own call (`grow`,
+`width`, `alignSelf`, …); `absolute: true` on a `rect`/`ellipse` (or any
+clip) takes it out of flow and resizes it to fill its flex parent's box
+exactly — how a plate sits behind a card's text with no pixel math.
+
+Reach for explicit `x`/`y` only for decoration (a stray mark, a background
+shape) or a deliberate free placement that has nothing to do with reading
+order. Anything a viewer reads — a title, a kicker, a caption, a row of
+stats — goes in a container.
+
+**Title block** — kicker, title, sub, stacked with a shared rhythm:
+
+```js
+// fragment
+const kicker = s.kicker("LAUNCHING TODAY");
+const title = s.text("Round-ups", { size: 120, weight: 700 });
+const sub = s.text("on every card", { size: 40 });
+s.stack([kicker, title, sub], { gap: 20 });
+```
+
+**Lockup** — a mark beside its wordmark, one row:
+
+```js
+// fragment
+const mark = s.image(logoAssetId);
+const wordmark = s.text("Northwind", { size: 64, weight: 700 });
+s.row([mark, wordmark], { gap: 16, align: "center" });
+```
+
+**Card** — a padded column over an absolute plate:
+
+```js
+// fragment
+const plate = s.rect(1, 1, "#0c2a21", { r: 24, absolute: true });
+const heading = s.text("Plan Pro", { size: 48, weight: 700 });
+const price = s.text("$12/mo", { size: 32 });
+s.stack([plate, heading, price], { gap: 8, padding: 24 });
+```
+
+**List / grid** — a row that wraps into a grid when it runs out of width:
+
+```js
+// fragment
+const chips = ["Round-ups", "Instant transfers", "No fees"].map((t) => s.pill(t));
+s.row(chips, { gap: 12, wrap: true });
+```
+
+## Grid
+
+Twelve columns for landscape, six for vertical. For a 1920-wide frame with a
+100px outer margin and a 24px gutter:
+
+```
+content = 1920 − 2×100 = 1720
+column  = (1720 − 11×24) / 12 = 121.3px
+```
+
+Space everything in multiples of 8. `fontSizePx` for body copy sits near 2.5–4%
+of frame height; below 2.5% `validate_timeline` reports `text_illegible`.
+Choose the family, weights, and title scale from `motion-direction` § Typography
+before placing text on this grid.
+
+## One focal point
+
+Place the subject on a thirds power point, not dead centre, unless the piece
+uses symmetry deliberately. The intersections:
+
+| Sequence | Power points (px) |
+|---|---|
+| 1920×1080 | x 640 / 1280, y 360 / 720 |
+| 1080×1920 | x 360 / 720, y 640 / 1280 |
+| 1080×1080 | x 360 / 720, y 360 / 720 |
+
+Rank the eye's path by **size, then contrast, then colour, then position**. One
+primary per frame; everything else supports. Leave negative space around it —
+a frame filled edge to edge reads as cheap and gives the motion nowhere to go.
+
+## Depth: planes and track order
+
+Split the picture into background, midground and foreground. Track index
+controls order **between** tracks: lowest index draws on top. Within one
+track, clips sort by `transform.depthPx`: farther values draw first and
+nearer, positive values draw later, in front. The same depth controls
+perspective under the sequence's `camera2d`. Moving a clip to another track
+changes its overlap order but not its camera distance.
+
+| Plane | Suggested track index | Clip depth | Motion and look |
+|---|---|---|---|
+| Foreground | lowest | Nearer, positive | The move the eye follows; sharp unless focus shifts |
+| Midground | middle | Around zero | The subject and contrast peak |
+| Background | highest | Farther, negative | Small drift and lower contrast |
+
+For flat parallax, run three speeds over one window. One `kenBurns` per layer
+with `zoom: 0` and a different drift is a `fullClip` preset, so all three
+cover the same span. Put the three on clips of the same length: the drift is
+spread over the clip, so its speed scales with clip length:
+
+```json
+{"role": "loop", "preset": "kenBurns",
+ "params": {"zoom": 0, "driftX": -0.02, "driftY": 0}}
+```
+
+Background −0.02, midground −0.06, foreground −0.12. One layer at one speed is
+not parallax, it is the template moving.
+
+For a shared 2.5D move, give the layers distinct `transform.depthPx` values and
+keyframe the sequence's `camera2d`. Its absolute `timeMs` keyframes interpolate
+camera position and depth linearly. `focusDepthPx` and `aperturePx` control depth of
+field. Use one camera move to connect the planes, then inspect a middle frame
+for unwanted scale or blur. Set track indexes for overlap between tracks and
+clip depth for order within a track.
+
+For a tilted card wall, parent the cards to a group with the wall's 2D
+`rotation`, `rotationX`, and `perspective`. Give each card its own `depthPx`
+and scroll curve, then use `camera2d` for the shared push and depth blur.
+This is a flat card projection: preview the wall at several frames to check
+that spacing, overlap, and blur read as one assembly.
+
+For a move with a shape of its own, write a `custom` curve instead and mind the
+role: an `in` window holds its `t=0` values before it and contributes nothing
+after, an `out` window holds its `t=1` values after it, and a `loop` repeats its
+cycle — so a one-way travel that must stay where it landed is an `out`, and a
+`loop` curve has to return to the value it started on or it jumps every cycle.
+
+Parent the assembly to a group when the layers must hold their relationship
+through a move: `add_group`, then animate the group. Children keep their own
+tracks, so grouping never changes what covers what.
+For a transition on the assembled picture, set `transitionIn` on the group. The
+children stay parented on their own tracks while the transition acts once on
+their precomposed surface.
+
+Shape geometry is rasterized inside a frame-sized source surface before the
+clip is placed. Keep normalized `shapeStyle` geometry inside that surface,
+then move the clip or parent group with `transform.position` or custom
+`offsetX`/`offsetY` curves for scrolling walls and flying cards. Geometry
+authored outside the source surface clips before placement.
+
+## Camera moves
+
+Choose between a sequence camera move and a local clip move. `camera2d`
+keyframes move the view across all depth planes. A layer animation moves one
+clip, and its `anchor` decides where scale or rotation pivots.
+
+| Move | How | Timing |
+|---|---|---|
+| Push / pull | `kenBurns` with `zoom` 0.08–0.2 and `direction` in or out | 1500–4000ms, `easeInOut` |
+| Drift | `kenBurns` `driftX` / `driftY`, ±0.02–0.08 | Same window as the zoom |
+| Pan | `custom` curve on `offsetX` across the clip | 800–2000ms, `easeInOut` |
+| Whip | `offsetX` over 150–250ms with a `blur` effect at 12–24px | On a cut, never mid-shot |
+| Follow | `offsetX` and `offsetY` tracking the subject, subject held off-centre and leading | Whatever the action takes |
+
+`camera2d` is a document field. `set_clip_params` changes a clip's `transform`
+but refuses `camera2d`, `layout`, `repeater`, `motionBlur`, and other new document
+fields. Read the full document with `get_timeline`, change the relevant fields,
+then write the full document with `set_timeline_document`. Keep its tracks,
+clips, markers, tempo, setup, media tracks, template identity, and other fields
+in the write. `timeline-edit-ops` carries the
+op contract.
+
+`kenBurns` is `fullClip`: it ignores `durationMs` and `delayMs` and runs across
+the whole clip. To time a push to something shorter, write it as a `custom`
+`scale` curve instead.
+
+One move per beat. A push plus a pan plus a rotate reads as chaos, and the three
+fold together into a direction nobody chose.
+
+## Enter and exit
+
+Motion that follows reading direction feels natural; reversing it reads as going
+back. Match `slide`'s `direction` to intent — it names the edge the element
+arrives **from**:
+
+- New content: from the right, or from below.
+- Dismissing or undoing: reverse the entrance.
+- Drilling in: `pop`, or a scale curve rather than a travel.
+
+Enter and leave through the nearest edge. Keep `distance` at or below 0.35 or
+the travel reads as a slide of the whole template — pair a longer move with a
+scale or opacity change on the same window. Same vocabulary on the cut:
+`set_transition` `direction` on `wipe`, `push` and `slide` also names the edge
+the incoming clip arrives from.
+
+## Safe areas
+
+Keep titles, logos, faces and calls to action inside the margin. The numbers are
+fractions of the frame, so convert against `width` and `height`.
+
+| Aspect | Top | Bottom | Sides |
+|---|---|---|---|
+| 16:9 | 5% | 5% | 5% |
+| 9:16 | 12–14% | 18–20% | 6% |
+| 1:1 | 7% | 7% | 7% |
+| 4:5 | 8% | 8% | 6% |
+
+On 1080×1920 that leaves the usable band roughly y 250 to y 1570. A caption clip
+already sits at `bottomMarginFrac` 0.12 by default, which is inside the phone UI
+zone on some platforms — raise it rather than assuming.
+
+## One layout, several aspects
+
+Master in the widest target with the focal point inside the centre band, then
+**restack** for vertical: move the headline above the subject, pull the subject
+up out of the bottom UI zone, and raise `fontSizePx` by about 20%. Cropping a
+16:9 layout to 9:16 clips whatever sat in the outer columns, which is usually the
+logo and the call to action.
+
+Building in code, restacking is usually one option change on the container
+above — flip `s.row` to `s.stack` (or its `align`/`justify`), or move it to a
+new `at`/`anchor` — not a rebuild of every child's `x`/`y`.
+
+On the ops path, `layout: {display: "flex", flexDirection: "row" | "column",
+gap}` on a group clip keeps its real children (their `parentId` names the
+group) laid out with ordinary CSS flexbox — `justifyContent`/`alignItems`
+position them, `padding` insets the container. For a shape behind text, give
+the shape `flexItem: {position: "absolute", inset: 0}` inside a padded flex
+column holding the text: the shape's box resizes to the text's padded box,
+including an animated font size, with no manual pixel math. These relations
+avoid redoing pixel math for each text change. A 16:9 document still needs a
+separate placement pass for 9:16, with safe areas checked at that size.
+
+## Check the frame, not the document
+
+`preview_timeline_frame` composites the real picture — every track in order,
+transforms and opacity applied, animations mid-flight. Read the layer list it
+returns beside each frame: it names the stack top first with each layer's
+`z_index`, `opacity` and wipe progress, which answers most staging questions
+without looking at a pixel.
+
+Preview at the midpoint of every move, not at its ends. What frames catch and a
+validator cannot: a title that slid outside the frame, a scrim covering the face
+it was meant to sit beside, a lower third under the wrong element because two
+track indexes are the wrong way round, a layer that never draws because it is on
+an audio track.
+
+## Before you finish
+
+- One focal point, on a power point or deliberately centred.
+- Every element assigned a track for overlap order and a depth plane when the camera moves.
+- One camera move or eased layer move, 800–4000ms.
+- Entrances through the nearest edge, `distance` ≤ 0.35 or paired with a second
+  channel.
+- Critical content inside the safe margin for every target aspect, vertical
+  restacked rather than cropped.
+- Previewed at the midpoints, and the layer stack read.