@a-company/atelier 0.36.0 → 0.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a-company/atelier",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "description": "CLI tool — validate, preview, render, info commands",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -20,8 +20,12 @@
   "files": [
     "dist",
     "templates/**",
-    "src/web/**"
+    "src/web/**",
+    "university/**"
   ],
+  "paradigm": {
+    "universityPack": "university/"
+  },
   "dependencies": {
     "@a-company/atelier-studio": ">=0.25.1",
     "@modelcontextprotocol/sdk": "^1.0.0",
@@ -31,7 +35,7 @@
     "ws": "^8.20.1",
     "yaml": "^2.7.0",
     "zod": "^3.25.0",
-    "@a-company/atelier-mcp": "0.27.1"
+    "@a-company/atelier-mcp": "0.27.2"
   },
   "peerDependencies": {
     "canvas": ">=2.0.0"
@@ -50,17 +54,18 @@
     "tsup": "^8.4.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0",
-    "@a-company/atelier-core": "0.26.0",
     "@a-company/atelier-lottie": "0.25.1",
-    "@a-company/atelier-canvas": "0.26.0",
-    "@a-company/atelier-types": "0.31.0",
     "@a-company/atelier-schema": "0.28.0",
-    "@a-company/atelier-svg": "0.25.1"
+    "@a-company/atelier-canvas": "0.26.0",
+    "@a-company/atelier-svg": "0.25.1",
+    "@a-company/atelier-core": "0.26.0",
+    "@a-company/atelier-types": "0.31.0"
   },
   "scripts": {
     "build": "tsup",
+    "bundle-university": "node scripts/bundle-university.mjs",
     "typecheck": "tsc --noEmit && tsc --noEmit -p src/web/tsconfig.json",
     "test": "vitest run",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist university"
   }
 }

package/university/content/notes/N-atel-001-first-render.md

@@ -0,0 +1,114 @@
+---
+id: N-atel-001-first-render
+title: Render your first animation
+type: note
+track: ATEL-001
+author: atelier
+created: '2026-05-18'
+updated: '2026-05-18'
+tags:
+  - course
+  - atel-001
+  - first-render
+  - cli
+difficulty: beginner
+estimatedMinutes: 5
+prerequisites:
+  - N-atel-001-install-and-launch
+summary: Create a minimal `.atelier` document by hand, preview a frame, and export to PNG — three CLI calls, no studio needed. Demystifies the document format before the visual surfaces hide it.
+---
+
+## The smallest possible document
+
+Save this as `hello.atelier` in any directory:
+
+```yaml
+name: Hello
+canvas:
+  width: 800
+  height: 600
+  fps: 60
+  background: "#0F1115"
+layers:
+  - id: title
+    visual:
+      type: text
+      content: Hello, Atelier
+      style:
+        fontFamily: Inter, system-ui, sans-serif
+        fontSize: 64
+        fontWeight: 600
+        color: "#F5F5F7"
+    frame:
+      x: 400
+      y: 300
+    bounds:
+      width: 600
+      height: 100
+    anchorPoint:
+      x: 0.5
+      y: 0.5
+    opacity: 0
+states:
+  default:
+    duration: 60
+    deltas:
+      - layer: title
+        property: opacity
+        from: 0
+        to: 1
+        startFrame: 0
+        endFrame: 30
+        easing: ease-out
+```
+
+That's a full Atelier document. One text layer, one state, one delta that fades the title in over 30 frames.
+
+## Validate it
+
+```bash
+atelier validate hello.atelier
+```
+
+The schema catches malformed easings, references to nonexistent layers, out-of-range frame numbers, missing required fields. Validation runs against a Zod schema with AI-readable error messages — if you ever ship a corrupt document, the validator will point at the field, not just say "invalid YAML."
+
+## Preview a frame
+
+```bash
+atelier preview hello.atelier --frame 15
+```
+
+Outputs the resolved layer state at frame 15: the title at 50% opacity, mid-fade. This is the same `resolveFrame` call the renderer makes; `preview` lets you inspect it without rendering.
+
+## Export
+
+```bash
+atelier export-image hello.atelier --frame 30 --out hello.png
+```
+
+PNG export from a single frame, via the `@napi-rs/canvas` rasterizer (prebuilt binaries — no native build, works on a plain `npm install`). For video, use `atelier render`:
+
+```bash
+atelier render hello.atelier --format mp4 --out hello.mp4
+```
+
+The CLI's `render` uses FFmpeg (must be on `$PATH`) and outputs MP4 or GIF. The browser studio exports via WebCodecs (MP4 / WebM / GIF, no FFmpeg dependency). Vector output is `atelier export-svg` and `atelier export-lottie` — see ATEL-701.
+
+## What you just learned about the format
+
+- **Canvas** sets dimensions, frame rate, background — the global render context.
+- **Layers** are visual elements with an ID, a `visual` (shape/text/image/video/group/ref), a `frame` (position), `bounds` (size), `anchorPoint`, and animatable properties (opacity, rotation, scale).
+- **States** are named keyframes. Each has a `duration` (in frames) and `deltas` (interpolations).
+- **Deltas** animate one property of one layer from a `from` value to a `to` value across `startFrame`–`endFrame`, with an `easing`.
+
+That's the mental model. Layers describe what exists. States describe how long. Deltas describe how things change. Everything else — easings, presets, templates, interactions, refs — extends these primitives.
+
+## Where to go next
+
+- **ATEL-101**: Document Model Fundamentals — every layer type, every easing, the resolveFrame interpolation model
+- **ATEL-201**: Authoring via MCP — the 61 tools an agent uses to build documents like this without touching YAML
+- **ATEL-301**: Visual System — shapes, typography, images, video; fills, strokes, shadows, blend modes, motion paths
+- **ATEL-501**: Video Project Pipeline — silence-trim, transcribe, captions, parametric cuts
+- **ATEL-601**: Studio Recipes — bundle silence policy + caption style + overlay rules + palette into a reusable preset
+
+You can also just run `atelier studio hello.atelier` and edit this document in the browser. Anything you change in the studio writes back to the same file.

