Skip to Content
Starlight

MCP server and tools

Starlight is a motion-graphics tool for sports-venue boards that is AI-first, twice (DESIGN.md §2 pillar 4):

  • In-app — ⌘K compose. Claude proposes one plan — a scene edit plus any hosted generations it places; the client quotes, gates, and applies it as one undoable turn. Model plans, never executes.
  • Out-of-app (the moat) — an MCP server ships inside the running app. Point Claude Code at the project folder and it drives Starlight: reads and writes scenes, renders frames it can actually look at, exports finished video, and scaffolds new effects and layer types into the project — hot-reloaded, never touching core.

This document is the developer reference for both paths: the in-app MCP server and its tools, the ⌘K compose loop, the extensions system + registry, the skills pack, and the intended Claude-Code-with-the-app workflow.

See also: architecture.md (the registry and process model), scene-format.md (the YAML the tools read/write), and export-rendering-and-building.md (the ffmpeg export pipeline the export_* tools drive).


1. Why AI-first — the moat

The bet (DESIGN.md §2 pillar 4, §3 "Registry rule"): MCP adds extensions, it never modifies core. A team points Claude Code at their Starlight project and grows the tool into their system — new effects, new layer types (and, planned, new surfaces / export formats). Those additions land as plain files in the project's extensions/ folder and register on the same plugin registry the built-ins use. Core source is never edited.

Two properties make this real rather than aspirational:

  1. Dogfooded plugin API. Every built-in node type (text, image, cutout, video, audio, shape, path, gradient, transform, group, clone, ref, adjust, matte) and every built-in effect (cutout, blur, sharpen, glow, chroma-shift, pixelate, halftone, grain, noise, threshold, feather and the nine colour ops — see Built-in effects) is registered through the exact API extensions/ uses. "If core can't be built on the extension API, the extension API isn't good enough" (DESIGN.md §3). So an extension is a first-class citizen, not a bolt-on.
  2. The catalog is introspected from the live registries. The MCP get_project tool reports node types and effects by reading the running registries — so a team's new effect appears in the tool output (and is teachable to the compose model) the instant it registers. No manifest to update, no restart.

The result: the tool a team ships with on day one is not the tool they have in month three. Starlight is a platform each team extends with Claude Code.


2. The MCP server

Where it runs

The server is hosted in the Electron main process (src/mcp/server.ts, startMcpServer). It is started/​re-homed by pointBackendAt(dir) in src/main/index.ts: on first load and on every Open Project, the old server is closed and a new one starts bound to the newly opened project directory. So the MCP tools always act on the project the app currently has open.

  • Transport: Streamable HTTP (StreamableHTTPServerTransport), stateless.
  • Address: 127.0.0.1:4150, path /mcp → http://127.0.0.1:4150/mcp (DEFAULT_MCP_PORT = 4150, MCP_PATH = '/mcp'). Loopback only — not exposed off the machine.
  • Port fallback: if 4150 is taken, it walks upward (4151, 4152, …) up to MAX_PORT_ATTEMPTS = 12 before failing (listen()).
  • Per-request instances: a fresh McpServer + transport is built per request (sessionIdGenerator: undefined). This is deliberate: a single shared stateless transport gets permanently wedged (500 on every later request) by one stray non-initialize request — e.g. a port scanner or health probe. Registering the 37 tools per request is cheap and makes that failure impossible.
  • Access control (AUDIT BUG-SEC-1): every request passes checkMcpAccess (src/mcp/access.ts) before it reaches a transport or a tool — see Who may call it below. A rejected request gets 403 (Host / Origin) or 401 (token) with a JSON-RPC error body.
  • Any request whose URL does not start with /mcp gets a 404. A handler throw returns a JSON-RPC -32603 internal error rather than crashing the process.

Gotcha — curling it directly: the transport is Streamable HTTP (SSE). Use curl -N (no-buffer) or the stream never flushes and the call appears to hang, and send the token: -H "Authorization: $(jq -r .mcpServers.starlight.headers.Authorization .mcp.json)".

How a client connects — .mcp.json auto-discovery

On start, startMcpServer loads the project's bearer token (created on first use, see the token lifecycle) and writes <project>/.mcp.json (mcpConfigText, src/mcp/config.ts):

{
  "mcpServers": {
    "starlight": {
      "type": "http",
      "url": "http://127.0.0.1:4150/mcp",
      "headers": { "Authorization": "Bearer <the project's token>" }
    }
  }
}

Claude Code, launched anywhere inside that project folder, reads .mcp.json and auto-discovers the running app — no manual server configuration; its http server entries send headers on every request. Every start rewrites the file whenever it differs, so it always matches the token file and the bound port (a fallback port stays discoverable), and leaves it owner-only (0600). This is the "out-of-app moat" wiring: the app that is running is the MCP endpoint, advertised in the folder Claude Code is already pointed at.

A shared project (one in Dropbox) is the exception: its .mcp.json carries this machine's token, so it is written under this machine's folder for the project (<root>/.mcp.json, shown in Settings › Project; shared-projects.md §2), never into the shared folder. A Claude Code session started in the shared folder does not find it on its own: start it with claude --mcp-config "<root>/.mcp.json". The Claude panel does this for you.

If the Starlight tools are not available in a Claude Code session, the app is not running — start Starlight, and the tools appear. Relaunching the app or re-opening the project keeps the same token, so a session that already loaded .mcp.json keeps working. A 401 / "missing or stale Starlight MCP token" means the token changed after the session read the file (a rotation, or .starlight/mcp-token was deleted) — or the session belongs to another project: reconnect the server in /mcp, or restart the Claude session, so it re-reads the file.

Long calls report progress

An MCP client stops waiting for a call that says nothing for a while. Claude Code (2.1.319, read in its bundled code on 2026-11-06) aborts a call to an http server after 300 s with no response and no progress (sent no response or progress for 300s; aborting); a stdio server gets 30 min. A per-server timeout (ms) in the MCP config raises that limit, but it also caps the whole call; CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT changes it for every server (0 = never). An export can run for 25 minutes and more, and it keeps running in the app after the client gives up. So the long tools send MCP progress (notifications/progress, src/mcp/progress.ts) while they run:

