Skip to Content
Starlight

Scene format

The authoritative reference for Starlight's YAML: the on-disk project layout, project.yaml, and the scene files that describe what every surface in a venue shows. It is written from the parser and serializer that actually read and write these files — src/engine/yaml/{parse,serialize,clock,effects}.ts — and the model schemas in src/engine/model/ and src/engine/clocks/. When this document and a scene disagree, the parser wins; report the drift.

Audience: an artist or engineer authoring scenes by hand, or an agent generating them. Everything here round-trips: parse → serialize → parse is a fixed point (byte-stable up to canonical scalar spellings and dropped auto-ids — see §9).

Sibling docs. Animation detail (clocks, keyframes, easing, cues, triggers) lives in docs/clocks-and-animation.md; the visual editor and DAG in docs/node-graph.md; the layer timeline and span in docs/timeline.md; the two-process engine in docs/architecture.md; the MCP tools and custom effects in docs/mcp-and-extensions.md; export and packaging in docs/export-rendering-and-building.md; the stages: block in docs/stages.md. This file cross-links to them rather than repeating them.


1. A project on disk

A Starlight project is a plain folder the user owns — no database, no bundle. It is discovered by the presence of a project.yaml at its root.

bolts-demo/
  project.yaml            # surfaces + brand kit (§2)
  scenes/                 # one .yaml (or .yml) per scene (§3)
    01-game-open.yaml
    03-touchdown.yaml
  assets/                 # images (png/jpg/svg/webp/gif) + video (mp4/webm/mov/m4v/ogv)
    logo.svg
    scoreboard-loop.mp4
  fonts/                  # brand font files (otf/ttf/woff/woff2), mapped in project.yaml
    Knockout-HTF.otf
  extensions/             # custom effects/layers (see docs/mcp-and-extensions.md)
    manifest.json
  effects/                # effect modules: shader effects as data (see docs/effects.md)
    ripple/effect.json    #   + main.wgsl, main.glsl
  .starlight/             # editor VIEW state — committed, not scene content (see below)
    layout.json
    workspace.json
  context/                # Claude session logs + the artist brief (docs/project-memory.md) — versioned
  .gitignore              # ignores renders/ and generations/ (regenerated or per-machine, never versioned)
  renders/                # export output — gitignored, regenerated on demand; in a shared project it syncs to everyone (docs/shared-projects.md §2a)
  generations/            # AI generation outputs + generation.json — gitignored (docs/project-memory.md)

Where to keep projects

Keep projects on local disk (e.g. ~/Documents/Starlight/), not inside a cloud-synced mount — ~/Library/CloudStorage/… (Dropbox, OneDrive, Google Drive, Box), iCloud Drive (~/Library/Mobile Documents/), ~/Dropbox, or a Windows OneDrive folder. Those providers offload files to dataless placeholders; touching one stalls until it downloads, which can freeze saving, versioning (git), and opening. Starlight times out its own housekeeping and shows a one-time warning when it opens such a project. To share a project, push its git repo to a remote, export renders, or copy the folder.

How a project is discovered and opened