package/university/content/notes/N-atel-001-install-and-launch.md

@@ -0,0 +1,84 @@
+---
+id: N-atel-001-install-and-launch
+title: Install Atelier and launch the studio
+type: note
+track: ATEL-001
+author: atelier
+created: '2026-05-18'
+updated: '2026-05-18'
+tags:
+  - course
+  - atel-001
+  - install
+  - cli
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites:
+  - N-atel-001-what-is-atelier
+summary: One npm install gives you three commands — `atelier` (CLI), `atelier-mcp` (MCP server for AI agents), and `atelier studio` (local browser editor). Walks through install, what each command does, and how the three relate.
+---
+
+## Install
+
+```bash
+npm i -g @a-company/atelier
+```
+
+That single install gives you three executables on your `$PATH`:
+
+| Command | What it does | When you use it |
+|---|---|---|
+| `atelier` | CLI for validating, inspecting, rendering, and processing `.atelier` files | Scripts, CI, Makefiles, ad-hoc inspection |
+| `atelier-mcp` | MCP server an AI agent can connect to for authoring | Configure once in Claude Desktop or any MCP-aware client |
+| `atelier studio` | Boots a local browser editor on `localhost` | Hands-on editing; image overlays; watching an agent mutate live |
+
+You only need Node 20+ and a modern browser. No native build, no cloud account, no signup.
+
+## Launch the studio
+
+```bash
+atelier studio
+```
+
+That command:
+
+1. Probes a free port starting at `4321` (override with `--port 5000` or `--port-range 4321-4340`)
+2. Boots a local HTTP server bound to `127.0.0.1` (never `0.0.0.0`)
+3. Opens your default browser to `http://localhost:<port>` (suppress with `--no-open`)
+4. Watches the current working directory for `.atelier` files and lists them in the sidebar
+5. If the directory is empty, scaffolds a `welcome.atelier` so you land in a real document instead of an empty shell
+
+The studio runs entirely on your machine. Nothing is sent anywhere.
+
+## Configure the MCP server (for AI agents)
+
+In your Claude Desktop config (or any MCP client):
+
+```json
+{
+  "mcpServers": {
+    "atelier": {
+      "command": "atelier-mcp"
+    }
+  }
+}
+```
+
+The agent now has 61 tools across 15 groups — document/layer/state/delta operations, visual configuration, asset and variable management, presets, templates, exports, and more. ATEL-201 covers the full tool surface and when to use which.
+
+## How the three commands relate
+
+They share a single underlying engine (`@atelier/core`) and document store. Mutations made by `atelier-mcp` are observable by `atelier studio` running in the same project — when you wire the live-mutation bridge (the WebSocket transport between the MCP store and the studio), an agent's tool calls appear in the studio canvas in real time, with a toast attributing each change to its source.
+
+This is the symbiotic loop Atelier is built for: the agent proposes, you tweak, the agent re-proposes, your tweaks survive. The detected-vs-user-edited convention from ATEL-501 (video pipelines) is the same idea generalized — every channel (silence-trim, captions, overlays, agent mutations) carries a source tag, and re-runs preserve human authorship.
+
+## Sanity-check your install
+
+```bash
+atelier --version
+atelier list
+```
+
+`atelier list` enumerates the `.atelier` files in CWD. If there are none and you haven't launched the studio yet, that's expected — the welcome scaffold only happens on `atelier studio` first run.
+
+Next: render your first animation.

