@a-company/atelier 0.36.0 → 0.37.0

package/university/content/notes/N-atel-301-effects.md

@@ -0,0 +1,136 @@
+---
+id: N-atel-301-effects
+title: Effects — fills, strokes, shadows, blends, clips, motion paths, tints
+type: note
+track: ATEL-301
+author: atelier
+created: '2026-05-18'
+updated: '2026-05-18'
+tags:
+  - course
+  - atel-301
+  - effects
+  - rendering
+difficulty: intermediate
+estimatedMinutes: 5
+prerequisites:
+  - N-atel-301-images-and-video
+summary: The non-geometry visual surface — paint (fills/strokes/gradients), depth (shadows), compositing (blends), masking (clip paths), trajectory (motion paths), color overlays (tints). What each does, when each animates well.
+---
+
+## Fills
+
+```yaml
+fill:
+  type: color                    # or: linear-gradient | radial-gradient | pattern
+  color: "#3B82F6"
+```
+
+Four fill types:
+
+| `type` | Shape |
+|---|---|
+| `color` | `color: "#RRGGBB"` or `"rgba(...)"` |
+| `linear-gradient` | `stops: [{offset, color}, ...]`, `angle: degrees` |
+| `radial-gradient` | `stops: [{offset, color}, ...]`, `center: {x, y}`, `radius: number` |
+| `pattern` | `assetId` (image), optional `repeat: 'repeat' \| 'no-repeat'` |
+
+Apply via `atelier_set_fill({ documentId, layerId, fill })`. Animatable: stop colors and offsets via deltas on `fill.stops[N].color` and `fill.stops[N].offset`. Solid colors animate via `fill.color`.
+
+## Strokes
+
+```yaml
+stroke:
+  color: "#F5F5F7"
+  width: 2
+  dash: [4, 4]                   # optional dash pattern
+  lineJoin: round                # 'miter' | 'round' | 'bevel'
+  lineCap: round                 # 'butt' | 'round' | 'square'
+```
+
+Animatable: `width`, `color`, `dash` (animate `dash[0]` and `dash[1]` for marching-ants effects).
+
+## Shadows
+
+```yaml
+shadow:
+  color: "#000000AA"
+  blur: 20
+  offsetX: 0
+  offsetY: 8
+  spread: 0                      # optional — extends the shadow before blur
+```
+
+Drop shadows (`offsetX/Y > 0`) and glows (`offsetX/Y === 0` with high `blur`) both use the same primitive. Animate `blur` and `spread` for pulse effects.
+
+Applied per-layer via `atelier_set_shadow({ documentId, layerId, shadow })`. Removing: pass `shadow: null`.
+
+## Blend modes
+
+```yaml
+blendMode: multiply              # or any Canvas composite operation
+```
+
+Layer-level. The full list: `normal`, `multiply`, `screen`, `overlay`, `darken`, `lighten`, `color-dodge`, `color-burn`, `hard-light`, `soft-light`, `difference`, `exclusion`, `hue`, `saturation`, `color`, `luminosity`.
+
+Most common in practice:
+- `multiply` — color over background (good for grading photos)
+- `screen` — lighten effect (good for flares, highlights)
+- `overlay` — contrast boost
+- `color` — preserve luminosity of base, take hue+saturation of overlay (good for color grading)
+
+Animatable indirectly: animate the layer's `opacity` with the blend mode held constant. The blend mode itself is not interpolated (it's a discrete switch).
+
+## Clip paths
+
+```yaml
+clipPath:
+  kind: ellipse                  # any Shape
+  radiusX: 200
+  radiusY: 200
+```
+
+Restricts rendering to inside the clip shape. Useful for: avatar circles, ken-burns inside a non-rectangular frame, transition reveals.
+
+The clip path is in the layer's local coordinate space (same as visual shapes). Animatable: animate the clip shape's properties (e.g. `clipPath.radiusX`) for reveal animations.
+
+## Motion paths
+
+```yaml
+motionPath:
+  points:
+    - { x: 100, y: 400 }
+    - { x: 600, y: 100, outControl: { x: 800, y: 100 }}
+    - { x: 1100, y: 400, inControl: { x: 900, y: 400 }}
+  closed: false
+  autoRotate: true               # layer rotates to follow path tangent
+  autoRotateOffset: 0            # degrees added to the auto-rotation
+```
+
+The layer's `frame.x` / `frame.y` is overridden by the motion path. Deltas that animate `frame.x` or `frame.y` are ignored when a motion path is present (the path is the trajectory; the delta on a parametric position would conflict). To control speed along the path, animate `motionProgress` (0..1) with a delta.
+
+If `autoRotate: true`, the layer's `rotation` follows the path's tangent — good for arrows tracing a curve, cars driving along a road.
+
+## Tints
+
+```yaml
+tint:
+  color: "#3B82F6"
+  amount: 0.4                    # 0..1, strength of the tint overlay
+```
+
+A solid color overlay applied to the rendered layer. Animatable: `tint.amount` produces a tint fade-in/out. `tint.color` interpolates RGB → animatable for color-cycling.
+
+Distinct from `blendMode: color` — tint is a per-layer overlay; blend mode is a composite operation between layers.
+
+## When to use what
+
+- **Color emphasis on a shape:** fill.
+- **Outline:** stroke.
+- **Depth:** shadow.
+- **Photo grading:** blendMode (`multiply`, `color`).
+- **Reveal mask:** clipPath.
+- **Curved trajectory:** motionPath.
+- **Color cycle without changing assets:** tint.
+
+For carousel social posts (the v1 headline use case): fills + a subtle `blendMode: multiply` on a dark overlay layer above the photo for caption legibility, with `tint` reserved for brand-color accents on overlay text.

