@a-company/atelier 0.29.0 → 0.37.0

package/university/content/notes/N-atel-101-the-atelier-format.md

@@ -0,0 +1,72 @@
+---
+id: N-atel-101-the-atelier-format
+title: The `.atelier` document format
+type: note
+track: ATEL-101
+author: atelier
+created: '2026-05-18'
+updated: '2026-05-18'
+tags:
+  - course
+  - atel-101
+  - format
+  - schema
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites:
+  - N-atel-001-first-render
+summary: The top-level shape of an `.atelier` YAML document — canvas, layers, states, assets, variables, presets, templates. Every field exists for one reason, named for what it means.
+---
+
+## The five required parts
+
+Every `.atelier` document is YAML with five mandatory top-level keys:
+
+```yaml
+name: My Animation                    # human-readable label
+canvas:                               # global render context
+  width: 800
+  height: 600
+  fps: 60
+  background: "#0F1115"               # optional, defaults to transparent
+layers: [ ... ]                       # ordered array of visual elements
+states:                               # named keyframes (always at least one)
+  default:
+    duration: 60                      # in frames
+    deltas: [ ... ]
+```
+
+That is the minimum. Validators accept it. The renderer can resolve any frame in the `default` state.
+
+## The optional parts
+
+Any of these can be absent. Add them when you need them.
+
+| Key | What it holds | When you need it |
+|---|---|---|
+| `assets` | External resources (images, videos, audio) referenced by `assetId` from layers | The moment you add an image or video layer |
+| `variables` | Named values referenced by `${name}` in templates and expression-driven deltas | When you want to parametrize a document or template |
+| `presets` | Reusable delta bundles applied by name | When the same animation pattern repeats across layers |
+| `templates` | Reusable layer subtrees instantiated by name with variable substitution | Carousels, lower-thirds, repeating motifs |
+| `audio` | Audio track + sync metadata | Video projects with sound |
+| `meta` | Free-form metadata (author, tags, source notes) | Anything you want a downstream tool to read |
+
+## The order of keys is not meaningful (to the engine)
+
+YAML is unordered for objects. The schema doesn't care whether `states` comes before `layers`. Conventionally we write them top-down — `name`, `canvas`, `assets`, `variables`, `presets`, `templates`, `layers`, `states`, `audio`, `meta` — because that order roughly matches "global setup → reusable bits → scene → motion → output."
+
+## The order of `layers` IS meaningful
+
+Layers render back-to-front. Index 0 is drawn first (background); the last layer is on top. This is also the order the layer panel shows them in the studio (top of the list = top of the stack, matching most design-tool conventions — the array is rendered bottom-up for display).
+
+## Layer IDs and references
+
+Every layer needs an `id` that is unique within the document. Deltas reference layers by id (`layer: title`). Parent-child relationships use `parentId`. Templates reference instance ids. The schema enforces uniqueness and rejects dangling references at validate time — you don't have to track them by hand.
+
+Conventionally, layer ids are kebab-case (`title`, `subtitle`, `clip-trim-1`, `caption-word-7`). Pipeline-generated layers carry a tag namespace prefix in the id: `silence-trim-N`, `caption-N`, `caption-word-N`, `overlay-N`. The tags drive the layer-tag isolation invariant (ATEL-501).
+
+## Reading order for the rest of ATEL-101
+
+1. **Layers** — anatomy of a single layer: visual, frame, bounds, anchor, opacity, rotation, scale, parent, visible, motion path, clip path, blend mode, shadow, tint, interactions
+2. **States and deltas** — what a state is, what a delta is, how `resolveFrame(doc, stateName, frame)` produces a renderable scene
+3. **Easings** — linear / cubic-bezier / ease presets / spring / step; the math you don't have to remember but should recognize

package/university/content/notes/N-atel-201-authoring-tools.md