package/university/content/notes/N-atel-001-what-is-atelier.md

@@ -0,0 +1,51 @@
+---
+id: N-atel-001-what-is-atelier
+title: What is Atelier?
+type: note
+track: ATEL-001
+author: atelier
+created: '2026-05-18'
+updated: '2026-05-18'
+tags:
+  - course
+  - atel-001
+  - orientation
+difficulty: beginner
+estimatedMinutes: 3
+prerequisites: []
+summary: Atelier is an AI-native animation engine — a declarative YAML format authored through MCP tools, runnable from a CLI, embeddable as a widget, and now bootable as a local browser editor with `atelier studio`.
+---
+
+## The short version
+
+Atelier is an **animation engine that an AI agent can author through tool calls**. A `.atelier` document is plain YAML describing layers (shapes, text, images, video, groups), states, and deltas (per-frame interpolations). An agent calling `atelier_create`, `atelier_add_layer`, `atelier_add_state`, `atelier_add_delta` builds a document the same way a human would in a GUI — except every step is structured, validated, and reproducible.
+
+Once a document exists, Atelier can:
+
+- **Resolve** any frame by interpolating delta values through easings (linear, cubic-bezier, ease presets, spring physics, step)
+- **Render** to Canvas 2D, SVG strings, or Lottie JSON
+- **Export** to PNG, MP4, WebM, GIF — from a browser (WebCodecs) or the CLI (FFmpeg)
+- **Edit** in a browser studio with a canvas preview, layer panel, property panel, and YAML view
+- **Trim, transcribe, caption** video projects with the silence-detect + Whisper + caption pipelines
+
+## What makes it "AI-native"
+
+Three things, in order of importance:
+
+1. **The document format was designed for an agent to write.** Layers have descriptive IDs, deltas reference layers by ID, states reference each other by name. There is no "drag this onto the canvas" — there is `atelier_add_layer({ id: "title", visual: { type: "text", content: "Hello", style: {...} } })`. The schema gives AI-readable validation errors when the agent gets it wrong.
+2. **61 MCP tools cover the full authoring surface.** An agent doesn't compose YAML by hand and pray it parses. It calls typed tools that mutate a document store, validate after each mutation, and return the updated document. Mistakes are caught at the tool boundary, not at render time.
+3. **The detected-vs-user-edited convention.** When a pipeline (silence-trim, captions) generates layers from analysis, those layers are tagged. User edits set `userEdited` / `userAdded` / `hidden` flags. Re-running the pipeline preserves user fixes by matching on timing tolerance. The human and the agent can both edit the same document forever without one erasing the other.
+
+## What it is not
+
+- **Not a code framework.** It does not ship React components, runtime hooks, or HTTP handlers.
+- **Not a cloud product.** Everything runs locally. There is no signup, no SaaS, no telemetry by default.
+- **Not a replacement for After Effects.** It is a programmable, AI-author-first format. You will not draw bezier paths with a mouse here (yet). You will describe them in YAML or generate them via tool calls.
+
+## Who uses Atelier today
+
+- **AI agents** authoring social-media-ready motion graphics, explainer animations, and short-form video composition
+- **Developers** scripting animations via the Builder API (`@atelier/core`) or driving the CLI from a Makefile
+- **Content creators** in `atelier studio` for hands-on layer editing with AI assistance live in the loop
+
+The rest of this track shows you how to install Atelier and render your first animation in under two minutes.

package/university/content/notes/N-atel-101-easings.md