package/university/content/notes/N-atel-301-images-and-video.md

@@ -0,0 +1,126 @@
+---
+id: N-atel-301-images-and-video
+title: Images and video — assets, cropping, spritesheets, playback
+type: note
+track: ATEL-301
+author: atelier
+created: '2026-05-18'
+updated: '2026-05-18'
+tags:
+  - course
+  - atel-301
+  - images
+  - video
+  - assets
+difficulty: intermediate
+estimatedMinutes: 5
+prerequisites:
+  - N-atel-301-shapes-and-text
+summary: ImageVisual and VideoVisual. The asset system, cropping via sourceRect, spritesheet animation, video playback controls, and the objectFit rules that decide what "fitting" actually means.
+---
+
+## ImageVisual
+
+```yaml
+visual:
+  type: image
+  assetId: hero-photo            # registered via atelier_add_asset
+  src: assets/hero.jpg           # optional — direct URL or data URL for inline use
+  sourceRect:                    # optional — crop region in source pixels
+    x: 100
+    y: 50
+    width: 800
+    height: 600
+  spritesheet:                   # optional — for spritesheet animation
+    columns: 4
+    rows: 4
+    frameWidth: 256
+    frameHeight: 256
+    frameCount: 16               # optional, defaults to columns*rows
+  frameIndex: 0                  # animatable for spritesheet playback
+```
+
+**Crop with `sourceRect`.** The 9-arg form of canvas `drawImage` is exposed directly — pick a sub-rectangle from the source image and draw it into the layer's bounds. The crop is in source-image pixels (not normalized 0–1). Animatable: deltas on `sourceRect.x`, `sourceRect.y`, `sourceRect.width`, `sourceRect.height` produce ken-burns-style pan/zoom.
+
+**Spritesheet animation.** Set `spritesheet` and animate `frameIndex` with a `step()` easing for sprite-frame indexing:
+
+```yaml
+deltas:
+  - layer: walking-character
+    property: frameIndex
+    from: 0
+    to: 15
+    startFrame: 0
+    endFrame: 120
+    easing:
+      type: step
+      count: 16
+      position: jump-none
+```
+
+That walks through 16 spritesheet frames over 2 seconds at 60fps.
+
+## VideoVisual
+
+```yaml
+visual:
+  type: video
+  assetId: hero-clip
+  src: assets/hero.mp4
+  startFrame: 30                 # composition frame when clip begins playing
+  sourceOffset: 5.2              # seconds into source video to start from
+  sourceEnd: 12.7                # seconds into source to stop (undefined = play to end)
+  playbackRate: 1.0              # 1.0 = normal speed
+  volume: 0.8                    # 0–1
+  muted: false
+  objectFit: contain             # 'contain' | 'cover' | 'fill'
+```
+
+- **`startFrame`** anchors the video to the composition timeline. Frame `0` of the composition shows the video frame at `sourceOffset` seconds.
+- **`sourceOffset` / `sourceEnd`** trim the source. The `atelier trim` pipeline writes these values onto `clip-trim-N` layers (with `tags: ["silence-trim"]`) — the layer-tag isolation invariant covered in ATEL-501.
+- **`playbackRate`** changes the source playback speed. `2.0` is 2x faster; `0.5` is half-speed. The audio is pitch-shifted accordingly (or muted if `muted: true`).
+- **`objectFit`** decides what to do when the video's intrinsic aspect doesn't match the layer's bounds:
+  - `contain` — fit entirely inside bounds, possibly with letterboxing
+  - `cover` — fill bounds entirely, possibly cropping
+  - `fill` — stretch to fit (distorts aspect)
+
+For most layouts: `cover`. For preserving aspect: `contain`. `fill` is rarely correct.
+
+## The asset system
+
+```
+atelier_add_asset    — register an asset with id + src + kind
+atelier_list_assets  — enumerate
+atelier_remove_asset — remove (rejects if referenced by a layer)
+```
+
+```ts
+await atelier_add_asset({ documentId,
+  asset: { id: "hero-photo", kind: "image", src: "assets/hero.jpg" }});
+```
+
+`src` can be:
+- A relative path (relative to the doc's directory). The studio's `/api/assets/:base64path` endpoint serves these with path-traversal protection.
+- An absolute `file://` URL.
+- A `data:` URL (inline base64) for portability — useful when shipping a doc as a single file.
+- An `https://` URL (the renderer fetches it; not recommended for offline rendering).
+
+**Why `assetId` + optional `src` (vs just `src`)?** Refactoring. Renaming an asset's source path means updating one entry in `atelier_add_asset`, not every layer that references it.
+
+## Cropping vs scaling — three knobs
+
+Atelier gives you three independent ways to control how an image fits into a layer:
+
+1. **`sourceRect`** — pick a sub-rectangle from the source. Crop *what's drawn*.
+2. **`Layer.scale.x` / `Layer.scale.y`** — scale the layer's transform. Stretch *how it's drawn*.
+3. **`Layer.bounds.width` / `bounds.height`** — change the destination size. Crop *where it's drawn* (and the renderer interpolates fit per `objectFit` if it's a video).
+
+For image carousels with consistent framing: set `bounds` to your target aspect (e.g. 1080×1080), use `sourceRect` to pick the focal area, leave `scale` at 1.0.
+
+For ken-burns pan/zoom: animate `sourceRect.x`/`sourceRect.y`/`sourceRect.width`/`sourceRect.height` with deltas. The image stays in place; the visible crop pans and zooms.
+
+## Drag-and-drop in the studio (v1)
+
+Dropping an image file onto the canvas creates an `ImageVisual` layer with the dropped file inlined as a `data:` URL (small files) or registered as an asset and referenced by `assetId` (larger files). The dropped image is centered on the canvas with bounds matching the image's intrinsic dimensions; you scale and crop from there.
+
+This is the headline workflow for v1: drop a photo, add overlays (handle, page-number), tweak crop, export PNG. The studio's first-run scaffolds a `welcome.atelier` with a placeholder image you immediately replace.