@@ -0,0 +1,141 @@
+---
+id: N-atel-201-authoring-tools
+title: Authoring tools — document, layer, state, delta
+type: note
+track: ATEL-201
+author: atelier
+created: '2026-05-18'
+updated: '2026-05-18'
+tags:
+  - course
+  - atel-201
+  - mcp
+  - authoring
+difficulty: intermediate
+estimatedMinutes: 6
+prerequisites:
+  - N-atel-201-mcp-overview
+summary: The tools you reach for to build animations. Document lifecycle, layer composition, state machines, delta authoring. Annotated by which to call when.
+---
+
+## Document lifecycle
+
+```
+atelier_create        — make a new document with name + canvas
+atelier_load          — load a .atelier file from disk by path
+atelier_list          — list .atelier files in CWD
+atelier_info          — return name + canvas + layer count + state count
+atelier_validate      — schema-validate the current doc; returns errors with paths
+atelier_preview       — resolve one frame and return ResolvedLayer[]
+atelier_batch_preview — resolve multiple frames in one call (for thumbnail rows)
+atelier_diff_frames   — compare two resolved frames; return property-level diffs
+atelier_profile       — measure resolveFrame latency per state
+atelier_complexity    — count layers, deltas, refs, max nesting; flag perf risks
+```
+
+**When to use which:**
+
+- Starting from scratch: `atelier_create({ name, canvas: { width, height, fps }})`. Returns a minimal doc with one empty `default` state.
+- Resuming on an existing file: `atelier_load({ path })`. The store now holds that doc; subsequent calls operate on it.
+- Sanity-checking before you ship: `atelier_validate` then `atelier_complexity` — the first catches schema issues, the second flags renderer perf risks (1000+ layers, 10+ levels of group nesting, etc.).
+- Visual debugging: `atelier_preview({ frame: 30 })` returns the same `ResolvedLayer[]` the renderer consumes. Compare against `atelier_diff_frames({ from: 29, to: 31 })` to find what changes.
+
+## Layer composition
+
+```
+atelier_add_layer    — add a layer with visual + frame + bounds
+atelier_edit_layer   — edit non-visual layer properties (id, tags, parentId, etc.)
+atelier_remove_layer — remove a layer by id (and any deltas referencing it)
+atelier_reorder      — change layer z-order
+atelier_list_layers  — list all layer ids + types
+atelier_edit_visual  — replace or patch the visual block (shape→text, fill, etc.)
+```
+
+**Pattern:** build all layers first, then animate. Adding layers triggers immediate validation; adding deltas requires the target layer to exist. Reverse order works but emits more errors.
+
+**`atelier_edit_visual` is the underrated one.** It's the single tool for "I want this rect to become a text layer" or "change this image's `assetId`." Most edit-flow agents use this far more than the dedicated `atelier_set_*` family.
+
+## State machines
+
+```
+atelier_add_state           — name a new state with duration (frames)
+atelier_edit_state          — change duration, parent state, transitions
+atelier_remove_state        — remove a state (rejects if it's the only one)
+atelier_list_states         — list state names + durations + parent chain
+atelier_set_state_parent    — make a state inherit deltas from another
+atelier_configure_transition — define transition from state A→B with easing
+```
+
+**State machines are the foundation of interactive motion.** A `default` state shows the resting layout. `hover` extends `default` (via `set_state_parent`) with extra deltas. `pressed` transitions from `hover` with a 200ms ease-out (via `configure_transition`). Three states, total complexity stays low, the interactive feel is right.
+
+For non-interactive animations: one `default` state is fine. State-machine complexity is opt-in.
+
+## Delta authoring
+
+```
+atelier_add_delta    — animate one property of one layer
+atelier_edit_delta   — change from/to/easing/range of an existing delta
+atelier_remove_delta — remove a delta
+```
+
+`atelier_add_delta` takes:
+
+```ts
+{
+  state: "default",
+  layer: "title",
+  property: "opacity",        // or "frame.x", "style.color", "scale.x", ...
+  from: 0,
+  to: 1,
+  startFrame: 0,
+  endFrame: 30,
+  easing: "ease-out"          // or cubic-bezier(...), spring({...}), step(...)
+}
+```
+
+The **no-overlap gate** rejects two deltas on the same `layer` + `property` whose `[startFrame, endFrame]` ranges overlap. If you need composed motion (e.g. wobble overlaid on a slide), use two layers or a `group`. The error message names both deltas; the fix is obvious.
+
+**Easing as an object, not just a string.** The string form (`"ease-out"`) is the preset shortcut; the object form (`{ type: "spring", stiffness: 170, damping: 26 }`) is the full surface. Use the object form when you want spring physics or a custom cubic-bezier with specific control points.
+
+## A complete worked example
+
+Building "fade in title, slide subtitle from below, hold for 2 seconds" from zero:
+
+```ts
+const { documentId } = await atelier_create({
+  name: "Intro", canvas: { width: 1920, height: 1080, fps: 60 }
+});
+
+await atelier_add_layer({ documentId, layer: {
+  id: "title", visual: { type: "text", content: "Atelier",
+    style: { fontFamily: "Inter", fontSize: 120, color: "#F5F5F7" }},
+  frame: { x: 960, y: 480 }, bounds: { width: 1200, height: 160 },
+  anchorPoint: { x: 0.5, y: 0.5 }, opacity: 0
+}});
+
+await atelier_add_layer({ documentId, layer: {
+  id: "subtitle", visual: { type: "text", content: "AI-native animation",
+    style: { fontFamily: "Inter", fontSize: 40, color: "#9CA3AF" }},
+  frame: { x: 960, y: 580 }, bounds: { width: 1200, height: 60 },
+  anchorPoint: { x: 0.5, y: 0.5 }, opacity: 0
+}});
+
+await atelier_edit_state({ documentId, state: "default", duration: 180 });
+
+await atelier_add_delta({ documentId, state: "default", layer: "title",
+  property: "opacity", from: 0, to: 1, startFrame: 0, endFrame: 30,
+  easing: "ease-out" });
+
+await atelier_add_delta({ documentId, state: "default", layer: "subtitle",
+  property: "opacity", from: 0, to: 1, startFrame: 20, endFrame: 50,
+  easing: "ease-out" });
+
+await atelier_add_delta({ documentId, state: "default", layer: "subtitle",
+  property: "frame.y", from: 680, to: 580, startFrame: 20, endFrame: 50,
+  easing: { type: "spring", stiffness: 120, damping: 22 } });
+
+await atelier_validate({ documentId });
+await atelier_preview({ documentId, frame: 40 }); // inspect mid-motion
+```
+
+Eight calls. Two layers, three deltas, one validate, one preview. The agent never touched YAML.