ToolFollowsMessage (Claude Code adds the percentage)
export_scene, export_scenes, export_reelmain's export progress events, the ones the export monitor draws (watchExport)checking the media files · intro, then frame 1200 of 4500 · intro · N · surface 2 of 6 · scene 1 of 3, finishing · intro, joining the reels
glimpse_publish (not a dry run)the same, with the publish's copies and uploadspreparing · intro, then the frames, then N: HEVC copy 42% · intro
glimpse_pullthe Glimpse service's download events (watchGlimpse)downloading N · wall 2 of 6
assets_ingest { wait: true }its batch and the ingest queue, read when a notice goes outingest · clip 2 of 5 · assets/walls/north.mp4
  • Only with a progressToken. The spec allows progress for a request only when it carries params._meta.progressToken. Claude Code's client sends one on every tools/call (it gives the SDK an onprogress, and the SDK adds the token), and each notice resets its 300 s timer. A client that sends no token gets no progress. Nothing else in the protocol resets such a client's timer: the SDK's SSE : keepalive comment (every 15 s) keeps the HTTP stream open, but it is not an MCP message. For that client, raise its timeout, or let it stop waiting: the work keeps running in the app, and cancel_export stops an export.
  • Cadence. A notice 10 s after the last one, and one at once when a milestone starts (each surface, each scene, a publish's copies and uploads, each pulled surface), at most one a second. Frames inside a surface only replace the latest event; they never send.
  • Numbers. progress is the share of the call's work in whole percent, rounded down; total is 100 once the size is known (not during the media check). For an export it is the export monitor's overall percentage (src/shared/export-progress.ts), so Claude Code's (62%) and the app's 62% overall say the same. It always rises, as the spec asks: when nothing moved since the last notice (the media check, finishing a file, joining the reels), it rises by 0.001, too little to change the percentage a client shows.
  • Cost. No timer runs for a request without a token, and none after the call ends, the client cancels the request, or a notice fails to send (the stream is gone, so the notices stop). The work never waits for a notice, and a failed one never reaches it. Main sends its export events to MCP only while such a call listens (createWatchers).

The other tools answer at once or within seconds: gen_create, version_create and prerender_node start a job and return (follow it with its status tool), generate_tiles renders its start frames, and render_*, make_loop, tiles_check and playback_stats (60 s at most) are short. Two can run long with nothing to measure, and send no progress: copy_to_project (copying big media) and compose_run (the planning model).

Who may call it — Host, Origin and the project token

The server binds 127.0.0.1 only, but loopback alone does not keep a web page out: DNS rebinding points a page's own domain at 127.0.0.1, and the browser then treats the endpoint as same-origin. With scaffold_extension writing JavaScript the app hot-loads, that would be a path from a web page to code running in the renderer. So every request must (checkMcpAccess, src/mcp/access.ts, checked in this order):

  1. Name a loopback Host — 127.0.0.1, localhost or [::1], any port. A rebinding page's Host is its own domain → 403.
  2. Carry no Origin, or a loopback one (http(s)://localhost|127.0.0.1|[::1]:*). Claude Code and other Node clients send none; a browser page always sends its own; the null origin of sandboxed frames and file:// is refused → 403.
  3. Present the token — Authorization: Bearer <token>, compared in constant time. No web page can read it (it only exists on disk, in .mcp.json and the token file) → else 401.

Token lifecycle (persistent per project). 32 random bytes (base64url), generated once into <project>/.starlight/mcp-token (owner-only 0600, written temp + rename; projectMcpToken, src/mcp/token.ts). Main restarts the server on every launch and on every Open Project (pointBackendAt); each start reuses the token from that file and rewrites .mcp.json to match, so Claude Code sessions survive app restarts. A new token is generated only when:

  • the file is missing or unreadable (empty, truncated, hand-edited — anything that is not a whole token): it is replaced, and sessions get 401 until they reconnect;
  • STARLIGHT_MCP_ROTATE=1 is set: every start while it is set mints and persists a new token (the old one stops working at once) — use it once to revoke a leaked token.

A read that stalls (a cloud-synced folder whose provider offloaded the file) is not a missing file: after the activation timeout the server starts on a fresh token for that run only and leaves the file alone; the next start reads it again. Each project has its own token, so a Claude session left in the previous project's folder after an Open Project gets 401 instead of silently driving the newly opened project on the same port. The handle reports tokenSource (file / new / rotated / ephemeral) and the start log line says which.

Never versioned. .mcp.json and .starlight/mcp-token hold the secret, and every checkpoint stages the whole tree (git add -A; restore_checkpoint depends on whole-tree snapshots), including the rest of .starlight/ (layout, workspace), which stays versioned. The per-machine list lives in src/shared/unversioned.ts: those two, the token store's interrupted temp writes (.starlight/mcp-token.*.tmp) and Claude Code's per-user .claude/settings.local.json, which the Claude panel's Claude writes when you approve a permission. They are kept out three ways:

  • commitAll makes the repo's own .git/info/exclude list them before it stages. That file is in no snapshot, so a restore to a checkpoint whose .gitignore predates the rules cannot un-ignore them, and add -A never stages or hashes them.
  • Activation appends them to the project .gitignore (idempotent, one append), so a clone and every other git tool agree.
  • Every checkpoint **git rm --cached**s them (--ignore-unmatch), so a copy an older checkpoint committed is untracked by the next one and stays on disk. Activation does the same at project open (untrackPaths), and a restore never puts an old copy back over the live one (restoreVersion excludes them).

Not an :(exclude) pathspec on the add: when the files are ignored, git counts an exclude that names an ignored path as an attempt to add it ("paths are ignored by one of your .gitignore files", exit 1), and every checkpoint would fail. A checkpoint where only these files changed is a no-op (the emptiness check reads staged changes only).

The git-checkpoint discipline on writes

Every mutating tool routes through the app's single writer + git, so every change is a checkpoint you can undo. There is no partial state: a rejected write changes nothing. An accepted write makes one checkpoint. If git cannot make it at that moment, the write is still saved, and the next checkpoint takes it in. Checkpoint messages are uniform:

ActionCheckpoint message
write_scenemcp: write <scene>
create_scenemcp: create <scene>
delete_scenemcp: delete <scene>
rename_scenemcp: rename <scene> → <to>
rename_compmcp: rename comp <from> → <to> in <scene>
precompmcp: pre-comp <n> layer(s) into <comp> in <scene>
set_comp_framemcp: comp <comp> frame <W>x<H> in <scene> / mcp: comp <comp> no frame in <scene>
fit_layermcp: fit <id> to <surface> (<mode>) in <scene>
make_loopmcp: make loop of <id> in <scene> (a tiled surface: mcp: make tiles loop <surface> in <scene>)
plan_tiles / assemble_tilesmcp: tile plan <surface> (<n> × <shape> <tier>) in <scene> / mcp: assemble tiles <surface> (<placed>/<total>) in <scene>
generate_tiles (with confirm: true)mcp: tile batch <batch> for <surface> in <scene>
set_tile_seamsmcp: tile seams <surface> in <scene>
assets_importimport: <file> (as a drop, By: claude)
restore_checkpointmcp: restore <hash7> (the app's own restore: restore: <hash7>)
stage_write / stage_deletemcp: stage <scene>/<id> / mcp: delete stage <scene>/<id>
stage_capture (a new capture; none when reused)stage: capture <scene>/<id>
glimpse_pullglimpse: pull <id> (<look name>)
⌘K compose (scene only)compose: <prompt-slug>
⌘K compose (with generations)compose: <summary>, then import: gen/<file> per output

Every scene write path also validates first (parse + token resolution — see below) and, on success, pushes a SCENE_CHANGED reload so the live canvas updates immediately. To undo any of them, restore_checkpoint the id returned by the write.

The note param: each version's description. The artist's v list shows each version with one short line that says what changed (help #save "What each version says"). Every tool that makes a version takes an optional note for it: write_scene, write_comp, write_node, import_track, track_region (when it writes onto a layer), create_scene, delete_scene, rename_scene, rename_comp, precomp, set_comp_frame, fit_layer, make_loop, restore_checkpoint, canvas_layout, plan_tiles, generate_tiles, assemble_tiles, set_tile_seams, tiles_check { scene, surface }, set_tile_match, stage_write, stage_delete, stage_capture, version_use, matte_use, assets_import and glimpse_pull (and its old name previz_pull).

  • What to write: what changed and why, in a few plain words, naming the surface, scene or layer: "N surface: slower gold shimmer, loop fixed at 27.8 s". Not the tool or the YAML path.
  • Shape: one line, at most 120 characters. Line breaks and runs of spaces become one space; a longer note is cut at a word end with …. A note never blocks the write.
  • Where it goes: a Description: line in the version's commit message, after the checkpoint message above (which stays the first line: the undo label and the logs read only that). One write is still one version. For the writes whose message the app builds (the layout save of canvas_layout, a glimpse_pull, a new stage_capture), the note is set on the version just after it is made, as a git note, with By: claude. Storage: architecture.md §9 "Descriptions".
  • No note: Claude's version has no description. The app's own versions always get one, with no AI call: saved 02-walls, imported logo.png, renamed scene intro to opener, restored version from 14:05. gen_import (imported <file>) and compose_run (the plan's summary) describe theirs by themselves and take no note.
  • The plugin's starlight:mcp skill makes this a rule: every change passes a note; a task that made several versions may end with checkpoints { action: "describe" } on the last one to sum it up; the artist's ✎ name is never changed, and the artist's own saves are described only when the artist asks.

Live scenes: while a scene is open, Claude edits the live scene. A scene the window has open, or holds with unsaved edits (architecture.md §8 "Unsaved scenes"), is read and written through the window, not its file (src/mcp/live-scene.ts, src/renderer/live-scene.ts):

  • Reads. The window sends main its live scenes (LIVE_SCENES_SYNC: the open scene's source YAML and every held one) when a scene loads, when an edit settles and when the held scenes change. read_scene, and every tool that reads a scene (set_*, fit_layer, make_loop, the tile and version tools, renders), gets that YAML, unsaved edits included.
  • Writes. A tool's saveScene to a live scene first asks the shared project's lock (the same refusal as before), then sends LIVE_SCENE_WRITE_REQUEST. The window applies it as ONE undo step on that scene's stack, labelled after the tool (Claude: write scene, Claude: fit logo to N (cover), from the checkpoint message), and answers. Main then writes the file and checkpoints exactly as before, and sends LIVE_SCENE_SAVED instead of a SCENE_CHANGED: the window marks the scene saved if it still shows that YAML. No external-change notice.
  • Stale writes are refused. Each write names the YAML it was built on: a read-modify-write tool its own read, write_scene what read_scene last showed the agent (or the file, when it never called read_scene). If the live scene is no longer that YAML (the artist edited it, ⌘Z'd, or another tool wrote it), nothing changes and the tool returns not written — "<scene>" changed in the Starlight window since you read it … Call read_scene("<scene>") again. The window also refuses while the artist drags in that scene, draws a pen path or has a path open for re-edit there, or while an outside change to it waits for Reload / Keep mine.
  • ⌘Z undoes Claude's write and keeps the artist's edits (the step holds the scene as it was just before, unsaved edits included); ⇧⌘Z brings Claude's change back.
  • A scene the window does not have keeps the file path below, byte for byte. create_scene, delete_scene, rename_scene, restore_checkpoint, compose_run and a finished tiled upscale also keep it.

Unsaved edits are never replaced silently (AUDIT BUG-MCP-2). File-path writes push with origin: 'external' (+ their checkpoint); the renderer decides each push in the pure planScenePush (src/renderer/external-change.ts):

The window…The push touches…Result
has no unsaved editsanythinglive reload, as before
has unsaved editsanother scene (create_scene, a write to a scene not open)reload the rest; the open scene keeps the edits
has unsaved editsthe open scene (another artist's sync, MCP compose, restore_checkpoint, delete / rename of it)held: a bar — Reload (the replaced edits go onto ⌘Z) or Keep mine (the scene stays as the user has it; the external version is the write's checkpoint, in Versions; ⌘S saves the user's over it)
has unsaved edits on a scene that is not open (held in memory, architecture.md §8 "Unsaved scenes")that scene, and its file really changed (heldSceneChanges)the edits stay held and the same bar asks: Reload takes the disk version (the held edits go onto that scene's ⌘Z and stay in its recovery draft) or Keep mine (saving that scene writes the user's over the change). If the write deleted or renamed it, the edits leave memory; its recovery draft still has them (a warning says so)

There is no Compare button yet: Starlight has no scene diff view. Versions shows each checkpoint's scene.

A later MCP push while the notice is up replaces the held payload (the newest disk state wins); a ⌘S settles it as "keep mine". Pushes the user caused in the app (⌘R, Open Project, in-app ⌘K compose, compose undo) reload as before; ⌘R now asks first when there are unsaved edits.

⌘Z after an external write. A write that lands (a live reload or a merge above, a generation landing, another artist's sync) is an undo step of its own on each scene it replaces, holding that scene as the window had it just before (externalWriteSteps, UndoStore.recordExternal). ⌘Z puts the write back with the user's edits intact — the scene is then unsaved, and the write is still its checkpoint in Versions — and only the next ⌘Z reaches the user's last edit; ⇧⌘Z puts the write back in. Before, the scene reloaded under the stack, so ⌘Z popped the user's last edit (a snapshot from before the write) and took both at once. A write that only reformats a scene is no step, and the same state pushed twice in a row is one. The toast says undid: external edit (another artist's edit for the Dropbox sync).


3. Every MCP tool

Eighty-two tools. They are registered in src/mcp/server.ts, the stage tools plus canvas_focus in src/mcp/stage-tools.ts (registerStageTools), brief_read / brief_add in src/mcp/brief-tools.ts (registerBriefTools), the net_* tools in src/mcp/net-tools.ts (registerNetTools), the version and pre-render tools in src/mcp/version-tools.ts (registerVersionTools), and checkpoints (the project's version history) in src/mcp/history-tools.ts (registerHistoryTools), the effect module tools in src/mcp/effect-tools.ts (registerEffectTools), and measure_text in src/mcp/text-tools.ts (registerTextTools): names, descriptions, zod input schemas — what an external Claude reads cold. The behaviour lives in pure handlers (createToolHandlers and its siblings in src/mcp/tools.ts, createStageToolHandlers), which unit-test with the filesystem, git, and renderer all mocked. All scene tools take scene = the file basename (e.g. intro, not scenes/intro.yaml).

JobTools
Project and scenesget_project, read_scene, open_scene, write_scene, write_comp, write_node, create_scene, delete_scene, rename_scene, rename_comp, precomp, set_comp_frame, fit_layer, make_loop, restore_checkpoint, checkpoints, create_project
A project that is not open ("Projects that are not open" below)the yaml tools' project argument, copy_to_project
The brief (project-memory.md §3)brief_read, brief_add
Motion tracking (clocks-and-animation.md §5)import_track, track_region
The Starlight Network room (network.md)net_read, net_post, net_tasks, net_task_update, net_presence
Eyesrender_still, render_surfaces, render_comp_still, tiles_check, playback_stats, measure_text, probe_pixels, diff_against (src/mcp/pixel-tools.ts, registerPixelTools)
Mediaassets_import, assets_ingest, music_map, glimpse_pull
Media versions and pre-render (local ops free; the cloud upscale paid; main/versions/, main/prerender/)versions_list, version_create, version_use, matte_use (cut a layer by a person / depth / roto matte of its clip, masks.md §8), version_status, version_cancel, prerender_node, prerender_status
Fonts (brand.fonts and the files in fonts/, read from the files)list_fonts
AI generationgen_models, gen_create, gen_list, gen_status, gen_cancel, gen_import, gen_grade, compose_run
Tile Plan (AI video on a big surface)plan_tiles, generate_tiles, assemble_tiles, set_tile_seams, make_loop { surface }, tiles_check { scene, surface }, set_tile_match
Stages and the canvas viewstage_list, stage_read, stage_write, stage_delete, stage_capture, canvas_focus, canvas_layout
Deliveryexport_formats, export_scene, export_scenes, export_reel, cancel_export, glimpse_status, glimpse_list, glimpse_publish
Effect modules (effects.md §13)effect_create, effect_check, effect_preview
Extensions and diagnosticsscaffold_extension, get_logs
The Claude panel's own hook (never a model's call)panel_chat: a panel tab's chat moved to another conversation (/clear, /resume), claude-panel.md

Two output conventions: handlers return { text } (usually pretty-printed JSON) or, for render_still, render_surfaces, render_comp_still, gen_status (a finished job's poster), stage_capture and diff_against { image: true }, { text, image }. A render's image is a capped preview, never the native image (see "Previews" below). An error returns { text, isError: true } — the client shows it and the model can recover; it does not throw across the transport.

A scene basename must match ^[A-Za-z0-9._-]+$ (no path parts).

get_project — read this first

  • Purpose: the full picture of the open project. Read it before writing anything.
  • Params: none.
  • Returns (JSON): name, projectDir, surfaces ([{ name, size: "WxH", fit? }]), brand ({ tokens, fonts } from the project brand kit), scenes (basenames), openScene (the scene the app has open and reopens on launch: the last-open scene, else project.yaml defaultScene, else the first), layout (where each surface sits on the canvas: the same answer as canvas_layout with no arguments; absent in a host without it), optional clocks (per-scene named clocks: { period, mode? } — only scenes that declare clocks appear), and catalog — the live registry snapshot: nodeTypes[] (kind, keyword, note, params, extension?) and effects[] (name, note, params with animatable flags, extension?). Every built-in node kind and effect carries a note and its params (name, type, default, range or options), enough to author it without guessing (src/engine/registry/catalog.ts; catalog.test.ts fails when one is missing). The matte entry's note is how Claude masks: a matte node with content and matte inputs, never a mask: field (masks.md). The cutout node note says it is the legacy spelling of an image with the cutout effect, and the audio note how a clock drive: follows a track's analysis. Also blendModes — the blend: field every node accepts: groups (Photoshop's: normal / darken / lighten / contrast / inversion / cancellation / component → mode names), hardware (the zero-pass modes: normal, add, screen, multiply), aliases (linear-dodge → add) and a one-line cost note (blend-modes.md). An unknown mode in write_scene / create_scene is rejected with …blend — expected a blend mode (…). effectAnimation and gradientAnimation say how effect params and a gradient's own attributes keyframe: the gradient entry lists what animates (animatable: angle, stops[i].offset, stops[i].color, center, radius, size — the same params the catalog's gradient entry marks animatable: true), that the lists ride the gradient node's clock, that a colour key is a hex or a brand $token (OKLab between keys), and that the scene must be schemaVersion: 4: write_scene stores YAML as given, so write it yourself (clocks-and-animation.md §4). shapeColorAnimation says the same for a shape's or a path's fill and stroke (animatable: fill, stroke; a colour list on the node's clock, no new scene version) with a short example (clocks-and-animation.md §4), and that a text's fill animates the same way, every markup run with it (textExample; §4 "Text colour"). The catalog marks the text's fill animatable: true. shapeTrim says how a shape's or a path's stroke is trimmed (animatable: trimStart, trimEnd, trimOffset — fractions 0..1 and degrees, each a value or a list on the node's clock), that the fill is never trimmed, where each outline starts, and that the scene must be schemaVersion: 16, with an example (clocks-and-animation.md §4). textLetters says type that arrives letter by letter is one text with letters:. particles says sparks, dust, snow and embers are ONE particles: node (scene format v17): a pure function of the scene time and its seed, seamless on the loop, its emitter at the node's origin, its budget and what it cannot do (flocking, collisions, fluids), with an example that writes as given (scene-format.md §particles).
  • Behaviour: the catalog is derived from the running registries, so extensions appear automatically and are flagged extension: true. If the renderer hasn't synced the catalog yet (app still starting), catalog carries a note telling you to retry shortly. A single unparseable scene is silently omitted from the clocks summary rather than sinking the whole call. This catalog is also what scene writes are validated against: an effect or param that is not in it is rejected.

read_scene { scene }

  • Purpose: return a scene's source YAML with $tokens intact.
  • Returns: the raw YAML text. Errors (isError) with the available scene list if the scene doesn't exist.

open_scene { scene }

  • Purpose: open a scene in the Starlight window, so the artist sees it on the canvas. A field report, 2026-11-06: Claude made a scene with create_scene, and the artist could not see it, because no tool could switch the window.
  • Behaviour: the same as a click in the scene list (switchScene in App.tsx): the scene the window leaves keeps its unsaved edits, held and unsaved, and the scene list marks them (help #scenes-unsaved). Nothing is saved, dropped or checkpointed. A scene that create_scene just wrote reaches the window with the reload it pushed, so the window waits up to 3 s for the scene to be listed. Refused while the artist holds a drag or a pen path on the open scene (try again), and for a scene that is not in the project (the error lists the scenes). Main asks the window over scene:open-request / scene:open-result (requestOpenScene); the window decides with planOpenScene (src/renderer/live-scene.ts).
  • Returns: { ok: true, scene, left?, note }: left is the scene it had open, and note says in words what happened (for example that left still has unsaved edits).

write_scene { scene, yaml }

  • Purpose: overwrite an existing scene with complete YAML (not a diff).
  • Params: scene (must already exist — otherwise it points you to create_scene); yaml (the full document).
  • Behaviour: validated first (validateSceneYaml, src/mcp/tools.ts): parseScene (structure and references/ranges — comp use:/clone.of, clock refs, matte inputs (both present, one node each, pixels to cut with — a v1 mask: is migrated first; masks.md §7), positive sizes, #hex/$token colours, phase/offset/ease ranges, numeric clone params; scene-format.md §11), then the live registry — every node kind is registered, every effect name is registered, and every effect param is one the effect declares (animated only if animatable, a choice within its options, numbers as numbers, colours as #hex/$token) — checked against the same catalog get_project returns, extensions included (AUDIT BUG-MCP-3); then resolveTokens (renderability; an unresolved $token counts as invalid) and the colour-op param check. Keyframe lists of colours (a gradient stop's, a shape's) are checked by the parser too: a key that is neither a hex nor a $token (… keyframe 1 needs a colour …; an unknown $token is the unresolved token error at the key), a gradient offset key outside 0..1, a malformed center / size. If invalid, nothing is written and it returns a path-anchored error like scenes/x.yaml: comps.main.0.size — expected WxH or scenes/x.yaml: comps.main.0.effects.1 — unknown effect "glw" — valid effects: cutout, blur, …. Fix that exact path and retry; never assume a rejected write partially applied. Before the renderer has synced its catalog (the window still starting) the built-in catalog stands in: built-in effects validate as usual, and an unknown name says (the app has not synced its live registry yet, so extension effects are not known — retry shortly). On success it saves through the app (checkpoint mcp: write <scene>) and the live canvas updates. While the scene is open (or held with unsaved edits), the write goes into the live scene as one undo step (Claude: write scene) and is saved with the artist's unsaved edits in it; it is REFUSED as stale when the scene changed since your read_scene (see "Live scenes" above).
  • Surfaces: a scene can only use the surfaces project.yaml declares (help #surfaces-bind). A binding for another name is valid YAML, so it is saved, but nothing shows, renders, exports or publishes it. The result then has warnings with one line that names those surfaces and lists the project's surfaces, so Claude fixes the binding at once (wallsNotInProject, @engine/model/focus; the words in src/shared/unknown-walls.ts). No tool adds a surface: it is a surfaces: entry in project.yaml, then File › Reload Project from Disk.
  • Particle budgets: a particle system that asks for more sprites than its max (scene-format.md §particles) is saved and drawn at a lowered rate, and warnings gets one line for it: comps.main.0.particles — rate × life needs 6100 sprites, over max 4000: drawn at 79 births/s (particlesBudgetWarnings, model/particles.ts); one still over max even at one birth per loop says so. When all the scene's systems together draw more than 20 000 sprites over every surface, tile and comp use, one more line says that (particlesSceneWarning). write_comp and write_node return the same lines.
  • Returns: { ok: true, scene, checkpoint, warnings? }. The scene is saved either way. The checkpoint field tells you if the checkpoint was saved: a commit hash means it was. When the tree was already clean, or git could not make the checkpoint this time, there is no hash, and the next checkpoint takes the change in.
  • Habit: render_still afterwards and LOOK. A scene that parses can still be ugly, clipped, off-brand, or seam at the loop.

create_scene { scene?, name?, yaml? }

  • Purpose: create a new scene.
  • Params: scene (canonical) or name (back-compat alias — prefer scene); yaml optional — omit it for a minimal, universally-valid starter template (a pulsing hero word). Must not already exist; name must match the basename pattern.
  • Behaviour: validated + saved exactly like write_scene (checkpoint mcp: create <scene>), with the same warnings for surfaces project.yaml does not have. The artist does not see the new scene until it is opened: open_scene.
  • Returns: { ok: true, scene, checkpoint, warnings? }, plus template (one short line) when it wrote the starter template. The YAML is not sent back (it only filled the context; a field report, 2026-11-06): you wrote it, or read_scene shows the starter.

delete_scene { scene }

  • Purpose: delete a scene through the save/git path (checkpoint mcp: delete <scene>).
  • Behaviour: refuses to delete the last remaining scene (a project must keep at least one). If the deleted scene was open, the app auto-switches to project.yaml defaultScene, else the first remaining scene; openScene names it.
  • Returns: { ok: true, deleted, checkpoint, scenes, openScene }.

rename_scene { scene, to }

  • Purpose: rename the file and patch its declared scene: line so the name inside follows the file (checkpoint mcp: rename <scene> → <to>).
  • Behaviour: refuses if to already exists, equals the current name, or isn't a valid basename. The renamed scene is re-validated before the write (parse + tokens; the registry check is skipped — a rename moves content without changing it, so a scene using an extension that is not loaded right now can still be renamed).
  • Returns: { ok: true, from, to, checkpoint }.

rename_comp { scene, from, to }

  • Purpose: rename a composition (a key of the scene's comps:) and every reference to it: each surface use:, each use: node and clone.of at any depth, and the graph layout, colour and note entries that name it (checkpoint mcp: rename comp <from> → <to> in <scene>). The app's "Rename Composition…" runs the same engine op (renameComp, src/engine/model/comp-rename.ts).
  • Behaviour: refuses, writing nothing, an empty name, the same name, a name another comp already has, a name with / or :, or an unknown comp. Node ids inside the comp are positional, so they are re-derived for the new name: the saved YAML gains no id: lines. The scene is saved in the app's own form (like any app save).
  • Returns: { ok: true, scene, from, to, uses, checkpoint } — uses counts the places that use the comp.

precomp { scene, ids, name, size | preset, origin? }

  • Purpose: Pre-comp (help #comp-frames; scene-format.md §3 "Framed comps"): move the layers ids into a NEW framed comp name and leave ONE transform: [ - use: <name> ] holder in their place that puts the frame's top-left on origin (in the layers' parent px; default: centred on their artboard). The holder turns around the frame's centre, like every new layer: anchor = (w/2, h/2), position = origin + anchor. The layers shift by −origin inside the comp, so nothing moves on screen (checkpoint mcp: pre-comp …). The app's Pre-comp… runs the same engine op (precompNodes, src/engine/model/comp-frame.ts), centring on the layers as drawn.
  • Frame: size ("2206x946", whole px) or preset: 16:9, 21:9, 4:3, 1:1, 3:4, 9:16, 16:9-4k, 21:9-4k (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) or surface:<name> (a project surface's size).
  • Behaviour: refuses, writing nothing, layers that are not side by side in one list, a taken or empty name, both or neither of size / preset, or a size that is not a frame. A layer's positioning transform moves with it; moved nodes keep their explicit ids and get the auto ids of where they stand, so the YAML gains no stray id: lines.
  • Returns: { ok, comp, frame, aspect, use, holder, origin, renamed?, checkpoint }.

set_comp_frame { scene, comp, size | preset | null }

  • Purpose: add, change or remove (size: null) a comp's frame (checkpoint mcp: comp <comp> frame …). The content does not move. An unchanged frame writes nothing (changed: false).
  • Returns: { ok, comp, frame, aspect?, changed, checkpoint }.

write_comp { scene, comp, yaml, create? } — one comp at a time

  • Purpose: replace ONE comp's node list without sending the whole scene. A field report (2026-11-06): a scene with about 250 keys was 26 KB, and every write_scene sent all of it again to change one layer.
  • Params: comp (a key of comps:); yaml: only the comp's node list, the lines that sit under comps: <comp>:, each node starting with - . The comp's frame stays (set_comp_frame changes it); a framed comp's children: are replaced. create: true adds a NEW comp (refused when one has that name; no / or : in it).
  • Behaviour: src/mcp/scene-patch.ts + the handler in src/mcp/tools.ts. The piece is put into the scene's YAML data at its place, in the LIVE scene (read_scene's source: the window's scene with the artist's unsaved edits, else the file). The whole scene is then parsed, written back by the app's own serializer (so a per-frame track stays compact and schemaVersion is raised to what the scene uses; comments do not stay, as with every tool that edits a scene), and checked with validateSceneYaml, exactly as write_scene checks a scene. It is saved through saveScene like write_scene: checkpoint mcp: write comp <comp> in <scene>, the canvas updates, and while the scene is open the write is ONE undo step, Claude: write comp <comp>; the shared-project lock rule applies. The save's base is the live scene the tool just read, so an edit made in the window in between refuses it (stale) instead of writing over it.
  • Never over the artist's edits. Every other comp keeps what the window has now, unsaved edits included. The comp you replace must be as you last saw it: unchanged since your read_scene (or your last write) of this scene, else the write is refused (comp "<x>" changed in the Starlight window since you read …). If you never read the scene and the window has unsaved edits of it, read it first. After the write, your read counts as your old read plus this comp, so a later write_scene built on that old read is still refused when the artist changed something else meanwhile.
  • Refused, writing nothing: a yaml that does not parse or is not a list, a scene that would be invalid (the same path-anchored errors as write_scene, at the comp's place: scenes/x.yaml: comps.row.0 — expected a node keyword …), an unknown comp without create, a stale comp. Nothing is ever half-written: the scene is saved whole, once, after every check.
  • Returns: { ok: true, scene, comp, nodes, created?, checkpoint }, never the scene. render_still afterwards and LOOK.

write_node { scene, id | path, yaml } — one node at a time

  • Purpose: replace ONE node (a layer: its keyword, keys, clock, effects and everything inside it), the smallest write there is.
  • Params: id (an id: in the YAML, an auto id another tool or the Claude panel's [node ID … at PATH] reference gives) or path, where the node sits in the YAML, written as errors and references write it: comps.main.0, comps.main.0.transform.1, comps.boxed.children.0 (a framed comp), surfaces.wall.children.0, comps.main.2.matte.content. One of the two. yaml: that one node as a map, with no - in front.
  • Behaviour: as write_comp (live scene, the whole scene checked, the app's serializer, one save; checkpoint mcp: write node <id> in <scene>, undo step Claude: write node <id>). The node must be as you last read it. A node's own id: stays when your YAML gives none, so what names it keeps naming it. Paths come from forEachNodeAt (model/walk.ts), the walk the parser's errors use.
  • Refused, writing nothing: both or neither of id and path, no node there (the error lists some node paths), a yaml that is not one map, an invalid scene, a stale node.
  • Returns: { ok: true, scene, id, path, checkpoint }: the node's id after the write (a node with no id: of its own gets an auto id from its place and kind, so a new kind there gets a new id).

render_comp_still { scene, comp, timeMs?, out? }

  • Purpose: render a FRAMED comp at exactly its frame size (returned as an image), from the saved scene, through render_still's path: a one-surface scene bound to the comp with size = design = frame. It does not spend.
  • Storage: the PNG is written to assets/comps/<scene>/<comp>-<hash8>.png (the hash names the pixels, so an unchanged comp writes the same file) with a sidecar in assets/.comps/<scene>/ — the way stage captures are stored — or to out (a .png under assets/). Use the returned path as a gen_create input (start_image for a clip, reference for a still) with the model's aspect set to aspect.
  • Behaviour: refuses a comp without a frame (set one first) and an out outside assets/. Needs the app window.
  • Returns: { comp, frame, aspect, width, height, timeMs, path } and the image: the PNG itself, or, for a comp bigger than a preview (more than 1568 px on its long side or about 1.15 MP), a smaller JPEG. Then preview gives its size and scale. The saved PNG is always full size.

fit_layer { scene, id, mode, surface?, timeMs? }

  • Purpose: the app's Scale to Fit (help #canvas-fit): scale a layer to a surface and centre it there. mode is width (the layer is as wide as the surface), height, fill (covers the surface with the larger scale; it may crop) or inside (the whole layer shows). The canvas menus, the transform sheet's fit buttons and the palette run the same engine code (src/engine/model/fit-layer.ts).
  • The layer: id is the transform, or the content its positioning transform places. Its size is its content's own box before the transform: an image or video's pixels (read from the file: an image's header, a video's ffmpeg probe), a shape or gradient's size (a stroke half outside). A text layer is refused: its box needs the renderer's fonts (the app's own command measures it). An unknown id is refused with a list of the scene's layers and their ids.
  • The surface: a layer in a surface's own tree fits that surface's design box. A layer in a comp fits each surface that shows the comp: a surface slice (- transform: [ - use: c ] at the surface's offset) maps the surface's box back into the comp. When several surfaces show it, surface is required (the app asks with a surface submenu instead). A later framed-comp feature adds a comp's own frame as a target here (fitTargets).
  • Behaviour: the anchor is respected (none = top-left); rotation is ignored (the unrotated box fits). A position or scale row a clock track drives gets a keyframe at timeMs (default 0) — the gizmo rule; the other keys stay. Saved like write_scene.
  • Returns: { ok, scene, id, mode, surface, target, box, scale, position, keyed, checkpoint }.

make_loop { scene, id | surface, overlap?, dissolve?, noiseScale?, softness?, seed?, evolve?, setSceneLoop? }

  • Purpose: the app's Make Loop (help #make-loop): turn a video that does not loop into a seamless loop. The canvas and graph menus run the same engine code (src/engine/model/make-loop.ts). The plugin's make-loop skill is the recipe around it.

  • How: a clip of length T is split at H (the middle). The second half (source H → T) plays from loop time 0; the first half (source 0 → H) starts O before the second half ends (overlap, default the smaller of 1 s and T/4). The loop is T − O: it starts on source frame H and ends on the frame before it, so the wrap is seamless; the real cut (T → 0) falls in the overlap, where the first half comes in through an animated noise matte (dissolve: noise, default) or a plain fade (crossfade). Cut points snap to the scene's fps. The clip's length and pixel size come from its ffmpeg probe.

  • The YAML it writes: the video node becomes a group (its transform is untouched):

    - group:
        - video: assets/clip.mp4          # bottom: the second half, from loop time 0
          trim: [4s, 8s]                  # source in / out
          id: loop-a
          span: [0ms, 4s]                 # when it shows, in loop time
        - matte:
            content:
              video: assets/clip.mp4      # top: the first half, in at 3 s
              trim: [0ms, 4s]
              id: loop-b
              span: [3s, 7s]
            matte:
              group:                      # two children, so the rect's effects run
                - shape: rect
                  size: 1920x1080         # the clip's pixel size
                  fill: "#000000"
                  id: loop-black
                - shape: rect
                  size: 1920x1080
                  fill: "#ffffff"
                  id: loop-noise
                  effects:
                    - noise: { scale: 200, seed: 0 }
                    - threshold:          # level 0 → 1 across the overlap (3 s → 4 s of 7 s)
                        level: [{ phase: 0.428571429, value: 0, ease: linear }, { phase: 0.571428571, value: 1 }]
                        softness: 0.15
              id: loop-dissolve
            mode: luma
            invert: true
          id: loop-matte
      id: loop

    The node's own effects, blend, span, clock and bypass move to the group. The noise rect sits in a two-child group because a matte input's own effects are ignored and a one-child group counts as its child (masks.md).

  • Refuses (writing nothing): an unknown id (the error lists the scene's video layers), a layer that is not a video, a clip already made into a loop (it has a trim), a matte's input, a video with a delay (a trimmed clip follows the scene loop, not the delay), a clip whose length cannot be read, a clip too short for the overlap (T < 2·O), or (with setSceneLoop: false) a scene loop shorter than the loop.

  • Behaviour: setSceneLoop (default true) sets the scene's loop to T − O; the loop only wraps seamlessly when the scene loop equals it; false keeps a longer scene loop and the loop plays once per pass. Saved like write_scene.

  • Returns: { ok, scene, id, bottom, top, matte, mask, clipMs, halfMs, overlapMs, loopMs, overlapStartMs, sceneLoopSet, check: { wrapMs, midOverlapMs }, checkpoint }. Render a still at both check.wrapMs instants (the last frame and the first) and at check.midOverlapMs.

  • A tiled wall (surface instead of id; Tile Plan, below): every placed tile gets the SAME cut, timed from the shortest clip, so the tiles stay in step. The cut is stored in the plan (tiles.loop, scene v10) and every assembly applies it, so assemble_tiles, set_tile_seams and a re-rolled tile keep the loop; a new generate_tiles { confirm: true } drops it. Each tile's nodes are named after its zone (tiles-N-z1, tiles-N-z1-a, …). The scene loop is set to the loop (setSceneLoop does not apply). The app's Tile Plan panel has the same button, make tiles loop. Returns { ok, scene, surface, comp, tiles, clipMs, halfMs, overlapMs, loopMs, sceneLoopSet, check, checkpoint } (+ note when the clips differ in length).

import_track { scene, id | path, data | file, format?, mode?, properties?, fps?, start?, frames?, ref?, plate? | offset? + scale?, source_size?, min_confidence? } — tracking data onto a layer

  • Purpose: make a layer follow something in the footage, from tracking data made elsewhere. A field report (2026-11-06): "No tracking. I had to write an outside tracker (ffmpeg plus Python) to get the motion." The full rules: clocks-and-animation.md §5 "Tracking data".
  • Params: the layer by id or path (a transform, or the content its transform holds alone: the tracks then go on that transform, and the answer says so). The data as data (its text) or file (a project file, assets/tracking/shot1.csv; online-only and over 16 MB are refused). format: ae, csv or json, else found from the text. mode: follow (default: the layer stays where it is on the reference frame and moves with the point) or pin (its position becomes the point, so its anchor sits on it). properties: what to write (position, scale, rotation, anchor; default position plus the scale and rotation the data has). Where the footage is: plate (its video or image layer, in the same comp or surface), or offset + scale (footage px × scale + offset = comp px; default 0 and 1). fps when the data does not say it; start (the clock frame of the first imported frame), frames: [from, to] (a part of the data), ref (the reference frame), source_size ("1920x1080", the footage's size when the data does not say it), min_confidence (0..1).
  • Behaviour: src/import/tracking/parse.ts reads the data into one table (path-anchored errors: data: line 7, column "y" — "oops" is not a number …; missing frames, empty cells, null and NaN become frames with no sample). src/import/tracking/apply.ts maps it: footage px → the layer's parent px (through the plate, or offset and scale, and the layer's parents); the data's own fps, never resampled; data frame n → clock frame n, moved by the plate clip's offset or trim and the layer's delay, or by start. It writes per-frame tracks (x, y, and scale or scaleX / scaleY, rotate) on the layer's clock, replacing those tracks and keeping the others, and in pin mode the position. The handler (src/mcp/track-tools.ts) saves the layer through write_node's save path (buildLivePiece + the app's save, as saveLivePiece in src/mcp/tools.ts): the live scene, checked whole as write_scene checks it, ONE undo step Claude: import track onto <id>, checkpoint mcp: import track onto <id> in <scene>. A read of the scene Claude made before (with the layer as it was) now counts the tracks too. Everything before the save is prepareImportTrack, which the Properties panel's import tracking… runs too (panels.md): one import, two callers.
  • Refused, writing nothing: both or neither of id / path or data / file; no such layer, or one with no transform; data that does not read (the line or key named); an fps that differs from the data's own (the data says 23.976 fps and fps is 30 …) or none at all; frames past the clock's end or before its start (the range that fits is named: pass frames); plate and offset / scale together; a plate in another comp; scale or rotation the data does not have; an invalid scene.
  • Returns: { ok, scene, id, path, onTransform?, read, mode, fps, tracks: { x: { start, values, empty }, … }, dataFrames, clockFrames, seconds, ref, position? (pin), anchor?, mapping, emptyFrames, confidence?, notes?, checkpoint, next }. mapping says in words how px and frames were mapped. Then render_still at a few times inside seconds and LOOK.

track_region { asset | scene + plate, rect, frame, frames?, search?, scale_too?, min_score?, id? | path?, mode?, … } — the rectangle tracker

  • Purpose: track something in a clip without another tool: draw a rectangle on one frame, get its centre on every frame.
  • Params: the clip: asset (assets/shot1.mp4), or scene + plate (its video layer). rect: { x, y, w, h } in the clip's own px (top-left and size, 8–1024 px a side) on clip frame frame. frames: [from, to] (default: from frame to the clip's end; at most 3000 frames a call, 600 of them before frame, so a call ends well inside an MCP client's idle timeout even where the decode is slow). search (px it may move between two frames beyond its last speed; default 48), scale_too (also measure its scale), min_score (default 0.6). With scene and id (or path) the track goes straight onto that layer through import_track (mode, properties, plate, offset, scale, start, ref as there; ref defaults to frame).
  • Behaviour: ToolContext.trackRegion → src/main/tracking/: ffmpeg decodes luma frames (-ss to the frame the app shows for that time; VideoToolbox on macOS), and the NCC matcher (ncc.ts: coarse to fine, Lucas–Kanade sub-pixel, the drawn template kept, so no drift) runs in a worker thread (region-worker.ts, its own Vite build entry beside main), one job at a time. Without the worker script it runs on main's event loop a frame at a time (speed.matchedIn says which). Frames before frame are decoded in chunks from the end (64 MB of frames each) and matched backward. While an export, reel or Glimpse publish runs it waits and starts after it (nothing heavy runs beside an export: export-rendering-and-building.md, "While a render runs"); the call sends MCP progress all along (trackRegionSource: track_region · waiting: an export runs; it starts after, then track_region · tracking), so the wait never hits the client's idle timeout. A track already running when an export starts finishes.
  • Refused: a clip that is not here or not a video, a rect outside the clip or of a bad size, a frame outside the clip or outside frames, more than 3000 frames (600 backward), a rectangle of one flat colour (nothing to follow).
  • Returns: without a layer: { ok, asset, fps, frames, drawnOn, lost, lostFrames?, score: { min, mean }, speed: { framesPerSecond, ms, decodeMs, matchMs, matchedIn }, data, next }, where data is { fps, start, width, height, x, y, scale?, confidence }: pass it (as JSON text) to import_track. With a layer: import_track's answer plus tracking (the same summary). Measured speeds: clocks-and-animation.md §5.

restore_checkpoint { id, note? } — undo

  • Purpose: undo external edits by restoring a checkpoint id (from any write/create/delete/rename result, or a version hash). Restores the files the same way as Versions in the app (restoreProjectVersion: under the write lock, and a shared project's mirror is read again), makes ONE new version of the restored state (mcp: restore <hash7>, described by note, else restored version from 14:05; none when nothing changed), then pushes a live reload. In a local project layout.json is in the checkpoint too: the reload moves every surface the artist has not moved since the last save. That is no undo step and leaves nothing unsaved.
  • Returns: { ok: true, restored: id }; errors clearly on a bad id.
  • This is the undo model for MCP edits — pair every risky write with the id you got from the last good one. (In-app, ⌘Z after a ⌘K compose does the same thing.)

checkpoints { action: "list", limit? } / checkpoints { action: "describe", hash, text } — the version history

  • Purpose: the project's version history, the one the artist's v button shows. The tools say checkpoint where the app says version (as restore_checkpoint does); the name also keeps it apart from the clips' media versions (versions_list). src/mcp/history-tools.ts, over main's listVersions / describeProjectVersion.
  • list: newest first, limit default 20, at most 200. Returns { checkpoints: [{ hash, time (ISO), name, description, by, current? }], more }: name is the artist's ✎ name, description the one-line description (null when the version has none: older versions), by artist, claude or app (null when not known), more true when older versions are left out.
  • describe: sets or replaces ONE version's description (a git note in refs/notes/starlight; the commit, its hash, files and name never change). hash is a full or short hash from list or a write result. text is one line, at most 120 characters; a line break or a longer text is refused and nothing is written; "" removes the description. An unknown hash is an error (not described — no version <hash> in this project's history). Returns { ok, hash, time, name, description, by, current? }.
  • When: at the end of a task that made several versions, to make the last one sum up the task; and to describe the artist's own saves when the artist asks. Never to change a name.

create_project { name, shared, location?, surfaces?, copyFrom? } — a NEW project

  • Purpose: make a new project folder through the app's one create path, the same as File › New Project… (projects.md): <location>/<slug of name>/ with project.yaml (project:, a stable id:, the surfaces, defaultScene: 01-main), scenes/01-main.yaml (the create_scene template bound to every surface), assets/, CLAUDE.md, git with one commit, and the MCP hookup.
  • Params: name (one line, at most 80 characters); shared (required, no default: ask the artist how they will work on it; false is "Just me, on this computer", true is "With others, through Dropbox" or the synced folder it is in; written into project.yaml); location (absolute or ~/…, default ~/Documents/Starlight); surfaces ([{ name, size: "WxH", fit? }]) or copyFrom (a project folder or its project.yaml, whose surfaces: block alone is copied); neither gives one 1920x1080 main.
  • Behaviour: refuses a folder that exists and isn't empty, and a location inside another project, and a request without shared; on any failure nothing is left behind. With shared: true only project.yaml, the scene, CLAUDE.md and assets/ go into the folder; the location never decides it (a synced folder only suggests true).
  • Not opened. Opening switches the whole app, this MCP server included (it restarts bound to the new project and its own token), so the session would lose its tools. The project is added to the recents after the open one; tell the artist to open it from File › Projects.
  • Returns: { ok: true, path, name, id, mode, provider?, surfaces, scene, opened: false, next }.

Projects that are not open: project and copy_to_project

One folder of work can hold several projects, and Claude may need to change one that is not open. Starlight has one open project at a time, and opening another one switches the whole window. So the yaml tools can work on a project that is not open, without opening it.

Words used here:

WordMeaning
open projectthe project in the Starlight window now
other projecta Starlight project that is not open: any project folder on this computer
version historythe project's checkpoints: <folder>/.git for a local project, <userData>/projects/<key>/git for a shared project (shared-projects.md §3)
edit lockin a shared project, the file that says which artist edits a scene now (shared-projects.md §11)
recovery draftunsaved edits of a scene that this computer keeps, to offer them back (architecture.md §8, "Unsaved scenes")

The project argument. These tools take project: get_project, list_fonts, read_scene, write_scene, create_scene, rename_comp, precomp, set_comp_frame, fit_layer, make_loop, plan_tiles, set_tile_seams, set_tile_match, stage_write and stage_delete. Their work is YAML only. They need the folder, the YAML files and a save. They need no render, no canvas and no window.

  • project is the other project's folder, or its project.yaml. Give the full path, or a path that starts with ~/. The folder is found the same way as File › Open Project… finds a pick (locateProject, projects.md §3): a job folder with one project in it works too.
  • A project that names the open project: the tool works exactly as it does without it.
  • Leave project out for the open project.

What a call on the other project does (src/main/closed-project.ts):

  1. It reads the other project's project.yaml and lists its scenes. In a synced folder (Dropbox) every read is bounded and checks the file's flags first. An online-only file is reported and never downloaded: make the project available offline, or open it.
  2. It finds out if the project is local or shared, and where its version history is (resolveMachineProjectState, the same way as the Claude panel finds the chats of the other projects).
  3. It checks the YAML the same way as for the open project: the parse, the tokens against that project's brand kit, the stage targets against its surfaces, and the catalog. The catalog here has the built-in node types and effects only, because the other project's extensions and effect modules are not loaded. A scene that uses one is refused, and the message says to open the project.
  4. It refuses the write, and writes nothing, when:
    • this computer has a recovery draft of that scene for that project. A later "restore" of the draft would undo the write without a word. Open the project first: Starlight offers the draft back, then save it or drop it.
    • in a shared project, another artist holds the scene's edit lock. The message names the artist and the computer. A lock with no heartbeat for 5 minutes does not count, and an old lock of this computer does not count.
  5. It writes the file atomically: a temp file in the same folder, then a rename. In a synced folder it uses the shared-folder IO (shared-fs.ts), so nothing there is synchronous.
  6. It makes one version in that project's own history, with the same mcp: … message as on the open project (mcp: write intro). A local project with no .git yet (it was never opened on this computer) gets the file and checkpoint: "failed", with the reason. Starlight never commits into a git repo above the folder.
  7. Nothing happens to the open project or the window: no reload, no change to a live scene.

An answer from the other project says so: a JSON answer has project (the folder), and an error starts with the project's name, for example Bolts Arena (not open): not written — ….

Every other tool refuses project. For example render_still, render_surfaces, render_comp_still, the exports, glimpse_*, gen_*, the version tools, stage_capture, canvas_layout, delete_scene, rename_scene, restore_checkpoint, checkpoints and assets_import. They need the canvas, the window, or the state of the open project. A project that names another project gets one line, render_still works on the open project only: open Bolts Arena first, and nothing runs. These tools do not show project in their input schema. The MCP SDK parses arguments with a zod object that drops the keys a tool does not declare, and a dropped project would make the tool work on the open project. So the server parses the arguments loosely (keepUndeclaredKeys, src/mcp/server.ts): the refusal sees project, and every other unknown key is still dropped. set_tile_seams { auto: true } needs the open project too, because the seam check reads the clips.

copy_to_project { project, scenes?, assets?, note? } copies from the open project into the other project:

  1. Each scene in scenes is read as read_scene shows it (unsaved edits included). Then it is checked against the other project, as in step 3 above. A scene that does not fit is refused.
  2. A scene brings every file that it uses in assets/ (sceneAssetRefs): image, video, audio and cutout sources, a cloner's file and a colour op's .cube. The files go to the same paths, so the sources in the scene still work. assets adds more files (paths under assets/). A linked media: file is not copied: notCopied lists it.
  3. It never overwrites. A scene name that the other project has (in any mix of capital and small letters), or an asset path that it has with other bytes, refuses the whole copy. The message names each one. A file with the very same bytes stays as it is (alreadyThere).
  4. A recovery draft or an edit lock on a copied scene refuses the copy, as for a write.
  5. It makes one version in the other project's history: mcp: copy intro and 2 asset files from Bolts Arena. In a shared project the history holds the scenes only; assets are not versioned there.
  6. A warning says when a copied scene uses a surface that the other project's project.yaml does not declare: that surface is not shown, rendered or exported there (a scene can only use its project's surfaces), and the warning lists the surfaces the other project has.

Returns { ok, project, scenes, assets: { copied, alreadyThere }, notCopied?, warnings?, checkpoint }.

Steps for Claude:

  1. get_project { project } to learn the other project: its surfaces and its scenes.
  2. read_scene { scene, project }, edit the YAML, then write_scene { scene, yaml, project, note }.
  3. To bring a scene over: copy_to_project { project, scenes: ["intro"] }.
  4. The other project cannot be rendered from here. Ask the artist to open it in Starlight to see it.

Code: src/mcp/closed-project.ts (the tool list, the context on the other project, copy_to_project); withProjectArg and keepUndeclaredKeys in src/mcp/server.ts; src/main/closed-project.ts (find, read, write, copy, locks, drafts, the commit), with withExternalGitDir (git.ts) and foreignLockHolder (scene-locks.ts); otherProjects in makeToolContext (index.ts). Tests: src/main/closed-project.test.ts and src/mcp/closed-project.test.ts, on real temp folders with real git (a local project and a shared one), and one call through the real MCP server.

Not built: delete_scene and rename_scene on the other project (they remove files), renders and exports of the other project (they need the canvas), and its extensions.

Previews: what an agent sees of a render

A render tool renders at native resolution, but it never sends the native image back. A whole 6400x1600 surface is an ~18 MB PNG: too big for a tool result. Also, the model takes in only about 1568 px on the long side. So every image a render tool returns is a preview:

  • The cap. At most 1568 px on the long side and about 1.15 MP (1,150,000 pixels). The model shrinks a bigger image again, so a squarer image is held under the pixel limit too. Then the scale a tool reports is the scale the model really sees.
  • The format. A preview is a JPEG at quality 0.85 (image/jpeg). The token cost of an image depends on its pixel size, not its bytes, and JPEG keeps the transfer small.
  • The files. save: true writes the full native image to disk instead. The format is PNG by default: it is lossless, and the show's dark haze and gradients would band in JPEG. A still may also become a reference or a start frame. format: "jpg" (quality 0.9) writes a small file to share. There is no WebP: its side limit is 16383 px, and a whole-room panorama is wider.
  • Where files go. renders/<scene>/stills/<scene>_<surface>_<w>x<h>_t<ms>.<png|jpg> in the project's renders folder, the same folder as exports. A region adds where it starts: …_<w>x<h>_x<x>y<y>_t<ms>.png. This is the project folder in a shared project too, so the still syncs to the other artists, as exports do. The file is written under a .~ temporary name and renamed when complete. The tool returns the absolute path: in a shared project the Claude panel runs in this machine's folder for the project, so a relative renders/… would name the wrong place. A name can never leave the renders folder (src/mcp/still-preview.ts stillRenderPath, src/main/render-stills.ts). Nothing is written without save. To measure a colour there is no need to save: probe_pixels and diff_against render in memory and write nothing into the project ("Measuring colour" below). The only other file a render tool writes is diff_against's optional difference picture, and it goes to this computer's temp folder, never the project.
  • One render per surface. Without save, the renderer shrinks the image with its own scale (RenderStillRequest.scale), so a big surface never crosses IPC whole. With save, the native PNG comes back once, is written as it is (or as JPEG), and the preview is shrunk from that same image in main (src/main/still-codec.ts, Electron nativeImage). The renderer, which also plays the show, does no extra work.

Sizes for a room of five LED walls (N 6400, E1 3200, E2 3840, S 4800, W 6400, all 1600 high) plus a 1920x1080 STAGE:

CallWhat comes back
render_still N, wholea 1568x392 JPEG, scale 0.245
render_still STAGE, wholea 1430x804 JPEG, scale 0.745 (held under 1.15 MP)
render_still N, region 1200x400that region at 1:1
render_surfaces, all sixone 1449x792 JPEG sheet, every surface at scale 0.149, in 3 rows
save: true on Nthe preview, plus renders/<scene>/stills/<scene>_N_6400x1600_t0.png on disk

render_still { scene, surface, timeMs, region?, scale?, save?, format?, fast? } — your EYES

  • Purpose: render one surface of a scene at native resolution, sampled at timeMs, and return a preview of it (see "Previews"). This is your eyes: ALWAYS render_still after a write_scene and look at the image before deciding you are done.
  • Params:
    • scene, surface (a surface project.yaml declares: a surface only the scene binds is refused with the project's surfaces, because it renders nowhere, as on the canvas and in an export; a field report, 2026-11-06, rendered stills of main-4k that the export then left out), timeMs (scene time in ms; 0 = frame 0). The description sends the model to get_project for both names (scenes, surfaces[].name): surfaces are whatever the project declares, so its examples are neutral ("main", "wall-left"). No tool description names a sports surface or size (server.test.ts pins it).
    • region? { x, y, width, height } — a pixel crop in the native frame, applied after the native render, to read detail at 1:1. A region up to the preview cap comes back at 1:1. A bigger region is shrunk to the cap, and the text says so and gives the largest region that shows 1:1. A region outside the surface is refused; one that runs off the edge is cut at the edge. Width and height must be positive.
    • scale? (0.1–1) — make the preview smaller still. It never goes past the cap: a bigger scale is lowered to the cap, and the text says so. Out of range is rejected.
    • save? — true also writes the full native image (the whole surface, or the region) to the project's renders folder and returns its absolute path. Only the preview is sent.
    • format? — the saved file's format, with save: true: "png" (default) or "jpg". format without save is refused.
  • Behaviour: a surface larger than the GPU texture limit is rendered in strips, never clamped to it. Errors clearly if the app window is closed.
  • Colour: a still has the colour of a best export: 16-bit frames, each clip from its deep file where it has one (assets.md §5), no dither; the PNG rounds each value to the nearest 8-bit level. The text says how it was read and names any clip read at 8 bits (no deep file, or its decode did not start). fast: true keeps the old path: the clips' 8-bit working files and 8-bit frames, the colour of a draft or an H.264 export, about half a level off a best export on a 10-bit clip (measured below, "Measuring colour"). render_surfaces takes fast too.
  • Returns: a text line and the preview image (image/jpeg). The text gives the preview size and the scale (native px = preview px ÷ scale), how to get 1:1 detail (region) and the full file (save), and the saved path when save was set. Sample a couple of times across the loop (e.g. 0 and half the loop) to catch motion and seam problems: the image is the source of truth, not the YAML.
  • A clip whose full file does not play on this computer (for example, an HEVC working file on a computer with no HEVC decoder) draws its proxy, a smaller copy, and the text has one line about it: 26-10_vinyl-n_003.mp4 drew its proxy (a smaller copy), not its full-size file: this computer cannot decode HEVC video. The image is then softer than an export. An export of that surface stops instead and names the file (assets.md §3).

render_surfaces { scene, timeMs, surfaces?, save?, format? } — the whole room

  • Purpose: see every surface of a scene in one image. Each surface renders once, at timeMs, and they all go on one contact sheet: a JPEG inside the preview cap.
  • The sheet: every surface of the project at the same scale, packed in rows in the project's surface order (get_project). A surface the scene binds but project.yaml does not declare is not on the sheet (a scene can only use the project's surfaces, help #surfaces-bind); warnings names it and lists the project's surfaces. Each tile has a label above it with the surface name and native size. A surface with nothing on it (no use: comp with nodes, no inline children) still appears, as a grey hatched tile marked empty; it is not rendered. A surface that fails to render is hatched and marked failed. The layout tries every row break that keeps the order and takes the largest scale (src/mcp/contact-sheet.ts). The labels use a small built-in pixel font, because main has no canvas.
  • Cost: the surfaces render one after another. Each one opens only the clips it draws, at their full working files, and closes them before the next surface starts. A clip whose full file does not play on this computer draws its proxy, as in render_still, and that surface's entry says so (proxy).
  • Params: scene, timeMs; surfaces? to render only some (the sheet keeps the project order; an unknown name is refused); save? and format? as for render_still, for every surface.
  • Returns: JSON — scene, timeMs, sheet (its size), scale, surfaces (each with name, size, its tile on the sheet as "WxH at (x, y)", and empty, error or proxy when they apply), saved (the paths, with save), warnings (surfaces the scene binds that the project lacks), read and next — and the sheet image (image/jpeg). On the sheet, native px = (sheet px − the tile's x or y) ÷ scale. It fails only when no surface rendered (for example, the app window is closed).

measure_text { text, font?, size?, …, wrap?, lineHeight?, maxLines? } or { scene, id? | path? } — type as it draws

  • Purpose: lay text out exactly as Starlight draws and exports it, and get the numbers: the lines, each line's width, the box, the baselines and the font's metrics. Use it to wrap, fit and line up type (UI cards, captions, a review in several lines) instead of measuring with font metrics of your own, which break whenever the font changes.
  • Params: either text with the text node's props (font, size, weight, letterSpacing, align, wrap, lineHeight, maxLines, overflow, anchorY, markup, stroke, strokeWidth; scene-format.md §text), to try a layout before writing it; or scene with id or path (comps.card.1.transform.0, as errors and references write it) for one text in a scene (the live scene when it is open), any props given laid over the node's own (wrap: 900 tries a width on it); or scene alone for every text in it (at most 200).
  • How it agrees with the pixels: the app lays the text out in a render window (where every export and still renders) with the canvas's brand fonts, through engine/registry/text-layout.ts layoutText, the function the text builder draws with. A plain text's lines are then drawn by Pixi's own text code; a unit test runs that code on a recording canvas and checks every line lands at the x and baseline layoutText reports (text-layout.test.ts).
  • Returns: JSON (one object for a text, a list with id and path for a scene). Every number is px in the text's own space: (0, 0) is its transform's point, y grows down. lines (text, width, x its left edge, baseline; a markup line's runs with each run's face, x from the line's left edge and width), box (x, y, width, height: what selection and snapping use), lineStep (baseline to baseline), topToBaseline (the box's top to the first baseline), outset (a text with an outline: half its strokeWidth; the box, and so topToBaseline, takes the outline in by that much on every side, while lines stay where the letters are, unmoved by the outline), size, font (asked, family that draws, fallback, and the font's own ascent and descent at this size, whole px as the browser gives them, and the ink height of a capital H and a lower-case x: capHeight, xHeight), faces (a markup text: the family, weight and slant of each style), truncated and lineCount (lines before a maxLines cut), units (how many letters, words and lines the text splits into for letters: as it draws, after wrapping and the cut; spaces are not units: time a stagger by it), letters (a text with letters:, scene format v15: its by, order, its own units count, staggerMs, lastStartMs = (units − 1) × stagger, when its last unit starts, and totalMs = its clock's period + lastStartMs when that clock has a period of its own), and warnings (a font that is not here, a missing italic or bold file). A markup text's style files are found by what the files say, by the table list_fonts reports (engine/model/font-styles.ts): the render window gets each file's family, weight and italic with the canvas's fonts.
  • Refused: no text and no scene; id with path; an id or path that names no text (the error lists the scene's texts); no app window (it measures with the app's fonts).
  • Cost: a layout is a few canvas text measures per line: well under a millisecond for a paragraph. The first call opens the render window if it is not open yet.

playback_stats { seconds?, play?, gpu?, glimpseAb?, recent? } — how the live canvas plays

  • Purpose: measure the open scene playing on the live canvas, for seconds (default 5, 1–60): the FPS HUD's numbers over the whole window, plus the video decoders. Use it after a heavy change (a tiled surface, big clips) to see whether the room still plays in time.
  • How: main asks the window (playback:stats-request); the canvas listens to its tick (the perf probe's seam, TickTiming: built only while someone listens) and the video transport counts each clip's waiting events, its seeks while playing, the seeks of matte files and the largest seek lead, and per clip what it was doing when it waited (VideoTransport.measure: listeners exist only during the measurement). So playback that is not measured does no extra work. A paused canvas is played for the measurement and paused again after; play: false refuses a paused canvas instead.
  • Returns: { scene, seconds, targetFps, fps, framesShown, dropped, ticks, tickMs: { mean, p95, max }, rebuilds, videos, videoStalls, videoResyncs, rendersPerSec, videoSeekLeadMaxMs, videoMatteSeeks, started, paused, hidden, walls, wallsTicked, clips, perClip, page, budget, note }. fps is frames shown per second; dropped the frames the transport skipped because a tick came late; videoStalls the times a playing clip ran out of decoded frames; videoResyncs the seeks a playing clip needed (drift past 6 frames, or a made loop's wrap). hidden: the window was hidden or minimized, which slows its frames. Errors clearly when no window is open.
  • Seeks and renders (0.2.28, clocks-and-animation.md §15). Use these numbers to check that playback does not get worse over time:
    • rendersPerSec: how many ticks per second drew the surfaces. While playing it is about targetFps (30 for a 30 fps scene). A number near the display rate (60 or more) means the surfaces are drawn again when no frame changed.
    • videoSeekLeadMaxMs: the largest seek lead of any clip, in ms. When a playing clip must seek, it aims this far ahead, so that it lands where the transport will be. It is never more than 250.
    • videoMatteSeeks: how many times the matte file of a two-file packed clip seeked. While playing it is 0 or a few. Before 0.2.28 a matte could seek on every frame.
    • The note says when rendersPerSec is well above targetFps, or when the mattes seeked more than about once a second.
  • What the zoom left the canvas drawing (assets.md §3), read once at the start and once at the end, never per frame:
    • walls: one entry per surface, in layout order: name, level (the texture level the surface draws at: 1 is its LED size, then two steps per halving: 0.707, 0.5, 0.354 … 0.03125), onScreen (on the canvas pane and not hidden by a focus), renders (how many times it rasterized during the window; 0 for a surface off the pane unless Glimpse reads it).
    • wallsTicked: the surface views the canvas updates each tick at the end (the surfaces on the pane, plus the ones the Glimpse feed reads).
    • clips: full (playing their full-size file: zoomed in, or a clip with no proxy), proxy (playing their quarter-size proxy), paused (no surface on the pane shows them, or still opening; while the scene plays, a clip a zoom just took off the pane plays on for up to 5 s first, docs/canvas-focus.md), parked (decoders a zoom swap replaced, kept open for 5 s for a zoom back).
    • The note says the same in words: which surfaces are on screen at which level, and the clip counts.
  • The Glimpse panel (0.2.30, previz-panel.md §6). While the panel is open, the reply also has room and feed, measured over the same window. With the panel closed, both are absent.
    • room: fps (room frames drawn per second; it draws only when something changed, at most maxFps), renders (frames drawn), idleSkips (display frames its loop ran without drawing; while nothing changes the loop stops, so it counts nothing), cpuMsP95 (CPU ms of one draw, 95th percentile), bufferPx (its drawing buffer in pixels at the end), resScale (the adaptive resolution, 1 = full), maxFps (the cap, room.feedFps) and paused (hidden: the panel could not be seen; background: the window did not have the focus; absent while it ran).
    • feed: copiesPerSec (surface frames drawn into the atlas), uploadsPerSec (atlas uploads: the crossings between the canvas's GPU device and the room's; one per new frame), bytesPerSec, msPerTick (CPU ms per feeding tick, mean), uploadMs (CPU ms of one upload, mean), maxMs (the slowest tick) and atlas (width, height, surfaces).
    • gpu: true (debug) adds GPU timings where the GPU offers them, and costs nothing when off: room.gpu (drawMsP95, uploadMsP95 from EXT_disjoint_timer_query_webgl2; available: false without it) and feed.gpu (copyMsP95 from WebGPU timestamp queries, timestamps: false when the device has none, which is the usual case; doneMsP95, the time from the feed's submit until the GPU had done it, including canvas work queued before it).
    • The note adds the room's draws per second and the feed's uploads and MB per second, and says when Glimpse was paused.
  • Each clip: why it waits (perClip). Use it when videoStalls is high but the canvas keeps its rate. There is one entry for each video element the transport drove during the window. The matte file of a two-file packed clip has its own entry. The counts exist only while the tool measures (VideoTransport.measure), so playback that is not measured does no extra work.
    • name: the file name only, never a folder. A trimmed node's clip or a plate keeps its #trim=… or #delay=… mark. role: full (the full-size file), proxy or matte.
    • clipFps: the clip's own frame rate, from the shortest step between two frames it showed. seconds: how long it was driven in the window (less when it joined or left during it).
    • framesShown and fps: the frames it presented (frame callbacks: each one is a new picture for the canvas). A matte has no frame count.
    • waiting: its waiting events. waitAtMs: when the first 30 came, in ms from the start of the window, so you can see the rhythm.
    • At each wait: waitReadyState counts how many waits found readyState 0, 1, 2, 3 and 4, and waitAheadS gives the seconds buffered ahead of currentTime (min, median, max). Both are read when the event arrives.
    • seeking: total (its seeking events), transport (the seeks the transport issued), resyncs (those it issued while the clip played), and other (seeks that someone else started, for example the clip's own loop wrap or the matte follower).
    • rateChanges (its ratechange events) and rate (the lowest and highest playbackRate).
    • playCalls and pauseCalls (made by the transport) and pauseEvents (from anyone).
    • quality: what getVideoPlaybackQuality() counted during the window (totalVideoFrames, droppedVideoFrames, corruptedVideoFrames).
    • driftMs: how far the clip's time was from the transport's target while it played (mean, max, samples; once per tick).
    • end: the element at the end of the window: readyState, networkState, paused, playbackRate, currentTime, the first 3 buffered ranges in seconds, and size (<width>x<height> of the decoded frame).
    • The note names the clip that waited most.
  • The page (page): visibilityState and hidden at the end, visibilityChanges during the window, rafs and rafFps (the page's own requestAnimationFrame callbacks; compare them with each clip's fps), and refreshHz (the refresh rate of the display the window is on, from the system).
  • How to read it. Some patterns, one per cause:
    • Too little data: waits find readyState 2 or less, and waitAheadS is small.
    • The transport: rateChanges, playCalls, pauseCalls or seeking.transport grow with the waits.
    • The decoder or the compositor: quality.droppedVideoFrames grows while waitAheadS stays large.
    • Drift: driftMs is large.
    • The page: page.hidden, visibilityChanges, or rafFps far from refreshHz.
  • The frame budget (budget, 0.2.34, previz-panel.md §6). Where each canvas frame's time went, over the same window. A canvas frame is the time from one canvas tick to the next (one animation frame). The budget is always counted, at almost no cost (under 1 µs a frame), so it is in every reply.
    • seconds, frames, frameFps (canvas frames per second: the page's rate, not the scene's) and playing (the share of frames that were playing, 0–1).
    • frameMs: the time from one frame to the next. Each number below is { mean, p95, max } in ms per frame. The p95 is accurate to about 10 %.
    • stages: the parts of the frame. Their means add up to frameMs.mean:
      • tickOther: the canvas tick, less the parts below (the transport, captions, HUD, rebuilds).
      • walls: the surfaces on the pane drawn.
      • feedOnly: the surfaces only Glimpse reads (off the pane or hidden), drawn on feed ticks.
      • feedDraw, feedCopy, feedUpload: the Glimpse feed. The changed surfaces drawn into its atlas; the atlas copied into a canvas the room can read (on WebGL this is a readback); that canvas uploaded into the room's texture (the crossing between the two GPU devices).
      • stage: Pixi's stage render.
      • roomDraw: one Glimpse room draw. roomReflect (the floor reflection) and roomZone (the zone glow) are parts of it.
      • wait: the time in none of the parts above. Something outside Starlight's own code held the next frame back: the GPU, the compositor, garbage collection or other page work.
    • gpuLagMs: how far behind each GPU device ran, sampled once a second: canvas (Pixi's device) and room (the Glimpse room's WebGL context). Each is { mean, max, samples } in ms, or null. It is the time from the moment the work was sent until the GPU had done it. The room's number is rounded up to the next canvas frame.
    • backend (webgpu or webgl) and glimpse (open, frames that fed the panel, atlas size, the room's bufferPx).
    • ab: the A/B mode of the window, when one was on.
    • Small parts can read 0 or 0.1 in one frame, because the page's clock has 0.1 ms steps. The means over many frames are right.
  • recent: true. The reply comes at once, with only { recent: true, budget, note }: the frame budget of the last 10 s. Nothing is played and nothing waits. Use it right after a slow moment, for example when the red fps warning shows.
  • glimpseAb (with the Glimpse panel open). It switches ONE Glimpse stage off for the window only. At the end it is switched on again. This also happens when the measurement fails, and by itself after 75 s.
    • no-upload: the feed draws and copies the surfaces, but does not upload them into the room. The room still draws, with its last wall frames.
    • no-feed: no feed at all (no atlas draw, copy or upload), and the surfaces only the room reads are not drawn. The room still draws when a surface on the canvas changes. The clips on hidden surfaces still play, and the panel's proxy floors stay.
    • no-room-draw: the room does not draw. The feed still draws, copies and uploads.
    • none (the default): nothing is switched off.
    • Without the panel open, any mode except none is refused. The note says what was off.
    • Compare the fps and budget of one run per mode. The recipe is in previz-panel.md §6.

Measuring colour: probe_pixels and diff_against

A field report (2026-11-06): stills and exports differed in colour, so a patch's colour could only be matched from exports, and the stills had to be saved into the shared renders/ folder to be measured. Three changes answer it (src/mcp/pixel-tools.ts, src/shared/pixel-probe.ts, src/main/plate-frames.ts).

Why a still differed from the export. A best export (HEVC 10-bit, ProRes) renders 16-bit frames and reads each clip with more than 8 bits from its deep file, through ffmpeg (assets.md §5). render_still read the clip's 8-bit working file through the render window's <video>, into 8-bit frames. The working file is the source rounded to 8-bit Y'CbCr, so a flat patch moves by up to half an 8-bit code of luma and chroma: about half a level in R'G'B'. Measured through the real ffmpeg and the app's own conversions (src/main/still-colour.test.ts: a 10-bit source of 16 flat patches ingested as ingest makes it, an H.264 working file and a ProRes deep file; the best export encoded with its own argv, libx265 4:4:4 quality best with the dither, and decoded back; mean |still − export| over each patch's middle, in 8-bit levels; STARLIGHT_STILL_COLOUR_REPORT=1 prints the table):

before: 8-bit working file, 8-bit framesnow: deep file, 16-bit frames
mean over the 16 patches0.450.07
worst patch (one channel)1.000.17
worst pixel1.890.83
the 8-bit pixel against the export's 8-bit pixel: mean, worst0.36, 20.15, 1

The "before" column is the <video> path at its best (an exact conversion of the 8-bit samples): Chromium's own conversion can only add to it. What is left "now" is the export's own dither (at most ±0.49 of a 10-bit code), its 10-bit rounding and the encoder's loss. A pixel of the still's PNG is within 1 level of the same pixel of the decoded export, on every pixel of the fixture. Every 8-bit level drawn opaque comes back as itself through the 16-bit path (src/shared/pixel-probe.test.ts), so an 8-bit picture is the same on both paths.

The fix. render_still and render_surfaces open their session as a best export does: frameFormat: 'rgba64le', the deep decode (deepClip), and no dither (a still shows the value, not the encoder's pattern); the PNG takes each value to the nearest 8-bit level (pixel-probe.ts deepTo8; a translucent colour to the nearest level the PNG's 2D canvas keeps, deepTo8ForCanvas). fast: true keeps the 8-bit path. Scene list thumbnails and the canvas's start frames keep the 8-bit path: they are small pictures, not measurements.

Cost. On WebGPU the 16-bit render and read-back cost no more than the 8-bit extract (§2 of export-rendering-and-building.md). The deep decode adds, per clip with a deep file and per still: main's open (the sample table and a probe), the first time per file the graphics card check (frame 0 on the card and on the CPU), and one ffmpeg that seeks and decodes one frame (tens of ms on the card, a few hundred at 6400×1600 on the CPU). Not measured in the app yet. Nothing changes for the canvas or playback: no per-frame cost. fast: true skips it.

probe_pixels { scene, surface, timeMs | frame, points?, rect?, fast? }

  • Purpose: the exact values of points (at most 64) and of a rectangle of one surface at one time, to check a colour without saving anything.
  • How: it renders exactly as render_still does, in memory: main opens a session in the render window (openPixelSession, the export's open with frameFormat: 'rgba64le' and dither: false), the window's read step renders the frame and answers only the values asked for (readFrame: the points, the rectangle's mean / min / max), and the session closes. No file is written anywhere. A file the scene draws that does not load fails the call: a check never measures an empty spot (render_still draws it empty).
  • Params: scene, surface (a surface project.yaml declares; another name is refused with the surfaces it has), timeMs or frame (an export frame at the scene's fps: frame × 1000 / fps), points: [{ x, y }] and/or rect: { x, y, width, height } (native px; off the surface is refused), fast.
  • Returns: JSON. Each point: rgb8 (the 8-bit pixel, as in render_still's PNG), alpha8, levels (R, G, B as 8-bit levels with the fraction the 16-bit render keeps, e.g. 64.62), float (0–1, with alpha) and hex. The rect: pixels, mean (the same fields), min and max (levels and hex). colour says how it rendered; clips8bit names any clip read at 8 bits.

diff_against { scene, surface, plate, frames | timeMs, plateOffsetMs?, region?, threshold?, image?, fast? }

  • Purpose: compare one surface with a plate (an image or a video in assets/, the surface's size) over a few frames, in plain numbers: the QA a person runs before handing a fix back.
  • How: one render session for all the frames (as probe_pixels; the window sends back the region's 16-bit pixels for each frame, one at a time). The plate is read by main with ffmpeg (plate-frames.ts openPlate): an ingested clip from its deep file when it has one (as a best export reads it), else the file; a video decodes as the deep decode does (4:4:4 16-bit Y'CbCr, then the file's matrix and range in floats: exact, no 8- or 10-bit rounding), an image at its own depth (rgb24 for 8 bits: swscale's 8 → 16-bit RGB is not exact). A file that is not on this computer (online-only) is refused, never downloaded. The plate frame for scene time t is floor((t + plateOffsetMs) × plate fps); a time past the plate's end is refused. The render is compared as an opaque export shows it (its colour times alpha, over black).
  • Params: frames (export frame numbers at the scene fps) or timeMs (scene times), at most 10; plateOffsetMs (default 0); region (the same part of both, native px; at most 20 million pixels a frame); threshold (levels, default 2); image; fast.
  • Returns: JSON: plate (the file read, how it decoded, its size, rate and frames), area, colour, summary (one sentence), overall and frames[], each with meanAbs, meanSigned (the bias: above 0, the render is brighter), maxAbs (per channel R, G, B, in levels), overThresholdPct (pixels with any channel more than threshold off), worstPixel (its place, both values) and worstBlock (the 32×32 square with the largest mean difference; smaller for a small region). With image: true: a picture of the difference (each channel × 32, so 1 level is dim and 8 are full; each image pixel the largest of those it covers, so one bad pixel shows), at most the preview size, sent for the frame with the largest mean difference, and one PNG per frame written to this computer's temp folder (<temp>/starlight-checks/<project>-<hash>/<scene>/…, src/main/check-images.ts), whose paths are in images.

Where check images go. render_still { save: true } writes into the project's renders/: a still someone asked to keep, which a shared project syncs to the team. A check image is nobody's deliverable, so it never goes there: probe_pixels writes nothing, and diff_against's pictures go to the system's temp folder, which never syncs and which the system empties by itself.

scaffold_extension { name, kind, description }

  • Purpose: scaffold a new extension into <project>/extensions/<name>/index.js — a working minimal example with TODO markers — and record it in the manifest.
  • Params: name (lower-kebab-case, must start with a letter, e.g. led-scan); kind = "effect" or "node"; description (one line, goes in the file header).
  • Behaviour: kind: "effect" is the fully-wired path — authorable in scene YAML immediately (effects: [{ <name>: {...} }]). kind: "node" registers a node type (appears in the catalog, builds correctly), written in scene YAML as node: <name> with its props as siblings (scene-format.md §4). Refuses to clobber an existing index.js (edit it in place instead).
  • Returns: { ok: true, path, instructions } — the project-relative path plus numbered next steps (edit → save → get_project to confirm → use → render_still).
  • Trust: the new extension is trusted for the rest of the app session (it and its edits load with no prompt — §5); the next launch asks once. Hand-copied or pulled-in extensions are asked about on load.

export_formats

  • Purpose: which delivery formats this machine's ffmpeg can write, probed from ffmpeg -encoders (on Windows the hardware HEVC encoders are test-encoded first): each with its id, label, extension, alpha, image-sequence, the encoder it will use (e.g. prores_videotoolbox, hardware ProRes on macOS; hevc_nvenc on Windows) with hardware and maxEdge (its largest frame edge), or why it is unavailable (e.g. HAP missing from the build). Call it before export_scene.

export_scene { scene, fps?, format?, output_fps?, interpolate?, surfaces?, loops?, length?, allowMissing?, quality?, dither?, size?, motionBlur? }

  • quality (HEVC): a preset (best, the default: 4:4:4 10-bit at constant quality 12 with spatial AQ 8; compatible: 4:2:0 Main 10; draft: quality 20) and fields that override it (chroma, quality, aq, aqStrength, maxrate, gop, bframes; an unknown key is an error), over project.yaml export.quality and the artist's last ⌘E sheet choice. The result returns the resolved quality, each surface's encoderArgs, and qualityFallback when a 4:4:4 preset encoded 4:2:0. export_reel takes the same quality (export-rendering-and-building.md).

  • Purpose: render a scene — every surface, or surfaces — to native-resolution video via the app's bundled ffmpeg (the same pipeline as ⌘E). Deterministic and loop-perfect (exactly loops × the surface's loop × fps frames). By default each surface's file is its own loop: a surface with a 10 s clip gets a 10 s file, a 17.2 s surface a 17.2 s file, so files started together play like the canvas, each on its own loop (export-rendering-and-building.md). Writes <project>/renders/<scene>/<scene>_<surface>_<WxH>_<fps>fps_<codec>.<ext> (or the project.yaml export.naming template; image sequences write a frame folder). This is the project folder in a shared project too: the files sync to the other artists, and outDir and every path in the result say where they really are. Each file is written as a hidden partial, .~<name>.partial.<ext> (Dropbox does not sync names that start with .~), and renamed into place only when it is finished, so an older file of the same name stays until then (and survives a cancel or a failure). The scene's audio nodes (export: true, the default) and un-muted video clips' own sound mux into every video. Requires the app window open.

  • Params: fps? (render fps; default the scene fps, else 30; at most 240); format? = h264 (mp4), hevc (mp4, HEVC Main 10 on NVENC / VideoToolbox, else libx265), hevc444 (mp4, HEVC Main 4:4:4 10 on NVENC, else libx265; QuickTime may not play it; = hevc at quality chroma 444 — hevc itself is 4:4:4 by default, the best quality preset), prores422hq, prores4444 (alpha), hapq, png-sequence, exr-sequence (prores = prores422hq; default project.yaml export.formats[0], else hevc on Windows and prores422hq on macOS when this ffmpeg can encode it, h264 elsewhere: defaultExportFormat); output_fps? (24 / 25 / 30 / 50 / 60: ffmpeg converts, duplicating or dropping frames, or motion-interpolating with interpolate: true, much slower); loops? (seamless passes of each surface's loop, default 1); length?: "native" (the default: each surface at its own loop, or the scene loop with the reason), "scene" (every surface at the scene loop: equal lengths, for a media server that restarts the surfaces together; "loops" is its old name), "track" (until the longest exported audio track ends, rounded up to whole scene loops); allowMissing? (below). Never change the scene loop to get other surface lengths: the default already gives each surface its own, and "scene" gives equal ones.

  • size (the pixel size of each surface's file; export-rendering-and-building.md §6): "wall" (the default: the LED size), "design" (the surface's artboard: the scene's design:, or the surface's own), or "WxH" (for example "3840x2160") of the surface's shape. The file is rendered at that size, never made bigger after: text, shapes and SVGs draw at the new size, clips read their full files, and a blur or a feather keeps the look it has on the surface. "design" needs a fit that scales the artboard onto the surface (fill, cover, contain) at the surface's shape; a surface whose artboard is its own size stays at its size. Refused in words, before anything renders: fit none or a tile fit, another shape (the error names a size that fits), more than 16384 px a side, more than the encoder takes; a surface this graphics card cannot draw in one piece at that size stops before its first frame. The file name and surfaces[].size carry the real size, surfaces[].wallSize is the surface's own, and the result has size. For a master at the plate's size, use size: "design"; never add a surface to project.yaml or the scene for it (a field report, 2026-11-06). A Glimpse publish always uses the LED size.

  • motionBlur (exports only, default off; export-rendering-and-building.md §2): true (a 180° shutter, 8 samples), false, or { shutterAngle, samples } (more than 0 to 360 degrees, 2–32 samples). Each frame becomes the mean of samples moments over a shutter centred on the frame, summed at 16-bit float precision, so fast motion smears instead of strobing. It costs about samples× the render time. Over project.yaml export.motionBlur; never the artist's ⌘E sheet choice. Videos and pre-render plates hold their frame for every sample. render_still and the pixel checks never blur, so a blurred export differs from them on purpose. The result has motionBlur with its cost; a surface whose card cannot render it says why in surfaces[].motionBlurNote. export_scenes and export_reel take it too.

  • Media pre-flight: before any frame renders, the export checks every file the exported surfaces draw and every sound it mixes. A file that is missing, online-only (Dropbox), cannot be read, needs a cutout this machine cannot make, or has a transparency this machine cannot decode makes the tool fail with nothing rendered. The error lists every such file, one per line, with its scene, layer, comp and surfaces (export-rendering-and-building.md §6). Fix the files. allowMissing: true renders anyway: the files draw as empty spots, and a video frame whose seek never lands renders the frame the clip holds. Never pass it just to make the error go away.

  • Returns: { ok, scene, fps, format, outputFps?, outDir, loopPerfect, loops, length, audioTracks, soundNote?, surfaces[] } (soundNote: the sound is cut to each surface's own length), plus, after allowMissing, warnings (plain words), mediaProblems and seekStalls (loopPerfect is false after a stall). Each surface carries path, size, frames / expectedFrames, wallLoop (with length: "native": { loop: "own" | "scene", seconds, frames, still?, reason? }, e.g. reason: "N mixes a 10 s video (forest.mp4) with the text \"GOAL\" animated over 17.2 s"), loopPerfect, durationMs, backend (webgpu/webgl/software), maxTextureSize, strips, msPerFrame, readback (direct/extract), and optional encoder, encoderFallback (why the better encoders were passed over, e.g. hevc_nvenc tops out at 8192 px), pattern (sequences), stageTiming, padded, seekStalls + stallSamples (clip + clip time), slowSeeks (seeks over a second that landed: ingest the clip), and replaced: true when it replaced an older file (the tool does not ask first; the app's ⌘E does).

  • Health check: if backend is webgl (not webgpu) or msPerFrame is high, the GPU path regressed — flag it. This delivers the finished per-scene package.

  • Canceled: an export that is canceled (Esc or the stop button in the app, or cancel_export) answers a normal result, not an error: { cancelled: true, cancelledBy?, message, scene, outDir, files }. cancelledBy is artist or claude when the app knows who canceled it. files are the surfaces that finished before the cancel; they are kept. message says the same in words, and tells the agent not to export again unless the user asks.

  • Several scenes: use export_scenes (below), not one export_scene call per scene.

export_scenes { scenes, fps?, format?, output_fps?, interpolate?, surfaces?, loops?, length?, allowMissing?, quality?, dither?, size?, motionBlur? }

  • Purpose: export several scenes, in the order given, as one export run. Each scene writes exactly the files export_scene writes for it: the same renders/<scene>/ folder, the same names, each surface its own loop by default. Nothing is joined (for one file per surface over every scene, use export_reel). Because it is one run, the app's export monitor shows the project line over every scene, scene 2 of 4, one time left, one done with every file, and show in Finder opens the top folder (renders/). Esc or cancel_export cancels the whole run. Claude exporting scenes with one export_scene call each makes one run per call, each showing only its own scene. Requires the app window open.
  • Params: scenes (required): scene names, in order, each once. An empty list, an unknown scene and a scene listed twice are refused before anything renders. The other params are export_scene's and apply to every scene (image sequences work too). With size: "design" each scene renders at its own artboard; every scene must take the size, checked before the first renders. There is no destination: the MCP export tools always write into the project's renders/.
  • Media pre-flight: every scene is checked before the first one renders, as in a reel: a problem in any scene stops the export with nothing rendered, and the error lists every file with its scene and layer. allowMissing: true renders anyway, as on export_scene.
  • Cancels and failures: a cancel (Esc, the stop button, cancel_export) or a scene that fails ends the run there. The scenes already written are kept, and so are the surfaces the last scene finished. A cancel answers { cancelled: true, cancelledBy?, message, outDir, files }, not an error; a failure is an error. Both name what was kept (scene a-intro finished and is kept (2 files)).
  • Returns: { ok, outDir, totals: { scenes, files, frames, durationMs }, warnings?, mediaProblems?, uiDelay?, scenes[] }. outDir is the renders folder. Each entry of scenes is the export_scene payload of that scene (its files, surface lengths, warnings, telemetry), plus its durationMs.
  • Progress: main tags each event with sceneIndex / sceneCount, the files before the scene and in all (filesBefore / filesTotal) and join: false, so the monitor counts no step for joining reels (export-rendering-and-building.md §6).

export_reel { fps?, format?, output_fps?, interpolate?, surfaces?, scenes?, allowMissing?, quality?, dither?, size?, motionBlur? }

  • Purpose: export the whole reel (the same pipeline as ⇧⌘E): render every scene, then join the scenes into one file per surface (ffmpeg concat) into <project>/renders/reel/reel_<surface>_<WxH>_<fps>fps_<codec>.<mp4|mov> — cut transitions only, no audio, stream-copy (re-encode-free). This is the finished multi-scene deliverable, one file per surface. Image sequences are not reel-able. Every surface of every scene is the scene loop (length: "scene"): the reel cuts every surface to the next scene at the same moment.
  • Params: as export_scene (output_fps is needed when scenes differ in fps), plus scenes? — explicit scene order; omitted → all scenes except names starting "99" (the convention for scratch/reference scenes). The media pre-flight checks EVERY scene before the first renders; allowMissing works as on export_scene. With size, every scene must render each surface at ONE size (the join copies the streams): two sizes for a surface are refused before anything renders (give one "WxH", or use export_scenes).
  • Returns: { ok, fps, format, reelDir, reels[], scenes[] } — one concatenated video per surface (reels) plus a per-scene breakdown (each an export_scene-shaped payload). For separate files per scene and no reel, use export_scenes. A canceled reel answers { cancelled: true, cancelledBy?, message, reelDir, files }, not an error: files are the scenes' files written before the cancel (and any reel already joined).

cancel_export

  • Purpose: cancel the export that runs now, whoever started it: an export_scene, export_scenes or export_reel call (from any session), the artist's ⌘E or ⇧⌘E, or a glimpse_publish (its exports, playback copies and uploads). It is the same cancel as Esc's Cancel Export in the app, without the question, because the person asked Claude to stop it. The export ends as canceled: the export monitor says export canceled · intro, never export failed. The surfaces that finished are kept; the surface in progress keeps its old file. A node pre-render is not an export, so it keeps going.
  • Params: none.
  • Behaviour: main's render guard (src/main/render-guard.ts stopExport) sets the same cancel flag as Esc, with cancelledBy: claude, and waits until the export has really ended: at most 20 s, the same wait as Stop and Quit.
  • Returns: { cancelled: true, kind, scene?, job?, ended, endedAfterMs | waitedMs, message }. kind is scene (⌘E, a surface, export_scene), scenes (export_scenes), reel or publish. ended: false means it had not ended after 20 s: it stops at its next frame, and a second call says when nothing runs any more. With nothing exporting: { cancelled: false, running: false, message }. That is an answer, not an error.
  • The waiting call: the export_* call that started the export answers cancelled: true with cancelledBy: claude and the files already written; glimpse_publish answers cancelled: true. Neither is an error.
  • Never kill ffmpeg. Killing ffmpeg or the app's processes from a shell makes the export fail (encode failed for "N" — ffmpeg exited -1). Every export tool's description says so.
  • When the MCP client stops waiting: an export_* call can run for 25 minutes or more. It sends MCP progress while it runs (Long calls report progress), so a client that resets its timeout on progress, as Claude Code does, keeps waiting. If the client stops waiting (the person interrupts Claude, or a client timeout), the MCP SDK sends notifications/cancelled for the request. Starlight does not cancel the export then: a client timeout sends the same notification as an interrupt, and a long export must never be canceled by surprise. The export keeps running in the app; cancel_export stops it.

music_map { asset }

  • Purpose: an audio asset's musical map, for pacing a scene to its song: bpm, the beat count and first beat, downbeats, key / mode, sections (each with a group letter shared by repeats, and its energy), drops, builds, climaxMs, and kick / snare / hat counts. Times in ms from the track start.
  • Params: asset, a project-relative path (absolute paths and .. are refused).
  • Behaviour: reads the analysis cache the app writes when the project is open; with no fresh analysis it errors and asks you to open the project with the asset in a scene.

assets_ingest { path?, dry_run?, wait?, status?, cancel? }

  • Purpose: ingest video already in assets/ that has no all-intra working file or proxy (copied in before ingest existed, or an interrupted ingest), so it scrubs and exports fast. It first re-keys ingest sidecars of clips moved or renamed outside the app, then queues every un-ingested .mp4 / .m4v / .mov (or just path) on the app's serial ingest queue. Scene srcs never change. Returns at once with queued, skipped (with reasons), rekeyed, unmatched and a batch id; status: true reports the batch plus queue: { done, total, failed, running }, the whole ingest queue (imports and drops too: the same count as the app's ingest line; queue.waiting while an export, reel or publish holds it: nothing ingests then, and it goes on by itself after), cancel: true stops it, wait: true blocks until it ends (at most 10 min, sending MCP progress meanwhile: Long calls report progress), dry_run: true changes nothing. Full reference: assets.md.

assets_import { path }

  • Purpose: import ONE image, video or audio file from outside the project, the same as dropping it on the app window: for designs the artist exports elsewhere (a Dropbox Design/_exports folder).
  • Behaviour: the drop's own path in main (importThroughIngest → importAssetFromPath): the file is copied into assets/ under a safe name that never overwrites (poster.png, poster-2.png, …); a HEIC / TIFF / EXR / AVIF / BMP / TGA / DPX still becomes a PNG; a video is copied, then gets its all-intra working file and proxy on the ingest queue; a checkpoint import: <file>. The asset watcher updates the app.
  • Refuses (nothing copied): a path that is not absolute (or ~/…), a file type the window drop does not take (DROP_MEDIA_RE, src/shared/asset-url.ts: the drop and this tool share it), a file already in the project's assets/, a missing file and a folder.
  • Returns: { ok, from, assetPath, kind: image | video | audio, note }.

list_fonts { family?, system? } — which file is which weight

  • Purpose: the project's fonts, read from the font files themselves, so Claude never guesses which file holds a weight. Field report (2026-11-06): "No font inventory tool, and no guidance on how a family's weights map to files in brand.fonts." Call it before writing text in a brand font, and when a text draws a fake bold or italic or the fallback font. The rule it enforces, and the guide for artists: scene-format.md §2 "Weights and styles of a brand font", help #brand-font-styles.
  • Params: family narrows everything to fonts whose family, key or file contains it ("inter"); system: true also lists the font families installed on this computer (at most 200, more counts the rest) and checks the texts in fonts that are not brand fonts against them. Takes project (a project that is not open, below): it reads every scene of it.
  • Returns (JSON):
    • rule: the one-line rule (one key = one file = one weight and style; a text picks its weight by its key; markup finds its style files by what the files say).
    • families: each brand family by the name inside its files (name ID 16, else 1), with keys (key → { file, style, weight, italic, format, variable? }; status for a file that is missing, online-only, unreadable or not-loadable), markup (for the family's regular key: the key a markup: true text draws *italic*, **bold** and ***bold italic*** from, or null), notes (a file in fonts/ with no key that is a style markup lacks; a variable font), and texts (every scene text in the family, at most 25: scene, path as measure_text takes it, key, font when written otherwise, the weight, italic and markup styles it asks for, and problems: a weight: on a brand file (600 and up is a fake bold, lower does nothing), italic asked of an upright file, a markup style with no file).
    • notDeclared: files in fonts/ that brand.fonts does not name, with what they are and addsAs: the key ↻ (or a drop on the window) gives each (rescanFonts: top-level files, name order, -2 on a clash). A file in a subfolder or a collection (.ttc) says why it has none.
    • problems: keys that do not load (a missing file, a path outside fonts/, a path spelled with other capitals than the file, not a loadable type) or were not read (online-only).
    • otherFonts: texts whose font is not a brand font, grouped by name, with where it draws and, when a brand family has that face, the key to write instead.
    • textsWithoutFont, scenesNotRead, and with system: true, system ({ total, families, more?, partial? }).
  • How the files are read: src/main/font-files.ts lists fonts/ (bounded, depth 4), reads every file's flags in ONE child process, and reads only the files on this computer (bounded, readSharedBytes). An online-only file is reported and never downloaded. Each file goes through src/main/font-meta.ts, a small reader of the name, OS/2, head and fvar tables (OpenType, TrueType, collections, WOFF through zlib, WOFF2 through brotli: Node's own zlib, no new dependency). Nothing is loaded into a renderer or a FontFace. The system list reads the font folders (macOS /System/Library/Fonts, /Library/Fonts, ~/Library/Fonts; Windows %WINDIR%\Fonts and the per-user folder), a few small reads per file, at most 15 s, kept for 10 minutes; a font an app activates by itself (Adobe Fonts) may be missing from it.
  • How a text is matched: as the app draws it: resolveFontChoice for its font: name over the keys that load (and the installed families with system: true); each brand file is one family at one weight (a FontFace with no weight); markup's style files come from the same table the text layout asks (engine/model/font-styles.ts brandFonts): the same family, the italic at the nearest weight, the Bold (700, else the nearest heavier), any key name, any capitals. A key whose file is online-only here is found by its name (<stem>-italic …), as the app does for a file it cannot read.
  • Registered in src/mcp/font-tools.ts (registerFontTools). Read-only: no version.

stage_list / stage_read / stage_write / stage_delete / stage_capture — stages

3D shot blocking for one AI generation, stored in a scene's stages: map. stage_list { scene?, catalog? } lists them (catalog: true adds the authoring reference and an example); stage_read returns one in full with its frame, shot, checks, layout paragraph and captures; stage_write { scene, stage, yaml? | doc? } creates or replaces one complete stage, validated first, touching only the stages: block (checkpoint mcp: stage <scene>/<id>); stage_delete removes one (its captures stay). stage_capture { scene, stage, passes?, long_side?, recipe? } renders the saved stage's grey layout off the main thread, returns it as an image with the layout paragraph and gen, a ready gen_create block, and never spends (checkpoint stage: capture <scene>/<id>; an unchanged stage answers reused: true). Full reference: stages.md.

canvas_focus { comp? | surface? | stage? | off? } — what the window shows

Read (no argument) or set the live canvas focus: comp shows and renders only the surfaces that comp feeds, surface only that surface, stage: "<scene>/<id>" opens the Stage panel on that stage (its scene must be the one on show), off: true brings every surface back. Returns { on, scene, comp?, surfaces, hidden, label, stage_panel } (stage_panel: the stage the Stage panel shows, or null). View state only: no checkpoint, and render_still, exports and glimpse_publish always render every surface. It errors when the app window does not answer within 1 s. Full reference: canvas-focus.md.

canvas_layout { set? | rows?, aside?, gap?, join? } — where the surfaces sit

The surface layout: where each surface sits on the canvas. It is view state only. It never changes the output, an export, render_still or Glimpse. One layout serves every scene of the project, and each surface's size comes from the open scene. The pure handler is src/mcp/layout-tools.ts; main's host (src/main/canvas-layout-host.ts) asks the window, and uses the file when no window has the project open.

  • Read (no arguments): { scene, surfaces: { <surface>: { x, y, w, h } }, gap, unsaved }. scene is the open scene (the sizes are its sizes). gap is the app's gap between stacked surfaces (260 px). unsaved is true when the artist moved surfaces and did not save yet. With a window, this is what the window shows, unsaved moves included. With no window, it is layout.json, and each surface at its size in the scene the app opens. A surface the file does not list is where the canvas would put it by itself.
  • set: { S: { x: 3840, y: 3720 } }: move only the surfaces it names. x, y are the top-left corner, in canvas px.
  • rows: [["N"], ["E1"], ["E2", "S"], ["W"]], aside?, gap?, join?: arrange surfaces in rows from (0, 0), top to bottom. The surfaces of a row share a top edge and sit left to right, join px apart (default 0: they touch). Each row starts gap px below the tallest surface of the row above (default: the app's gap). aside: ["STAGE"] stacks surfaces in a column, gap px to the right of the widest row. Surfaces you do not list keep their place. Each surface may be listed once.
  • Positions are whole pixels (rounded).
  • Applying a move: live, through the same path as a surface drag: the artist's open edit burst lands first as its own step, then the move is ONE undo step (Claude: move 2 surfaces) on the open scene's ⌘Z list. A move is refused while the artist drags a surface (or holds another drag). Nothing moves then.
  • Saving: at once, as a layout-only save (saveProject with scenes: [] and the surfaces). Only the layout's unsaved flag clears. It is never ⌘S's save(), which would also save, checkpoint (and in a shared project publish) the artist's unsaved scene edits. In a local project the save makes a checkpoint, because layout.json is in git.
  • No window: main writes the file: the moved surfaces (each keeps its guides), and the other surfaces where the read showed them, only where the file has no entry yet.
  • Returns: { ok, moved, scene, surfaces, saved, checkpoint?, overlaps?, warnings?, note }. surfaces has every surface's new rectangle. overlaps lists surfaces that cover each other ("E2 and N"; surfaces that only touch do not count). warnings has a line for each moved surface that another scene gives another size (it may overlap there). An unknown surface name is an error that lists every unknown name and the project's surfaces, and nothing moves. Nothing to move (every surface already there) answers moved: [] and saves nothing.

The file. layout.json is in the project's state folder: .starlight/layout.json in a local project (in git, so every checkpoint holds it and a restore puts it back), and <app data>/projects/<key>/state/layout.json in a shared project (this computer's own file: never in the shared folder or in git). The app reads and writes it through the per-machine state service (architecture.md "Per-machine state files"), which also watches it. So a hand edit of the file shows on the canvas at once too: each surface the artist has not moved since the last load or save takes the file's place. A surface the artist did move keeps the artist's place, and a bar asks the artist which one wins. ⌘S writes only the surfaces moved since the last load or save, merged into the file as it is then, so an outside edit to another surface survives it. Prefer canvas_layout to a hand edit: it checks the names, and it is an undo step.


gen_models / gen_create / gen_list / gen_status / gen_cancel / gen_import / gen_grade — AI generations

Hosted AI jobs (Magnific API by default, videorouter.sh, the Higgsfield API, or the Atlas Cloud API) through the same main-side service as the Generations panel — a job created here is the same record the panel lists and is pushed to it live. gen_create quotes first (dry_run: true) and only spends when called again with max_usd ≥ the quoted price, under STARLIGHT_MCP_GEN_MAX_USD, i.e. the MCP spend cap in Settings › Generation (default $20) per job. A job with no price estimate (quote.usd absent) has nothing for either to check, so it spends only with accept_unpriced: true, which the agent sets after telling the user the cost is unknown and hearing yes (the refusal says so; a $0 cap refuses it whatever; with transparent, a priced job alone still answers to the cap). The same rule holds for gen_import { transparent }, generate_tiles and compose_run. The dry run's cap block (src/mcp/spend-cap.ts) says before anything is approved whether the job is over the cap and, for a model priced by length, which durations fit under it (lengthsUnderCap, from the service's own quote per length: no provider call); a quote and a job carry two levels of message: warnings (worth stopping for: it may be refused, cost more than the estimate, or come back worse or another size than asked) and notes (information only: where a price comes from, which host VideoRouter used); gen_status returns the result poster as an image once done, and lostAtProvider: true when the provider no longer has the job and its result is not on this machine (expired, or made with another key: only a retry, which spends again, makes it again); gen_import copies an output into assets/ with a checkpoint. transparent: true on gen_create (image results) or gen_import adds a paid Magnific Remove Background follow-on whose transparent PNG imports itself into assets/. A stage capture is an ordinary image input: stage_capture returns a ready gen_create block for it (stages.md). gen_create with a tile block runs a tiled upscale at native resolution (overlapping tiles under the 25.3 MP / 8192 px caps, one quote and one max_usd for the set, the comp written into a scene); tiles_check { id } measures every seam of it (a rendered strip across each overlap, plus how differently the two tiles drew it); tiles_check { scene, surface } checks a Tile Plan surface instead (below). gen_grade { id, grade | null, reason? } marks a job the way the panel does (circled · select · hold · soft · ng · ref) and answers with the previous mark; gen_list { grade } filters by it. Full reference: generation.md (§8 for tiles, §9 for grading).

version_create — versions of a clip, local and cloud

version_create { src | scene+node, preset | op+params, from?, target?, dry_run?, max_usd? } makes a version of a clip (assets.md §10). It is the same job service as the app's make version menu. Follow a job with version_status, and put the result on a layer with version_use.

  • Local ops (denoise-light, denoise-strong, deflicker, deband-light, deband-strong) are free and run on this computer.
  • Mattes (person-matte, person-matte-accurate, depth-matte; op person with { quality: balanced | accurate }, op depth) are free and made on a Mac only (elsewhere the plan is refused). The first depth matte downloads the depth model once (≈ 50 MB; the quote says so). A matte never becomes a layer's picture: cut a layer by it with matte_use (masks.md §8).
  • Cloud mattes (not offered yet: until a real run has pinned what fal sends back, their plan is refused with This cloud matte awaits a test run…) are made at fal.ai on any computer, Windows too, with a fal key in Settings › Keys. They are paid and follow the same money rules as the cloud op below (dry_run first, then max_usd ≥ the quote, the per-job MCP cap).
    • roto-matte-fal (op roto, params { prompt: 'the singer' }): SAM 3 tracks what the prompt names through the clip; white keeps it. A comma keeps several things (person, guitar). $0.005 per 16 frames (10 s at 30 fps ≈ $0.095).
    • depth-matte-fal (op depth, params { engine: 'fal' }; without engine a depth matte is made on this Mac): Video Depth Anything Small, white = near. $0.04 per second.
    • At most 2400 frames. The clip goes up at 1920 px on its long side at most, without sound; the matte comes back at the clip's size and frames. fal keeps both for a day at most.
    • When the job is done, matte_use cuts a layer by it. The same matte (op, prompt, the clip as it is) already made is used again instead of paid twice.
  • The cloud op upscale-ltx (upscale to surface · LTX, op upscale, params { model: 'ltx-refine' }) renders the clip again, sharper, on starlight cloud. It is paid.
    1. Pass target: { width, height }: the size the clip is shown at on its surfaces. It has the original's shape, is at most 8192 px a side, and is not smaller than the clip.
    2. Call with dry_run: true first. The answer has the quote (steps, seconds, usd, estimated, line, notes) and a cap block: the MCP spend cap per job and whether this job is over it.
    3. A quote over the MCP spend cap (Settings › Generation) is refused. The user can start it from the app instead.
    4. To start it, call again with max_usd ≥ the quote: the price the user accepted. This is the gen_create rule. The version service checks both again.
    5. version_status shows the steps (guide, cloud, adopt), the cloud's own words (for example rendering, 12 min), and the cost once the render ends.
    6. version_cancel cancels the cloud job too. A render that has already started cannot be stopped: it runs on and is billed, and the job's warnings say so.
  • The plan refuses a clip with too many frames for its size, and says the limit (starlight cloud takes up to 481 frames (19.2 s) at 6400×1600; this clip has 600 frames). It also refuses a clip with alpha (LTX refine makes no alpha). The version keeps the clip's sound, as the local versions do.
  • from: <version id> upscales a version (a chain), for example after a denoise.

plan_tiles / generate_tiles / assemble_tiles / tiles_check / set_tile_match — Tile Plan

A surface can be bigger than any video model makes (N is 6400×1600; Seedance 21:9 at 1080p is 2206×946). Tile Plan cuts the surface into zones, one generation each, and puts the clips back as one picture. The same code as the app's right-click › Tile Plan… (help "Tile a surface for AI video"): engine/model/tile-plan.ts, shared/tile-gen.ts, shared/tile-assembly.ts; the tools are in src/mcp/tile-tools.ts.

  1. plan_tiles { scene, surface, model, tier, shape, overlap?, feather? } — the zones. Each zone is the full surface height at the tile's aspect (21:9: 3731×1600 on 1600 px; 16:9: 2844×1600). One row. The fewest zones that keep at least overlap (default 20%), spread evenly; each overlap holds a crossfade band, centred and 400 px from the surface edges where it fits. Saved as the surface's tiles: block (scene-format.md). Returns the zones, seams, scale (×1.69 for 1080p 21:9, ×1.48 for 16:9, ×0.85 at 4K) and warnings (over ×1.5; zones that hang off the surface). Models: seedance-2.5-pro (1080p), seedance-2.0-pro (1080p or 4k), videorouter-seedance-2.5 (1080p).
  2. generate_tiles { scene, surface, prompt, seed?, duration?, loop?, timeMs?, confirm? } — renders each zone of the surface as it is now (its layers, without an assembled tiles comp) at the tile's exact px through render_still's path, saves it as assets/tiles/<scene>/<surface>/start-NN-<hash8>.png (+ a sidecar in assets/.tiles/), and quotes ONE batch: one prompt, one seed (random when none is given, the same for every tile), the static camera on, sound off, loop = end frame equals start frame. Every tile's prompt ends with the static-camera sentence and then The lighting and colours stay the same for the whole clip. (TILE_STEADY_LIGHT_PROMPT, shared/tile-gen.ts: the first run's NG tiles darkened, and a sky turned purple). The prompt should name the people's motion ("the crowd sways and waves their arms"), keep the motion small and local, and ask for no global change in light, colour, sky or time of day. The quote carries cap (the MCP per-job cap, each tile against it, lengthsUnderCap for a model priced by length) and loop when the clip length does not fit the scene loop. Each run deletes the surface's older start frames that no batch used (removedOldStartFrames; main/tile-stills.ts: never one that a job, a clip's .gen.json or a scene names, never one younger than an hour (a day in a shared project: an open form or another computer's batch may hold it), and nothing while the surface's current batch was sent from another computer and has not landed). Without confirm: true nothing is spent; with it, every tile starts (each under the MCP per-job cap; a batch with no price also needs accept_unpriced: true, the user's yes), labelled <surface> tile k/N. Each clip lands at assets/tiles/<scene>/<surface>/<batch>-tile-NN.mp4; a Retry of one tile lands on the same path. When the last tile lands, the surface assembles itself (a checkpointed scene write).
  3. assemble_tiles { scene, surface } — assemble now with the finished clips: one 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 — the crossfade recipe; a band that starts inside the overlap first cuts the top clip in a framed comp tiles-<surface>-tN), and one use: of it on top of the surface. The artist's layers stay. A surface with a tile loop is cut into it again. warnings (read from the clips' ffmpeg probe) says when the clips differ in length, or their length does not fit the scene loop (4.04 s clips in a 10 s loop jump at the wrap).
  4. set_tile_seams { scene, surface, seams?, feather? } — what a seam drag and the panel's crossfade box do, for an agent (the artist: "move the seam on W off the singer's face"). seams: each crossfade's centre in surface px, one per seam; feather: one width for every seam or one per seam (a list is scene v10). The pure setTileSeams (engine/model/tile-plan.ts) checks that each band stays inside its overlap and refuses, writing nothing, with every seam's allowed centres; Tile Plan's automatic seams build on it. An assembled surface is put back together (nothing is generated), checkpoint mcp: tile seams <surface> in <scene>. Returns { seams, feather?, bands: [{ n, overlap, crossfade, width, centre, allowed }], comp, warnings }. set_tile_seams { scene, surface, auto: true } instead runs the seam check (item 6) and applies its suggested seams through the same setTileSeams.
  5. make_loop { scene, surface } — every tile the same loop, kept in the plan (see make_loop above).
  6. tiles_check { scene, surface, store? } — check the seams of the assembled surface, the same check as the panel's check seams (help "Check the seams"; src/main/tiles/, the tool in src/mcp/tile-check-tools.ts). Main reads every placed clip with the app's ffmpeg: 9 frames spread over its length, area-scaled to 400 rows (4 surface px per grid px on a 1600 px surface), in one decode per clip, two clips at a time — about 0.7 s for a surface of two 4 s 1080p clips, plus about 0.45 s of numbers. It returns, per seam: ghosting (how much of each overlap column shows different things in the two clips, 0..1, at each sampled time — 1 − SSIM's structure term in 8 × 16 grid-px windows, so a darker, hazier or recoloured copy is not ghosting; each column is weighted by how much the crossfade shows both clips there, 4·k·(1 − k); over 0.35 at a time = doubled people or changing light in the blend), step (the colour step across the band, 8-bit levels: the mean of each row block's median over the columns, and the worst block; over 4, or 10 in one block, shows), colourMatch (the fit and the block mismatch before / with it), drift (each clip's shift of fixed structure first → last frame, surface px; over 2 misregisters) and suggested (the widest crossfade from 1024 down to 64 px whose weighted ghosting stays at or under 0.3, at its calmest place, else the narrowest at the least ghosting, 400 px from the surface edges where the overlap allows); per tile: lighting (mean luma first → last, the swing, the most a quarter-by-third region darkens or brightens: over 6 / 12 levels) and motion.moving (the share of the picture that changes between samples beyond its 9 × 9 neighbourhood's own change, so rolling haze is not motion; under 50% of the other tiles' = its people may not animate). Each seam and tile has verdict pass / check and plain reasons. Unless store: false, the colour fits and the detail mask go into the plan (tiles.match, scene-format.md) with a checkpoint: colour match is then on and the surface re-assembles. A colour fit is per channel gain and offset for the later clip, from the overlap over every sampled frame; it is kept only when it brings the block mismatch under 75% and every gain stays within ±15% of 1 (a cast that differs by region or drifts over the clip is not one gain and offset: then no fit, and a reason). The detail mask (assets/tiles/<scene>/<surface>/detail-<hash8>.png, grid px, white = the design shows) is open only where every clip that covers a px stays within 10 levels of its first frame and changes less than 8 between samples (on 3 × 3-smoothed frames), pulled in and softened by 16 surface px. suggested is one centre and one width per seam; set_tile_seams { scene, surface, auto: true } checks the surface and applies them (or pass them yourself).
  7. set_tile_match { scene, surface, colour?, detail? } — switch the check's fixes. colour: the colour match, built as a masked adjustment layer above the later clip in its cut comp (adjustment-layers.md): a levels effect (per channel in / out black and white = the gain and offset, one baked LUT) cut by a static linear gradient matte (rastered once): opaque across the band, fading to 0 where the next band starts or the zone ends. It adjusts whatever plays below it (the clip, or a tile loop's halves), so it adds no video node and no decode. Expected cost: colour-only, so ONE pass over the corrected zone with one pooled texture (adjustment-layers.md §4) — the standalone LUT filter's class, measured at +2.5 ms per frame at 1:1 and +0.3 ms at ¼ over the whole 6400×1600 surface N, so about 60% of that for a 3731 px zone. detail: keep design detail sharp (off by default): a matte node on the surface around the use: tiles-<surface> holder, cut by the mask (mode: luma, invert: true), so the surface's own design layers under the tiles show at full sharpness where nothing moves. It is an ordinary matte in the surface's list: a re-assembly never touches it, and the artist edits it with the mask tools (feather, opacity, the pen, a group of shapes as the matte input). Expected cost: the tiles comp renders into one pooled texture plus one composite pass over the surface — the standalone LUT filter's class, measured at +2.5 ms per frame at 1:1 and +0.3 ms at ¼ on surface N.

glimpse_status / glimpse_list / glimpse_publish / glimpse_pull — the LED-room Glimpse site

Glimpse was called Previz before 0.2.16. For one release each tool is also registered under its old name (previz_status, previz_list, previz_publish, previz_pull): the same schema and handler, with a description that says it is the old name and will be removed. Use the glimpse_* names.

Publish a scene to the team's Glimpse web app as a look, and pull a look back, through the same main-side service as window.starlight.previz. glimpse_publish exports one H.264 MP4 per LED wall (the export_scene pipeline; surfaces match the venue's walls by name), makes each movie's two playback copies (HEVC at full size, H.264 at half size, so browsers play the walls smoothly), uploads the movies and their copies and saves the look, with no thumbnail (the site renders its own in-room one). Each wall's movie is its own loop, because Glimpse plays each wall on its own length: one publish gives Electric Forest's walls 10 s, 14.53 s and 17.2 s. The dry run's summary and each slot's length ({ loop, ms, frames, reason? }) say each wall's length and why a wall keeps the scene loop. Never change the scene loop, or publish the walls in several passes, to get other lengths. The look: look (a name or an id) is any existing look, whoever made it, from Starlight or uploaded in the browser; without it, the look this project + scene was published into before (meta.source), else a new look under an id derived from project + scene. If two looks match a name (or this scene), the call stops and lists them in choices (owner, updated, id): ask the user, then pass the id. Look names are unique on Glimpse: a new or renamed look whose name is taken is stored as the next version ("X v2"), and the dry run says so. It publishes the saved scene. With surfaces it re-renders only those walls and keeps the look's other slots as they are (kept in the result); a kept movie without copies gets them (backfill), and surfaces: [] re-renders nothing and only adds those copies. An omitted name / notes keeps the look's. Each slot of the result has copies: { hevc, h264 } (w, h, mbps, encoder, bytes, key, seconds; the dry run: the planned sizes and Mb/s); a copy that could not be made is in the slot's copyNotes, copyProblems and warnings. While it runs, glimpse_status has progress (N: HEVC copy 42 %). glimpse_list shows each movie's play copies (none: made before copies). Call it with dry_run: true first (no export, no upload) and tell the user its summary: the look it replaces (name, who made it, how, last update, walls), or "makes a new look X", or that the name is taken (offer that look, else the stored version). Replacing needs a yes: ask the dry run's question (Replace the look '' (made by …, updated …)?); only after the user says yes, publish with replace: "<that name>". Without it a publish into an existing look stops with errorKind: "needs-confirm" and renders nothing. The yes also covers a look someone else owns (?force=1 is sent then, never otherwise; there is no force argument any more). After the publish, summary has the name Glimpse stored ("Published as "Electric Forest v2" because "Electric Forest" exists"). glimpse_pull streams a look's media into assets/previz/<lookId>/ with one checkpoint. Full reference: previz.md.

net_read / net_post / net_tasks / net_task_update / net_presence — the project's room

The agent's way into the Starlight Network, through the same main-side service as window.starlight.network (network.md). The agent is the person's Claude Code session under the name they gave it in Settings › interstellar; a tool whose switch is off says so and does nothing.

ToolSwitchWhat
net_read { since?, lanes?, thread?, limit? }readthe messages the agent may see (shared with agents, the agent and system lanes, its owner's own), oldest first, from this machine's mirror (works offline): { room, count, messages }. since keeps those changed after that room sequence (pass the highest rev read); limit the newest (100, at most 1000)
net_post { lane: "agent", text, refs?, thread?, to? }postone message on the agent lane as the agent, through the agent's own socket to the room, audience: agents, a new id: { ok, as, room, seq, id }. Refused while that socket is not online; a room's refusal (hourly-limit, thread-limit, self-address, duplicate, …) comes back as net_post failed — <code>: <text>, the room's words as they are
net_tasks { mine? }readthe project's tasks; mine: assigned to the agent's owner
net_task_update { id, status, note }tasksset a task's status (todo, doing, review, done, blocked); the note is the text of the task message the room posts
net_presencereadevery node in the room now (person, device, scene, its agent's state) and the team's agents (id, name, owner, presence)

Every tool also needs the agent's name. STE and when to post are the network skill's rules, not the tools'. While the team sign-in is hidden (account.md), every tool answers team sign-in is off; turn it on with ⌘K › Team sign-in (beta) (an error) and does nothing else.

get_logs { limit?, level?, source? } — the app's diagnostics log (read-only)

The newest entries of Starlight's local diagnostics log (userData/logs/starlight*.log, see architecture.md §13), newest LAST: { logsDir, count, entries, truncated? }. Each entry is one LogEntry (time, process, level, message, stack, source, data, appVersion, os, gpu). limit defaults to 200 (max 2000); level keeps that level and above (debug < info < warn < error < fatal); source is a case-insensitive substring (ffmpeg, export, webgpu, pixi, generation, …). Secrets were redacted before the lines were written; the answer is capped at about 1 MB (oldest entries dropped and counted). Reach for it when an export, ingest, generation or the canvas failed.

4. In-app compose (⌘K)

By default ⌘K does not plan in the app. It sends the artist's words, with the scene, the selection and the playhead, to the Claude panel's Claude Code session as a message, and Claude Code makes the change over this MCP server with no key (compose.md §1). Everything below is the openrouter lane, where a model plans inside the app.

The in-app planning path: ONE feature for scene edits and hosted generations. A single ⌘K prompt can produce media (Magnific / videorouter.sh) AND the scene edit that uses it, as one reviewable, undoable plan — a turn. The pieces: src/mcp/compose.ts (plan schema, the validate-retry loop, the system prompt), src/mcp/compose-plan.ts (the emit_plan tool and the user turn), src/main/compose/openrouter.ts (the model call), src/main/compose/ (semantic validation, placeholders, the ComposeOrchestrator and its IPC). The ⌘K bar and the MCP compose_run tool drive the same orchestrator; turns are stored beside the jobs they start, so the Generations panel is the shared history (see generation.md §7).

Flow:

  1. The ⌘K bar sends the prompt, the open scene and the selected surface (if any). A prompt starting with /generate or /gen skips planning and opens the generation form pre-filled (prompt + selected surface) — no key needed.

  2. runCompose calls the model with a system prompt built from the live registry catalog, the available generation catalog (provider, id, kind, prompt rule, every param with its allowed values, input slots, price hint — Magnific first) and the room (every surface with its native size and how it tiles for stills and for video). The model must call a forced emit_plan tool exactly once:

    { summary: string,
      steps: Array<
        | { kind: 'scene', scene, yaml }                        // the COMPLETE revised YAML
        | { kind: 'generate', label, provider, model, genKind,  // one hosted job
            prompt, negativePrompt?, params, inputs, surface?,
            place?: { scene, assetPath },                        // the path the scene step references
            tile?: { target, scene?, replace?, comp?, … } }      // a tiled upscale instead of place
      > }
  3. The plan is validated — parsePlan (zod: shape, ≤ 1 scene step per scene, ≤ 8 generate steps) then checkPlan (only the open scene; the model exists, is wired and makes that kind; the request quotes without errors; every place.assetPath is new, under assets/, and referenced by the scene step; the scene YAML passes validateSceneYaml, registry check included, against the live catalog; no new reference to a missing file). Any error goes back to the model for one retry. A missing provider key is the account's problem, not the plan's: it is kept on the step's quote for the gate to show.

  4. Placeholder paths. Each generate step gets its output path before anything runs: assets/gen/<slug(label)>-<6 hex>.<png|mp4> (png for image/upscale, mp4 for video — video steps are pinned to an MP4 output_format where the model offers one). The scene YAML is rewritten from the model's draft path to that path.

  5. The gate. A plan that costs nothing (scene-only) is applied at once, exactly as compose always did. A plan with generations is parked as an awaiting turn: the bar shows one row per step (kind · label · estimated cost · details) and ONE approve button carrying the total. There is no standing allowance in the generation service to reuse, so in the app every paid turn takes that one click.

  6. Approve re-checks (the scene must not have changed since planning; every step re-quotes), writes the placeholders (a 2×2 grey PNG; a 1-second black MP4 from the bundled ffmpeg, with an embedded fallback), writes the scene and commits one checkpoint compose: <summary>, then starts the jobs (parentId = the turn, targetAssetPath = the step's path).

  7. When a job finishes, the generation service writes its output at that exact path (checkpoint import: gen/<file>), and the renderer refreshes its assets — the boards swap the placeholder for the real media with no scene rewrite. A rejected / failed / cancelled job leaves its placeholder; the turn becomes partial and the step can be retried (it lands on the same path).

runCompose itself never writes — "model plans, never executes". Everything the plan touches goes through the same write path as MCP write_scene and the same job service as the panel.

Undo. ⌘Z after a compose undoes the scene edit through the renderer's undo stack, as before. The turn's own undo (the Generations panel, or COMPOSE_UNDO with a turnId) restores the pre-checkpoint, cancels the turn's active jobs, and removes each placeholder it wrote that is still a placeholder and that no scene references. A real output that already landed is kept (it cost money); its job keeps it in generations/ as well.

Hard budgets (so it can never hang the UI or overspend):

  • COMPOSE_DEADLINE_MS = 30_000 — one AbortController aborts planning at 30 s.
  • COMPOSE_MAX_RETRIES = 1; COMPOSE_MAX_GENERATE_STEPS = 8.
  • Paid generations never run without an approval: one click in the app, or max_usd ≥ the total through MCP (each job also under the MCP spend cap, Settings › Generation, default $20). Steps with no price estimate also need accept_unpriced: true, the user's yes asked in chat; max_usd then covers the priced steps, and a $0 cap refuses them. A stale plan is refused at approval.

Lanes. Who handles ⌘K is a setting with two lanes: claude code (the default: the request goes to the Claude panel's session as a message; no key) and openrouter (any OpenAI-compatible model through OpenRouter plans in the app, with the forced emit_plan tool and its own encrypted key). The ⌘K bar's status row shows the active lane. Setup, the message and its queue, the exact OpenRouter request, usage/cost and the planning cap are in compose.md. Every planned turn records its planning lane, model, tokens and (where reported) cost. The earlier anthropic lane (an Anthropic API key) and mcp only are retired; a saved one reads back as claude code.

The system prompt is two blocks — the stable guide (YAML format + registry + generation rules and catalog) and the per-project room. An anthropic/… model on OpenRouter gets them as two cache_control: ephemeral breakpoints, so repeat composes read from the cache.

compose_run { prompt?, scene?, surface?, dry_run?, max_usd?, turn_id?, provider?, model? }

The ⌘K loop as an MCP tool, on the same orchestrator. Returns the turn: turn_id, status, summary, steps (scene / generate with model, params, assetPath, quote, job id), total_usd, estimated, checkpoints, planning (provider, model, attempts, tokens, cost_usd where reported) and a note saying what to do next.

  • provider (openrouter) and model plan this one turn in the app whatever the app's setting is (the OpenRouter key must be set in the app). They are refused with turn_id, because an approval re-plans nothing. When the app's lane is the Claude Code session (the default), compose_run errors unless provider is passed: plan with read_scene / write_scene / gen_create instead (compose.md §5).

  • A plan that costs nothing is applied at once (undo with restore_checkpoint).

  • A plan with generations is parked awaiting (an error result, so the agent notices). Approve with compose_run { turn_id, max_usd ≥ total_usd }; the user can also approve it in the app.

  • A step with no price estimate leaves total_usd null. Approve it with compose_run { turn_id, accept_unpriced: true, max_usd ≥ the priced steps }, and only after telling the user the cost is unknown and hearing yes. A $0 MCP cap refuses it. accept_unpriced counts only with turn_id.

  • dry_run: true plans and quotes, never applies (it returns scene_yaml too); with turn_id it just reports the turn's current state.

  • scene is required when the project has more than one scene.

5. The extensions system

What an extension is

An extension is a plugin on the registry — today an effect (GPU filter) or a node type (layer type); the same mechanism is the intended path for new surfaces and export formats. It is a plain ESM module that default-exports one register(api) function and imports nothing — everything it needs is on the injected api.

In the app, an extension's effects appear in Properties › the + on the effects head, in the picker's own extensions block below the colour and effects columns, drawn with the puzzle-piece glyph (only built-in effects have their own icon, props/effect-icons.tsx) — and in the command palette's effect column, one row per effect, like the built-ins.

Where it lives

<project>/extensions/<name>/index.js — one directory per extension (EXTENSIONS_DIR = 'extensions', EXTENSION_ENTRY = 'index.js'). An optional extensions/manifest.json records { name, kind, description } per extension (written by scaffold_extension) and pins load order; absent, extensions load in alphabetical dir order. Manifest entries whose dir is missing are skipped; a dir without an index.js is skipped.

Discovery + hot-reload (the chokidar watcher)

Main is the single reader of extensions/ (src/main/extensions.ts). It never executes extension code — the renderer owns the GPU-facing registries and runs each module via a Blob-URL dynamic import(). Main ships the sources over IPC and watches the folder:

  • watchExtensions(root, onChange) chokidar-watches extensions/, debounced 150ms, ignoreInitial: true, and ignores manifest.json (the source add/change already triggers a reload). On any add/change/unlink it reads fresh sources and sends them to the renderer via EXTENSIONS_CHANGED.
  • The watcher follows Open Project — pointBackendAt restarts it bound to the new project alongside the MCP server.
  • Only trusted sources are sent (the trust model); a new or changed untrusted file raises the trust prompt instead of loading.

It registers on the same registry as builtins

The reload contract (src/engine/extensions/index.ts applyExtensions):

clear both registries → re-register builtins → applyExtensions(modules).

So removed extensions vanish cleanly, overrides re-apply, and a failing module is caught, reported as a one-line ExtensionError (a red line at the canvas's bottom-left), and skipped — never crashes the app (a partial registration from the failed module is rolled back).

The injected api (ExtensionApi) — the same API the built-ins use:

api memberWhat it does
registerNodeType(kind, def)Register a node type — { schema, build(ctx, node) → Container }.
registerEffect(name, def)Register a GPU effect — { schema, animatableParams, defaults, create, update } — or a colour point op — { schema, animatableParams, defaults, pointOp, separable? } (below).
defineShaderEffect(spec)Build a working dual-backend (WebGPU + WebGL) effect from GLSL/WGSL fragment bodies + params. Returns an EffectTypeDef.
definePointOp(compile)Build a pointOp from compile(params) → (rgb) => void: setup once per LUT bake, the returned function once per grid point. Pure, so it also runs headless.
pixiThe injected Pixi toolkit — { Container, Graphics, Sprite, Text, TextStyle } (extensions can't import Pixi).
zA tiny zod-like schema builder (number/string/boolean/enum/object, .optional()).
EASING_PRESETSThe sports easing presets (snap, overshoot, smooth, …) so extensions animate on-brand.

Because the catalog is introspected from the registry, the moment an extension registers it is fully editable in the props panel and visible in the get_project catalog — flagged extension: true — with no restart.

The trust model — unsandboxed, behind a first-load prompt

Extensions run with full renderer privileges. There is no sandbox (documented, not accidental): a team extending its own install is editing its own machine, exactly like an After Effects script. What changed (AUDIT BUG-SEC-2) is that opening a project no longer runs its code unasked. Main ships an extension to the renderer only when it is trusted (src/main/extension-trust.ts):

Trusted becauseScopeRemembered
You clicked trust for this project, and the extension's code is what you trusted — the sha256 of the index.js main would ship, i.e. exactly what runsthis project diryes — app prefs (starlight-prefs.json › extensionTrust: dir → name → hash), across launches
You trusted it this session, or MCP scaffold_extension created it this sessionthat extension name, any codeno — until the app quits
It is byte-identical to an extension bundled with the app (the demo project's scanlines)anywhere— (it is Starlight's own code)

Everything else is held back: not imported, not registered, absent from the catalog and get_project's effect list, and listed as extensionsAwaitingTrust. The window shows one line — this project runs its own code: led-scan, ticker — extensions get full access to the app. trust them? with trust / not now (an approved extension whose file changed: led-scan changed since you trusted it — run the new code?).

  • Per project, per exact code. The same extension in another folder asks again; any byte change to an approved index.js asks again on the next load.
  • Your edits don't nag. Once you trust an extension (or Claude scaffolds it), its later edits hot-reload without asking for the rest of the session — the scaffold → edit → render loop never stops. The new code is not recorded as approved, so the next launch asks once about what changed.
  • No time-of-check gap. The prompt answers with the exact name + hash pairs it showed; main drops an approval whose file changed in between, and asks about the new code.
  • "not now" hides that prompt for the session (the extensions stay unloaded); the palette's trust project extensions… brings it back. A new or changed file asks again.
  • One gate. Every payload main sends (readProject — initial load, Open Project, reloads, scene pushes; fail-closed until the gate is installed) and every watcher hot-reload go through it.
  • What a trusted extension can do is unchanged: everything the renderer can. Trusting a project's extension means trusting that code fully. A Worker/realm sandbox is future hardening if extensions ever become shareable.

Built-in effects

Registered in src/engine/registry/effect-builtins.ts through the same EffectRegistry API extensions use; get_project's catalog lists each with its params (type, default, animatable, and for choice params type: 'enum' + options).

Animating a param (animatable only): write a keyframe list in place of the value — glow: { intensity: [0.2, 0.9, 0.2] }. With no clock: on the effect the keys ride the host node's clock (its period/mode or named use:; the scene loop when it has none), so they move with the node's transform tracks; clock: { period, mode } on the effect gives it its own clock. get_project carries the same rule as effectAnimation, and the properties panel's ◇ chip writes exactly this form (clocks-and-animation.md §4).

EffectParams (default)AnimatableWhat it does
cutout——Texture stage: swaps an image for its background-removed subject (Apple Vision, cached).
bluramount 8, quality 4amountGaussian blur (quality capped at 5).
sharpenamount 0.5amount3×3 sharpen; crisps LED text.
glowcolor #ffffff, intensity 0.6, threshold 0.5, radius 6intensity, threshold, radiusThresholded ring bloom, additive tint.
chroma-shiftoffset 4, angle 0offset, angleRGB split.
pixelatesize 8sizeCell snap (LED-preview look).
halftonesize 6, angle 45, amount 1size, angle, amountPrint-dot knockout.
grainamount 0.2, size 2, seed 0amount, seedPer-cell hash noise.
noisescale 200 (px, ≥ 1), octaves 3 (1..6), evolve 0, seed 0, amount 1 (0..1)evolve, amountFractal noise generator in node px: rgb → grey noise (alpha kept), mixed at amount. evolve 0 and 1 give the same field: key [0, 1] to loop.
thresholdlevel 0.5 (0..1), softness 0.1 (0..1)level, softnessRec. 709 luma → white above level, black below, alpha kept. level 0 = all white, 1 = all black. A spatial effect, so it runs after noise: [noise, threshold] on a white rect is a dissolve matte (inside the matte's input group, not the input itself: a matte input's own effects are ignored).
featherleft 0, right 0, top 0, bottom 0 (px, ≥ 0), curve smooth|linear (smooth)left, right, top, bottomEdge alpha ramps — blend overlapping AI tiles (below).
exposureexposure 0, offset 0, gamma 1allColour point op: AE Exposure in linear light.
brightness-contrastbrightness 0, contrast 0, legacy off|onbrightness, contrastColour point op: AE Brightness & Contrast.
hue-saturationhue 0 (°), saturation 0, vibrance 0, lightness 0allColour point op: AE Hue/Saturation master + vibrance.
levelsinBlack 0, inWhite 255, gamma 1, outBlack 0, outWhite 255 + red…/green…/blue… variantsallColour point op: AE Levels (Individual Controls), 0..255.
curvesmaster, red, green, blue = "0,0 255,255"—Colour point op: monotone cubic through x,y points (0..255).
color-balanceshadowRed … highlightBlue 0, preserveLuminosity off|onthe nine balancesColour point op: lift / gamma / gain per range.
temperature-tinttemperature 0, tint 0bothColour point op: Lumetri white balance.
invertchannel rgb|red|green|blue, blend 0 (%)blendColour point op: AE Invert.
lutfile (.cube under assets/), strength 1strengthColour point op: a .cube file (1D/3D) composed into the stack.

The nine colour ops build no filter of their own: every colour op on a node fuses, in stack order, into one baked 3D LUT that runs before the node's spatial effects. Full reference, maths and ranges: color.md.

Colour point ops

A point op maps one colour to another and looks at nothing else: no neighbours, no position. An effect def with a pointOp and no create is one. The renderer builds no Filter for it. Instead every point op on a node (built-in or extension) is composed, in stack order, into the node's single 33³ LUT, and one lookup per pixel applies the whole colour stack before the spatial effects (color.md).

type PointOp = (rgb: Float32Array /* len 3, sRGB-encoded 0..1, in place */, params: EffectParams) => void;
interface EffectTypeDef {
  // … schema, defaults, animatableParams, paramMeta as for any effect
  pointOp?: PointOp;
  /** Per-channel op (output c depends only on input c): the baker samples it on a 1D
   *  table instead of all 33³ points, and fuses runs of such ops into one lookup. */
  separable?: boolean | ((params: EffectParams) => boolean);
}
  • Contract. Map rgb in place. Values are sRGB-encoded (display-referred, After Effects' default working space), and the baker clamps to 0..1 after each op. The op must be pure, because bakes are cached by params. It is called about 36 000 times per bake with one params object, so do setup in api.definePointOp(compile) (memoized per bake).
  • Animated params re-bake the LUT on frames where the sampled params change. That is one bake for the whole stack, not one pass per op.
  • separable is a speed hint, and a wrong true gives wrong colours. Leave it out unless output channel c depends only on input channel c.
  • The props panel lists every point op in the effects section's Color group. The catalog lists them like other effects.
export default function register(api) {
  api.registerEffect('posterize', {
    schema: api.z.object({ levels: api.z.number().optional() }),
    defaults: { levels: 4 },
    animatableParams: ['levels'],
    separable: true,
    pointOp: api.definePointOp((p) => {
      const n = Math.max(2, p.levels) - 1;
      return (rgb) => {
        for (let c = 0; c < 3; c++) rgb[c] = Math.round(rgb[c] * n) / n;
      };
    }),
  });
}

feather — edge alpha ramps for overlapping tiles

effects:
  - feather: { left: 800 }                 # 800 px ramp in from the left edge
  - feather: { left: 400, right: 400, curve: linear }
  • Params. left / right / top / bottom: the ramp width in node-local px (number, default 0, min 0; negative / non-finite values act as 0). 0 = no feather on that side. curve: smooth (default, smoothstep(0, 1, t)) or linear (t); any other string falls back to smooth. The props panel shows the sides as number fields and curve as a dropdown.

  • Semantics. Output = input × a factor per side that is 0 at the node's edge and reaches 1 at <side> px inward; with several sides the factors multiply. Pixi textures are premultiplied, so RGB and alpha are scaled together (no fringes).

  • Pixels are the node's own pixels. A tile scaled 0.5 on the canvas still feathers 400 source px (= 200 screen px). The ramp is measured in node space, not in the filter's quad: every time the filter runs it maps its texture coords back through the node container's inverse world transform onto the node's local bounds. So it is exact under translation, scale, rotation and skew (the ramp follows the node's own edges, not its axis-aligned bounds), any render resolution, render_still / export strips (Pixi clips a filter's quad to the viewport — the mapping is unaffected), and when chained after a padded effect like blur. "The node's edges" means its local bounds (for an image, the image's pixel size). Padding is 0: the effect never grows the node's bounds.

  • Crossfade recipe (seams between overlapping AI tiles). Starlight composites with Pixi's normal blend — premultiplied source-over (out = src + dst·(1 − src.a)), later siblings on top. Feather only the top tile's overlapping edge, over an opaque bottom tile: out = B·k + A·(1 − k), alpha k + (1 − k) = 1 — a true crossfade. Feathering both tiles (A's right edge and B's left edge) darkens the seam: alpha t + (1 − t)² (both ramps at the same t) dips to 0.75 at the midpoint over black. A 6400×1600 surface from two 3600×1600 tiles overlapping 800 px (A at x 0..3600, B at x 2800..6400):

    # project.yaml
    surfaces:
      wall: { size: 6400x1600 }
    
    # scenes/wall-crossfade.yaml
    scene: wall-crossfade
    loop: 4s
    design: 6400x1600
    comps:
      main:
        - transform:                     # A — bottom, opaque, NOT feathered
            - image: assets/gen/tile-a.png
          position: { x: 0, y: 0 }
        - transform:                     # B — drawn on top; ramps 0→1 across the overlap
            - image: assets/gen/tile-b.png
              effects:
                - feather: { left: 800 }  # = the overlap width (2800..3600)
          position: { x: 2800, y: 0 }
    surfaces:
      wall: { use: main, design: 6400x1600 }

    curve: linear gives a constant-rate crossfade; smooth (default) eases both ends of the overlap so the seam has no visible start/stop line. The bottom tile must be opaque across the overlap (it is the "1 − k" half of the mix); for a vertical stack use top/bottom the same way. A 3-tile surface feathers the middle tile's left edge and the right tile's left edge (each over its opaque left neighbour).

Walkthrough — add a custom effect

The common case (scaffold_extension writes exactly this shape; see the shipped demo-project/extensions/scanlines/index.js for a complete example):

  1. Scaffold. scaffold_extension { name: "led-scan", kind: "effect", description: "…" } → writes extensions/led-scan/index.js with TODO markers + updates the manifest.

  2. Edit the file. Each param becomes a float uniform u<Capitalized> (amount → uAmount); mark animatable: true to allow keyframing it from YAML. Keep the GLSL and WGSL bodies doing the same math — they run on the two backends:

    export default function register(api) {
      api.registerEffect('led-scan', api.defineShaderEffect({
        name: 'led-scan',
        params: [{ name: 'amount', default: 0.5, animatable: true }],
        // WebGL (GLSL 300es): read texture(uTexture, vTextureCoord); write finalColor.
        // uInputSize.zw = per-texel size. Uniforms: uAmount.
        glsl: `
          vec4 c = texture(uTexture, vTextureCoord);
          finalColor = vec4(c.rgb * (1.0 - uAmount), c.a);
        `,
        // WebGPU (WGSL): read textureSample(uTexture, uSampler, uv); return vec4<f32>.
        // Effect uniforms on fx.*; global filter uniforms on gfu.* (gfu.uInputSize).
        wgsl: `
          let c = textureSample(uTexture, uSampler, uv);
          return vec4<f32>(c.rgb * (1.0 - fx.uAmount), c.a);
        `,
      }));
    }
  3. Save — Starlight hot-reloads it (150ms debounce). If it failed to load, a one-line error shows as a red line at the canvas's bottom-left; the tools stay usable.

  4. Verify — get_project: led-scan appears in catalog.effects (flagged extension: true) with its params.

  5. Use it — add to a node's effects: list and write_scene: effects: [{ led-scan: { amount: 0.6 } }], or animated { led-scan: { amount: [0, 1, 0] } } on the node's clock, or with its own clock: { period: 1s } (animatable params only — the panel's ◇ chip keys exactly these). write_scene checks the effect against the live registry: while led-scan is not loaded (or failed to load) the write is rejected with unknown effect "led-scan" — valid effects: …, and a param the effect does not declare in its defaults / animatableParams is rejected by name. (An extension that declares no params at all is not checked param-by-param — its schema lives in the renderer.)

  6. Render + look — render_still a surface that uses it, and iterate on the shader.

Walkthrough — add a custom node type

scaffold_extension { kind: "node" } writes a working square node built with the injected Pixi toolkit:

export default function register(api) {
  const { Graphics } = api.pixi;
  api.registerNodeType('badge', {
    schema: api.z.object({ size: api.z.number().optional(), fill: api.z.string().optional() }),
    build(ctx, node) {              // ctx offers assets + buildChildren + resolveComp
      const g = new Graphics();
      g.rect(0, 0, node.size ?? 100, node.size ?? 100).fill(node.fill || '#ffffff');
      return g;
    },
  });
}

The node type appears in the catalog and builds correctly. In scene YAML it is written with the node: keyword and its props as siblings (- node: badge / size: 120; the parser does not know the registry, so badge: is not a keyword of its own), and the palette's create row for it saves the same way (scene-format.md §4).


6. Skills — the Starlight plugin

Starlight's guidance for Claude Code ships with the app as a Claude Code plugin (claude-plugin/ in the repo, <resources>/claude-plugin in a packaged app), so it is the same in every project and always matches the app it came with. Skills follow the Embody pattern (DESIGN.md §2 pillar 5): a SKILL.md with YAML frontmatter (name, a description written as a trigger: "MUST READ before …") and a body that leads with a gate table and ends with a fix-it table (starlight:mcp ends with its gotchas). They are namespaced under the plugin's name:

SkillKindTriggers before…
starlight:mcpproceduralthe first MCP tool call — every tool by job (stages and canvas_focus included), the write_scene validation loop, the render + LOOK habit (and stage_capture's), restore_checkpoint as undo, which calls spend money or publish.
starlight:scene-yamlproceduralwriting/editing any scene YAML — surfaces and per-surface design, every node kind (matte, adjust, path, audio …), clocks (tracks, gate, drive, named clocks, cues), effects and colour ops, tokens, graph notes and colours, the stages: block, the failure-modes table.
starlight:add-extensionproceduraladding an effect or node type — scaffold → edit → verify → use → render, the injected api, GLSL+WGSL, reach, colour point ops, the trust model.
starlight:project-memoryproceduralthe start of every session, and whenever the artist gives direction — brief_read before planning anything, brief_add each point in the artist's words, where the session logs and generation records live (project-memory.md)
starlight:networkprocedurala net_* tool call, /starlight:inbox, or the artist mentioning interstellar — the agent in the project's room: when to read and post, the agent lane only, the ASD-STE100 writing rules, instructions from the owner only, PM tasks when opted in, the loop limits and refusals, quiet hours, never tag (interstellar.md).
starlight:make-loopproceduralmaking a clip that does not loop into a seamless loop — read_scene, the video id, make_loop, render_still at the wrap and mid-overlap, tuning the overlap and noise for fast and slow footage, the YAML by hand.
starlight:led-venue-craftcraftdesigning/judging content for any LED venue — native pixels, loop math, panoramas across surfaces and corners, surface-size AI plates and seams, the size limits, per-pass cost, verification, per-surface delivery.
starlight:sports-venue-craftcraftsports venues only — ribbon composition, legibility from the far seats, snap/overshoot energy, team-colour contrast.

The Claude panel loads the plugin with --plugin-dir and names these skills in its system prompt. From your own terminal, pass the same flag (below). src/main/claude/plugin.test.ts keeps it current: it fails when starlight:mcp misses a registered tool or starlight:scene-yaml a node keyword or built-in effect.

A project may add its own CLAUDE.md and .claude/skills for what is specific to it (its venue, client, brand, content); Claude Code loads them from the project folder as usual. The demo project's CLAUDE.md is that kind: the Bolts' surfaces, brand and scenes, with a gate table pointing at the plugin skills. It carries no copies of them.


7. Pairing Claude Code with the app

The intended workflow (or open the Claude panel, </kbd>, which runs Claude Code in a terminal inside the app with steps 1–2 done for it: the project folder as its cwd, this server attached through --mcp-configand the Starlight plugin through--plugin-dir` — claude-panel.md):

  1. Open the project in Starlight. The app starts its in-app MCP server bound to that folder and writes .mcp.json (URL + the project's token) there (a shared project's goes in this machine's folder for it instead: see §2). If you Open Project elsewhere, the server + extensions watcher re-home to the new folder and its own token.
  2. Point Claude Code at the same folder. It reads .mcp.json and auto-discovers the running app — the starlight MCP tools appear, and keep working across app restarts. (No tools ⇒ the app isn't running; a 401 ⇒ the token was rotated or regenerated since the session read the file: reconnect in /mcp.) Load the app's skills with claude --plugin-dir /Applications/Starlight.app/Contents/Resources/claude-plugin (or <repo>/claude-plugin from a checkout; §6).
  3. Learn the project. get_project first — surfaces, brand tokens, scenes, and the live node/effect catalog (extensions included). An extensionsAwaitingTrust list means the app is asking the user to trust those extensions — they aren't loaded until then.
  4. Iterate on scenes. read_scene → edit the whole document → write_scene (rejected writes are no-ops with path-anchored errors) → render_still and look (the whole surface first, then a region for 1:1 detail; render_surfaces for the whole room) → sample across the loop → restore_checkpoint if a change made it worse.
  5. Block a generated shot. For an AI still or clip with people or a set in it, stage_write a stage, stage_capture it and look, then gen_create from the capture's gen block, dry_run first (stages.md).
  6. Extend the tool. When a scene needs an effect or layer that doesn't exist, scaffold_extension scaffolds it into extensions/, edit the index.js, save (hot-reload), confirm in get_project, use it in YAML, and render_still. Core is never touched.
  7. Deliver. export_scene for one scene's package (a file per surface), export_scenes for several scenes' packages as one export, or export_reel for the whole reel joined into one file per surface — native-res, loop-perfect, ready to drop into show control. Watch the backend/msPerFrame telemetry.

Every step above is git-checkpointed and undoable, the canvas stays live, and the tool grows into the team's own system as they go — the AI-first moat in practice.

On this page

1. Why AI-first — the moat2. The MCP serverWhere it runsHow a client connects — .mcp.json auto-discoveryLong calls report progressWho may call it — Host, Origin and the project tokenThe git-checkpoint discipline on writes3. Every MCP toolget_project — read this firstread_scene { scene }open_scene { scene }write_scene { scene, yaml }create_scene { scene?, name?, yaml? }delete_scene { scene }rename_scene { scene, to }rename_comp { scene, from, to }precomp { scene, ids, name, size | preset, origin? }set_comp_frame { scene, comp, size | preset | null }write_comp { scene, comp, yaml, create? } — one comp at a timewrite_node { scene, id | path, yaml } — one node at a timerender_comp_still { scene, comp, timeMs?, out? }fit_layer { scene, id, mode, surface?, timeMs? }make_loop { scene, id | surface, overlap?, dissolve?, noiseScale?, softness?, seed?, evolve?, setSceneLoop? }import_track { scene, id | path, data | file, format?, mode?, properties?, fps?, start?, frames?, ref?, plate? | offset? + scale?, source_size?, min_confidence? } — tracking data onto a layertrack_region { asset | scene + plate, rect, frame, frames?, search?, scale_too?, min_score?, id? | path?, mode?, … } — the rectangle trackerrestore_checkpoint { id, note? } — undocheckpoints { action: "list", limit? } / checkpoints { action: "describe", hash, text } — the version historycreate_project { name, shared, location?, surfaces?, copyFrom? } — a NEW projectProjects that are not open: project and copy_to_projectPreviews: what an agent sees of a renderrender_still { scene, surface, timeMs, region?, scale?, save?, format?, fast? } — your EYESrender_surfaces { scene, timeMs, surfaces?, save?, format? } — the whole roommeasure_text { text, font?, size?, …, wrap?, lineHeight?, maxLines? } or { scene, id? | path? } — type as it drawsplayback_stats { seconds?, play?, gpu?, glimpseAb?, recent? } — how the live canvas playsMeasuring colour: probe_pixels and diff_againstprobe_pixels { scene, surface, timeMs | frame, points?, rect?, fast? }diff_against { scene, surface, plate, frames | timeMs, plateOffsetMs?, region?, threshold?, image?, fast? }scaffold_extension { name, kind, description }export_formatsexport_scene { scene, fps?, format?, output_fps?, interpolate?, surfaces?, loops?, length?, allowMissing?, quality?, dither?, size?, motionBlur? }export_scenes { scenes, fps?, format?, output_fps?, interpolate?, surfaces?, loops?, length?, allowMissing?, quality?, dither?, size?, motionBlur? }export_reel { fps?, format?, output_fps?, interpolate?, surfaces?, scenes?, allowMissing?, quality?, dither?, size?, motionBlur? }cancel_exportmusic_map { asset }assets_ingest { path?, dry_run?, wait?, status?, cancel? }assets_import { path }list_fonts { family?, system? } — which file is which weightstage_list / stage_read / stage_write / stage_delete / stage_capture — stagescanvas_focus { comp? | surface? | stage? | off? } — what the window showscanvas_layout { set? | rows?, aside?, gap?, join? } — where the surfaces sitgen_models / gen_create / gen_list / gen_status / gen_cancel / gen_import / gen_grade — AI generationsversion_create — versions of a clip, local and cloudplan_tiles / generate_tiles / assemble_tiles / tiles_check / set_tile_match — Tile Planglimpse_status / glimpse_list / glimpse_publish / glimpse_pull — the LED-room Glimpse sitenet_read / net_post / net_tasks / net_task_update / net_presence — the project's roomget_logs { limit?, level?, source? } — the app's diagnostics log (read-only)4. In-app compose (⌘K)compose_run { prompt?, scene?, surface?, dry_run?, max_usd?, turn_id?, provider?, model? }5. The extensions systemWhat an extension isWhere it livesDiscovery + hot-reload (the chokidar watcher)It registers on the same registry as builtinsThe trust model — unsandboxed, behind a first-load promptBuilt-in effectsColour point opsfeather — edge alpha ramps for overlapping tilesWalkthrough — add a custom effectWalkthrough — add a custom node type6. Skills — the Starlight plugin7. Pairing Claude Code with the app