package/university/content/notes/N-atel-301-shapes-and-text.md

@@ -0,0 +1,118 @@
+---
+id: N-atel-301-shapes-and-text
+title: Shapes and text — the foundational visuals
+type: note
+track: ATEL-301
+author: atelier
+created: '2026-05-18'
+updated: '2026-05-18'
+tags:
+  - course
+  - atel-301
+  - shapes
+  - text
+  - typography
+difficulty: intermediate
+estimatedMinutes: 5
+prerequisites:
+  - N-atel-101-layers
+summary: The four shape primitives (rect, ellipse, polygon, path), the typography stack, and the design rules that prevent 90% of "the text looks wrong" problems.
+---
+
+## ShapeVisual — four primitives
+
+```yaml
+visual:
+  type: shape
+  shape:
+    kind: rect           # or: ellipse | polygon | path
+    # ... kind-specific fields
+```
+
+| `kind` | Required fields | Notes |
+|---|---|---|
+| `rect` | `width`, `height`, optional `cornerRadius` | The most common. `cornerRadius` accepts a number or `{tl, tr, br, bl}` for per-corner control. |
+| `ellipse` | `radiusX`, `radiusY` | For circles, set `radiusX === radiusY`. |
+| `polygon` | `points: [{x, y}, ...]` (≥ 3 points) | Closed path through the points. |
+| `path` | `points: PathPoint[]`, optional `closed` | Bezier-capable. Each PathPoint has `{x, y}` and optional `inControl`/`outControl` for curves. |
+
+Shapes are drawn at the layer's `frame` position with the layer's `bounds` as the local coordinate space. Shape coordinates are in that local space — `(0, 0)` is the bounds' top-left.
+
+## Fills and strokes — covered in the effects note
+
+The shape `kind` defines geometry; `fill` and `stroke` (on the visual or set via `atelier_set_fill` / `atelier_set_stroke`) define paint. They're covered in N-atel-301-effects because they apply to text and image layers too, not just shapes.
+
+## TextVisual — the typography stack
+
+```yaml
+visual:
+  type: text
+  content: "Hello"
+  style:
+    fontFamily: Inter, system-ui, sans-serif    # required
+    fontSize: 48                                  # required
+    fontWeight: 600                               # optional, defaults to "normal"
+    color: "#F5F5F7"                              # optional, defaults to canvas-appropriate
+    letterSpacing: 0                              # optional, em units
+    lineHeight: 1.2                               # optional, multiplier
+    textAlign: center                             # 'left' | 'center' | 'right' | 'justify'
+    fontStyle: normal                             # 'normal' | 'italic'
+    textDecoration: none                          # 'none' | 'underline' | 'line-through'
+```
+
+`fontFamily` is treated as a CSS-style fallback chain. The renderer (canvas, SVG, Lottie) loads the first available font and falls back through the chain. **For consistent rendering across renderers and platforms, ship your fonts as assets** — register a font file with `atelier_add_asset({ kind: "font", src: "fonts/Inter-SemiBold.woff2" })` and reference it by the font's PostScript name in `fontFamily`.
+
+Without font assets, the browser studio uses system fonts; the CLI's PNG export (node-canvas) uses whatever's installed on the machine. Renders diverge. Font assets fix this.
+
+## Text bounds
+
+Text layers have `bounds` like every other layer. The renderer wraps text to fit the bounds' width. Lines that exceed the bounds' height are clipped (not pushed off-screen — clipped, like overflow:hidden).
+
+If you want auto-sizing bounds: leave bounds at a generous default (e.g. 1200×400 for a title) and let the text size itself within. Tight bounds give precise layout but require you to know the text content in advance.
+
+Animatable text properties via deltas:
+- `opacity`, `rotation`, `scale`, `frame.x`/`frame.y`, `bounds.width`/`bounds.height` (layer-level — animate any text)
+- `style.fontSize`, `style.color`, `style.letterSpacing`, `style.lineHeight` (style-level)
+- `content` is **not** animatable — to "type" text on, use a series of TextVisual layers each appearing on a successive frame, or use the upcoming `atelier_set_typewriter` interaction (planned, not yet shipped)
+
+## The three rules that prevent most text problems
+
+1. **Always specify `fontSize`.** Defaults exist but vary by renderer. Pin it.
+2. **Always specify `fontFamily` with a fallback chain.** Even if you ship font assets, the chain handles "asset not loaded yet" gracefully.
+3. **Use `anchorPoint: {x: 0.5, y: 0.5}` for any text you'll animate.** Rotation and scale pivot from the anchor — centered text rotates around its center, top-left text rotates around the corner. The latter is almost never what you want.
+
+## Worked example — a title with subtitle
+
+```yaml
+layers:
+  - id: title
+    visual:
+      type: text
+      content: Atelier
+      style:
+        fontFamily: Inter, system-ui, sans-serif
+        fontSize: 120
+        fontWeight: 700
+        color: "#F5F5F7"
+        textAlign: center
+    frame: { x: 960, y: 460 }
+    bounds: { width: 1200, height: 160 }
+    anchorPoint: { x: 0.5, y: 0.5 }
+
+  - id: subtitle
+    visual:
+      type: text
+      content: AI-native animation, locally launched
+      style:
+        fontFamily: Inter, system-ui, sans-serif
+        fontSize: 32
+        fontWeight: 400
+        color: "#9CA3AF"
+        textAlign: center
+        letterSpacing: 0.02
+    frame: { x: 960, y: 600 }
+    bounds: { width: 1400, height: 60 }
+    anchorPoint: { x: 0.5, y: 0.5 }
+```
+
+Two layers, no animation — just composition. Open this in the studio and you have a still composition; add deltas and the title fades and the subtitle slides.

