@a-company/atelier 0.36.0 → 0.38.0

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.

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.