Source: src/main/project.ts.

  • Bundled demo → working copy. On first launch the app copies the bundled demo-project/ to ~/Documents/Starlight/bolts-demo, runs git init, and opens that copy henceforth (ensureDefaultProject). Keeping the working copy outside the app's own repo makes every project a real folder with its own version history.
  • A folder is a project when it contains project.yaml. readProject reads the project YAML, every scenes/*.{yaml,yml} (in the scene order: project.yaml's sceneOrder:, else by name — readdir order is OS-dependent), lists assets/ as starlight-asset:// URLs (stat only — the bytes stream over a Range-capable protocol; see docs/assets.md) and inlines fonts/ as data URLs (the renderer never touches the filesystem; see docs/architecture.md).
  • Which scene opens first — the scene that was last open in this project (lastScene in .starlight/workspace.json, written on every scene open), while it still exists; otherwise project.yaml's defaultScene, when it names an existing scene; otherwise the first scene in the scene order (pickOpenScene / pickDefaultScene in model/project.ts — a deleted or renamed remembered scene falls back quietly). The MCP get_project reports the same choice as openScene. This is why the demo scenes are numbered 01-…, 03-….
  • Every save is a git checkpoint. ⌘S (and each MCP write_scene) writes the file(s) and git commits them; restore_checkpoint <hash> / in-app undo rolls back. See docs/mcp-and-extensions.md and docs/export-rendering-and-building.md.

.starlight/ — editor view state, not content

.starlight/layout.json (canvas placement) and .starlight/workspace.json (panel layout, per-scene graph pan/zoom, the last-open scene) are view state: they ride the next checkpoint (they are not gitignored) but are never part of the rendered scene. (A surface move and a guide edit are undoable in the editor; see docs/architecture.md.) layout.json maps each surface to its place, { "N": { "x": 0, "y": 0, "guides": { "x": [960], "y": [540] } } }: guides is optional, the surface's guides in its own pixels (x the vertical ones, y the horizontal ones; help #canvas-rulers), and absent when the surface has none. What you arrange in the graph is not view state: node moves, node colours and sticky notes are scene content (§3). A corrupt workspace file is ignored with one console warning and falls back to defaults.

Schema versioning

Both project.yaml and every scene carry schemaVersion (a positive integer). A scene that omits it reads as v3 (BASE_SCHEMA_VERSION); the serializer always writes it back, raising it only when the scene uses something newer. It exists so a reader can migrate older documents — and refuse newer ones: a scene above CURRENT_SCHEMA_VERSION fails with this scene is schemaVersion N, written by a newer Starlight — this build reads up to 18; update Starlight to open it rather than being half-read.

DocumentCurrentHistory
scene18 (CURRENT_SCHEMA_VERSION, model/scene.ts)1 the original format. 2 the matte composite node (§4), which replaces v1's mask: { source } field: a v1 mask: is still read and migrated into a matte node at parse (masks.md §7), so the next save writes v2. A scene that holds a matte node is v2 whatever it claims; a v1 scene with no masks keeps its 1 (an older Starlight can still open it). 3 an effect with no clock: of its own keys its animated params on its host node's clock (v1/v2: the scene loop) — §8. A v1/v2 effect whose reading would change (animated params, no clock:, on a node whose clock sets a period, mode or use:) is pinned at parse with clock: { mode: loop }, which is lossless (period absent = the scene loop, still following a loop change); a scene holding a clockless animated effect on such a node is written as v3, else it keeps its version. 4 a gradient's attributes can be keyframe lists, and a radial gradient carries center / radius (§4). A v3 reader would misread them (an angle list as NaN; centre and radius ignored), so a scene that uses any of it is v4 whatever it claims (raised at parse, like a matte) and is written as v4 (gradientSchemaVersion); every other scene keeps its version. Nothing older migrates: no v1–v3 scene can hold these shapes. 5 a video can carry an offset: (§4), the layer timeline's slip. A v4 reader would play the clip unshifted, so a scene with one is v5 whatever it claims and is written as v5 (videoOffsetSchemaVersion); every other scene keeps its version. Nothing older migrates. 6 an extension's node type, written node: <kind> (§4). A v5 reader knows no node: keyword, so a scene with one is v6 whatever it claims and is written as v6 (extensionNodeSchemaVersion); every other scene keeps its version. Nothing older migrates: before v6 such a node saved as null and could not be read back. 7 a node, or a surface binding's use: comp, can carry a delay: (§4): it and everything in it run later. A v6 reader would play it on time, so a scene with one is v7 whatever it claims and is written as v7 (delaySchemaVersion, model/delay.ts); every other scene keeps its version. Nothing older migrates: no v1–v6 scene holds one. 8 a comp can have a frame, written name: { size, children } instead of a node list (§3). A v7 reader expects a list there, so a scene with a framed comp is v8 whatever it claims and is written as v8 (compFrameSchemaVersion, model/comp-frame.ts); every other scene keeps its version. Nothing older migrates: no v1–v7 scene holds one. 9 a video can carry a trim: [in, out] (§4): a piece of the source, locked to the scene loop, on its own decoder. A v8 reader would play the whole clip on the transport, so a scene with one is v9 whatever it claims and is written as v9 (videoTrimSchemaVersion, model/video.ts); every other scene keeps its version. Nothing older migrates: no v1–v8 scene holds one. 10 a surface's tile plan can give each seam its own crossfade width (feather: [1024, 600]), carry the tiles' loop: and the seam check's match: (§3). A v9 reader refuses these keys in a plan, so a scene that uses any is v10 whatever it claims and is written as v10 (tilePlanSchemaVersion, model/tile-plan.ts); every other scene keeps its version. Nothing older migrates: no v1–v9 plan holds them. A bypassed comp (name: { children, bypass: true }, §3) is v10 too, for the same reason: a v9 reader refuses the key on a comp map (compBypassSchemaVersion, model/bypass.ts). 11 a video can name a version of its clip, version: denoise-41c0e9aa (§4, assets.md §10). A v10 reader would draw the original clip. For a clean-up or a new look, that is a different picture, so it would be a misread. So a scene with one is v11 whatever it claims and is written as v11 (versionSchemaVersion, model/video.ts); every other scene keeps its version. An older Starlight refuses a v11 scene and asks you to update; it never shows the original by mistake. Nothing older migrates: no v1–v10 scene holds one. 12 a clock track can be per-frame samples, x: { fps: 29.97, start: 187, values: [..] } (§8, clocks-and-animation.md §5). A v11 reader expects a key list there and refuses the scene with an error about the list, so a scene that writes a track as samples is v12 whatever it claims and is written as v12 (sampledTrackSchemaVersion, model/sampled-tracks.ts); a track that was samples but is now ordinary keys raises nothing. Every other scene keeps its version. Nothing older migrates. 18 matte sources (masks.md §8): a matte node can carry range: [low, high] (near / far on a depth matte, §4), and a video can name a matte version, version: depth-1a2b3c4d (a person, depth or roto mask of its clip that a matte node cuts with, §4). A v15 reader keeps range as an unknown key and cuts by the whole matte, and where the mask file is missing it would cut by the clip's own picture (a version falls back to its original there), both a different picture, so a scene with either is v18 whatever it claims and is written as v18 (matteSourcesSchemaVersion, model/matte.ts); every other scene keeps its version. Nothing older migrates: no v1–v17 scene holds one. The prerender: key (§4) needs no new version: it is a cache, not content. When the app saves it keeps the file's version and raises it only when the scene needs a newer one (it never lowers it); YAML written through MCP is stored as given, so write schemaVersion: 4 (an animated gradient), 5 (a video offset), 6 (a node:), 7 (a delay), 8 (a framed comp), 9 (a video trim), 10 (a tile plan's feather list, loop or match, or a bypassed comp), 11 (a video version:) or 12 (a per-frame track) yourself (write_comp and write_node save the scene in the app's own form, which sets it). 13 a text can lay out its lines: wrap, lineHeight, maxLines with overflow, anchorY: baseline and markup (§4). A v12 reader keeps them as unknown keys and draws one long line at the top of its box, a different picture, so a scene with any of them is v13 whatever it claims and is written as v13 (textLayoutSchemaVersion, model/text-layout.ts); every other scene keeps its version, and a text without them draws exactly as before. Nothing older migrates: no v1–v12 scene holds one. 14 a text can have an outline: stroke (a colour or a keyframe list), strokeWidth and fill: none for a hollow word (§4). A v13 reader keeps stroke and strokeWidth as unknown keys and draws no outline, a different picture, and refuses fill: none with a colour error, so a scene with any of them is v14 whatever it claims and is written as v14 (textStrokeSchemaVersion, model/text-stroke.ts); every other scene keeps its version (a v13 scene stays v13), and a text without them draws exactly as before. Nothing older migrates: no v1–v13 scene holds one. 15 a text can animate its letters one after another: letters: { by, stagger, order, clock } (§4). A v14 reader keeps letters as an unknown key and draws the word still, a different picture, so a scene with one is v15 whatever it claims and is written as v15 (textLettersSchemaVersion, model/text-letters.ts); every other scene keeps its version (a v14 scene stays v14), and a text without it draws exactly as before. Nothing older migrates: no v1–v14 scene holds one. 16 a shape or a path can trim its stroke, After Effects' Trim Paths: trimStart, trimEnd and trimOffset, each a value or a keyframe list (§4). A v15 reader keeps them as unknown keys and draws the whole stroke, a different picture, so a scene whose trim changes the picture is v16 whatever it claims and is written as v16 (trimSchemaVersion, usesTrim in model/trim-path.ts): the node draws a stroke, and its trimStart or trimEnd is a keyframe list whose keys differ, or its still values do not span the whole outline. Every other scene keeps its version (a v15 scene stays v15): an offset alone, a whole lap (0 → 1, or 1 → 0), trimEnd: 1 written out at its default, or a trim on a node that draws no stroke draws exactly what an older Starlight draws, and a shape without a trim draws exactly as before. Nothing older migrates: no v1–v15 scene holds one. 17 a particles node, a particle system (§4). A v15 reader knows no particles: keyword and would refuse the scene with expected a node keyword, so a scene with one is v17 whatever it claims and is written as v17 (particlesSchemaVersion, model/particles.ts); every other scene keeps its version. Nothing older migrates: no v1–v16 scene holds one. The prerender: key (§4) needs no new version: it is a cache, not content. When the app saves it keeps the file's version and raises it only when the scene needs a newer one (it never lowers it); YAML written through MCP is stored as given, so write schemaVersion: 4 (an animated gradient), 5 (a video offset), 6 (a node:), 7 (a delay), 8 (a framed comp), 9 (a video trim), 10 (a tile plan's feather list, loop or match, or a bypassed comp), 11 (a video version:), 13 (a text's wrap, lineHeight, maxLines, overflow, anchorY or markup), 14 (a text's stroke, strokeWidth or fill: none), 15 (a text's letters), 16 (a shape's or a path's trimStart, trimEnd or trimOffset), 17 (a particles node) or 18 (a matte range, or a video naming a matte version) yourself.
project.yaml1 (PROJECT_SCHEMA_VERSION, model/project.ts)Unchanged since 1.

2. project.yaml

Declares the venue's canonical surfaces (every physical board, named once) and the brand kit (design tokens + fonts). Parsed by parseProject (yaml/parse.ts), validated by ProjectSchema (model/project.ts).

FieldTypeDefaultMeaning
schemaVersioninteger > 01Document schema version (§1); the project format is still 1.
projectstring (non-empty)— requiredProject name (the project: key).
surfacesmap: name → { size, fit? }{}Every surface in the building.
brand.thememap: token → value{}Design tokens ($team.gold → #FFB81C).
brand.fontsmap: family → file path{}Font family name → project-relative file.
assetsstringassetsParsed into assetsDir and written back, but not used: the app always reads and writes assets/ (main/asset-list.ts, main/project.ts), so another value has no effect.
defaultScenestring—Scene basename to open on launch when no last-open scene is remembered (falls back to the first scene in the scene order).
sceneOrderlist of scene basenames— (name order)The scene order (help #scenes-order): the scene list, ⌘PageDown / ⌘PageUp, the palette, the reel and the MCP scene lists. Listed scenes first, in this order; every other scene after them, by name; a name that is not a scene is skipped. The scene list's drag, ⌥↑ / ⌥↓ and move up / down write it, one atomic edit of this key alone (src/shared/scene-order.ts) and one version per burst of moves; a rename, a duplicate (right after its scene) and a delete keep it right. An older Starlight keeps it untouched and lists by name.
idstring (non-empty)—Optional stable project id; never written automatically, and it outlives a rename of project:.
exportmap—Delivery settings: naming (template; default {scene}_{surface}_{w}x{h}_{fps}fps_{codec}, tokens {project} {scene} {surface} {w} {h} {fps} {format} {codec}), formats, fps, aliases (surface → pixel-map name) — export-rendering-and-building.md.
roommap—The Glimpse panel's venueUrl, feedWidth (512, 1024 or 2048) and feedFps (15, 30 or scene; default 30: how often the room takes a new frame and draws, at most) — previz-panel.md.
mediamap: root name → folder—Linked media folders; scenes reference media:<root>/<path> — assets.md.
sharedboolean—Shared-project mode: omitted, a project in a cloud-synced folder is shared; false opts out, true forces it — shared-projects.md.

Unknown top-level keys are preserved on the project's unknown bag (§10).

surfaces

Each surface is { size, fit? }. size is the surface's output resolution — the pixels Starlight renders for it (on an LED wall, its pixel map). It is required (WxH, e.g. 1920x1080, both sides > 0); a surface without a size is a ParseError (surfaces.<name>.size — expected WxH), and so is a zero or negative one. fit is optional and is the default fit a scene uses for that surface unless the scene's binding overrides it (§7).

surfaces:
  jumbotron:   { size: 1920x1080 }              # fit defaults to none
  ribbon-main: { size: 10080x84, fit: tile-x }  # a long, short ribbon
  vomitory:    { size: 384x640,  fit: cover }   # a portrait tunnel board

brand — the brand kit

brand.theme holds design tokens. Keys may be dotted (team.gold) or nested maps (team: { gold: … }) — both resolve identically (§6). Values are usually #hex colours but can be any scalar or a $token that chains to another token.

brand.fonts maps a family name (used in scene text via font:) to a file under fonts/ (fonts/<file>, subfolders allowed; .otf/.ttf/.woff/.woff2). Only fonts/ is read into the payload, so a path anywhere else never loads. The renderer loads each via the FontFace API before the first build, and again on every project load (an open, a switch, Reload Project from Disk): new or changed files load, and families no longer declared are removed (planFontLoad in brand-fonts.ts, loadFontFamilies in CanvasStage); a replaced face clears Pixi's text-metrics cache. A missing file is skipped gracefully — text falls back to a heavy-condensed system stack — so a scene never breaks for a font the repo can't ship. The in-app font-row refresh also auto-discovers font files directly in fonts/ (not subfolders) and names each by its filename (lower-cased, spaces/underscores → -, -2 on a clash), writing project.yaml and a rescan fonts (+N) checkpoint.

schemaVersion: 1
project: bolts-demo
defaultScene: 01-game-open

surfaces:
  jumbotron:   { size: 1920x1080 }
  ribbon-main: { size: 10080x84, fit: tile-x }
  vomitory:    { size: 384x640,  fit: cover }

brand:
  theme:
    team.gold:     "#FFB81C"   # dotted keys …
    team.navy:     "#0B162A"
    team.electric: "#2BD9FF"
    ink.white:     "#F4F7FB"
    wash.gold-0:   "#FFB81C00" # 8-digit hex → RGBA (fully transparent gold)
  fonts:
    knockout-heavy: fonts/Knockout-HTF.otf

assets: assets

brand.theme and brand.fonts always serialize (as {} when empty); this is intrinsic to the model, not something you must author.

Weights and styles of a brand font: one key per file

A family such as Inter comes as one file per weight and style. In brand.fonts each file is its own key, and the key is what a text names. The MCP tool list_fonts (mcp-and-extensions.md §3) shows every key with the weight (100–900) and style read from the file itself, so nobody has to guess which file is which.

brand:
  fonts:
    inter-regular: fonts/Inter-Regular.otf        # Regular, 400
    inter-italic: fonts/Inter-Italic.otf          # Italic, 400
    inter-bold: fonts/Inter-Bold.otf              # Bold, 700
    inter-bolditalic: fonts/Inter-BoldItalic.otf  # Bold Italic, 700 (the key ↻ gives this file)

How a text picks a weight or italic:

  1. Write the key of the file in font:. font: inter-bold draws Inter Bold. The menu name works too: font: Inter Bold finds inter-bold (resolveFontChoice).
  2. Leave weight: out of a text in a brand font. Each file is loaded as a family of its own at one weight (a FontFace with no weight, engine/compositor/assets.ts). So weight: 600 or more makes the browser thicken the file (a fake bold), even when the file is the Bold, and a weight under 600 changes nothing.
  3. For a weight that has no file (SemiBold, say), add the file (below). Do not fake it.

Add a weight or a style:

  1. Put the file in the project's fonts/ folder: drop it on the Starlight window, or copy it in.
  2. A dropped file is added to brand.fonts at once. For a file you copied in, click ↻ beside the font field. The key is the file name in lower case, with a dash for each run of spaces or underscores (Inter-SemiBold.otf → inter-semibold, -2 when the key is taken; rescanFonts). list_fonts shows this key as addsAs before you click.
  3. Write font: inter-semibold in the text.

Italic and bold inside one text (markup: true, §4 text) draw each style from its own file. Starlight finds the file by what the font files say (their family, weight and italic flag), not by the key names. For a text in a family at a weight:

  • *italic*: the same family's italic file, at the nearest weight;
  • **bold**: the same family's Bold (700), else the nearest heavier file (600 or more, never lighter than the text);
  • ***bold italic***: the same family's italic file at that bold weight.

So any key name works: graphik-regularitalic (Graphik-RegularItalic.otf), gotham-bookitalic, minionpro-it, helveticaneueltstd-bdit. A Medium text's **bold** is the Bold, and font: Inter-Regular (other capitals) finds the same files as inter-regular. Starlight reads the files once, when the project's fonts load or change (engine/model/font-styles.ts). A file it cannot read is found by its key name instead: <stem>-italic, <stem>-bold, <stem>-bold-italic, where <stem> is the text's key without -regular.

When a file is not there:

  • A key whose file is missing draws with the fallback fonts (below), and so does a key whose path is outside fonts/ or spelled with other capital letters than the file.
  • A style a markup text uses with no file draws upright or at the regular weight, and the text's properties say which file to add. Starlight never slants or thickens a brand file for markup.
  • A variable font (one file with every weight, wght 100–900) draws one weight. For several weights, use one static file per weight.
  • An online-only file (Dropbox) loads in the app once Dropbox has downloaded it. list_fonts reports it and never downloads it, so it cannot say that file's weight and style.

3. The scene file

A scene names a loop, a design resolution, optional token overrides and named clocks, shared comps, and per-surface surfaces bindings. Parsed by parseScene, validated by SceneSchema (model/scene.ts).

FieldTypeDefaultMeaning
schemaVersioninteger > 03 (BASE_SCHEMA_VERSION; the current version is 10)Document schema version (§1).
scenestring (non-empty)— requiredScene name.
loopduration—Loop period, e.g. 4s. Absent → clocks fall back per-node. Keys are phases, so editing loop: by hand stretches every key on a clock that follows the loop. The app's duration field keeps the key times instead, or stretches everything in ms with them when asked (clocks-and-animation.md §3).
fpsnumber, 0 < fps ≤ 24030 at runtimeFrame rate for stepping + export encoding.
designsize1920x1080The artboard: the canvas the shared comps are authored on. Each surface's fit scales it into that surface's output resolution.
thememap: alias → value—Scene-local token overrides; chain to the brand kit.
clocksmap: name → named clock—Shared timing sources (docs/clocks-and-animation.md).
cuesmap: cue name → phase 0..1—Cue points on the scene clock (the loop).
markerslist of markers—Timeline markers at scene time (below). Never rendered.
compsmap: name → node list{}Shared branches, instanced by surfaces.
surfacesmap: name → binding{}What each surface shows.
graphLayoutmap: graph key → offset—Node-graph moves (below). Never rendered.
graphColorsmap: graph key → colour name—Node-graph organising colours. Never rendered.
graphNoteslist of notes—Node-graph sticky notes. Never rendered.
stagesmap: stage id → stage—3D shot blocking for AI generation (below). Never rendered.

loop, fps, design, theme, clocks, and cues are omitted from the serialized output when unset, and markers, graphLayout, graphColors and graphNotes when empty, so a minimal scene round-trips clean. Unknown top-level keys land on the scene unknown bag (stages rides it today, so it is written at the end of the file).

scene: 01-game-open
loop: 4s
design: 1920x1080          # the artboard: comps authored at 1920×1080, fit into each surface
theme:                      # scene aliases → brand tokens (resolved at render)
  primary:  $team.gold
  base:     $team.navy
  electric: $team.electric

comps:
  main:                     # a shared branch — file order = draw order (top drawn first / lowest)
    - transform:
        - gradient: radial
          stops: [ { offset: 0, color: $base }, { offset: 1, color: $base } ]
          size: 2600x1700
      position: { x: 960, y: 540 }

surfaces:
  jumbotron:   { size: 1920x1080, use: main }
  ribbon-main: { size: 10080x84,  use: band, fit: tile-x, design: 1920x84 }
  vomitory:    { size: 384x640,   use: portrait, fit: cover, design: 384x640 }

comps — shared branches

comps is a map of comp name → node list. A comp is a reusable branch: a surface instances one with use:, and a clone or use node can instance one by name (§4). File order within a comp is draw order — the first item draws first (lowest / furthest back), the last draws on top.

Framed comps — a comp with a size

A comp can have a frame (scene format v8, model/comp-frame.ts), like an After Effects comp. It is then written as a map instead of a list:

comps:
  hero:                     # framed: a 2520×1080 box (21:9)
    size: 2520x1080
    children:
      - transform:
          - image: assets/plates/skyline.png
        position: { x: -400, y: 0 }
  main:                     # unframed: a plain list, as always
    - transform:
        - use: hero         # the holder transform places (and scales) the box
      position: { x: 3200, y: 800 }   # the frame's centre lands here: its top-left is at (1940, 260)
      anchor: { x: 1260, y: 540 }     # the frame's centre: the holder turns around its middle
FieldTypeNotes
sizeWxH, whole px, 1–16384 a siderequired in the map form unless bypass is given. A missing size, a size that is not whole pixels, or any key other than size / children / bypass is a parse error at comps.<name>.….
childrennode listThe comp's nodes, exactly what an unframed comp's list holds. Omitted = empty.
bypasstrue / falseA bypassed comp (scene format v10, model/bypass.ts): it draws nothing wherever it is used — every use: of it, every clone of it, every surface bound to it (that surface's inline children still draw). Written only when true: name: { children: [...], bypass: true }, a framed one { size, children, bypass: true }; switched off, the comp goes back to its list (or { size, children }) form. A scene with a bypassed comp is v10 (compBypassSchemaVersion); a v9 reader refuses the key. In-app: b, or the bypass switch, on the comp's root node.
  • The crop. A framed comp draws only (0, 0, w, h) of its own px, wherever it is drawn: at a use: (the holder transform places and scales the box), in each copy of a clone of it (the copy's cell is the frame), and on a surface bound to it with use: (the box sits at the surface's design origin; design and fit work as before). The viewer crops the same way. An unframed comp is unbounded, as before.
  • Node ids do not change. The nodes keep the plain comp path (comp/<name>/<i>), so framing or unframing a comp keeps every auto id, and an unframed comp is written as before.
  • Presets (compFramePresets): Seedance's own output sizes — 16:9 1920x1080, 21:9 2206x946, 4:3 1664x1248, 1:1 1440x1440, 3:4 1248x1664, 9:16 1080x1920 (the 1080p tier of Seedance 1.5 / 2.0 / 2.5), and 16:9-4k 3840x2160, 21:9-4k 4398x1886 (Seedance 2.0 Pro 4K). These are ByteDance's own output sizes (BytePlus ModelArk API reference); ByteDance offers no 9:21 — and each project surface's size. A frame of exactly the size the model makes is an input it does not resample or re-crop.
  • Pre-comp (precompNodes, the app's Pre-comp…, MCP precomp) moves sibling layers into a new framed comp and leaves ONE transform: [ - use: <comp> ] holder in their place that puts the frame's top-left on its origin; the layers shift by −origin inside the comp, so nothing moves on screen. Like every new layer, the holder turns around its centre: its anchor is the frame's centre (w/2, h/2) and its position is origin + that anchor. A moved layer with no transform of its own gets a wrapper that only does the shift, and no anchor (it had none). New Comp… (createFramedCompUse) writes its holder the same way. Set Comp Frame (setCompFrame, MCP set_comp_frame) adds, changes or removes a frame without moving the content. Renaming a comp keeps its frame.
  • Generate from this comp (MCP render_comp_still) renders the frame at its pixel size (a one-surface scene bound to the comp at size = design = frame) and stores the PNG as assets/comps/<scene>/<comp>-<hash8>.png, with a sidecar in assets/.comps/. For Seedance 2.0, which makes six shapes only, the app grows the frame to the nearest shape first and renders that bigger box, the comp's layers past the frame included (generation.md §12). When the clip lands, the app adds it to the comp as an ordinary transform: [ - video: … ] on top, scaled to that box, so the frame crops the added band: no new format.
  • Scale to Fit inside a framed comp fits the frame: fitTargets (model/fit-layer.ts) returns the frame as the one target (kind: 'comp') for a layer in a framed comp, through compFrameOf(scene, comp), so the app and MCP fit_layer never ask which surface.

surfaces — per-surface bindings

A scene's surfaces map binds content onto the project's surfaces by name. Each binding is { size?, fit?, design?, use?, delay?, children?, tiles?, prerender? } (SurfaceBinding).

FieldTypeDefaultMeaning
sizesizeproject surface's sizeThe output resolution for this scene: the pixels rendered. Overrides the project's.
fitfit modeproject surface's fit / noneHow the artboard maps into the output resolution (§7).
designsizescene design (1920×1080)This surface's own artboard: the canvas its content is laid out on.
usecomp name (non-empty)— (unbound)Comp to instance at the surface root — the comp that feeds this surface, re-routable in the node graph. Must name a comp in comps (unknown comp "<x>" — valid comps: …).
delayduration (may be negative)— (on time)Runs the use: comp this much later on this surface — the surface-to-surface chase: one comp on five surfaces, each a little later. The comp's whole timeline turns: its keys, its effects and its layers' spans. The surface's own children keep scene time. Scene format v7; serialized only when set (§4).
childrennode list—Extra nodes drawn at the surface root, on top of use.
tilesmap—The surface's tile plan for AI video (below). Editor metadata: never rendered.
prerendertrue, or { alpha: auto | on | off }— (drawn live)Play the whole surface's content from a file rendered on this computer (§4). A cache: no new scene version.

Both use and children may be present — the comp draws, then the inline children draw over it. Neither is required: a binding without use is an unbound surface — N: {} is valid, round-trips, validates and exports; the surface renders its inline children, or black when it has none. One comp may feed any number of surfaces. Re-routing a surface (the node graph's feed wires, or a write_scene) changes only use: the surface's size, fit, design and children stay. Surface children are ordinary design-space nodes and are fit into the surface just like a comp, so a child that needs positioning must be wrapped in a transform (§4).

One rule: a scene can only use the surfaces project.yaml declares. A binding for another name (an unknown surface, e.g. main-4k beside a project that has only main) parses, round-trips and shows in the node graph, so the artist can rewire or remove it (its Properties sheet notes not in project.yaml — not shown, rendered or exported). Nothing else treats it as a surface: the canvas and exports build only project.yaml's surfaces, its clips never decode, render_still / render_surfaces refuse or leave it out, Glimpse publishes only project surfaces, and the thumbnails, Tile Plan, pre-render, Scale to Fit and the effect preview never pick it. The canvas warns once per scene (This scene uses a surface named main-4k, but the project has no surface with that name. It is not shown or exported. …), and an MCP write_scene / create_scene saves it with a warnings line that lists the project's surfaces. The rule is wallsNotInProject (model/focus.ts); the words are src/shared/unknown-walls.ts.

To add a surface, add it under surfaces: in project.yaml (a name and its size, §2) and choose File › Reload Project from Disk (a shared project reloads by itself). No button and no MCP tool adds one.

Output resolution vs artboard. The two sizes do different jobs, and the Properties sheet names them by that job (the YAML keys stay size and design): the output resolution (size) is what renders, the artboard (design) is what you lay content out on, and fit scales the artboard into the output. Selecting a surface shows one row each: the output resolution as W × H (marked overridden, with the project's value and a reset, only when this scene's size differs from project.yaml's), the fit (its inherited value reads none (project)), and the artboard, folded to same as output when the two match. Every edit is the scene binding; project.yaml is never written from the sheet.

The per-surface design is the ribbon pattern. The scene design is jumbotron-native (1920×1080). A ribbon is 10080×84 — fitting a 1080-tall comp down to 84px is a ~13× crush that makes marks illegible. Instead, author a band-native comp and give the ribbon its own design: 1920x84, so tile-x scales it 1:1 and repeats honest tiles:

comps:
  band:                                # authored at true 84px ribbon height
    - clone: { of: assets/bolt-rib.svg, count: 6, gap: 480, direction: x, drift: -240px/s }
surfaces:
  ribbon-main: { size: 10080x84, use: band, fit: tile-x, design: 1920x84 }

Fit computation and how surfaces render across the multi-surface canvas are detailed in docs/export-rendering-and-building.md.

tiles — a surface's tile plan

Tile Plan (help "Tile a surface for AI video") cuts a surface into zones, one AI video generation each, at a Seedance output shape. The plan rides the surface's binding. It is editor metadata like markers: nothing renders it, an older Starlight keeps it as an unknown key, and a surface without one writes no tiles: line, so older scenes read and write byte for byte as before. A plan needs no new schemaVersion, except that a feather list (one width per seam), a loop or a seam check's match makes the scene v10: Starlight 0.2.12 and 0.2.13 read plans but refuse those keys, so v10 makes them say "update Starlight" instead (tilePlanSchemaVersion, model/tile-plan.ts).

surfaces:
  N:
    design: 6400x1600
    fit: none
    children: [ … ]                 # the artist's layers; never removed
    tiles:
      model: seedance-2.5-pro       # seedance-2.5-pro | seedance-2.0-pro | videorouter-seedance-2.5
      tier: 1080p                   # 1080p, or 4k (seedance-2.0-pro only)
      shape: 21:9                   # 21:9 (2206x946, 4K 4398x1886) or 16:9 (1920x1080, 4K 3840x2160)
      overlap: 20%                  # the least overlap asked for (0.2 also reads)
      zones: [0, 2669]              # each zone's left edge, in the surface's native px
      seams: [3200]                 # optional: each crossfade's centre (default: mid-overlap)
      feather: 1024                 # optional: the crossfade width (default: the overlap, at most 1024),
                                    #   or one per seam: [1024, 600] (v10)
      batch: b5k2m9                 # set by Generate tiles
      videos: [assets/tiles/01-panorama/N/b5k2m9-tile-01.mp4, null]   # set by Assemble
      video: 2206x946               # optional: the clips' real px when not the shape's
      loop:                         # optional (v10): every tile made into the same loop
        clip: 4041.667ms            #   the length every tile is cut as (the shortest clip)
        overlap: 1s                 #   optional: Make Loop's settings, its defaults when absent
        dissolve: noise             #   (noise | crossfade), noiseScale, softness, seed, evolve
      match:                        # optional, set by Check seams (schemaVersion 10)
        colour: true                # colour match on (default); false keeps the fits unused
        fits:                       # one per seam (~ = none): the LATER clip's correction
          - clips: [assets/…-tile-01.mp4, assets/…-tile-02.mp4]
            gain: [1.021, 0.968, 1.044]    # R, G, B: later' = gain · later + offset, 8-bit levels
            offset: [-2.4, 3.1, 0.6]
        mask: assets/tiles/01-panorama/N/detail-5d1c2e9a.png   # white = every clip stays still
        maskClips: [assets/…-tile-01.mp4, assets/…-tile-02.mp4]
  • A zone is always the full surface height at the tile's aspect (21:9 on a 1600 px surface is 3731×1600), so only its x is stored. There is one row: a horizontal seam would cut through people.
  • Assemble writes the comp tiles-<surface> (each clip in its zone, scaled to surface px; later zones on top; the top clip's left edge feathered across the seam's band) and, when a band starts inside the overlap, a small framed comp tiles-<surface>-t<N> that cuts the top clip first. One use: tiles-<surface> goes on top of the surface's children. These are ordinary comps; a re-assembly (a seam or the feather changed) rewrites them.
  • loop (Make Loop on a tiled surface: the panel's make tiles loop, MCP make_loop { scene, surface }): every assembly makes each placed clip into the same Make Loop cut (video trim), named after its zone (tiles-N-z1, tiles-N-z1-a, -b, -matte, -dissolve, -black, -noise), and sets the scene loop to it. So a seam move or a re-rolled tile keeps the loop. A new batch drops the key.
  • match is what the seam check found (help "Check the seams"; tiles_check { scene, surface }; engine/model/tile-match.ts). A fit (or the mask) applies only while videos still names the clips it was measured on, so a re-rolled tile never gets a stale correction. With colour match on, Assemble puts a masked adjustment layer above the later clip in its cut comp: adjust: {} with a levels effect for the gain and offset, cut by a gradient ramp from the band to the zone's end (no second video node). It makes the scene v10 (above). Gains 0.5–2, offsets ±128; gain and offset ranges, list lengths and keys are checked at parse.
  • Keep design detail sharp is not in the plan: it is a matte node (mode: luma, invert: true) around the surface's use: tiles-<surface> holder, cut by the detail mask image (scaled from grid px onto the surface). It is an ordinary matte in the surface's list.
  • Prefer the tools to a hand edit: plan_tiles, generate_tiles, assemble_tiles, set_tile_seams, make_loop { scene, surface }, tiles_check, set_tile_match (mcp-and-extensions.md).

graphLayout, graphColors, graphNotes — node-graph metadata

Three top-level keys hold what you arrange in the node graph (node-graph.md): where you moved nodes, the colours you gave them, and the sticky notes on the graph. They are editor metadata: scene content, versioned with the scene and undoable edit by edit, that is never rendered. The surfaces, the viewer, export and MCP renders never read them, and changing them rebuilds no surface (the rebuild plan files them as inert). Each is omitted when empty.

graphLayout:
  "@surface:N": { x: 40, y: 0 }
  pin-k3x9a2: { x: 0, y: -24 }
graphColors:
  "@surface:N": blue
  "@comp:wall-N": purple
  pin-k3x9a2: green
graphNotes:
  - id: note-0f3k2a
    x: 120
    y: -80
    w: 220
    h: 110
    color: yellow
    text: intro hits on the downbeat
  - id: note-9a1b2c
    in: wall-N        # inside comp wall-N's graph; absent = top level
    x: 0
    y: 140
    w: 220
    h: 110
    text: |-
      two lines
      of text

Graph keys. graphLayout and graphColors key a glyph the same way: @surface:<name> a surface root, @comp:<name> a comp, @main the scene dial, @clock:<name> a named clock's dial, and a content node by its id. A content node with an auto id is given an explicit pin-… id the first time it is moved or coloured, so its key survives a reorder (an auto id is positional, §9). A node whose id the YAML already spells out (id: logo, or an earlier pin) keeps it and is keyed by it, so MCP edits and references that name it never break. Effect chips and synthetic glyphs (a clone's source, a use instance) have no key of their own: they follow the auto layout, and an effect chip wears its host node's colour. Renaming a comp, surface or clock in the YAML does not carry its key along; rename the key too, or the offset / colour / note is left behind.

  • graphLayout — graph key → a manual offset { x, y } (graph px, a Vec2) added on top of the auto layout. Written by node moves; reset layout clears the map.
  • graphColors — graph key → red, orange, yellow, green, blue or purple. A neutral organising palette with no meaning of its own (not the Generations grades). Anything else is a parse error that names the six.
  • graphNotes — the sticky notes, in draw order (a later note draws over an earlier one). A hand-written note needs only text:
FieldTypeDefaultMeaning
textstring""The note's plain text. Use a |- block for several lines.
idstringnote-<n> (n = its place in the list, from 1)Stable note id. A repeated id is made unique at parse.
incomp name— (the top level)The comp whose drilled-in graph the note belongs to; it shows only there.
neargraph key or name— (the first column)What the note is about, so a note with no position is placed beside it: a graph key ("@comp:wall-E1", "@surface:N", "@main", "@clock:<name>"), a node's id, or a bare comp / surface name. Read only while the note has no position.
x, ynumber— (none saved)Top-left corner, in that graph view's graph px. Leave both out and the graph places the note in free space beside near, never on a node or another note (node-graph.md). Moving or resizing the note in the graph saves them. One alone is a position (the other is 0).
w, hnumber > 0— (sized to the text)Size in graph px. Left out, the note is as wide as its longest line (90 to 320) and as tall as its wrapped lines.
colorgraph colour— (uncoloured)One of the six graphColors names.

A note written with only its text is saved the same way: no x, y, w or h, so it stays placed by the graph until someone moves it. Starlight 0.2.27 and older filled in x: 0, y: 0, w: 220, h: 110 for such a note and saved that; this exact rect reads as no position. near and a note with no rect raise no schemaVersion: notes are never rendered, and an older Starlight reads a note without a rect at 0, 0 (and ignores near), as before.

They sit beside graphLayout rather than inside it on purpose: a Starlight build that predates them keeps them as unknown top-level keys (§10) instead of refusing the file. read_scene returns them with the rest of the scene, so an agent can read the user's notes.

markers — timeline markers

Labelled, coloured moments on the timeline (timeline.md §markers), at scene time. Editor metadata like graphNotes: versioned and undoable, never rendered, and changing them rebuilds no surface. A marker drives nothing — unlike a cue (§8), which a trigger can fire from, so moving or renaming a marker can never retime a clock.

markers:
  - 1.5s                                  # a marker with no label
  - { at: 3s, label: drop, color: red }
FieldTypeDefaultMeaning
atduration ≥ 0— requiredThe instant, in scene time.
labelstring—What the flag reads (else its time).
colorgraph colour—One of the six graphColors names.

An item is a bare duration (a marker with neither label nor colour) or the map. Parse sorts the list by at; serialize writes the bare form when it can. A video node carries its own list in the same grammar at clip time (video). No schema bump: a Starlight that predates markers keeps them as unknown keys (§10) and renders the scene identically.

stages — 3D shot blocking

A stage blocks out one AI generation before anything is spent: clay boxes, cylinders, cones, spheres and posable figures on a ground, in metres, seen through a render camera with a real lens, framed to the aspect the model will make. Its grey layout capture goes to an image or video model as an input. A stage belongs to the scene but is not a node: it adds nothing to the graph, renders on no surface and reaches no deliverable. The full reference (every key, frames and checks, figures and poses, captures, recipes, the stage_* MCP tools): stages.md.

stages:
  hero-wide:                         # stage id: ^[a-z0-9][a-z0-9-]{0,47}$, at most 64 per scene
    name: Hero on the riser
    target: jumbotron                # a project surface (optional): default frame, crop guide
    frame: surface                   # the OUTPUT aspect: `surface` (the target's; the default with a target) or W:H like '21:9'
    camera:
      pos: { x: 0, y: 1.6, z: 9 }    # metres, Y up, the ground is y 0
      target: { x: 0, y: 1.3, z: 0 }
      focal: 35                      # mm on a 36 mm-wide frame, 8..1200
    items:
      - id: k1
        kind: figure                 # box | cylinder | cone | sphere | figure
        name: hero
        pos: { x: 0, y: 0.6, z: 0 }  # the centre of the footprint: standing on the riser
        size: { x: 0.56, y: 1.75, z: 0.42 }
        pose: { name: arms-up }
      - id: k2
        kind: box
        name: riser
        pos: { x: 0, y: 0, z: -1 }
        size: { x: 8, y: 0.6, z: 4 }
  • Validated on write, lenient on load. Plain parsing never checks a stage, so a broken one never stops its scene from opening (the stage list marks it invalid). The MCP write paths — stage_write, and a write_scene / create_scene / compose plan that carries stages: — check each stage against the project and reject a broken one with an issue at the exact path (§11).
  • Write paths. stage_write / stage_delete change only the stages: block (comments elsewhere survive). A write_scene is the whole file, so leaving stages: out of one deletes the scene's stages.
  • Captures live beside the scene, not in it: assets/stages/<scene>/<id>-<hash8>.png with a provenance sidecar under assets/.stages/.
  • An older Starlight keeps the block as an unknown key (§10).

4. Nodes

A node is a map whose single type keyword selects its kind; sibling keys are its props. The keyword → kind mapping (NODE_KEYWORDS, model/nodes.ts):

KeywordKindKeyword value is…
texttextthe string content
imageimagethe asset path
cutoutimage (+ a cutout effect)the asset path — a legacy spelling (below)
videovideothe asset path
audioaudiothe asset path (a track: draws nothing)
shapeshaperect | ellipse | line
pathpaththe list of subpaths
gradientgradientlinear | radial
transformtransformthe child list
groupgroupthe child list
cloneclonethe { of, count, … } map
particlesparticlesthe { rate, life, emitter, … } map (every key optional)
userefthe comp name
adjustadjust{} — an adjustment layer has no content of its own
mattemattethe { content, matte, … } map — two input nodes and the matte's settings
nodean extension's kindthe node type an extension registered (below)

Exactly one keyword must be present. Zero keywords → expected a node keyword (text, image, …). Two or more → ambiguous node — multiple keywords present: …. Both are friendly ParseErrors anchored to the node's path (§11).

Fields on every node

Regardless of kind, any node may carry these common fields (NodeCommon):

FieldTypeDefaultMeaning
idstringauto-derivedStable identity. Usually omitted — see §9.
clockclock block—Phase-space animation driving this node (docs/clocks-and-animation.md).
bypasstrue—Switches off what the node adds (model/bypass.ts). A transform or group passes its children through: they draw and animate as if it were not there (none of its position, scale, rotation, skew, anchor, opacity, blend, clock, gate, span, delay or effects). A source (image, cutout, video, shape, path, gradient, text, use, clone, particles, audio, an extension's node) hides, with its subtree, and samples nothing. A matte shows its content uncut. An adjust layer is inert.
blenda blend mode (below)—How the node's finished pixels (after effects + opacity) combine with what is beneath. Omit/normal → default; serialized only when set. Full reference: blend-modes.md.
effectslist—Stacked GPU effects (§8).
span[in, out] — two durations— (the whole loop)The layer's in/out point in scene time (After Effects' layer bar): the subtree renders only while in ≤ t < out, t being the wrapped loop time live preview and export both sample. 0 ≤ in < out; bare numbers are ms. Independent of the clock — keyframes stay in phase space. Serialized only when set, as a flow pair (span: [1s, 2500ms]) (below; docs/timeline.md).
delayduration (may be negative)— (on time)The node and everything inside it run this much later: its clock, its effects' and gradient's keys, its children, and — on a use: / clone of a comp — the comp's whole timeline. Read on the looping scene time, wrapped. Moving a layer bar in the timeline sets it. Scene format v7; serialized only when set (below).
prerendertrue, or { alpha: auto | on | off }— (drawn live)Play the node's content from a video file that Starlight renders on this computer (below). A cache, not content: it needs no new scene version. Serialized only when set.

bypass is a special case: only the literal true is retained — any other value (false, absent) leaves the field unset, so an un-bypassed node serializes without it. In-app, b (or the bypass switch on the node in the graph) toggles bypass on the selected node. Before 0.2.14 a bypassed transform or group hid its subtree; the file is the same, only the reading changed.

blend modes, grouped as in Photoshop (the props panel's dropdown uses the same groups):

GroupModes
normalnormal
darkendarken multiply color-burn linear-burn
lightenlighten screen color-dodge add
contrastoverlay soft-light hard-light vivid-light linear-light pin-light hard-mix
inversiondifference exclusion negation
cancellationsubtract divide
componenthue saturation color luminosity

Spellings are forgiving: case, spaces, underscores and camelCase normalize (Soft Light, softLight, soft_light → soft-light), and linear-dodge (also plus, plus-lighter, Linear Dodge (Add)) is add — it parses to add and serializes as add. Anything else is a parse error that lists the valid set (comps.main.0.blend: expected a blend mode (…)), so a typo never silently renders normal. normal, add, screen and multiply are free GPU blend states; every other mode costs one backdrop copy + one pass over the node's bounds (blend-modes.md §4). A group with effects or a non-hardware blend is isolated: its children blend against each other inside it, then the group blends onto the scene.

span — a layer's in/out in scene time

- text: "TOUCHDOWN"
  span: [1s, 3s]        # on from 1s, off at 3s (half-open: 3s itself is off)

span is the After Effects layer bar on a model whose motion lives in phase space. It gates whether the subtree is drawn at scene time t — nothing else. The node's clock keeps sampling, its keyframes stay where they are, and a gate on the same node still applies: the node shows only where both the span and the gate are on (bypass still wins over both). The rules:

  • Half-open, scene time, wrapped. Visible while in ≤ t < out, t the transport's wrapped loop time — never the unwrapped audio time — so a span is loop-perfect by construction and two abutting spans never overlap or gap by a frame.
  • No wrap-around. in < out always; a stretch that would cross the loop seam is two layers, or a gate (the phase-space in/out, which repeats every clock cycle).
  • Full = absent. A span covering the whole loop is not stored, so trimming a bar back out in the timeline leaves no YAML behind.

Edited in the layer timeline (an edge's top half trims, the body's bottom half moves and its top half copies, ⌥[/⌥] set at the playhead); edits write whole milliseconds that land on frame boundaries. A move (or copy, paste, nudge) writes the span and the layer's delay together, so the keys go with the bar. Errors: §11. Full detail: docs/timeline.md.

delay — a layer runs later

- transform:
    - text: "LINE 2"
  clock: { tracks: { x: [-400, 0, 0] } }
  delay: 200ms             # the whole layer runs 0.2 s later: its fly-in starts 0.2 s after LINE 1's

delay is After Effects' layer start time, on a model whose keys live in phase space (docs/clocks-and-animation.md §3). The node and everything inside it read the looping scene time t − delay, wrapped into the loop: a delayed loop is the same loop, turned, so it never seams. Negative runs it earlier. The rules:

  • What it reaches. The node's own clock (tracks and gate), its effects' animated params (their own clock or the node's), a gradient's keys, every child (delays add up down the tree), and through a use: / clone of a comp the comp's whole timeline, its spans included. A clone draws one raster per frame, so all its copies share the one delay.
  • What it leaves alone. The node's own span, and the spans of the layers beside it in the same comp: a span is where a layer shows, in its comp's time. Audio drives follow the song. A video's frames follow its clip (offset:, one decoder per clip).
  • A surface's delay. A surface binding's delay turns its use: comp on that surface only (§3): the surface-to-surface chase.
  • The timeline writes it. Moving a layer bar moves its spans and its delay together (⌘ / Ctrl moves the span only). A comp's own timeline shows the comp's own time; each use of it runs its delay later.
  • Absent = 0. A zero delay is not stored. A duration (2s, -250ms; bare numbers are ms), stored in whole ms. A scene that holds one is written as v7.

prerender — play a layer from a file

- transform:
    - use: crowd-heavy
  prerender: true              # or { alpha: auto }, { alpha: on }, { alpha: off }

A heavy layer (many clips, effects or nested comps) can be slow to draw live. With prerender:, Starlight renders the node's content once to a video file and plays that file instead (shared/prerender.ts, model/prerender-key.ts). Any node can carry the key, and so can a surface binding (§3). To pre-render a comp, put the key on its use: node. A framed comp's map cannot hold it: an older reader refuses unknown keys there.

  • The values. true is the same as { alpha: auto }. auto keeps transparency only when the content has it (Starlight checks the first, the middle and the last frame). on always keeps it. off renders the content over black.
  • What is in the file. The node's content: its children, with their clocks, effects, spans and comps. For a use:, the comp. For a matte node, the cut result.
  • What stays live. The node's own transform, clock, opacity, effects, blend and span. So the file sits exactly where the content sat. To bake the node's own effects too, pre-render its parent instead.
  • Delays. On a use: (or a clone), the delay stays live: its own, and every delay above it. On any other node, its own delay and its parents' delays in the same comp are in the file (its children's spans keep the comp's time, so they cannot move with the file); changing them makes the file stale. A delay that comes from outside the comp (a use: above it, a surface's delay:) stays live: one file plays on every surface of a chase.
  • While you edit inside. When the selection is inside the node, the node draws live, so you can still click, select and move its layers.
  • A cache on each computer. The files live in this computer's renders folder (renders/.prerender/<key>/; in a shared project <root>/renders/.prerender/<key>/, which never syncs). They are not in the scene and not in git. Each computer renders its own. The key is a hash of everything the content depends on: its nodes, media files, versions, clocks, the scene loop and fps, fonts and colour files. Graph layout, notes and markers do not change it. Changing the code of an extension that the content uses (extensions/<name>/index.js) makes its files stale.
  • Fresh, stale, none. Fresh: a file matches the content now, so the file plays. Stale: the content changed after the last render, so the node draws live and shows a stale badge until it is rendered again. None: no file yet, so the node draws live. An undo back to an earlier state finds that state's file again.
  • One loop. The file holds exactly one scene loop. Content that does not repeat every loop cannot be pre-rendered, and Starlight says why. Examples: an untrimmed clip whose length does not divide the loop, a clock on audio time, a music drive.
  • No new scene version. An older Starlight keeps the key and ignores it (§10). It draws the node live, which is the same picture.
  • Export. An export always renders live, so its pixels are exact (the files are 8-bit 4:2:0). There is no switch yet to export from the pre-rendered files. The request field for it, ExportRequest.usePrerenders, exists, but the export sheet and the MCP tools do not set it.
  • A/B. ⌥B / Alt+B on the selection shows the node live or from its file. Only the view changes; the scene does not.

Positioning: only transform moves things

A text / shape / path / image / gradient / clone / particles node has no position of its own — it draws at its parent's origin. To place one, wrap it in a transform and set position there. A stray position: on a bare shape is not an error — it lands silently on the node's unknown bag and is ignored by the compositor.


text

- text: "TOUCHDOWN"        # keyword value = content (coerced to a string)
  font: knockout-heavy     # a brand.fonts family name
  size: 204
  fill: $primary           # #hex or $token
  weight: 800              # number or string ("bold")
  letterSpacing: 2
  align: left              # left | center | right
FieldTypeDefaultNotes
contentstring— requiredThe text: value; a non-string is coerced with String(). A line break starts a new line.
fontstring—A brand font family, or a font installed on this computer (Arial, Segoe UI). The name a font menu shows also works: Knockout Heavy finds the brand family knockout-heavy, and a weight or style word on the end (Segoe UI Semibold, Helvetica Neue Bold Italic) sets that weight (unless weight is set) and style. Resolved by resolveFontChoice (engine/model/font-choice.ts). A name with no form that is there falls back to the condensed system stack.
sizenumber > 0—Type size in design px.
fillcolour, a list, or none— (white)#hex or $token — anything else is a ParseError (§5) — or a keyframe list of them (animated, below). v14: none draws no fill: with a stroke, a hollow word (outline, below).
strokecolour or a list— (no outline)v14. The outline's colour, #hex / $token or a keyframe list of them (animated, below). Drawn centred on the letters' edges, under the fill (outline, below).
strokeWidthnumber > 01 (with a stroke)v14. The outline's width in px of the text's own space: 6 puts 3 px outside each letter and 3 px inside it. Without a stroke it draws nothing.
weightnumber | string—e.g. 800 or "bold", for a font installed on this computer. A brand font file has one weight: name the weight's key instead (font: inter-bold), because 600 or more on a brand file is a fake bold (§2 weights and styles).
letterSpacingnumber—Tracking in px.
alignleft|center|right—Horizontal alignment — it also sets the block's anchor: left puts the left edge on the transform's point, center the middle, right the right edge. Lines of several line up the same way inside the block.
wrapnumber > 0— (no wrapping)v13. The width, in px of the text's own space, that lines wrap at: as many words as fit go on a line, breaking at spaces (the spaces at a break are dropped); a word wider than wrap breaks between its letters. A line break still starts a new line.
lineHeightnumber > 0— (the font's own line box)v13. Baseline to baseline, as a multiple of size: 1.25 with size: 40 puts the baselines 50 px apart. The extra space goes half above and half below each line, as in CSS and Figma.
maxLineswhole number ≥ 1— (all lines)v13. At most this many lines; the rest is cut.
overflowellipsis | clipellipsisv13. What a text cut by maxLines shows: ellipsis ends the last kept line in … (letters come off its end until the line with … fits wrap), clip just stops.
anchorYtop | baselinetopv13. Which part of the text sits on the transform's point vertically: the top of its box, or the FIRST line's baseline. The baseline comes from the metrics of the face that draws, so it is exact for any font.
markuptrue— (off)v13. *italic*, **bold** and ***bold italic*** in the content draw in those styles (below).
lettersmap— (the text draws as one)v15. { by, stagger, order, clock }: the text animates unit by unit, each unit on its own run of clock, one stagger after the one before (letters, below).

Optional fields are omitted from the model until set; at render a text with no size / fill / align / letterSpacing falls back to 48px / #ffffff / left / 0 (registry/builtins.ts), and a stroke with no strokeWidth is 1 px wide.

Layout (v13). A text with any of wrap, lineHeight, maxLines, overflow, anchorY or markup is laid out by engine/registry/text-layout.ts layoutText: the canvas, every export and still, and the MCP measure_text tool all run it, so its lines and baselines are the same everywhere (measure_text: mcp-and-extensions.md §3). It measures with the renderer's own canvas text measure and the font string the text draws with. A text with none of these fields is built exactly as before (its pixels do not change).

# A review card: the body wraps at 920 px, baselines 54.75 px apart, the first
# baseline on the transform's point, at most 4 lines with an ellipsis.
- transform:
    - text: "easily one of the most beautiful animated films i've seen in years. *every frame* looks like a page from an illuminated storybook"
      font: Inter
      size: 38
      fill: $bodyInk
      wrap: 920
      lineHeight: 1.4408   # 54.75 / 38
      maxLines: 4
      anchorY: baseline
      markup: true
  position: { x: 40, y: 213.5 }   # where the first baseline goes

Markup. With markup: true: *italic*, **bold**, ***bold italic***. A run of asterisks opens a style when a letter follows it and closes one when a letter comes before it; it closes the nearest open run with the same number of asterisks. Anything else is a plain asterisk (5 * 3, an opener never closed, four or more in a row), and \* is always an asterisk (in a double-quoted YAML string, write \\*). Styles nest and run across line breaks. Each style draws with its own face:

  • A brand font (a brand.fonts file) draws each style from its own file: the file of the same family that is that style, found by what the files say, whatever its key (§2 weights and styles). A style with no file draws with the regular file, and the text's properties panel and measure_text say which file is missing. Starlight never slants or thickens a face itself.
  • An installed font asks the system for its italic, and for a bolder weight (CSS bolder: 400 → 700, 600 → 900), as any app does.

The runs of a line sit on one baseline, and baselines are lineHeight apart whatever the faces.

Outline (v14). stroke draws an outline round every letter, strokeWidth px wide (1 when not set), and fill: none leaves the letters empty, so outlined type needs no SVG.

- text: GOAL              # a hollow word: only the outline
  size: 220
  fill: none
  stroke: $team.gold
  strokeWidth: 6
- text: TOUCHDOWN         # a filled word with a contrasting edge
  size: 160
  fill: "#FFFFFF"
  stroke: $ink
  strokeWidth: 10
  • Centred on the edge, under the fill. The stroke straddles each letter's edge, half outside and half inside, and the fill is drawn over it, so with a fill only the outer half shows (a strokeWidth: 10 edge looks 5 px wide). Every stroke is drawn before every fill, so a thick outline never covers a neighbouring letter or the line above.
  • Round joins. Corners of the outline are rounded, so the sharp corners of an italic or a condensed face do not grow spikes.
  • The letters do not move. Adding an outline leaves every letter, line and baseline where it was, for every align, wrap, lineHeight, maxLines, anchorY, markup run and letterSpacing; the outline reaches out half its width. Wrapping still measures the letters, not the outline.
  • The box grows. The text's box (selection, snapping, a clock's pivot, effects) is the letters' box grown by half the stroke width on every side, as a shape's stroke is. measure_text reports that box, with outset (the half width); its lines and baselines are the letters', unchanged.

Animated colour. fill may be a keyframe list instead of a colour, the shape fill's form (shape): shorthand [a, b, a] or long form [{ phase, value, ease }], each value a #hex or a $token. It rides the node's own clock: (else the scene loop), blends in OKLab with the usual eases, and carries alpha in the colour (#rrggbbaa). Every *italic* and **bold** run follows the one colour. The outline's stroke animates the same way, on the same clock, apart from the fill. A still colour stays a value on save; an animated one stays its shortest list (clocks-and-animation.md §4).

- text: GOAL
  size: 160
  fill: ["#FFFFFF", $team.gold, "#FFFFFF"]   # white, gold, white
  clock: { period: 2s }

No new schemaVersion for an animated fill: an older Starlight refuses a list in fill (expected a colour …, naming the field) rather than drawing it some other way, so the scene keeps the version its other content asks for (a layout field still makes it v13, an outline v14, letters v15).

Letters (v15). Type that arrives letter by letter is ONE text with letters:, never one node per letter. The text splits into units and each unit runs its own copy of a clock, each a stagger after the one before: the clone cascade on a text (engine/model/text-letters.ts).

- text: TAYLOR                 # a hero name, 2 frames per letter at 60 fps, a small landing
  font: anton
  size: 520
  fill: $ink
  letters:
    by: letter                 # letter (default) | word | line
    stagger: 33ms              # unit k starts k × 33 ms after the first
    order: forward             # forward (default) | reverse | center | edges | random
    clock:                     # each unit's own clock: a node clock's shape
      period: 200ms
      mode: once
      tracks:
        opacity: [0, 1, 1]
        scale: [{ phase: 0, value: 0.4, ease: overshoot }, { phase: 1, value: 1 }]   # peaks ≈ 1.06
        fill: [{ phase: 0, value: "#FF5A1F", ease: hold }, { phase: 0.2, value: "#FF5A1F" }, { phase: 1, value: $ink }]
FieldTypeDefaultNotes
byletter | word | lineletterWhat one unit is. A letter is a grapheme (a letter with its accents, an emoji with its skin tone, a flag: Intl.Segmenter, the splitter Pixi draws spaced text with); a ligature the font draws splits into its letters. A word is a run of letters between spaces (a markup word that changes style is one unit). A line is a laid-out line (after wrap and maxLines). Spaces are never units and take no stagger slot.
staggerduration ≥ 00The time between one unit's start and the next's, as a clone's stagger: unit k in order runs k × stagger behind the first. At 60 fps a frame is 16.67 ms: 33ms is 2 frames per letter.
orderforward | reverse | center | edges | randomforwardThe order units start in, over the whole text (line by line, left to right). center: the middle unit first, then outward, the left one of an equal pair first (TAYLOR runs Y L A O T R). edges: both ends first, then inward (T R A O Y L). random: a fixed shuffle seeded by the node's id (integer hashing): the same every frame and on every machine; another node, or another unit count, shuffles otherwise. Every order gives each unit a slot of its own.
clockclock— (the units hold still)Each unit's clock, the shape of a node's clock: (§8): period (else the scene loop), mode (once | loop | pingpong), or use: a named clock (its trigger and anchor apply), and tracks. gate and drive are refused here (they belong on the text's own clock).
clock.trackstracks—x, y, scale, scaleX, scaleY, rotate, skewX, skewY, opacity, keyed in phase like any track (shorthand, long form or per-frame samples), plus fill: a colour keyframe list (#hex / $token, OKLab) that colours each unit's fill in place of the text's fill. A stroke track is refused: the outline keeps the text's stroke (still or keyed on the text's own clock).
  • Each unit moves from its own place. x / y offset it, opacity fades it, and scale, scaleX, scaleY, rotate and the skews turn round the middle of the unit's advance horizontally and its line's baseline vertically, so a letter grows up from the line it sits on.
  • Timing is the clone's (compositor/instancing.ts instancePhase, unit slot as the index): loop and pingpong repeat each unit on its own phase; a once clock holds its first key until the unit starts and its last after it ends, so the word is still at the end. The node's delay delays the letters too. The last unit ends at period + (units − 1) × stagger (with 6 letters, 200 ms and 33 ms: 365 ms). measure_text gives the unit counts (units) and, for a text with letters:, lastStartMs and totalMs.
  • At rest the picture is the text's. With every unit at rest (opacity 1, no offset, scale 1, no turn) every glyph is exactly where the text without letters: draws it: kerning with the letter before it, align, letterSpacing, wrap, lineHeight, maxLines and its …, anchorY, markup runs and the outline (every stroke under every fill). Each unit is drawn at the pen Pixi's own draw of the line reaches it at, W(line) − W(line[i:]) + i × letterSpacing, and on the same pixel grid, at the same fraction of a pixel, so on whole-px placements the pixels are the same. Off the grid (a fractional position, a scale, a turn) only the filtering of edge pixels can differ, each letter's texture keeping a 1 px empty margin.
  • The text's own clock still drives the whole text (a slide under the type-on), and its own fill / stroke keys tint every unit's fill / outline on that clock.
  • Cost: one texture per unit per paint pass (an outline doubles it), built once; each frame moves and tints units, never redraws them. Fine for names and titles; a paragraph by letter is hundreds of textures.
  • In the app. The text sheet has letters by, order and stagger ms (under more until set) and a note of the unit count and timing; the per-unit clock is set in YAML in this version. The timeline shows the text's own clock lanes and colour lanes, not the per-unit tracks.
  • Errors at the key: letters.by — expected letter, word or line, letters.order — …, letters.stagger — expected the time between one unit's start and the next's: 0 or more, letters.clock.gate — a letter does not take a gate, letters on any other node (only a text animates its letters). Keys inside the map that Starlight does not know stay inside it, as a clone's do.
  • v15. A v14 reader would keep letters as an unknown key and draw the word still, so a scene with one is written as v15 (textLettersSchemaVersion) and an older Starlight asks to update; every other scene keeps its version.

image

- image: assets/logo.svg   # asset path under the project assets dir
FieldTypeDefaultNotes
srcstring (non-empty)— requiredThe image: value. A non-string is a ParseError (expected an asset path). png/jpg/svg/webp/gif. Draws at its own pixel size, top-left at the origin; an SVG scaled up is drawn again at the size it is shown, so it stays sharp at the same layout size (assets.md §9). A missing or undecodable file draws Texture.WHITE — a single 1×1 white pixel — and the canvas's bottom-left line names it: missing media: … when the file is gone, could not load: … when it will not decode (renderer/missing-media.ts).

cutout

- cutout: assets/players/jane.jpg   # legacy spelling of the form below
# parses to, and saves back as:
- image: assets/players/jane.jpg
  effects:
    - cutout: {}                    # the subject, background removed

cutout: is legacy sugar. It parses to an image node with a cutout effect at the head of its effects stack, and the next save writes that form, so the graph always shows image → cutout → filters and b A/Bs the extraction. A non-string value is a ParseError (expected an asset path). Write the image + cutout effect form. The subject is extracted (background removed) by macOS subject extraction (Vision) on a Mac and saved in the project as assets/.cutouts/<name>-<hash>.png, so every machine (Windows too) draws the same cutout (assets.md §8). Where none is saved and this machine cannot make one, the original image draws and the canvas says cutout not made yet – open on a Mac to make it. Nothing in the scene names the cutout file; the format is unchanged.

video

- video: assets/scoreboard-loop.mp4
  loop: true               # default true — venue content loops
  muted: true              # default true — venue playback is silent; false plays the clip's sound
FieldTypeDefaultNotes
srcstring (non-empty)— requiredThe video: value (mp4/webm/mov/m4v/ogv).
loopbooleantrueLoop the clip.
mutedbooleantrueMute the clip's own sound. false plays it on the transport, through the monitor, and mixes it into exports at full volume (when the file has an audio stream). Once per clip however many layers show it, timed like the picture (the first node's loop and offset); any un-muted, un-bypassed layer on the clip sounds it.
offsetduration (may be negative)0Scene v5. The clip's place on the transport: transport 0 shows this clip time (2s starts the clip 2 s in; -1s starts it a second late, holding its first frame). What the layer timeline's slip writes (timeline.md §gestures). One decoder per clip: every node on a src plays at the first one's offset, and a slip writes them all. Not written when 0.
trim[in, out] (two durations, 0 ≤ in < out)—Scene v9. Play only this piece of the source (trim: [5s, 10s]), locked to the scene loop: at its span's start (loop time 0 with no span) it shows source in, then plays on with the loop, and holds its frame just before out if the piece is shorter than its time on screen. Outside its span it waits on its in frame, ready for its next entrance. It restarts on every loop pass, so it never drifts against the loop. A trimmed node has its own decoder: two trimmed layers on one file show different times (Make Loop uses this). It ignores loop and offset, a slip never moves it, and it never sounds (the file's sound comes from its untrimmed layers). The loop time it reads is the scene's, not a comp's delay. Not written when absent.
versiona version id, <op>-<hash8> (denoise-41c0e9aa)— (the original)Scene v11 (a matte version, person-…, depth-… or roto-…: v18, and only as a matte node's input, below). The layer plays this version of its clip: a file made from it, such as an upscale or a clean-up (below; assets.md §10). video: still names the original. Not written when absent.
markerslist of markers—Layer markers at clip time (ms into the source), the scene markers grammar. They mark the content: they show wherever the clip plays that frame, so a slip slides them with the clip (timeline.md §layer markers). Never rendered.

(loop/muted are only written when explicitly set; their runtime default is true.) A span never shifts the clip — it is a window onto it (timeline.md §span); the offset does.

Transparent video needs nothing in the scene. A clip imported with alpha (ProRes 4444, VP9 alpha, HEVC with alpha, a dropped PNG/EXR/TIFF sequence folder) is ingested to a packed matte — colour and alpha in one hardware-decoded stream — and the video node draws it with its alpha at the clip's own size (docs/assets.md §6). The packing is recorded next to the asset (assets/.mattes/), not in the scene.

A version of the clip

- video: assets/walls/north.mp4    # the scene still names the original
  version: denoise-41c0e9aa        # scene v11: this layer plays the version

A version is a new file made from a clip: sharper, cleaner, at another frame rate, or with a new look. It lives beside the clip, in assets/.versions/ (assets.md §10), never in the scene. version: only says which version this layer plays (VideoNode.versionId, model/versions.ts).

  1. The scene names the original. Remove version: and the layer plays the original again. New layers start on the original.
  2. The layout does not change. A version draws at the original's size. A 2× upscale draws in the same place, at the same size; only the pixels are sharper.
  3. When the version cannot play, the original plays. This happens when the version file is not on this computer, or when the version does not match the clip or this layer now (for example, it was made for 60 fps and the scene is 30 fps). The canvas line and Properties say why, for example version not used: north.mp4 · fps-a1b2c3d4 made for 60 fps; the scene is 30 fps. The version file stays.
  4. Export uses the version's full file. When the version is not on this computer, the export refuses, like a missing file: shipping the original without a word would be wrong. When it is there but does not match, the export goes ahead with the original, and the result lists the reason as a warning.
  5. Scene v11. A scene with a version: is v11. An older Starlight refuses to open it and asks you to update.
  6. A/B. ⌥B / Alt+B on the selection shows the original or the version. Only the view changes; the scene does not.

audio

- audio: assets/audio/anthem.mp3
  volume: 0.8              # 0..1, default 1
  offset: 1.5s             # start this far INTO the track (transport 0 plays from here)
FieldTypeDefaultNotes
srcstring (non-empty)— requiredThe audio: value (mp3/wav/m4a/aac/flac/ogg). A non-string → expected an asset path.
volumenumber 0..11Playback gain.
mutedbooleanfalseSilence playback; the track and its analysis stay.
offsetduration ≥ 00Where in the track transport 0 starts (1.5s, 1500ms, bare ms). Negative → validation error.
loopbooleanfalseRestart the track when it ends (a song plays once by default).
exportbooleantrueMux this track into exports.

A track, not a picture: it draws nothing and plays against the transport's unwrapped time, so a song longer than the loop plays on across loop wraps. Clocks can follow it with drive (clocks-and-animation.md); it is never a matte input.

shape

- shape: rect              # rect | ellipse | line
  size: 850x18
  fill: $electric
  stroke: $ink
  strokeWidth: 2
  radius: 9                # rect corner radius
FieldTypeDefaultNotes
shaperect|ellipse|line— requiredAnything else → expected rect, ellipse, or line.
sizesize (WxH)—Bounding size; width and height > 0.
fillcolour or a list—#hex / $token, or a keyframe list of them (animated, below).
strokecolour or a list—Stroke colour (#hex / $token), or a keyframe list of them.
strokeWidthnumber ≥ 0—Stroke width in px.
trimStartnumber 0..1 or a list0Trim paths (scene v16, below): where the stroke starts, a fraction of the outline.
trimEndnumber 0..1 or a list1Where the stroke ends, a fraction of the outline.
trimOffsetnumber (degrees) or a list0Turns the drawn stretch round the outline; 360 = one lap.
radiusnumber ≥ 0—Corner radius (rect).

At render, an omitted size draws at 100×100 and an omitted strokeWidth strokes at 1. A line ignores fill and strokes in its stroke colour (falling back to fill, else #ffffff). A rect / ellipse with neither fill nor stroke draws nothing. The box is drawn from its top-left corner; an ellipse fills it.

Animated colours. fill and stroke may each be a keyframe list instead of a colour, the gradient stop colour's form: shorthand [a, b, a] or long form [{ phase, value, ease }], each value a #hex or a $token. The list rides the node's own clock: (else the scene loop); keys blend in OKLab with the usual eases; alpha rides in the colour (#rrggbbaa), so a fill fades by keying its alpha. A $token key plays the colour the token resolves to, and follows the brand kit. A still colour stays a value on save; an animated one stays its shortest list (clocks-and-animation.md §4).

- shape: rect
  size: 400x120
  radius: 12
  fill: ["#1E3A8A", $team.gold, "#1E3A8A"]
  clock: { period: 2s }

No new schemaVersion: an older Starlight refuses a list in fill (expected a colour …, naming the field) rather than drawing it some other way, so the scene keeps the version its other content asks for.

Trim paths — draw part of the stroke

trimStart, trimEnd and trimOffset draw only part of a shape's or a path's stroke: After Effects' Trim Paths, for line reveals, logo stroke builds, progress rings and underline wipes. The fill is never trimmed: it draws whole whatever the trim. A node that draws no stroke has nothing to trim (a rect or ellipse without stroke, a path with a fill, a closed subpath and no stroke set).

  • trimStart, trimEnd are fractions 0..1 of the outline's length (After Effects' Start and End, 0–100 %). Absent: 0 and 1, the whole outline. A value outside 0..1 is an error (trimEnd 1.5 is out of range 0..1, at its key).
  • They are interchangeable, as in After Effects: trimStart: 0.8, trimEnd: 0.2 draws the stretch from 0.2 to 0.8. Equal values draw no stroke. 0 → 1 is the whole outline, drawn as an untrimmed stroke (a closed outline stays closed, with no seam).
  • trimOffset turns the drawn stretch round the outline, in degrees (After Effects' Offset): 360 is one lap, a negative value turns it back, and any number works (720 = two laps). On a closed outline a stretch the offset carries past the start point runs on through it as one unbroken stroke; on an open one it comes out as two pieces, one at each end.
  • Where an outline starts (After Effects' order): an ellipse at 12 o'clock, a rect at its top-right corner (just below its rounding), both running clockwise; a line at (0, 0) towards its size corner; a path at the first vertex of each subpath, in vertex order.
  • Several subpaths trim together, each by the same fractions of its own length (After Effects' "Simultaneously"): trimEnd: 0.5 draws the first half of every subpath.
  • The ends of a trimmed piece are square (butt), as an open path's are.
  • Animated: each value may be a keyframe list in place of the number — shorthand [0, 1] or long form [{ phase, value, ease }] — riding the node's own clock: (else the scene loop), the gradient angle's form (clocks-and-animation.md §4). A still value stays a value on save, a list its shortest form.
  • The box does not change: selection, a clock's pivot and fit use the untrimmed shape's bounds at every trim.
- shape: ellipse           # a progress ring that draws itself round once
  size: 300x300
  stroke: $team.gold
  strokeWidth: 12
  trimEnd: [0, 1]
  clock: { period: 2s, mode: once }

- shape: line              # an underline that wipes in from the left
  size: 800x1
  stroke: "#ffffff"
  strokeWidth: 6
  trimEnd: [{ phase: 0, value: 0, ease: snap }, { phase: 0.4, value: 1 }]

- shape: ellipse           # a quarter arc that spins (a loader)
  size: 120x120
  stroke: "#ffffff"
  strokeWidth: 8
  trimEnd: 0.25
  trimOffset: [0, 360]
  clock: { period: 1s }

Scene v16. A scene whose trim changes the picture — on a node that draws a stroke, a trimStart or trimEnd that moves (a keyframe list whose keys differ) or still values that do not span the whole outline — is written as schemaVersion: 16 (§1): an older Starlight would keep the fields as unknown keys and draw the whole stroke, so it refuses the scene and asks to update instead. A trim that draws the same picture an older Starlight draws (an offset alone, a whole lap, a node with no stroke) raises nothing.

path

- path:                    # keyword value = a LIST of subpaths
    - vertices:
        - { p: [0, 0],    in: [0, 0],   out: [40, 0] }   # corner: in = out = [0,0]
        - { p: [160, 90], in: [-40, 0], out: [0, 0] }    # in/out are deltas RELATIVE to p
      closed: true
  fill: $primary           # fills CLOSED subpaths only
  stroke: $ink
  strokeWidth: 2
FieldTypeDefaultNotes
pathlist of subpaths— requiredThe keyword value; a non-list → expected a list of subpaths.
fillcolour—#hex / $token. Paints closed subpaths only.
strokecolour—Stroke colour (#hex / $token).
strokeWidthnumber ≥ 0—Stroke width in px (render fallback 2).
trimStart / trimEnd / trimOffsetnumbers or lists0 / 1 / 0Trim paths (scene v16), as on a shape: every subpath trimmed by the same fraction, from its first vertex.

An editable cubic-bezier vector shape — created by the pen tool (command palette pen → create · path); it is not emitted by SVG or After-Effects import in the shipping UI. Like shape, a path has no position of its own — wrap it in a transform.

Each subpath is { vertices, closed } with at least 2 vertices (fewer → validation error); closed (default false, only literal true closes) joins the last vertex back to the first — a fill needs at least one closed subpath. Each vertex is { p, in, out }, three [x, y] points (each defaulting to [0, 0] when omitted):

  • p — the on-path point, in design px.
  • in / out — the cubic-bezier handles, as deltas relative to p (the Lottie / After Effects convention): absolute controls are p + in and p + out. A corner vertex has in = out = [0, 0]; a smooth vertex mirrors them.

An open or unfilled path always strokes — the builder defaults it to white at width 2, so a freshly-drawn line is always visible (precisely: with no stroke, it strokes white unless it has a fill and at least one closed subpath). path.fill / path.stroke resolve $tokens exactly like shape, and animate like it: a keyframe list of colours in place of the colour, on the node's clock. Its stroke trims like a shape's (Trim paths): a logo's outline that draws itself on is its path with trimEnd: [0, 1].

gradient

- gradient: linear         # linear | radial
  angle: 90                # linear angle: 0 = left→right, 90 = top→bottom
  stops:
    - { offset: 0.0, color: $base }
    - { offset: 0.5, color: $sweepMid }   # offset optional — see below
    - { offset: 1.0, color: $base }
  size: 760x1700
FieldTypeDefaultNotes
gradientlinear|radial— requiredAnything else → expected linear or radial.
stopslist of { offset?, color }— requiredA missing list → expected a list of gradient stops.
anglenumber (degrees) or a list0Linear only; 0 = left→right, 90 = top→bottom (clockwise, y down). Any angle.
center[x, y] / { x, y } / a number, fractions of the box[0.5, 0.5]Radial only. Animated: { x: <n | list>, y: <n | list> }.
radiusnumber ≥ 0 or a list, fraction of the box0.5Radial only; 0.5 = the ramp ends at the box edges.
sizesize (WxH)the design sizeThe box the gradient fills, from its top-left corner; width and height > 0. The default is the design size of the surface it is built on (surfaceDesign: the binding's design, else the scene's). Animated: { width: <n | list>, height: <n | list> } (px).

A linear gradient runs through the box's centre along the true angle, in the box's own pixels, and spans it corner to corner the way CSS linear-gradient does: the first and last stops land exactly on the far corners, so a 30° ramp is 30° on a 6400×1600 box too (linearGradientLine, registry/builtins.ts). Only the zero direction differs from CSS (here 0 points right, not up). A radial gradient is centred at center (default the middle), its last stop at radius (default the box's edge).

Each stop needs a color — a #hex or $token (a ParseError otherwise). offset is optional, and when given must be a number in 0..1 (stop offset 1.5 is out of range 0..1, checked like a cue phase); when omitted it is auto-distributed evenly — stop i of n gets i/(n-1) (a lone stop gets 0). So stops: [ {color: $a}, {color: $b}, {color: $c} ] implies offsets 0, 0.5, 1.

Animated attributes (scene v4). Each of angle, radius, a stop's offset and color, center.x / center.y and size.width / size.height may be a keyframe list instead of a value — shorthand [a, b, a] or long form [{ phase, value, ease }] (a colour's value is a hex string or a $token). The lists ride the gradient node's own clock: (else the scene loop); colour keys blend in OKLab, and a $token key plays the colour it resolves to. A static attribute stays a value on save; an animated one stays its shortest list (clocks-and-animation.md §4).

- gradient: linear
  angle: [0, 90, 0]
  stops:
    - { offset: 0, color: ["#1E3A8A", "#86198F", "#1E3A8A"] }
    - { offset: [1, 0.6, 1], color: "#4C1D95" }
  clock: { period: 10s }

- gradient: radial
  center: { x: [0.3, 0.7, 0.3], y: 0.5 }   # static: center: [0.5, 0.5]
  radius: [0.3, 0.6, 0.3]
  size: { width: [800, 1200, 800], height: 600 }   # static: size: 1920x1080
  stops: [ { offset: 0, color: "#ffffff" }, { offset: 1, color: "#ffffff00" } ]

transform

The only node that moves, scales, rotates, skews, fades, or re-anchors its subtree. The keyword value is the child list.

- transform:
    - text: "BOLTS"
      fill: $primary
  position: { x: 170, y: 455 }
  scale: 1.05              # scalar → { x: 1.05, y: 1.05 }
  rotation: -16            # degrees
  skewX: -10
  skewY: 0
  opacity: 0.85           # 0..1
  anchor: { x: 0, y: 150 } # pivot in local px
FieldTypeDefaultNotes
positionvec2—Translation in parent px.
scalevec2—Non-uniform; a scalar normalises to {x,y}.
rotationnumber—Degrees.
skewX / skewYnumber—Skew in degrees.
opacitynumber 0..1—Out-of-range → validation error.
anchorvec2—Pivot / anchor in local px: the point that lands on position. Static and animated (clock-track) scale, rotation and skew turn around it. Without it, static ones turn around (0,0) and a clock's around the subtree's box centre (the rule scenes made before keep). New layers made in the app write it at their content's centre, with position where that centre lands (or anchor: 0 when the content's size is not known at create time).
childrennode list— requiredThe transform: value.

group

A pure container — children share the group's clock and effects but the group applies no transform of its own (bypassed, it passes its children through). The keyword value is the child list.

- group:                   # e.g. an L-bracket built from two rects
    - shape: rect
      size: 88x10
      fill: $primary
    - shape: rect
      size: 10x88
      fill: $primary
FieldTypeDefaultNotes
childrennode list— requiredThe group: value.

clone — repetition in one draw call

Instances a source many times along a line or grid. The keyword value is a map; its params live inside that map (not as node siblings).

- clone:
    of: assets/bolt-sm.svg   # an asset path OR a comp name
    count: 16
    gap: 160                 # primary-axis pitch in px
    direction: x             # x | y | grid | radial
    drift: -160px/s          # seamless belt velocity
    stagger: 80ms            # per-instance clock phase offset (a cascade wave)
  clock: { period: 2s, tracks: { scale: [0.9, 1.2, 0.9] } }

Grid form:

- clone:
    of: assets/bolt-sm.svg
    count: 48
    gap: 236                 # column pitch (x)
    gapY: 210                # row pitch (y)
    direction: grid
    rows: 6
    cols: 8
    clock: { period: 2s }
    stagger: 55ms            # offsets the clone's own clock per copy; no clock, no cascade
FieldTypeDefaultNotes
ofstring (non-empty)— requiredA comp name, else an asset path (which has a file extension). Missing/non-string → expected a source path or comp name; neither a comp nor an asset path → "<x>" names no comp and is not an asset path … — valid comps: ….
countinteger ≥ 00Instance count (ignored by direction: grid, which draws rows × cols). Always serialized. A non-number ("16") is a ParseError, never 0 instances.
gapnumber0Primary-axis pitch in px. Always serialized. A non-number is a ParseError.
directionx|y|grid|radialxLayout axis (or a circular ring).
rowsinteger ≥ 0—Grid rows (direction: grid).
radiusnumber ≥ 0—Ring radius px (direction: radial) — instances spread evenly, first at 12 o'clock. drift then spins the ring in degrees/s (seamless when drift × loop is a multiple of 360/count).
colsinteger ≥ 0—Grid columns (direction: grid).
gapYnumbergapGrid row pitch in px.
driftvelocity (px/s)—Seamless belt velocity along the row / column; the belt wraps within count × gap px. A grid does not drift.
staggerduration—Per-instance clock-phase offset (the cascade). It offsets the clone's own clock:; with none it does nothing.

The clone's own clock animates each copy (x, y, scale, scaleX, scaleY, rotate, opacity; skew is not applied per copy), copy i running i × stagger behind the first. A comp source is rasterized once per frame and that one texture is instanced, so every copy shows the same frame of the comp's own animation. A text's letters cascade the same way, one letter (word, line) per copy, with letters: { stagger, order, clock } on the text (§4 text, letters).

rows, cols, gapY and radius must be numbers too (rows/cols whole). Unknown keys inside the clone: map stay inside the map, and unknown sibling keys stay siblings — each re-serializes where it was written.

Seamless belts: a drifting belt loops cleanly only when drift × loop is a whole number of gaps — e.g. -160px/s × 4s = 640 = 4 × 160. See docs/clocks-and-animation.md. With a stagger AND a clock, each copy carries its own phase, so a whole number of gaps is not enough: copy i lands in copy i + k's slot with a different phase and the animation jumps at the wrap. Make drift × loop a whole number of belt widths (count × gap) instead. A radial drift is read as degrees/s whatever its unit (drift: 45 or 45px/s; it re-serializes as 45px/s). The properties panel's clone section offers radial too, with a radius (px) field, and its drift reads °/s. Picking radial sets no radius, so the copies stack until one is typed.

particles — a particle system

Sparks, dust, snow, embers, confetti, stars: sprites born at rate per second from an emitter, each flying its own path for its life, sized, faded and tinted over that life (model/particles.ts, registry/particles-sim.ts). One node, one draw call. Scene format v17.

- transform:
    - particles:
        of: assets/spark.png        # optional: an asset or a comp, as for clone; absent = a soft dot
        seed: 7
        rate: 120                   # births per second
        life: 2.5s
        lifeRandom: 0.3             # ±30 %
        emitter: { shape: ellipse, size: 600x200, from: edge }
        angle: -90                  # 0 = right, 90 = down (the gradient rule); or outward
        spread: 30                  # the launch cone's width in degrees; 360 = every way
        speed: 240                  # px/s
        speedRandom: 0.4
        gravity: { x: 0, y: 180 }   # px/s²
        drag: 0.6                   # 1/s, linear
        turbulence: { amount: 80, scale: 400, evolve: 1, octaves: 2 }
        size: 18                    # px at birth
        sizeRandom: 0.5
        color: $team.gold           # the tint, when there is no overLife.color
        rotation: 360               # random start angle range, degrees
        spin: 120                   # each particle turns a random -120..+120 °/s
        overLife:                   # keyframe lists on phase = age / life
          size: [0.3, 1, 0]
          opacity: [0, 1, 1, 0]
          color: ["#FFFFFF", $team.gold, "#FF4800"]
        trail: { length: 150ms, samples: 5, fade: 1 }
        max: 4000
      blend: add
  position: { x: 960, y: 980 }
  anchor: 0

Every param is optional and lives inside the particles: map (- particles: {} is a working system); only authored values are stored. Keys the map does not know stay in it, as a clone's do; a key the nested maps (emitter, turbulence, trail, overLife) do not know is an error.

FieldTypeDefaultNotes
ofstringa soft dotAn asset path or a comp name, by clone.of's rules (a comp is rasterized every frame; cycles, typos, renames and asset references follow it). size sets the sprite's longer side.
seedwhole number0Another seed is another pattern of the same system. The app writes a random one on create and on duplicate.
ratenumber > 040Births per second, snapped so rate × loop is a whole number (at least 1).
lifeduration > 02sHow long each particle lives.
lifeRandom, speedRandom, sizeRandom0..10± fraction (0.3 = ±30 %).
emitter.shapepoint | line | rect | ellipsepointCentred on the node's origin.
emitter.size / emitter.lengthsize / px100x100 / 100A rect's or an ellipse's box; a line's length, along x.
emitter.fromarea | edgeareaBorn anywhere inside a rect / ellipse, or on its outline.
angledegrees, or outward-90The launch direction: 0 right, 90 down, -90 up. outward: away from the emitter's centre (a ring burst); from a point, every way.
spread0..36030The launch cone's full width.
speedpx/s ≥ 0120
gravity{ x, y } px/s²noneA sideways one is a wind.
drag1/s ≥ 00Linear: 1 slows a particle to about a third of its speed in a second.
turbulence{ amount, scale, evolve, octaves }noneA curl-noise push off the path: amount px (60), features scale px wide (300), evolve whole field cycles per scene loop (1; 0 = a still field), octaves 1..4 (2). turbulence: {} is on with the defaults.
sizepx > 012At birth.
colorcolour#ffffffThe sprite's tint (#hex / $token), multiplied into it.
rotation / spindegrees / °/s0 / 0A random start angle in a range that wide; each particle turns a random speed between -spin and +spin.
overLife.size / .opacity / .colorkeyframe lists—On phase = age / life (0 born, 1 dies), shorthand or long form with eases. size multiplies size, opacity is 0..1, color keys (hex or $token, OKLab-blended) replace color.
trail{ length, samples, fade }nonesamples (1..16, 4) copies of each particle's own past, the last length ago (150ms), fading by fade (0..1, 1). trail: {} is on with the defaults.
maxwhole 1..200002000Sprites per instance: particles × (1 + trail samples).

A pure function of time. A particle's state is a closed-form function of the scene time and the seed, never stepped frame to frame (docs/clocks-and-animation.md §3 "Particles"). So scrubbing, delay, span, the loop wrap, nested comps and parallel export segments all draw the same frame, and preview and export are the same pixels.

  • The loop is seamless by construction. Births repeat every scene loop: N = rate × loop births per loop, one per slot, and every random a particle draws is keyed by its slot. At the start of the loop the particles born near its end are still in flight, so the system never starts empty and never jumps at the wrap. A life longer than the loop shows two generations of each particle at once.
  • Its clock is its layer's. The node's own clock: moves, scales, turns, skews and fades the WHOLE cloud like any layer's (the cloud lives in the node's space: a moving parent carries it). A span reveals a system that is already running.
  • The budget. max caps the sprites one instance draws; every surface, every tile of a tile-x surface and every use: of a comp holding it is its own instance. Over max the rate is lowered to fit (the Properties panel says so, and MCP writes return a warning); when even one birth per loop needs more (a life of several loops, a long trail), the warning says it is still over. A scene should stay under 20 000 sprites in all, over every surface, tile and comp use (PARTICLES_SCENE_BUDGET, particlesSceneSprites); past it, MCP writes and the panel say so.
  • What it does not do. Turbulence displaces each particle off its path; it does not advect particles along streams. There is no flocking, no collision and no fluid solver: each of those needs the other particles' history, which a pure function of time does not have.
  • In the app. The palette's particles row makes soft dots drifting up, faded in and out, blend: add, with a random seed. Properties › particles edits every param but the over-life curves (write those in the scene).

use (ref) — instance a comp

- use: td-stack            # instance the comp named "td-stack"
FieldTypeDefaultNotes
usecomp name (non-empty)— requiredNon-string → expected a comp name.

Like any node, a use: takes a delay: — the per-copy time offset: several use: layers of one comp, each a little later, chase each other (delay).

(The keyword is use; the model kind is ref. A surface binding's use: is the same idea at the surface root — §3.)

A use: of a framed comp is a w×h box: the comp's content is cropped to its frame, and the transform holding the use: places and scales the box (§3).

An unknown comp name is a parse error, naming the valid comps: comps.main.0.use — unknown comp "td-stak" — valid comps: main, td-stack. So is a comp that instances itself — directly, or through other comps' use: / comp-naming clone.of — reported once at the reference that closes the loop: comp cycle a → b → a — a comp cannot instance itself, directly or through other comps (collectCompRefIssues, model/comps.ts). A clone's of: naming no comp is an asset path; one that has no file extension either is rejected as a typo'd comp name.

matte — the matte composite

Masking is a node: a matte cuts its content (what you see) by the coverage of its matte input (the shape that cuts it — never drawn itself). Full detail — the lowering onto the fused composite pass, the matte cache, the editor tools: docs/masks.md.

- matte:
    content:                   # required: ONE node — what you see
      transform:
        - video: assets/plates/N-tile-a.mp4
      position: { x: 0, y: 0 }
    matte:                     # required: ONE node — the shape that cuts it
      transform:
        - path: [ … ]          # drawn with the pen, or any visual node
          fill: "#ffffff"
      position: { x: 800, y: 200 }
    mode: alpha                # alpha (default) | luma
    invert: false              # default false
    feather: 40                # px in the CONTENT's space, default 0
    opacity: 1                 # 0..1 matte strength, default 1
    range: [0, 1]              # scene v18: remap of the matte value, default [0, 1]
FieldTypeDefaultNotes
contentone node— requiredAny visual node (a transform, group, plate, text, clone, use, an adjustment layer…). A list → expected ONE node — wrap several in a group.
matteone node— requiredAny visual node; its coverage cuts the content and it is never drawn. Not audio, not an adjustment layer.
modealpha|lumaalphaalpha = coverage (a shape's alpha); luma = Rec. 709 luminance over black. Anything else → matte mode must be alpha or luma.
invertbooleanfalseKeep everything OUTSIDE the matte.
feathernumber ≥ 00Edge softening across ≈ feather px (Gaussian, σ = feather/4), in the content node's px.
opacitynumber 0..11The matte's strength: mix(1, matte, opacity); 0 leaves the content uncut.
range[low, high], 0 ≤ low < high ≤ 1[0, 1]Scene v18. A remap of the matte's value FIRST, before the feather, invert and opacity: below low cuts, above high keeps, linear between. Near / far on a depth matte (white = near: [0.5, 1] keeps the nearer half), a choke on a soft matte. Anything else → a matte range is [low, high] with 0 ≤ low < high ≤ 1 ….

Both inputs and every setting live inside the matte: map (only authored settings serialize; unknown keys inside the map are kept there). The matte node adds no transform — each input keeps its own, so the shape sits where you place it — and nothing is referenced by id. Common fields sit beside the keyword: bypass: true shows the content uncut (the matte stays hidden, the matte node's own effects and blend off), effects apply to the cut result, blend composites it. The cut applies before the content node's own spatial effects (a blur on it softens the edge). A group as the matte input unions shapes; a matte node (invert: true) as the matte input subtracts; an adjustment layer as the content is a masked adjustment layer (adjust). A cut image / video plate costs no extra pass — through its positioning transform too.

A matte version as the matte input (masks.md §8): a clip's person, depth or roto mask is a version of the clip. Cut layer writes the cut on the clip itself, inside its transform, with a second video of the same clip that names the matte version (the "twin"):

- transform:
    - matte:
        content: { video: assets/singer.mp4 }
        matte: { video: assets/singer.mp4, version: depth-1a2b3c4d }   # the twin
        mode: luma
        range: [0.5, 1]
  position: { x: 1333, y: 24 }

The twin plays its clip's timing (the same src: one offset and loop; the clip's trim when it has none of its own) and lays out at the clip's size, so the mask stays on the picture. Where the matte file is missing or no longer matches the clip, the content draws uncut: a matte version never falls back to the clip. A twin may also be one shape of a group used as the matte (a union). A video naming a matte version outside every matte input is not used: it plays its original. Scene v18.

An image's depth matte is the same shape with an image: matte: { content: { image: <p> }, matte: { image: <p>, effects: [{ depth: {} }] } }, luma. The depth effect (texture stage, no params) swaps the image for its grey depth map (white = near), made once on a Mac and saved at assets/.depth/<name>-<hash>.png (masks.md §8). Where the map is not made, the cut is dropped and the image draws uncut: never cut by the photo. Scene v18 while a depth effect is used.

v1 mask: — scene-format 1 wrote masks as mask: { source: <id>, … } on the cut node, naming a matte-only node elsewhere. It is still read, and migrated into a matte node at parse (the next save writes the matte node); a v1 mask that no matte node can express without changing the picture is a parse error naming the fix (masks.md §7).

adjust — an adjustment layer

No content of its own: its effects, opacity and blend apply to every sibling below it in the same list (the earlier entries of the comp / group / transform / surface binding), like an After Effects adjustment layer. Siblings after it draw on top, untouched. To limit WHERE it applies, make it the content of a matte node standing in its place.

- video: assets/plates/N-tile-a.mp4       # adjusted
- text: "TOUCHDOWN"                        # adjusted
- matte:                                   # a masked adjustment layer
    content:
      adjust: {}
      opacity: 0.8                         # 0..1 strength, default 1
      blend: screen                        # the result over the unadjusted layers (normal = replace)
      effects:
        - hue-saturation: { saturation: 25 }   # colour ops → one LUT, one pass
        - blur: { amount: 6 }                  # + one pass per spatial effect
    matte: { shape: ellipse, size: 2400x1200, fill: "#ffffff" }   # where it applies
    feather: 60
- image: assets/logo.png                   # above it: not adjusted
FieldTypeDefaultNotes
adjust{}— requiredThe keyword. A bare adjust: or adjust: true parse too and re-emit as adjust: {}; keys inside the map are preserved there. Anything else → expected adjust: {} — an adjustment layer has no content of its own ….
opacitynumber 0..11The adjusted result mixed over the unadjusted layers. Non-number → expected an adjustment opacity 0..1; out of range → validation error. Serialized only when set.
clockclock block—Drives opacity (tracks, drives) and the gate only — any other track → parse error.

Several adjustment layers stack in list order (the upper one adjusts the lower one's result). The layers an adjustment covers render isolated, like a precomp: blend modes among them composite against each other, and an ancestor's hardware mode lands on the adjusted result instead of reaching in. An adjustment that changes nothing (bypassed, opacity 0, nothing below it, or no active effect and a normal blend) costs nothing. It is never a matte input and carries no texture-stage effect (cutout). Full reference — the math, the GPU path, export strips and the cost per adjustment: docs/adjustment-layers.md.

node — an extension's node type

A node type an extension registers (api.registerNodeType('badge', …), docs/mcp-and-extensions.md) is written with the node: keyword, its own props as siblings, because the parser does not know the registry. The palette's create row for an extension kind writes the bare - node: badge.

- transform:
    - node: badge          # the kind the extension registered
      size: 120            # its own props, kept on the node as they are (node.size)
      fill: "#ff0000"
  position: { x: 400, y: 200 }

The fields on every node (id, clock, effects, blend, bypass, span, delay) work as usual; every other key is the extension's (a built-in keyword such as text: beside node: is one of its props), round-trips verbatim, and is checked by the extension's own schema when it builds. A scene holding one is v6 (§1). node: text (a built-in kind) → text is a built-in node — write it with its own keyword (text: …); a missing or non-string kind → expected the node type an extension registered, e.g. node: badge. The scene parses and saves without the extension, but drawing the node needs it loaded (its builder).


5. Value scalars

The scalar vocabulary (model/values.ts). All are normalised to a canonical in-memory form and re-serialized to a canonical string, which is what makes the round-trip a fixed point.

ScalarAuthored formsNormalised toSerializes asParser
Size1920x1080, 1920×1080, { width, height } (both > 0){ width, height }WxHparseSize
Duration4s, 250ms, bare number (= ms)milliseconds (number)Ns for whole seconds, else NmsparseDuration
Velocity-120px/s, bare number (= px/s)px/second (number)Npx/sparseVelocity
Vec25, [x, y], { x, y }{ x, y }number if x == y, else { x, y }coerceVec2
Colour#rgb/#rgba/#rrggbb/#rrggbbaa, $tokenstring (verbatim)as authoredisHexColor / isTokenRef
Token$name, $dotted.namestring refas authoredisTokenRef

Notes:

  • Size accepts the ASCII x or the Unicode ×; whitespace around it is tolerated. A bad size → expected WxH; a zero or negative side → expected WxH with a width and height > 0 (got 1920x0). (YAML reads 0x10 as the hex integer 16, so it is expected WxH.)
  • Duration normalises to ms, so 4s, 4000ms, and 4000 are the same value and always re-serialize as 4s. A bad duration → expected a duration like 4s or 250ms.
  • Velocity normalises to px/s and always re-serializes with the px/s unit. A bad velocity → expected a velocity like -120px/s.
  • Vec2 collapses a scalar to {x, y} equal on both axes; scale: 1.05 and scale: { x: 1.05, y: 1.05 } are identical, and serialize back to 1.05.
  • Colour is any #hex (3/4/6/8 digits — 4/8 carry alpha) or a $token; it is stored as-authored and resolved separately (§6). It is checked at parse on every colour field (fill, stroke, stop color): #ZZZ, a bare number, or a CSS name like white → expected a colour — #rgb, #rgba, #rrggbb, #rrggbbaa, or a $token (got "#ZZZ"). A text's still fill may also be none (no fill, scene v14). Quote hex colours — an unquoted #fff starts a YAML comment, and the error says so (got nothing — quote a hex colour …).

6. Tokens

A $token is a late-bound reference resolved through a two-level chain (model/tokens.ts): the scene theme first, then the project brand.theme, following $-references until a literal (non-$) value is reached.

fill: $primary
  → scene.theme.primary  = $team.gold      (scene alias → brand token)
  → brand.theme["team.gold"] = "#FFB81C"   (literal — done)
  • Two brand spellings, one meaning. brand.theme may use dotted keys (team.gold: …) or nested maps (team: { gold: … }); a lookup tries the exact dotted key first, then walks the nested path. Both resolve.
  • Where tokens are resolved. Colour-bearing fields — text.fill, text.stroke, shape.fill, shape.stroke, path.fill, path.stroke, particles.color, gradient stop colours, and #hex/$token effect params — and the keys of an animated colour (a stop's, a shape's, a path's or a text's fill / stroke list, a text's letters.clock.tracks.fill, a particle system's overLife.color). Resolution produces a token-resolved twin of the scene; the authored scene (with $tokens intact) is what's saved. A token key keeps its name and plays the colour it resolves to, so a brand-kit change re-colours the animation too.
  • Errors. An unresolved token (unresolved token $x) or a reference cycle (token cycle at $x) raises a TokenError anchored to the field path. The MCP write_scene guard rejects unresolved tokens too. Fix by defining the token in the scene theme or the brand kit, or by using a literal #hex.

7. Fit modes

How a surface's artboard (the scene design, or the surface's own design) maps into its output resolution (size) (Fit, model/scene.ts). Set per surface (scene binding), falling back to the project surface's fit, then none.

FitBehaviour
noneNo scaling — artboard pixels map 1:1 at the surface origin (default).
fillStretch to the surface on both axes (aspect not preserved).
coverScale to cover the surface, preserving aspect, centred; overflow is cropped.
containScale to fit inside the surface, preserving aspect, centred; letterboxed.
tile-xScale to the surface height, then repeat horizontally (ribbons/belts).
tile-yScale to the surface width, then repeat vertically.

Tiles start at the left (tile-x) or top (tile-y) edge, at most 64 of them; the last is cut at the edge. Everything is clipped to the surface rect (applyFit, compositor/surface-renderer.ts).

The exact math and the multi-surface compositor are covered in docs/export-rendering-and-building.md. The authoring rule that matters: pair tile-x with a band-native per-surface design (§3) so ribbon marks read at true height.

A master at the artboard's size is an export option, not a surface. A scene authored at the plate's pixels (design: 3840x2160) on a 1920×1080 surface at fit: fill plays at 1920×1080. For a 3840×2160 file, export with size: design (MCP export_scene / export_scenes / export_reel, or the ⌘E sheet's size › design): the surface renders at its artboard's size, sharp. It needs fill, cover or contain at the surface's shape. Never add a surface to project.yaml, or a binding for a made-up surface, for a master (export-rendering-and-building.md §6).


8. Clocks, cues, and effects (summary)

Animation is authored in phase space (0..1 around the loop), so loops are seamless by construction. Full detail — the sampler, easing curves, named-clock graphs, cues, and triggers — is in docs/clocks-and-animation.md. The essentials as they appear in scene YAML:

A node's clock. Any node carries a clock block: a period (which should divide the scene loop), a mode (loop default, or once / pingpong), and tracks (property → keyframes).

clock:
  period: 2s
  tracks:
    scale: [1, 1.16, 1]        # SHORTHAND — values spread evenly over phase 0..1
    skewX:                     # LONG FORM — explicit phase + ease
      - { phase: 0.0, value: 0,   ease: snap }
      - { phase: 0.08, value: -12 }
      - { phase: 1.0, value: 0 }
  • Animatable props: x, y, scale, scaleX, scaleY, rotate, skewX, skewY, opacity (scale is uniform and multiplies scaleX/scaleY). An unknown property is a ParseError.

  • x and y tracks add to the static position. A key of 0 means "at position", so key how far the layer moves, not where it lands:

    - transform: [ { text: "ROW" } ]
      position: { x: 800, y: 540 }            # where it rests
      clock: { tracks: { x: [0, 400, 0] } }   # x 800 → 1200 → 800

    The place written into the track (x: [800, 1200, 800]) draws the layer at 1600 → 2000, twice as far. rotate, skewX and skewY tracks add to the static values too; scale, scaleX, scaleY and opacity tracks multiply them (clocks-and-animation.md §4).

  • Shorthand [a, b, a] distributes keyframes at even phases with the smooth default ease (cubic-bezier(.4,0,.2,1)) on every non-terminal keyframe.

  • ease (the segment leaving a key, to the next one) is one of:

    • a cubic preset: linear, ease, ease-in, ease-out, ease-in-out, smooth, snap, overshoot, expo-in, expo-out, expo-in-out, back-in, back-in-out;
    • a custom cubic: cubic-bezier(x1,y1,x2,y2), [x1,y1,x2,y2] or {x1,y1,x2,y2} — x1/x2 in 0..1 (they are time), y1/y2 free (overshoot);
    • a step: hold (keep the value until the next key) or steps(n) — n (a whole number ≥ 1) equal jumps across the segment, each at the end of its step; steps(n, start) jumps at the start (steps(n, end) is the default spelled out; steps(1) writes back as hold);
    • a function: elastic, bounce or spring, each settling onto the next key. Two take settings: spring(bounce), bounce from 0 (never passes the target) to 0.95 (plain spring is 0.5), and elastic(amplitude, period), amplitude 1 or more and period above 0 up to 1 of the segment (plain elastic is 1, 0.3).

    The same values work on animated effect params and gradient attributes (a colour key included). The gate takes no ease. None of these needs a newer schemaVersion: an older Starlight refuses a scene that uses one (unknown ease "hold") rather than misreading it. (clocks-and-animation.md §6.) Omit period to inherit the scene loop.

  • A long-form phase is a number in 0..1, like a cue phase.

  • Per-frame samples (scene v12), for tracking data and baked motion: a track can be { fps, start, values } instead of a key list, one value per frame at fps, the first on frame start of the clock (default 0), straight lines between; null is a frame with no sample. The parser places them on the clock's period as linear keys (the first value holds before start, the last after the end), and the serializer writes them back in this form while the keys still sit one per frame with straight segments (clocks-and-animation.md §5). Clock tracks only: on an effect param or a gradient attribute it is an error. MCP import_track and track_region write them from tracking data (clocks-and-animation.md §5).

    clock:
      tracks:
        x: { fps: 29.97, start: 187, values: [1640, 1620, 1580, 1520, 1440, null, 1220] }

Named clocks (scene.clocks). Shared timing sources — { period?, mode? } (plus optional cues, trigger, and the beat-clock fields offset: — a duration, where phase 0 lands — and unwrapped: true — sample the song's unwrapped time, not the loop) with no tracks. A node references one with clock: { use: <name>, tracks: {…} }, drawing period + mode from it. A period can be a concrete duration or a derived ratio scene/N (the scene loop ÷ N; scene alone = ÷1). Carrying a local period/mode beside use: is a validation error, and an unknown use: is rejected naming the valid clocks.

clocks:
  heartbeat: { period: 2s, mode: loop }
  quarter:   { period: scene/4 }          # derived: scene loop ÷ 4
comps:
  main:
    - text: "A"
      clock: { use: heartbeat, tracks: { scale: [1, 1.1, 1] } }

Cues + triggers. A cue is a named phase point on a clock's loop. Named clocks carry their own cues: (name → phase 0..1); the scene clock's cues live at scene.cues (the scene loop isn't in the clocks: map). A named clock may carry a trigger: { from, cue } — it starts when clock from reaches cue cue (from is a named clock or the literal scene). Trigger chains compose and wrap mod the scene loop; a chain that loops back (a → b → a) is a parse error. A triggered clock is loop-perfect only when it starts on a whole cycle of its period (docs/clocks-and-animation.md §11).

cues:                      # cues on the scene clock (the loop)
  impact: 0.25
clocks:
  flash:
    period: 1s
    trigger: { from: scene, cue: impact }   # starts at the scene's "impact" cue

Effects (effects). A stack of GPU effects on a node, authored as a list of single-key maps — { <effectName>: { …params } }. A param is a const (a number, a #hex/$token colour, or a choice string such as feather's curve: linear) or an animated keyframe list (animatable params only). Animated params ride the host node's clock (its period/mode, or the named clock it uses, trigger offset included; the scene loop when the node has none), so they move with the node's transform keys; a reserved clock: key on the effect, { period?, mode? }, gives the effect its own clock instead (clocks-and-animation.md §4). The properties panel's ◇ chip on each animatable param writes exactly this form.

- text: "GOAL"
  clock: { period: 2s, tracks: { scale: [1, 1.16, 1] } }
  effects:
    - glow:
        color: $primary
        radius: 7
        intensity: [0.12, 0.6, 0.15]  # animated — rides the node's 2s clock
    - chroma-shift: { angle: 0, offset: [0, 3, 0], clock: { period: 1s } }  # its own clock
    - scanlines: { gap: 3 }           # an extension effect (see below)

Each entry must have exactly one key (the effect name); zero or multiple keys is a ParseError. Its value must be a map — - cutout: {} for an effect with no params (a bare - cutout: is effect "cutout" params must be a map). An effect name the live registry does not know is kept on save and builds nothing when rendered (it may be an extension that is not loaded or not trusted yet); only the MCP writers reject it. Effect names (including extension effects) and which params are animatable come from the MCP get_project catalog — see docs/mcp-and-extensions.md. The parser does not know the registry, but MCP write_scene / create_scene / compose do: an unknown effect, an unknown or non-animatable param, a choice outside its options, or a wrong-typed value is rejected against the live catalog (§11). The built-in effects and their params are tabled in docs/mcp-and-extensions.md → Built-in effects (e.g. - feather: { left: 800 } — edge alpha ramps for overlapping AI tiles).

Effect modules (effects/<name>/ in the project, effects.md) are used by their name, exactly like a built-in: - ripple: { amount: 8, scale: [4, 12, 4] }. No new schemaVersion: the stack already takes any registered name. Their params map to the scene like this: a number, a whole number or a choice as usual; an on/off as 0 or 1; a colour as a #hex or a $token; a point or vector as one number per part (center → centerX, centerY, and Z, W for 3 and 4 parts), each one able to animate; a curve as text, "0,0 0.5,0.8 1,1"; an image or clip input as an asset path (dust: assets/dust.png). A module that is not loaded (a broken rule, a compile error) is kept on save and draws nothing, like any unknown effect.

Colour effects (exposure, brightness-contrast, hue-saturation, levels, curves, color-balance, temperature-tint, invert, lut) are point ops. All of a node's colour effects fuse, in stack order, into ONE baked LUT that is applied before the node's spatial effects, wherever the colour entries sit in the list. Full reference: color.md. Two param shapes are specific to them:

effects:
  - curves: { master: "0,0 64,52 192,206 255,255", red: "0,0 128,140 255,255" }  # "x,y …" in 0..255
  - levels: { inBlack: 16, inWhite: 235, gamma: 1.1, redGamma: 0.95 }              # 0..255 units
  - lut: { file: assets/luts/film.cube, strength: 0.8 }                            # a .cube asset path

A curve is a string of x,y control points (0..255, at least two, separated by spaces; ; and newlines also work), so it is not animatable. Every numeric colour param is animatable. write_scene rejects a malformed curve, an unknown colour param and an invalid choice (invert.channel), naming the param. A lut file counts as an asset reference: it blocks rename/delete of the .cube, and Replace rewrites it.


9. IDs and the round-trip contract

Every node has a stable string id, but scenes almost never write one. An id is auto-derived on parse as a pure function of the node's kind and its positional path in the document (comp/surface name + child indices), via a tiny FNV-1a hash (autoNodeId, model/ids.ts). Because the path survives serialize unchanged, re-parsing regenerates identical ids — so the round-trip is a fixed point without writing ids to disk.

The serializer recomputes each node's auto id and omits id when it matches. Therefore:

  • Omit id almost always — clean YAML, ids regenerated deterministically.
  • Write an explicit id only when you need identity to survive structural edits (reordering, re-nesting), because a positional auto id changes when a node's path changes. An explicit id overrides the auto id and is written back on serialize.

This is why the demo scenes contain no id: keys: they are all auto-derived.


10. Forward tolerance

Unknown keys are preserved, not rejected. At every level — project, scene, surface binding, node, and the inside of a clone or particles map — any key the parser doesn't recognise is collected onto an unknown bag and re-emitted verbatim on serialize. This lets a newer document survive an older reader (and a stray key like a position: on a non-transform node is silently kept rather than crashing the parse — though it has no effect). The clock block is a known key lowered to the typed model, not an unknown-bag passenger. The scene's stages: map rides the bag on purpose: its accessor (src/engine/stage3d/scene-stages.ts) is the only code that knows where stages live, and only the write paths validate it (§3).


11. Errors

Parse and token errors are friendly and path-anchored (model/errors.ts). The format is:

scenes/03-touchdown.yaml: surfaces.ribbon-main.size — expected WxH

i.e. <source>: <dotted.path> — <message>. Multiple issues are listed together. ParseError covers structural/schema problems; TokenError covers unresolved tokens; the low-level scalar parsers throw a path-free ValueError that the caller re-anchors.

What triggers a validation error:

TriggerMessage (shape)
No node keywordexpected a node keyword (text, image, …)
Multiple node keywordsambiguous node — multiple keywords present: …
Bad shape: valueexpected rect, ellipse, or line
Bad gradient: valueexpected linear or radial
Bad path: value (not a list)expected a list of subpaths
Malformed subpath / vertex / pointexpected a subpath { vertices, closed } / expected a list of vertices / expected a vertex { p, in, out } / expected a point [x, y]
Non-string image:/video: srcexpected an asset path
Bad scalar (size/duration/velocity/vec2)expected WxH / expected a duration like 4s or 250ms / …
A size with a zero or negative side (surface, design, shape, gradient, project surface)expected WxH with a width and height > 0 (got <w>x<h>)
A colour that is not #hex / $token (fill, stroke, stop color)expected a colour — #rgb, #rgba, #rrggbb, #rrggbbaa, or a $token (got "<x>"); on a shape's, a path's or a text's fill (and a shape's or a path's stroke), which may be a list, … a $token, or a list of colours to animate it (got "<x>"); a key in a colour list → "fill" keyframe <k> needs a colour — #rgb, #rgba, #rrggbb, #rrggbbaa or a $token (got "<x>") (an unquoted #… → got nothing — quote a hex colour …)
A gradient stop offset out of range / not a numberstop offset <n> is out of range 0..1 / expected a stop offset 0..1 (got "<x>")
A bad gradient keyframe list (scene v4) — a colour key that is neither a hex nor a $token, a key out of range, a malformed center / sizestops.<i>.color — … keyframe <k> needs a colour — #rgb, #rgba, #rrggbb, #rrggbbaa or a $token (got "<x>") / stops.<i>.offset — keyframe <k>: stop offset <n> is out of range 0..1 / radius <n> must be 0 or more / size.width — keyframe <k>: width <n> must be more than 0 / center — expected [x, y], { x, y } or a number …, or { x: [..], y: [..] } to animate an axis
A clone number that is not a number (count, gap, rows, cols, gapY, radius)expected a whole number ≥ 0 (got "16") / expected a number (got "<x>") / expected a number ≥ 0 (got <n>)
A surface / node use: naming no compunknown comp "<x>" — valid comps: …
A clone.of that is neither a comp nor an asset path"<x>" names no comp and is not an asset path (an asset path has a file extension, e.g. assets/logo.svg) — valid comps: …
A comp that instances itself (directly or through other comps)comp "<x>" instances itself — a comp cannot contain itself / comp cycle a → b → a — a comp cannot instance itself, directly or through other comps
A long-form keyframe phase out of range / not a number (tracks, gate, animated effect params)"track <prop>" keyframe <i> phase <n> is out of range 0..1 / … keyframe <i> needs a numeric phase (0..1)
An ease x1/x2 outside 0..1, or a non-number control pointease x1 <n> is out of range 0..1 — x control points are time (y1/y2 may overshoot) / ease x1 must be a number (got NaN)
An unknown ease, or a bad steps()unknown ease "<x>" (a name like smooth or hold, steps(n), or cubic-bezier(...)) / steps(<n>) needs a whole number of steps ≥ 1 / steps(<n>, <x>) jumps at start or end
Unknown animatable property in a trackunknown animatable property "<x>"
A bad per-frame track (scene v12)….clock — "track x" needs fps: the frames per second of its values, a number above 0 up to 1000 (got null) / "track x" start is the frame of the first value: a whole number, 0 or more (got -1) / "track x" needs values: a list with one number per frame, e.g. values: [0, 2.5, 5] / "track x" value 3 must be a number, or null for a frame with no sample (got "a") / "track x" needs at least one number in values / "track x" — a per-frame track is { fps, start, values }; "ease" is not one of its keys
Per-frame values past the end of their clock….clock.tracks.x — 600 values from frame 0 at 29.97 fps run to frame 599 (19.99 s), past the end of its clock: 18.42 s, whose last frame is 552. Drop the last 47 values, or make the clock longer.
Per-frame samples on an effect param or a gradient attribute"<label>" — per-frame samples ({ fps, values }) work on clock tracks only (x, y, scale, scaleX, scaleY, rotate, skewX, skewY, opacity); write keys here
clock.use naming no scene clockunknown named clock "<x>" — valid clocks: …
use: beside a local period/modea clock with use: … takes its period and mode from that named clock — remove the local period/mode
Bad modemode must be once, loop, or pingpong
A trigger's unknown from clockunknown trigger source "<x>" — a named clock or "scene"
A trigger's missing cue on fromclock "<from>" has no cue "<cue>"
A clock triggering its own cueclock "<x>" cannot trigger off its own cue
A multi-clock trigger cycle (once per cycle)trigger cycle a → b → a — a clock cannot start off a chain that leads back to itself
A matte: that is not a map / misses an input / takes a listexpected { content: <node>, matte: <node>, … } / ….matte.content — expected the node to cut — content: { video: … } / ….matte.matte — expected the node whose shape cuts the content — matte: { path: … } / expected ONE node — wrap several in a group: { group: [ … ] }
Audio as a matte's content; audio or an adjustment layer as its matte inputthe content is an audio node — a matte cuts pixels, and audio has none / the matte input "<x>" is an audio node — it has no pixels to cut with / the matte input "<x>" is an adjustment layer — it has no pixels of its own …
A bad matte settingmatte mode must be alpha or luma / expected true or false / expected a feather in px (a number ≥ 0) / expected a matte opacity 0..1 / a matte range is [low, high] with 0 ≤ low < high ≤ 1 …
A v1 mask: no matte node can expressmask source "<x>" contains "<n>" or sits inside it — … / … lives in another comp or surface than "<n>" — … / … sits inside "<t>", whose clock the cut node does not share — … / "<n>" has spatial effects inside the wrapper "<w>" — … / mask chain from "<n>" loops back to itself … / mask source "<x>" names no node in the scene (masks.md §7)
effects / blend / clock / span on a matte node cutting an adjustment layera matte node cutting an adjustment layer carries no <field> of its own — put it on the adjustment layer (its content)
A scene newer than this buildschemaVersion — this scene is schemaVersion <n>, written by a newer Starlight — this build reads up to 18; update Starlight to open it
A bad particles value (scene v17)….particles — expected { rate, life, emitter, … } — a particle system's settings (got 7) / ….particles.rate — expected births per second, a number above 0 (got "fast") / ….particles.life — expected a lifetime above 0, like 2s or 250ms / ….particles.speedRandom — expected a fraction 0..1, 0.3 = ±30 % (got 30) / ….particles.emitter.shape — expected point, line, rect or ellipse (got "star") / ….particles.emitter.radius — not an emitter key (shape, size, length, from) / ….particles.angle — expected degrees (0 = right, 90 = down, -90 = up) or outward / ….particles.spread — expected the launch cone's width in degrees, 0..360 / ….particles.gravity — expected { x, y } in px/s², e.g. { x: 0, y: 300 } pulls down / ….particles.turbulence.evolve — expected a whole number of field cycles per loop, 0 or more (got 0.5) / ….particles.overLife.opacity — keyframe 1: opacity 1.4 is out of range 0..1 / ….particles.trail.samples — expected a whole number 1..16 / ….particles.max — expected a sprite budget, a whole number 1..20000; a particles.of that names no comp and has no file extension gets the clone's message
A bad text layout value (scene v13)….wrap — expected the width lines wrap at, in px: a number above 0, like 820 (got 0) / ….lineHeight — expected the distance between baselines as a multiple of size: a number above 0, like 1.25 (got -1) / ….maxLines — expected a whole number of lines, 1 or more (got 1.5) / ….overflow — expected ellipsis or clip (got "fade") / ….anchorY — expected top or baseline (got "middle") / ….markup — expected true or false (got "yes")
Content on an adjust: keywordexpected adjust: {} — an adjustment layer has no content of its own; its effects, opacity and blend apply to the layers below it (got …)
A non-number adjustment opacityexpected an adjustment opacity 0..1 (got "<x>")
An adjustment layer's clock driving anything but opacityan adjustment layer's clock drives opacity only (and its gate) — "<prop>" has nothing to move; animate its matte to move the adjusted area
Malformed v1 mask:expected the id of the matte node / matte mode must be alpha or luma / expected true or false / expected a feather in px (a number ≥ 0)
Malformed delay: (on a node or a surface binding)comps.main.0.delay — expected a duration like 4s or 250ms
Malformed span: (not a pair of durations)expected [in, out] — two durations like [1s, 3s] (a bad member → span.<i> — expected a duration like 4s or 250ms)
A span that starts before 0 / ends at or before its inspan in -500ms is before 0 — scene time starts at 0 (a bare -500) / span out 1s must be after its in 2s
A video trim that is not two times / starts before 0 / ends at or before its in (scene v9)expected [in, out] — two times in the source like [5s, 10s] / trim in -1s is before 0 — the source starts at 0 / trim out 2s must be after its in 5s
Cue phase out of rangecue "<x>" phase <n> is out of range 0..1
A malformed markers list (the scene's or a video's)markers — expected a list of markers — a duration, or { at, label, color } / marker <i>: expected a time like 1.5s or 250ms / marker <i>: -1s is before 0 / marker <i>: needs an at — { at: 1.5s } / marker <i>: expected a colour — one of red, orange, yellow, green, blue, purple
A graphColors value, or a note's color, that is not one of the sixgraphColors.<key> — expected a graph colour — one of red, orange, yellow, green, blue, purple (got "<x>") / graphNotes.<i>.color — expected a graph colour — one of …
A malformed graphNotes entryexpected a list of notes { text, x, y, w, h } / graphNotes.<i>.<x|y|w|h> — expected a number (graph px) / … — expected a size > 0 (graph px) / graphNotes.<i>.text — expected the note text
Effect entry not a single { name: {…} }effects[i] must have exactly one effect name …
Schema violation (e.g. opacity > 1, fps > 240, a non-integer count)zod message at the field path

MCP writes only (write_scene, create_scene, compose plans — checked against the live registry catalog after parse; mcp-and-extensions.md):

TriggerMessage (shape)
An effect nobody registered (a typo, an extension that is not loaded)comps.main.0.effects.<i> — unknown effect "<x>" — valid effects: … (before the app has synced its registry: … (the app has not synced its live registry yet, so extension effects are not known — retry shortly))
A param the effect does not declare….effects.<i>.<effect>.<param> — effect "<e>": unknown param "<p>" — valid params: …
Animating a non-animatable parameffect "<e>": param "<p>" is not animatable — animatable: …
A choice param outside its optionseffect "<e>": param "<p>" must be one of a, b (got "<x>")
A wrong-typed constanteffect "<e>": param "<p>" expects a number (got "8") / expects a string (got 7) / expects a colour — #rgb, … or a $token (got "white")
A node kind the registry lacksthe "<keyword>" node type is not registered in this app — registered: …
A texture-stage effect (cutout) on an adjustment layer….effects.<i> — effect "cutout" replaces an image's source pixels — an adjustment layer has none (put it on the image node)
A broken stage (stages:; stage_write gives the same messages)stages.<id>.target — unknown surface "<x>" — valid surfaces: … / stages.<id>.frame — expected "surface" or W:H like 21:9 / stages.<id>.items.<i>.size.y — expected a number > 0 / stages.<id>.items.<i>.id — duplicate item id "<x>" / stages.<id>.camera.focal — expected a focal length in mm from 8 to 1200 / stages.<id> — expected a stage id like hero-walk (lowercase letters, digits and -, up to 48) (stages.md)

The clock.use reference check, the trigger from/cue/cycle check, the matte-input check and the comp-reference check (use: / clone.of existence + cycles) run after schema validation, so a typo in a clock name never silently retimes a node to the scene loop, a matte never silently fails to cut, and a typo in a comp name never silently blanks a surface — each is a hard, named error at parse. (The v1 mask migration runs before schema validation, so its errors come first.)

On this page