package/university/content/notes/N-atel-401-hierarchical-states.md

@@ -0,0 +1,71 @@
+---
+id: N-atel-401-hierarchical-states
+title: Hierarchical states — `parent`, inheritance, and merge
+type: note
+track: ATEL-401
+author: atelier
+created: '2026-05-20'
+updated: '2026-05-20'
+tags:
+  - course
+  - atel-401
+  - states
+  - hierarchy
+  - resolve-frame
+difficulty: intermediate
+estimatedMinutes: 6
+prerequisites:
+  - N-atel-101-easings
+summary: A state can name a `parent` and inherit its deltas. Inheritance is per `layer+property` group — the child replaces the whole group or leaves it untouched. Know that one rule and hierarchical states stop surprising you.
+---
+
+## Why states inherit
+
+Interactive UI motion is variations on a theme. `hover` is `default` plus a lift. `pressed` is `hover` plus a sink. Re-authoring every shared delta in every state is duplication that drifts — change the entrance once and you have to remember to change it in four places.
+
+A `parent` lets a state say "everything the parent does, plus my changes." You author the shared motion once on the base state and let `hover`, `pressed`, `disabled` extend it.
+
+```ts
+atelier_add_state({ id, stateName: "hover", duration: 30 });
+atelier_set_state_parent({ id, stateName: "hover", parent: "default" });
+```
+
+`atelier_add_state` creates the state with an empty `deltas` array. `atelier_set_state_parent` wires the inheritance link (pass `parent: null` to clear it). The parent must already exist, and a state cannot be its own parent — the tool walks the parent chain and rejects cycles before writing.
+
+## When to use hierarchy (and when not)
+
+Use a parent when states are **variations of the same composition** — the same layers, mostly the same motion, a few overrides. Interaction states (`default` → `hover` → `pressed`) are the canonical case.
+
+Do **not** use a parent to splice unrelated segments of a narrative together. Two states that share no layers and no motion should just be two flat states. Hierarchy earns its keep only when there is real shared motion to inherit.
+
+## How `resolveFrame` merges parent + child
+
+This is the one rule that matters. When a state has a `parent`, the resolver builds the **ancestor chain** (root → … → parent → self), then collects deltas with this algorithm:
+
+1. Group each state's deltas by a `layer+property` key (e.g. `title:opacity`, `title:scale.x`).
+2. Walk the chain from root to self. For each `layer+property` key, the **most-derived state's group wins outright**.
+3. Flatten the surviving groups into the merged delta list, and resolve the frame against that list.
+
+The merge is **per group, not per field**. If the child declares any delta for `title:opacity`, the parent's `title:opacity` is dropped entirely — the child does not patch the parent's `from`/`easing` and keep the rest. Either the child owns that `layer+property` or it inherits the parent's.
+
+| Key | `default` (parent) | `hover` (child) | Resolved on `hover` |
+|---|---|---|---|
+| `title:opacity` | fade 0→1 | fade 0→1, faster | **child** (parent dropped) |
+| `title:scale.x` | — | 1→1.05 | **child** (new key) |
+| `card:shadow.blur` | 4→8 | — | **parent** (inherited) |
+
+So `hover` inherits the card's shadow animation untouched, overrides the title's fade, and adds a title scale the parent never had.
+
+## The trap
+
+The surprising case is partial override. If `default` animates `title:opacity` with a nice spring and `hover` adds *any* `title:opacity` delta — even a tiny one — the spring is gone, replaced wholesale. If you want to keep the parent's motion and add something, add it on a **different property** (or a different layer). One `layer+property` key has exactly one owner in the resolved frame.
+
+## Inspecting the merge
+
+```bash
+atelier preview button.atelier --frame 10 --state hover
+```
+
+The resolved `ResolvedLayer[]` reflects the merged deltas — if a property looks wrong, it is almost always because a child group silently replaced a parent group you meant to keep. Compare against `--state default` at the same frame to see exactly which keys the child took over.
+
+Next: transitions — how you move *between* these states with timing of their own.