package/university/content/notes/N-atel-201-mcp-overview.md

@@ -0,0 +1,86 @@
+---
+id: N-atel-201-mcp-overview
+title: MCP in the Atelier context
+type: note
+track: ATEL-201
+author: atelier
+created: '2026-05-18'
+updated: '2026-05-18'
+tags:
+  - course
+  - atel-201
+  - mcp
+  - architecture
+difficulty: intermediate
+estimatedMinutes: 4
+prerequisites:
+  - N-atel-101-easings
+summary: What the `atelier-mcp` server actually is, why every authoring tool maps to a single mutation on a single document store, and how the LLM↔Studio live-mutation bridge works without conflict.
+---
+
+## What `atelier-mcp` is
+
+`atelier-mcp` is a Model Context Protocol server. An AI agent connects to it (via stdio in Claude Desktop, or WebSocket when paired with `atelier studio`) and gains 61 tools across 15 groups. Each tool is a typed function the agent calls; each call is a single mutation against a shared in-memory `DocumentStore`. The server doesn't talk to the LLM; it just exposes the mutation surface and lets the LLM drive.
+
+The boundary is intentional: the agent does the planning, the server does the validating. If the agent asks `atelier_add_delta` to animate a property that doesn't exist on a layer, the Zod schema rejects the call with an AI-readable error message. The agent reads the error, fixes the request, retries. No invalid document ever reaches the renderer.
+
+## The single-store invariant
+
+There is **one** `DocumentStore` per project session. Every client — the MCP server's tool handlers, the `atelier studio` browser canvas, the WebSocket bridge between them — reads and writes the same store.
+
+This is why the live LLM-mutation feature works at all. When an agent calls `atelier_add_layer`, the store updates, fires `onChange`, and the bridge broadcasts the mutation to any connected Studio. The Studio applies the mutation via `applyMutation(op)` (with a suppress-notify flag for one tick so the change doesn't echo back as a human edit), re-renders the canvas, and shows a toast: *"agent added layer `title`"* with an Undo affordance.
+
+Conflict policy in v1: **last-write-wins**. Human edits during agent mutation overwrite the agent's pending change. No CRDT, no operational transform — Atelier is a single-author tool with an AI collaborator, not a real-time multiplayer canvas. Every op is tagged `source: "human" | "llm"` so the UI can attribute changes.
+
+## Tool conventions
+
+Every MCP tool follows the same conventions. Recognize the pattern once and you can read any tool's signature:
+
+| Convention | Example |
+|---|---|
+| `atelier_<verb>_<noun>` naming | `atelier_add_layer`, `atelier_edit_delta`, `atelier_remove_state` |
+| First argument is always `documentId` (or implicit if the server has a current doc) | `atelier_add_layer({ documentId, ... })` |
+| Mutations return the **updated document** (not just the changed fragment) | An agent doesn't have to re-fetch after every call |
+| Inspect tools return only what was asked for | `atelier_preview` returns resolved layers, not the whole doc |
+| Validation runs after every mutation; tool calls fail fast with field-level errors | Errors include the offending path: `layers[0].visual.style.fontSize: expected number` |
+| Tools that need a frame number accept either an absolute frame or `{ state, frame }` | Clarity over cleverness |
+
+## The 15 groups
+
+```
+document    — create, load, list, info, validate, preview, batch_preview,
+              profile, complexity, diff_frames, export, export_svg, export_lottie
+layer       — add, edit, remove, reorder, list, edit_visual
+state       — add, edit, remove, list, set_parent, configure_transition
+delta       — add, edit, remove
+visual      — set_shape, set_fill, set_stroke, set_shadow, set_blend_mode,
+              set_clip_path, set_motion_path, set_tint
+asset       — add, list, remove
+variable    — add, list, remove, find
+preset      — define, list, apply
+template    — instantiate
+interaction — add, list, remove
+ref         — set_ref, resolve_refs
+audio       — set_audio
+overlay     — add_handle, add_page_number   (Phase 1.5)
+recipe      — recipe_list, recipe_get, recipe_validate, recipe_save, recipe_apply
+import      — import_images
+```
+
+The next three notes cover the high-frequency tools — what to call and when. The full reference is `docs/mcp-reference.md` in the atelier repo (and at `https://atelier.dev/mcp`, when that lands).
+
+## Configuring the server
+
+```json
+{
+  "mcpServers": {
+    "atelier": {
+      "command": "atelier-mcp"
+    }
+  }
+}
+```
+
+That's it. No auth tokens. No project path — the server scans CWD for `.atelier` files and loads them lazily on `atelier_load`. To bind the server to a specific project directory, set `ATELIER_PROJECT_ROOT=/path/to/project` in the env.
+
+For the live Studio bridge, run `atelier studio` first; the MCP server detects the bridge's WebSocket endpoint and connects automatically. No config needed.

package/university/content/notes/N-atel-201-patterns.md

@@ -0,0 +1,108 @@
+---
+id: N-atel-201-patterns
+title: Authoring patterns and decision rules
+type: note
+track: ATEL-201
+author: atelier
+created: '2026-05-18'
+updated: '2026-05-18'
+tags:
+  - course
+  - atel-201
+  - mcp
+  - patterns
+  - best-practices
+difficulty: intermediate
+estimatedMinutes: 4
+prerequisites:
+  - N-atel-201-visual-and-effects
+summary: The high-frequency patterns — build-then-animate, snapshot-edit-restore, batch-mutate-validate, preset-vs-hand-author. When to reach for which tool, and the four mistakes agents make most.
+---
+
+## Pattern 1 — Build, then animate
+
+Adding deltas before layers is rejected (the delta's target layer doesn't exist yet). Adding all layers first, then all deltas in the order they'll fire, produces clean diffs and easy debugging.
+
+Rough order for a fresh document:
+
+```
+atelier_create
+↓ (variables / assets / presets / templates if needed)
+atelier_add_variable        (× N)
+atelier_add_asset           (× N)
+atelier_define_preset       (× N)
+↓
+atelier_add_layer           (× N)
+atelier_edit_visual / set_* (× N — visual configuration that doesn't animate)
+↓
+atelier_add_state           (× N — if multi-state)
+atelier_set_state_parent    (× N — for hierarchical states)
+atelier_configure_transition (× N — for interactive transitions)
+↓
+atelier_add_delta           (× N — the motion)
+↓
+atelier_validate
+atelier_preview { frame: N } (sanity-check mid-motion)
+```
+
+Reverse-order works (the validator still catches problems) but produces noisier error logs.
+
+## Pattern 2 — Snapshot, edit, restore
+
+When an agent is about to make a destructive change (e.g. restructuring states, replacing a layer type), snapshot first:
+
+```ts
+const before = await atelier_info({ documentId });
+// ... mutations ...
+await atelier_validate({ documentId });
+// if it doesn't pass: reload from the prior state or use the studio's undo stack
+```
+
+The MCP store doesn't have an undo stack of its own (yet — that's Studio-side via `History`). For agent workflows: persist the doc with `atelier_export` before risky changes, restore from the export if validation fails.
+
+## Pattern 3 — Batch-mutate-validate
+
+Many small mutations followed by one `atelier_validate` is more efficient than validating after every call. The schema runs on every tool call regardless (you can't bypass it), but `atelier_validate` also reports advisory warnings — long pauses, overly-deep nesting, missing transitions — that you don't want firing 50 times during a build.
+
+For very large compositions (50+ layers), the studio bridge benefits from grouping mutations into a "build session" — start with `atelier_create`, end with one validate, broadcast one `doc:patch` instead of 50 incremental `llm:mutation` events. The bridge's `coalesce` flag (when set on the WS envelope) suppresses incremental broadcasts until the session ends.
+
+## Pattern 4 — Preset vs. hand-author
+
+If the same motion repeats across three or more layers: define a preset.
+
+```ts
+await atelier_define_preset({ documentId, name: "fade-in-from-below",
+  deltas: [
+    { property: "opacity", from: 0, to: 1, startFrame: 0, endFrame: 24, easing: "ease-out" },
+    { property: "frame.y", from: "${baseY + 24}", to: "${baseY}", startFrame: 0, endFrame: 24, easing: { type: "spring", stiffness: 120, damping: 22 }}
+  ]});
+
+for (const layerId of ["title", "subtitle", "caption"]) {
+  await atelier_apply_preset({ documentId, name: "fade-in-from-below",
+    layer: layerId, state: "default", offset: layerId === "title" ? 0 : 6 });
+}
+```
+
+The `offset` parameter shifts the applied deltas by N frames — that's how you stagger entrances without hand-authoring N delta sets.
+
+If a motion is one-of-a-kind: hand-author. Don't define a preset for a one-time animation.
+
+## Pattern 5 — Use templates for *layers*, presets for *deltas*
+
+Templates produce layer subtrees (with variable substitution). Presets produce delta bundles.
+
+If you find yourself defining a "preset" that's actually a `group` layer with three children — that's a template. Switch and use `atelier_instantiate_template`.
+
+If you find yourself defining a "template" that's just three deltas on a single layer — that's a preset. Switch and use `atelier_define_preset`.
+
+## The four most common agent mistakes
+
+1. **Adding a delta to a property that doesn't exist on the layer's visual type.** A `TextVisual` has `style.fontSize` but no `style.borderRadius`. The schema rejects it; the agent should read the error message verbatim ("`property "style.borderRadius" is not animatable on a text layer`") and pick a real property.
+
+2. **Forgetting to set `endFrame ≤ state.duration`.** The schema accepts deltas that extend past the state's duration, but the renderer clamps them — you get motion that "freezes" at the boundary value. If you want a 2-second animation, set `state.duration: 120` (at 60fps) before adding deltas.
+
+3. **Overlapping deltas on the same layer + property.** The no-overlap gate rejects it. Fix: split into two adjacent ranges (`0–30` then `30–60`), or use two layers.
+
+4. **Mutating a doc without saving.** The MCP store is in-memory. Closing the session loses unsaved work. Either run inside `atelier studio` (which autosaves), or call `atelier_export({ format: "yaml", out: "session.atelier" })` periodically.
+
+That closes ATEL-201. The next track (ATEL-301) covers the visual system in depth — every shape, every fill mode, the typography stack, image handling, and the new overlay namespace.

package/university/content/notes/N-atel-201-visual-and-effects.md

@@ -0,0 +1,125 @@
+---
+id: N-atel-201-visual-and-effects
+title: Visual configuration, effects, assets, and refs
+type: note
+track: ATEL-201
+author: atelier
+created: '2026-05-18'
+updated: '2026-05-18'
+tags:
+  - course
+  - atel-201
+  - mcp
+  - visual
+  - assets
+difficulty: intermediate
+estimatedMinutes: 5
+prerequisites:
+  - N-atel-201-authoring-tools
+summary: The visual configuration toolset — shape, fill, stroke, shadow, blend mode, clip path, motion path, tint. Plus assets, variables, presets, templates, interactions, refs, audio, and the overlay namespace.
+---
+
+## Visual configuration tools
+
+These tools mutate a layer's `visual` or layer-level effect properties:
+
+```
+atelier_set_shape       — change a ShapeVisual's shape (rect → ellipse → path)
+atelier_set_fill        — set/clear fill color, gradient, or pattern
+atelier_set_stroke      — set/clear stroke color, width, dash pattern
+atelier_set_shadow      — drop shadow / glow on the layer
+atelier_set_blend_mode  — Canvas composite operation (multiply, screen, etc.)
+atelier_set_clip_path   — restrict rendering to inside a shape
+atelier_set_motion_path — animate position along a path with optional auto-rotate
+atelier_set_tint        — color overlay strength 0-1
+```
+
+Each is a single mutation. The tools exist (instead of bundling into `atelier_edit_visual`) because their argument shapes are stable — fill takes a color/gradient/pattern union, stroke takes width + color + dash, shadow takes offset + blur + color. Type narrowing in your IDE makes them friendly to call.
+
+**Fill, stroke, and shadow are animatable.** A delta on `fill.color` or `shadow.blur` interpolates the value frame-by-frame. The visual-config tools set the *current* (static) value; deltas animate it.
+
+## Assets
+
+```
+atelier_add_asset    — register an image / video / audio asset (assetId + src)
+atelier_list_assets  — enumerate registered assets
+atelier_remove_asset — remove (rejects if referenced by a layer)
+```
+
+Assets are referenced by `assetId` from `ImageVisual.assetId`, `VideoVisual.assetId`, and the audio block. Registering an asset doesn't load it — the renderer fetches lazily. Use relative paths (relative to the doc) or absolute file:// URLs; the studio's `/api/assets/:base64path` endpoint serves them with path-traversal protection.
+
+## Variables
+
+```
+atelier_add_variable    — declare a named variable with a default value
+atelier_list_variables  — enumerate variables
+atelier_remove_variable — remove a variable (rejects if referenced)
+atelier_find_variables  — find layers/deltas using ${name} substitution
+```
+
+Variables enable templates and parametric documents. A `${title}` in a text layer's `content` is substituted at resolve time. The recipe system (ATEL-601) uses variables to inject `{current}`/`{total}` for page-number overlays.
+
+## Presets and templates
+
+```
+atelier_define_preset    — bundle a set of deltas as a named preset
+atelier_list_presets     — enumerate presets
+atelier_apply_preset     — apply a preset's deltas to one or more layers
+atelier_instantiate_template — instantiate a named layer subtree with variable substitution
+```
+
+**Preset** = "I want this fade-in pattern on every title." Define it once with `atelier_define_preset`, apply it to N layers with `atelier_apply_preset` — each application substitutes the layer id and produces deltas.
+
+**Template** = "I want this layout (logo + handle + page-number) in every carousel page." Define a template subtree with variable holes; `atelier_instantiate_template({ template, variables: { handle: "@me", page: "01/05" }})` produces a fresh subtree with those values.
+
+The studio recipe system (ATEL-601) is partially built on templates — applying a recipe instantiates a default template per layer type if no user-authored layer occupies that slot.
+
+## Interactions
+
+```
+atelier_add_interaction     — bind an event (hover, click) to an action (state transition)
+atelier_list_interactions   — enumerate interactions on the document
+atelier_remove_interaction  — remove an interaction
+```
+
+Interactions live on layers and trigger state transitions. `hover` on the title layer transitions the document into the `hover` state with the transition easing defined by `atelier_configure_transition`. The renderer's interactive runtime (used by the studio, by SVG embeds, and by `@atelier/react`) consumes these.
+
+For pure video output: skip interactions. They're for interactive embeds.
+
+## Refs (sub-documents)
+
+```
+atelier_set_ref      — point a RefVisual layer at another .atelier file
+atelier_resolve_refs — preview the rendered ref tree (for nested refs)
+```
+
+A `RefVisual` layer renders another `.atelier` document inside itself. Use for: reusable lower-thirds across multiple compositions, lock-up logos that need a single source of truth, carousels where every page references a shared layout template.
+
+Refs are resolved at render time. The studio re-renders the ref when the source file changes (file watcher), so editing the referenced doc updates every composition that uses it.
+
+## Audio
+
+```
+atelier_set_audio — attach an audio track to the document with sync metadata
+```
+
+For video projects with sound. The `atelier transcribe` pipeline (ATEL-501) writes the transcript and the audio sync metadata that drives caption layer alignment.
+
+## Overlays (Phase 1.5)
+
+```
+atelier_add_handle      — create a @handle text overlay layer (tag: overlay)
+atelier_add_page_number — render {current}/{total} into a text overlay layer
+```
+
+These are convenience tools matching the recipe `overlay_rules` schema. Layers carry `tags: ["overlay"]` so they participate in the layer-tag isolation invariant — re-applying an overlay recipe drops only overlay-tagged layers and replaces them; user-authored layers and other pipelines' outputs are untouched.
+
+## Export
+
+```
+atelier_export        — top-level export (auto-detects format from --out extension)
+atelier_export_svg    — SVG string of one frame
+atelier_export_lottie — Lottie JSON of the full document
+```
+
+Export tools call into `@atelier/canvas`, `@atelier/svg`, `@atelier/lottie`, or `@atelier/video` depending on format. Single-frame PNG, multi-frame MP4/WebM/GIF, vector SVG, and motion-design Lottie all land here.

package/university/content/notes/N-atel-301-composition-and-overlays.md

@@ -0,0 +1,141 @@
+---
+id: N-atel-301-composition-and-overlays
+title: Composition, refs, and the overlay namespace
+type: note
+track: ATEL-301
+author: atelier
+created: '2026-05-18'
+updated: '2026-05-18'
+tags:
+  - course
+  - atel-301
+  - composition
+  - overlays
+  - refs
+  - groups
+difficulty: intermediate
+estimatedMinutes: 5
+prerequisites:
+  - N-atel-301-effects
+summary: GroupVisual + parentId for transform-inherited clusters, RefVisual for sub-documents, and the `overlay` tag namespace — handle and page-number overlays as parameterized text layers protected by the layer-tag isolation invariant.
+---
+
+## Groups and parentId
+
+A `GroupVisual` layer renders nothing of its own. It exists to provide a parent transform for child layers:
+
+```yaml
+- id: card
+  visual: { type: group }
+  frame: { x: 200, y: 400 }
+  rotation: -8
+  bounds: { width: 600, height: 800 }
+
+- id: card-photo
+  parentId: card
+  visual: { type: image, assetId: hero-photo }
+  frame: { x: 0, y: 0 }
+  bounds: { width: 600, height: 600 }
+
+- id: card-title
+  parentId: card
+  visual: { type: text, content: "Title", style: { ... }}
+  frame: { x: 24, y: 640 }
+  bounds: { width: 552, height: 80 }
+```
+
+The `card` group is positioned at canvas (200, 400) and rotated -8°. Its children render in the group's local coordinate space — the photo is at (0, 0) relative to the rotated card, not the canvas. Animating the group's `rotation` or `frame.x` moves the whole cluster as one unit.
+
+**Use groups for:** anything that needs to move/rotate/scale as a unit. Cards, lower-thirds, picture-in-picture clusters, repeated elements you want to manage together.
+
+**Don't use groups for:** ordering or styling. Layer z-order is the array index; styling is per-layer.
+
+## Refs — sub-documents
+
+```yaml
+- id: lower-third
+  visual:
+    type: ref
+    src: ./lower-third.atelier
+    state: default           # optional — defaults to first state
+    frame: 0                 # optional — defaults to parent frame, clamped to sub-doc duration
+  frame: { x: 0, y: 900 }
+  bounds: { width: 1920, height: 180 }
+```
+
+A `RefVisual` renders another `.atelier` document inside itself. The sub-document is resolved (via `resolveFrame`) and rendered into the parent's coordinate space.
+
+**Use refs for:** brand lock-ups (logo + tagline) reused across compositions, lower-thirds with consistent style, carousel templates where every page references a shared layout, scenes that are themselves composed scenes.
+
+The studio file-watches every referenced `.atelier` file. Editing the sub-document updates every parent composition that references it — refs are how Atelier expresses "single source of truth."
+
+## The overlay namespace
+
+The `overlay` tag namespace is a Phase 1.5 first-class slot for decorative text layers that mark a composition (handle, page-number, credit, date, QR). Every overlay layer carries `tags: ["overlay"]`.
+
+The contract:
+
+1. Pipelines and recipes that produce overlays use `applyRecipeToOverlay`, which drops only `overlay`-tagged layers before re-adding. The layer-tag isolation invariant (ATEL-501) applies.
+2. User edits to overlay layers (move, restyle, hide) survive re-runs as long as the layer id matches a recipe-defined overlay (the `userEdited` flag is preserved across re-applications).
+3. MCP convenience tools (`atelier_add_handle`, `atelier_add_page_number`) emit overlay-tagged layers with sensible defaults; recipes generate the same shape declaratively.
+
+### Handle overlay
+
+A handle is a static text overlay — typically a social-media handle (`@username`), credit (`by Author`), or watermark. Authored:
+
+```yaml
+overlay_rules:
+  handle:
+    text: "@username"
+    anchor: bottom-left
+    margin: 32
+    style:
+      fontFamily: Inter
+      fontSize: 24
+      fontWeight: 600
+      color: "#F5F5F7"
+```
+
+Applied via `apply-recipe` or `atelier_add_handle`. Layer id: `overlay-handle` (stable, so re-apply replaces in place).
+
+### Page-number overlay
+
+A page-number is a parameterized text overlay rendering a template like `{current}/{total}` or `{current:02d} of {total:02d}`. Authored:
+
+```yaml
+overlay_rules:
+  page_number:
+    format: "{current:02d}/{total:02d}"
+    anchor: bottom-right
+    margin: 32
+    style:
+      fontFamily: Inter
+      fontSize: 18
+      fontWeight: 500
+      color: "#9CA3AF"
+```
+
+Applied during carousel batch processing: the renderer threads `currentIndex` and `totalCount` into `applyRecipeToOverlay`, which renders the format string into the layer's content. Layer id: `overlay-page-number`.
+
+Single-frame applies (where the carousel context isn't available) skip the page-number layer with a logger warning — by design. A page-number doesn't make sense on a standalone composition.
+
+### Anchor math
+
+All four corners are supported. The translator maps anchor → frame/anchorPoint as follows:
+
+| `anchor` | `frame` | `anchorPoint` |
+|---|---|---|
+| `top-left` | `{ x: margin, y: margin }` | `{ x: 0, y: 0 }` |
+| `top-right` | `{ x: canvas.width - margin, y: margin }` | `{ x: 1, y: 0 }` |
+| `bottom-left` | `{ x: margin, y: canvas.height - margin }` | `{ x: 0, y: 1 }` |
+| `bottom-right` | `{ x: canvas.width - margin, y: canvas.height - margin }` | `{ x: 1, y: 1 }` |
+
+The anchor doubles as the rotation/scale pivot — animating `rotation` on an overlay rotates around the corner the overlay is anchored to.
+
+### Why overlays are their own namespace (and not just "text layers")
+
+Because they're **generated and re-generated** by recipes. The layer-tag isolation invariant lets a user tweak an overlay (drag the handle a few pixels, restyle it), re-apply the recipe, and keep the tweak. Untagged user-authored text layers are never touched. Caption-pipeline layers (`tags: ["caption"]`) and silence-trim layers (`tags: ["silence-trim"]`) are never touched either.
+
+That isolation is what makes the human↔agent symbiotic loop safe at every level of the pipeline — silence-trim, captions, overlays, and (soon) carousel-batch page-numbers.
+
+That closes ATEL-301. You now know every visual primitive Atelier renders and how composition + overlays slot into the layer-tag invariant. The remaining tracks (ATEL-401 motion deep-dive, ATEL-501 video pipelines, ATEL-601 recipes, ATEL-701 export) layer on top of this foundation.