@@ -0,0 +1,97 @@
+---
+id: N-atel-101-easings
+title: Easings — linear, cubic-bezier, presets, spring, step
+type: note
+track: ATEL-101
+author: atelier
+created: '2026-05-18'
+updated: '2026-05-18'
+tags:
+  - course
+  - atel-101
+  - easings
+  - motion
+difficulty: beginner
+estimatedMinutes: 4
+prerequisites:
+  - N-atel-101-states-and-deltas
+summary: Five easing kinds in Atelier. What each is, when to use it, and the one rule that prevents 90% of bad motion (don't use `linear` for organic movement).
+---
+
+## What an easing does
+
+An easing is a function `f(t: 0..1) → 0..1` that maps "fraction of time elapsed" to "fraction of value progress." `f(0) = 0`, `f(1) = 1`. What happens in between is the personality of the motion.
+
+Atelier supports five kinds:
+
+## 1. `linear`
+
+`f(t) = t`. Constant rate. Use for: progress bars, scrubbing, opacity crossfades where the perceived speed matters. **Do not use** for object motion — it looks robotic. Most "feels wrong" motion in the wild is `linear` doing the wrong job.
+
+```yaml
+easing: linear
+```
+
+## 2. Cubic-Bezier — `cubic-bezier(x1, y1, x2, y2)`
+
+The CSS-style four-control-point bezier. Full control over the shape. This is what every preset below desugars to.
+
+```yaml
+easing: cubic-bezier(0.4, 0.0, 0.2, 1.0)    # Material "standard"
+```
+
+If you've used CSS transitions, this is the same function.
+
+## 3. Ease presets
+
+Named shortcuts to common bezier curves. Use these instead of memorizing coefficients.
+
+| Preset | Bezier | Use for |
+|---|---|---|
+| `ease-in` | `(0.4, 0, 1, 1)` | Object accelerating off-screen |
+| `ease-out` | `(0, 0, 0.2, 1)` | Object decelerating on entrance (most UI entrance animation) |
+| `ease-in-out` | `(0.4, 0, 0.2, 1)` | Crossfades, value-to-value transitions where both endpoints are visible |
+| `ease` | `(0.25, 0.1, 0.25, 1)` | The CSS default — generic "feels OK" |
+
+Default for most UI motion: `ease-out` for entrances, `ease-in` for exits.
+
+## 4. Spring physics — `spring({ stiffness, damping, mass? })`
+
+Physics-based. Produces overshoot and oscillation that no bezier can match. Use for: anything that should feel tactile — toggles, drag-release, dismissals.
+
+```yaml
+easing:
+  type: spring
+  stiffness: 170
+  damping: 20
+  mass: 1
+```
+
+Stiffness controls how aggressively the spring pulls toward the target. Damping controls how quickly oscillation dies out. Atelier solves the spring numerically per-frame; the same `startFrame`–`endFrame` window still applies (the spring is clipped at `endFrame` and held at the resolved value after).
+
+When in doubt: `stiffness: 170, damping: 26` for a clean snap; `stiffness: 100, damping: 10` for visible oscillation.
+
+## 5. Step — `step(count)` or `step(count, position)`
+
+Discrete jumps. `step(4)` produces four equal jumps from `from` to `to`. Use for: spritesheet frame indexing (jump through frames at 12fps inside a 60fps composition), digital-readout counters, deliberate stop-motion feel.
+
+```yaml
+easing:
+  type: step
+  count: 4
+  position: start    # 'start' | 'end' | 'jump-none' | 'jump-both'
+```
+
+## The rule that prevents most bad motion
+
+> If a real physical object would do it, use spring or ease-out.
+> If a UI element is reporting progress, use linear.
+> Almost nothing else should be linear.
+
+Easings are why motion feels "designed" or "wrong." The engine doesn't care which you pick — the renderer interpolates whatever `f(t)` returns. But your viewer does care, every time.
+
+## Inspecting an easing
+
+The studio's easing-curve-editor (in PropertyPanel when you select a delta) shows the bezier curve, lets you drag control points, and previews the shape against the timeline. For springs, it samples the solver and plots the actual oscillation. There is no "easings preview file" — every delta you author can be inspected and tuned in place.
+
+That closes ATEL-101. You now know enough to read any `.atelier` document and predict what it will render. ATEL-201 covers the MCP tool surface — how an agent builds documents like this without ever touching YAML.

package/university/content/notes/N-atel-101-layers.md

@@ -0,0 +1,106 @@
+---
+id: N-atel-101-layers
+title: Layer anatomy
+type: note
+track: ATEL-101
+author: atelier
+created: '2026-05-18'
+updated: '2026-05-18'
+tags:
+  - course
+  - atel-101
+  - layers
+  - format
+difficulty: beginner
+estimatedMinutes: 5
+prerequisites:
+  - N-atel-101-the-atelier-format
+summary: Every field on the `Layer` type, what it does, what's required vs optional, and which fields are animatable through deltas.
+---
+
+## The minimum layer
+
+```yaml
+- id: title
+  visual:
+    type: text
+    content: Hello
+    style:
+      fontFamily: Inter, system-ui, sans-serif
+      fontSize: 48
+  frame:
+    x: 400
+    y: 300
+  bounds:
+    width: 600
+    height: 80
+```
+
+Four required fields: `id`, `visual`, `frame`, `bounds`. The rest are optional and default to sensible values.
+
+## The six visual types
+
+The `visual` field is a discriminated union on `type`:
+
+| `type` | Renders | Required sub-fields |
+|---|---|---|
+| `shape` | A geometric shape — rect, ellipse, polygon, path | `shape`, optional `fill` and `stroke` |
+| `text` | A string with typography | `content`, `style` (fontFamily required) |
+| `image` | A static image asset | `assetId` (and optional `src`, `sourceRect`, `spritesheet`) |
+| `video` | A video clip | `assetId`, optional `sourceOffset`, `sourceEnd`, `playbackRate` |
+| `group` | A container for child layers (via `parentId`) | none — just a container |
+| `ref` | A reference to another `.atelier` file rendered as a sub-document | `src`, optional `state` and `frame` |
+
+## Position, size, and anchor
+
+- **`frame: { x, y }`** — position of the anchor point in canvas pixels.
+- **`bounds: { width, height }`** — the layer's box.
+- **`anchorPoint: { x, y }`** — normalized 0–1 coordinate inside the bounds that `frame` positions. `{x: 0.5, y: 0.5}` centers the layer on `frame`. `{x: 0, y: 0}` puts the top-left at `frame`. Default is `{x: 0, y: 0}`.
+
+The anchor also defines the pivot for `rotation` and `scale`.
+
+## Animatable layer properties
+
+These can appear in deltas (`property: <name>`):
+
+| Property | Type | Default |
+|---|---|---|
+| `opacity` | number 0–1 | 1 |
+| `rotation` | degrees | 0 |
+| `scale` | `{ x, y }` | `{1, 1}` |
+| `frame.x`, `frame.y` | number | as authored |
+| `bounds.width`, `bounds.height` | number | as authored |
+| `tint.amount` | 0–1 (color tint strength) | 0 |
+| Any color, gradient stop, stroke width, shadow blur on the visual or its style | various | — |
+
+The full animatable list is 27 properties. The schema enforces that a delta's `property` path is reachable on the named layer's visual.
+
+## Non-animatable structural fields
+
+| Field | Purpose |
+|---|---|
+| `id` | Unique identifier |
+| `tags` | Namespace markers (used by pipelines for layer-tag isolation) |
+| `description` | Human-readable note, kept out of render |
+| `parentId` | Parents this layer to another for transform inheritance |
+| `visible` | Hard on/off (rendered if `true` or absent) |
+| `blendMode` | Canvas composite operation |
+| `clipPath` | A Shape that restricts rendering to its interior |
+| `motionPath` | A path the layer follows over time, with optional auto-rotate |
+| `interactions` | Event-driven trigger-action bindings (e.g. hover → state transition) |
+
+## Parent-child and transform inheritance
+
+Setting `parentId` on a layer makes its `frame`, `rotation`, and `scale` relative to the parent's transformed coordinate space. A `group` visual has no rendered output of its own — it exists purely to provide a parent transform. Use groups when you want to translate or rotate a cluster of layers as one unit.
+
+## Tags: the pipeline contract
+
+Tags are how the silence-trim, caption, and overlay pipelines find layers they own. Each pipeline writes a tag namespace:
+
+- `silence-trim` — clip layers produced by `atelier trim`
+- `caption`, `caption-word` — text layers produced by `atelier captions regenerate`
+- `overlay` — handle / page-number / recipe-driven decorative layers
+
+The invariant: re-running a pipeline drops only its own tagged layers and replaces them. Layers without that tag (user-authored, or owned by another pipeline) are never touched. This is what makes the human↔agent symbiotic loop safe (ATEL-501 covers this in depth).
+
+Next: states and deltas.

package/university/content/notes/N-atel-101-states-and-deltas.md

@@ -0,0 +1,94 @@
+---
+id: N-atel-101-states-and-deltas
+title: States, deltas, and `resolveFrame`
+type: note
+track: ATEL-101
+author: atelier
+created: '2026-05-18'
+updated: '2026-05-18'
+tags:
+  - course
+  - atel-101
+  - states
+  - deltas
+  - resolve-frame
+difficulty: beginner
+estimatedMinutes: 5
+prerequisites:
+  - N-atel-101-layers
+summary: A state is a named span of frames. A delta animates one property of one layer over a sub-range of that span. `resolveFrame(doc, stateName, frame)` is the function the renderer calls — knowing its shape demystifies everything else.
+---
+
+## A state is a named span
+
+```yaml
+states:
+  default:
+    duration: 60
+    deltas:
+      - layer: title
+        property: opacity
+        from: 0
+        to: 1
+        startFrame: 0
+        endFrame: 30
+        easing: ease-out
+```
+
+`default` is the state name. `duration: 60` means this state runs for 60 frames (one second at 60fps). Frames are 0-indexed, so this state spans `0..59` inclusive. The renderer plays through the state and either loops, transitions to another state, or stops, depending on configuration.
+
+A document always has at least one state. Most documents have only one. Multi-state documents are the foundation of interactive UI motion (`hover`, `active`, `pressed`) and segmented narratives.
+
+## A delta animates one property
+
+Every field on a delta exists for a reason:
+
+| Field | Meaning |
+|---|---|
+| `layer` | Which layer (by id) this delta animates |
+| `property` | Which animatable property (e.g. `opacity`, `frame.x`, `style.color`) |
+| `from` | Starting value at `startFrame` |
+| `to` | Ending value at `endFrame` |
+| `startFrame` | Frame within the state where this delta begins |
+| `endFrame` | Frame within the state where this delta ends |
+| `easing` | How the value interpolates between `from` and `to` |
+| `expression` | Optional override — a function of `t` (0..1) returning the interpolated value, for non-trivial animations |
+
+Outside `[startFrame, endFrame]`, the property holds its boundary value (clamped). Multiple deltas on the same `layer` + `property` are rejected by the schema's no-overlap gate — overlapping motion is almost always a bug; if you need composition, use two layers or a `group`.
+
+## `resolveFrame` is the whole engine in one function
+
+```ts
+const scene = resolveFrame(doc, stateName, frameNumber);
+// scene is { layers: ResolvedLayer[] } — every property concrete, no deltas
+```
+
+What it does, in order:
+
+1. Look up the state by name. If it doesn't exist, throw.
+2. For each layer in `doc.layers`, start with its authored values.
+3. For each delta in `state.deltas`:
+   - If `frameNumber < startFrame`, the layer's property stays at `from`.
+   - If `frameNumber > endFrame`, the layer's property stays at `to`.
+   - If between: compute `t = (frameNumber - startFrame) / (endFrame - startFrame)`, run `t` through the easing function (returning `t'`), then interpolate `from + (to - from) * t'`.
+4. Apply parent transforms (if a layer has `parentId`), motion paths, clip paths, tints.
+5. Return the resolved scene — every layer now has concrete property values ready for the renderer.
+
+The renderer (canvas, SVG export, Lottie export, video exporter) all consume the same `ResolvedLayer[]` output. Adding a new renderer is "consume one frame at a time"; adding a new animatable property is "add to the interpolation switch."
+
+## Hierarchical states and transitions
+
+States can declare a `parent` (extending another state's deltas) and a `transitions` block (named transitions from one state to another with their own duration, easing, and target deltas). This is the foundation of interactive UI motion — `hover` extends `default` with extra deltas, `pressed` transitions from `hover` with a 200ms ease-out. Full coverage in ATEL-401 (State Machines & Motion).
+
+## Inspecting a frame from the CLI
+
+```bash
+atelier preview hello.atelier --frame 15
+atelier preview hello.atelier --frame 15 --state hover
+```
+
+The output is the same `ResolvedLayer[]` array `resolveFrame` produces — perfect for debugging "what does the engine actually think this scene looks like at frame N?"
+
+For multi-frame inspection, `atelier_batch_preview` (MCP) or `atelier diff_frames` (CLI) compare two frames side by side.
+
+Next: easings.

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