package/university/content/notes/N-atel-401-motion-deep-dive.md

@@ -0,0 +1,106 @@
+---
+id: N-atel-401-motion-deep-dive
+title: Motion deep dive — springs, expressions, motion paths
+type: note
+track: ATEL-401
+author: atelier
+created: '2026-05-20'
+updated: '2026-05-20'
+tags:
+  - course
+  - atel-401
+  - motion
+  - springs
+  - expressions
+  - motion-path
+difficulty: intermediate
+estimatedMinutes: 8
+prerequisites:
+  - N-atel-101-easings
+summary: Three ways to push past from→to-with-easing. Springs for physical feel, expression-valued deltas for math-driven motion, and motion paths for trajectories. When each earns its complexity.
+---
+
+## When a bezier isn't enough
+
+A plain delta is `from → to` shaped by an easing. That covers most motion. This note is the other 10% — three escape hatches, each for a problem the basic delta can't express.
+
+## 1. Spring physics — tuning, not guessing
+
+A spring easing is solved numerically per frame, so it can overshoot and settle in a way no bezier can fake. You set it as the delta's `easing`:
+
+```yaml
+easing:
+  type: spring
+  stiffness: 170
+  damping: 20
+  mass: 1
+```
+
+The three knobs:
+
+| Knob | What it controls | Push it up → |
+|---|---|---|
+| `stiffness` | how hard the spring pulls toward the target | snappier, faster arrival |
+| `damping` | how fast oscillation dies out | less bounce (high = no overshoot) |
+| `mass` | inertia of the moving thing | slower, heavier, more lag |
+
+The relationship that matters: **damping relative to stiffness** decides bounce. Low damping against high stiffness oscillates; high damping against the same stiffness glides in with no overshoot. Starting points: `{ stiffness: 170, damping: 26 }` for a clean snap, `{ stiffness: 100, damping: 10 }` for visible springiness. The delta's frame range still clips the solver — the spring is held at its resolved value after the range ends.
+
+Use a spring when the thing should feel **tactile** — toggles, drag-release, dismissals. Use a bezier for crossfades and value-to-value moves where overshoot would be wrong.
+
+## 2. Expression-valued deltas — math as the curve
+
+A delta's `from` and `to` normally hold concrete values. Either can instead hold an **expression object** `{ expr: "..." }` that the engine evaluates **per frame**:
+
+```yaml
+- layer: badge
+  property: rotation
+  range: [0, 120]
+  from: 0
+  to: { expr: "sin(t * tau) * 8" }
+```
+
+The evaluator is a safe recursive-descent parser — **no `eval`, no `Function`**, so an expression can never run arbitrary code. Inside the string you have:
+
+- **Context variables:** `t` (eased progress 0→1), `progress` (raw progress before easing), `frame` (current frame number), `duration` (the delta's length in frames).
+- **Functions:** `sin cos tan abs min max floor ceil round sqrt pow clamp sign log`.
+- **Constants:** `pi`, `tau`, `e`. Operators `+ - * / % **`, comparisons, and a `cond ? a : b` ternary.
+
+Reach for an expression when the motion is a **function**, not a tween — a continuous wobble (`sin(t * tau)`), a value derived from frame number, a conditional that changes behavior partway. For anything a bezier or spring can already do, use those; expressions are for genuinely procedural motion. Note the contract: an expression resolves to a **number**, so it's for numeric properties.
+
+## 3. Motion paths — trajectory instead of two axes
+
+A motion path makes a layer travel a defined trajectory rather than animating `frame.x` and `frame.y` independently:
+
+```yaml
+motionPath:
+  points: [ ... ]      # PathPoint[] defining the curve
+  closed: false
+  autoRotate: true     # turn the layer to follow the path tangent
+  autoRotateOffset: 0  # degrees of rotation offset when autoRotate is on
+```
+
+`autoRotate` makes the layer **bank into the curve** — a paper plane that points where it's going, a label that rides along a route. `autoRotateOffset` corrects for art that doesn't point "right" at 0°.
+
+You control **position along the path with progress**. When a motion path is present, the layer's `frame.x`/`frame.y` are overridden by the path, so you animate the `motionPath.progress` property (0→1) instead — that delta's easing now shapes *speed along the trajectory*:
+
+```yaml
+- layer: plane
+  property: motionPath.progress
+  range: [0, 90]
+  from: 0
+  to: 1
+  easing: ease-in-out
+```
+
+A `frame.x` delta on a layer that has a motion path is ignored at render time — the path won. Express speed and timing through `motionPath.progress` plus easings, not through frame deltas.
+
+## Choosing among the three
+
+> Tactile, physical, should bounce or settle → **spring**.
+> Continuous or procedural, a function of time/frame → **expression**.
+> Should follow a defined route, maybe banking into it → **motion path** + `motionPath.progress`.
+
+Everything else is a plain delta with an easing — and that's the right default. These three are tools for when the default genuinely can't say what you mean.
+
+Next: presets and templates — packaging motion and structure for reuse.

package/university/content/notes/N-atel-401-presets-and-templates.md

@@ -0,0 +1,98 @@
+---
+id: N-atel-401-presets-and-templates
+title: Presets and templates — reusing motion and structure
+type: note
+track: ATEL-401
+author: atelier
+created: '2026-05-20'
+updated: '2026-05-20'
+tags:
+  - course
+  - atel-401
+  - presets
+  - templates
+  - reuse
+difficulty: intermediate
+estimatedMinutes: 7
+prerequisites:
+  - N-atel-101-easings
+summary: Two reuse mechanisms that are easy to confuse. Presets are bundles of deltas you apply to a layer; templates are layer subtrees you instantiate with variables. One rule keeps them straight.
+---
+
+## The one rule
+
+> **Presets = delta bundles. Templates = layer subtrees.**
+
+A preset is *motion* you stamp onto a layer that already exists. A template is *structure* — layers and their content — you instantiate to create new layers. If you keep that distinction, the rest of this note is detail.
+
+## Presets — define once, apply anywhere
+
+Define a named bundle of deltas on the document. Each preset delta describes a property animation **without naming a layer or absolute frames** — those get filled in at apply time.
+
+```ts
+atelier_define_preset({
+  id,
+  presetName: "fade-rise",
+  description: "Fade in while rising 20px",
+  deltas: [
+    { property: "opacity", from: 0,  to: 1, offset: [0, 20], easing: "ease-out" },
+    { property: "frame.y", from: 20, to: 0, offset: [0, 20], easing: "ease-out" },
+  ],
+});
+```
+
+The `offset: [start, end]` on a preset delta is a **relative frame window** — measured from wherever you apply the preset, not from the document's frame 0. Then apply it to a concrete layer in a state:
+
+```ts
+atelier_apply_preset({
+  id,
+  stateName: "intro",
+  presetName: "fade-rise",
+  layerId: "title",
+  startFrame: 0,
+});
+```
+
+Apply expands the preset into real deltas on that layer: each delta's `range` becomes `[startFrame + offset[0], startFrame + offset[1]]`. If a preset delta has no `offset`, it spans `startFrame` to `startFrame + duration` (where `duration` defaults to the state's duration). Expanded deltas go through the same no-overlap check as hand-authored ones — applying a preset that collides with existing motion on the same `layer+property` is rejected.
+
+## Two kinds of stagger
+
+Stagger — the same motion rippling across a row of elements — comes from two different offsets, and it's worth knowing both:
+
+1. **Intra-preset sequencing** — give the deltas *inside* one preset stepped `offset` windows so they fire in sequence from a single apply (e.g. opacity at `[0, 12]`, then a label at `[6, 18]`).
+2. **Cross-instance stagger** — apply the *same* preset to several layers with stepped `startFrame` values. This is the classic stagger-cards pattern:
+
+```ts
+atelier_apply_preset({ id, stateName: "intro", presetName: "fade-rise", layerId: "card-1", startFrame: 0  });
+atelier_apply_preset({ id, stateName: "intro", presetName: "fade-rise", layerId: "card-2", startFrame: 5  });
+atelier_apply_preset({ id, stateName: "intro", presetName: "fade-rise", layerId: "card-3", startFrame: 10 });
+```
+
+Three identical applies, each five frames later than the last — the cards cascade in. Author the motion once; the stagger lives entirely in the stepped `startFrame`.
+
+## Templates — instantiate a layer subtree
+
+A template is a document that uses `{{variableName}}` placeholders in its layers and content. `atelier_instantiate_template` resolves the placeholders against bindings you provide and **creates a new document** in the store:
+
+```ts
+atelier_instantiate_template({
+  id: "lower-third-template",
+  bindings: { name: "Ada Lovelace", title: "Mathematician" },
+});
+```
+
+Use `atelier_find_variables` first to see what a template expects — it reports the `{{...}}` references found, which are declared, and which are undeclared or unused. Instantiation fails (with per-variable messages) if a required binding is missing, so you find gaps before you render.
+
+A template gives you the *whole structure* — layers, text, the lock-up — parameterized. That is fundamentally different from a preset, which only carries motion and needs a layer to land on.
+
+## Choosing
+
+| You have… | You want… | Reach for |
+|---|---|---|
+| A layer that exists | To animate it like other layers | **Preset** (`define` then `apply`) |
+| A repeated structure (cards, lower-thirds) | To stamp out copies with different content | **Template** (`instantiate`) |
+| A row of elements | The same motion, cascading | **Preset** applied N times with stepped `startFrame` |
+
+Presets and templates compose: instantiate a template to build the structure, then apply presets to the layers it produced. Structure from one mechanism, motion from the other — the rule holds.
+
+That closes ATEL-401. You can now build hierarchical, interactive, physically-tuned motion and package it for reuse.