@a-company/atelier 0.36.0 → 0.38.0

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.

package/university/content/notes/N-atel-401-transitions.md

@@ -0,0 +1,94 @@
+---
+id: N-atel-401-transitions
+title: Transitions and the interaction layer
+type: note
+track: ATEL-401
+author: atelier
+created: '2026-05-20'
+updated: '2026-05-20'
+tags:
+  - course
+  - atel-401
+  - transitions
+  - interactions
+  - state-machine
+difficulty: intermediate
+estimatedMinutes: 6
+prerequisites:
+  - N-atel-101-easings
+summary: A transition is the timed bridge from one state to another. Interactions are the triggers that fire those transitions. Together they turn a pile of states into an interactive state machine.
+---
+
+## A transition is a bridge with its own timing
+
+States are destinations. A transition is *how you get from A to B* — with a duration and easing that belong to the move, not to either state.
+
+```ts
+atelier_configure_transition({
+  id,
+  stateName: "default",
+  targetState: "hover",
+  transition: {
+    duration: 12,
+    easing: "ease-out",
+  },
+});
+```
+
+Read it as: "from `default`, the transition to `hover` takes 12 frames, eased-out." The `duration` is in frames (a positive integer) and the `easing` accepts the same forms you already know — `"ease-out"`, `{ type: "cubic-bezier", x1, y1, x2, y2 }`, `{ type: "spring", stiffness, damping }`, `{ type: "step", steps }`.
+
+Transitions are **directional**. `default → hover` and `hover → default` are configured separately, and they usually differ — entrances ease-out, exits ease-in. Pass `transition: null` to remove a configured transition. A state cannot transition to itself, and the target state must already exist (the tool checks both).
+
+## Interactive motion: default → hover → pressed
+
+The classic button is three states and the transitions between them:
+
+```ts
+// states
+atelier_add_state({ id, stateName: "hover",   duration: 30 });
+atelier_add_state({ id, stateName: "pressed", duration: 30 });
+// (hover and pressed typically set parent: "default" — see hierarchical states)
+
+// transitions, each with timing that fits the move
+atelier_configure_transition({ id, stateName: "default", targetState: "hover",   transition: { duration: 10, easing: "ease-out" } });
+atelier_configure_transition({ id, stateName: "hover",   targetState: "pressed", transition: { duration: 6,  easing: "ease-in"  } });
+atelier_configure_transition({ id, stateName: "pressed", targetState: "hover",   transition: { duration: 8,  easing: "ease-out" } });
+atelier_configure_transition({ id, stateName: "hover",   targetState: "default", transition: { duration: 14, easing: "ease-in"  } });
+```
+
+At this point the document *describes* a state machine — but nothing fires the transitions yet. States and transitions are pure data. Something has to say "go."
+
+## The interaction layer — triggers that fire transitions
+
+`atelier_add_interaction` attaches a **trigger → action** binding to a layer. The trigger is the event; the action is what happens.
+
+```ts
+atelier_add_interaction({
+  id,
+  layerId: "button",
+  interactionId: "to-hover",
+  trigger: { type: "hover" },
+  action: { type: "go-to-state", state: "hover" },
+  description: "Lift the button when the pointer enters",
+});
+```
+
+Triggers: `click`, `hover`, `pointerdown`, `pointerup`, `timer` (needs a `delay` in ms), `signal` (needs a `signal` name). Actions: `go-to-state` (needs a `state`), `emit-signal`, `set-variable`, `toggle-visibility`. For the button you wire `hover → go-to-state hover`, `pointerdown → go-to-state pressed`, `pointerup → go-to-state hover`.
+
+A `go-to-state` action does **not** snap. It runs the **transition** you configured from the current state to the target — with that transition's duration and easing. Interactions decide *when*; transitions decide *how it looks getting there*. If no transition is configured for that pair, the runtime cuts to the target's frame 0.
+
+## Two-trigger patterns worth knowing
+
+- **Auto-advance:** a `timer` trigger with `delay` plus `go-to-state` — an intro state that walks itself to the main state after N milliseconds, no input required.
+- **Decoupled choreography:** one layer's `click` action is `emit-signal`; another layer has a `signal` trigger that does `go-to-state`. The clicker doesn't know who's listening. This is how a single tap drives several layers into new states without hard-wiring them together.
+
+## Inspecting an interaction
+
+```ts
+atelier_list_interactions({ id });            // every layer
+atelier_list_interactions({ id, layerId: "button" });  // one layer
+```
+
+The studio's interaction inspector shows each binding and lets you fire it manually to watch the transition play. If a click "does nothing," it is almost always a missing transition for that state pair — the action fired, but there was no bridge to animate across.
+
+Next: the motion deep dive — springs, expressions, and motion paths.

package/university/content/notes/N-atel-501-detected-vs-user-edited.md

@@ -0,0 +1,76 @@
+---
+id: N-atel-501-detected-vs-user-edited
+title: Detected vs. user-edited — why your fixes survive a re-run
+type: note
+track: ATEL-501
+author: atelier
+created: '2026-05-20'
+updated: '2026-05-20'
+tags:
+  - course
+  - atel-501
+  - video
+  - aspects
+difficulty: intermediate
+estimatedMinutes: 6
+prerequisites:
+  - N-atel-101-layers
+summary: The `~detected-vs-user-edited` aspect — detections are immutable, but your overrides (padding, userEdited/userAdded/hidden, corrected text) are re-attached across re-runs by matching on timing tolerance plus unchanged detected text.
+---
+
+## The problem this aspect solves
+
+The video pipeline is meant to be re-run. You re-transcribe after swapping the audio; you re-detect after a re-cut. But every re-run regenerates the machine's findings from scratch. If a re-run wiped your corrections, you'd never trust it — you'd transcribe once, then refuse to touch it.
+
+`~detected-vs-user-edited` is the invariant that makes re-running safe:
+
+> AI-detected content is immutable. User overrides are preserved across re-runs by matching fresh detections to existing entries on timing tolerance **plus** unchanged detected text.
+
+Detected and edited values live in *separate fields* so the two never collide. A transcript word carries both:
+
+```json
+{ "detected": "atelyer", "text": "atelier", "start": 3.40, "end": 3.72, "userEdited": true }
+```
+
+`detected` is what Whisper heard — the machine's column. `text` is what renders — yours. The same split exists on a cut: `rawStart`/`rawEnd` are detected, `paddingPre`/`paddingPost` are yours.
+
+## How a re-run re-attaches your edits
+
+When you re-run, the merge walks the **fresh** detections and asks, for each one: did the user override a matching old entry? "Matching" means two conditions, both required:
+
+1. the timing is within a tolerance, **and**
+2. the `detected` string is unchanged.
+
+| Pipeline | Tolerance | Second condition |
+|---|---|---|
+| Transcript (`mergeTranscriptWithExisting`) | `0.3s` | `detected` string identical |
+| Cuts (`mergeWithExisting`) | `0.5s` | both `rawStart` and `rawEnd` within tolerance |
+
+If both hold, the old override (`text`, `userEdited`, `hidden`, or the cut's padding and label) is copied onto the fresh detection. If they don't, the fresh default wins — because the underlying audio genuinely changed there, and your old correction may no longer make sense.
+
+Requiring **unchanged detected text** is the subtle part. Timing alone isn't enough: if Whisper now hears a different word at that timestamp, blindly carrying your old correction forward would graft a fix onto the wrong word. Matching the `detected` string guarantees you're editing the same finding you edited before.
+
+## userAdded words are orphans — and they're kept
+
+A word you inserted with `atelier transcript add` has no fresh detection to match — Whisper never heard it. These `userAdded` words are preserved as orphans and re-inserted into the right segment by their timing. Your additions don't evaporate just because they aren't in the new Whisper output.
+
+`hidden` words (from `atelier transcript delete`) follow the same rule as edits: matched on timing + unchanged `detected`, then the `hidden` flag rides along.
+
+## Concrete: fix a misheard word, re-transcribe, fix survives
+
+```
+# Whisper hears "atelyer" at word 12
+atelier transcript fix ./proj --word 12 --text 'atelier'
+#   → word 12 now { detected: "atelyer", text: "atelier", userEdited: true }
+
+# later — re-transcribe (swapped a louder take of the same audio)
+atelier transcribe ./proj
+#   → fresh detection at ~3.40s still hears "atelyer"
+#   → matches on 0.3s timing + unchanged detected "atelyer"
+#   → your text:"atelier" + userEdited:true are re-attached
+
+atelier transcript list ./proj
+#   [  12]    3.40s  "atelier" ← "atelyer" [edited]
+```
+
+The same shape holds for cuts: nudge `--cut 3 --pad-post 0.4`, re-run `atelier trim`, and as long as cut #3's raw boundaries land within `0.5s` of where they were, your `0.4s` of trailing padding rides through. Re-detect freely; the human's editorial layer is sticky by construction.

package/university/content/notes/N-atel-501-layer-tag-isolation.md

@@ -0,0 +1,62 @@
+---
+id: N-atel-501-layer-tag-isolation
+title: Layer-tag isolation — pipelines that never step on each other
+type: note
+track: ATEL-501
+author: atelier
+created: '2026-05-20'
+updated: '2026-05-20'
+tags:
+  - course
+  - atel-501
+  - video
+  - aspects
+difficulty: intermediate
+estimatedMinutes: 5
+prerequisites:
+  - N-atel-101-layers
+summary: The `~layer-tag-isolation` aspect — each content pipeline owns a tag namespace and on re-run drops ONLY its own tagged layers, never touching another pipeline's output or user-authored layers. Proven by tests.
+---
+
+## One document, many writers
+
+A `project.atelier` is written by several actors at once: `atelier trim` owns the cut layers, `atelier transcribe` owns the caption layers, recipes own the overlay layers — and *you* hand-author whatever else the scene needs. They all live in the same `layers` array. Re-running any one of them must not disturb the others.
+
+`~layer-tag-isolation` is the rule that makes that work:
+
+> Every content pipeline owns a layer tag-namespace and, on re-run, drops ONLY its own tagged layers before re-adding them — never touching user-authored (untagged) layers or other pipelines' outputs.
+
+This is the load-bearing invariant of the whole human-and-agent loop. Without it, every regenerate would be a gamble; with it, you can re-run a pipeline a hundred times and lose nothing you didn't ask it to touch.
+
+## The namespaces
+
+| Tag | Owner | Status |
+|---|---|---|
+| `silence-trim` | `atelier trim` | Actively written |
+| `caption` | `atelier transcribe` / `atelier captions regenerate` | Actively written |
+| `caption-word` | reserved for per-word caption layers | Reserved in the isolation contract |
+| `overlay` | Studio Recipes (handle, page-number, decoration) | Written by the recipe pipeline |
+
+`silence-trim` and `caption` are what the commands in this track produce. `caption-word` is a reserved slot in the isolation contract — the namespace is claimed so that a future per-word caption mode can't collide with phrase-level `caption` layers. `overlay` belongs to the recipe pipeline (ATEL-301 covers it). Anything **untagged** is yours, and no pipeline ever touches it.
+
+## How a rewrite stays isolated
+
+The mechanism is one line of intent: **filter by tag before rewriting.** When the caption builder rewrites, it partitions the document:
+
+```ts
+// keep everything that ISN'T a caption layer
+const preserved = doc.layers.filter((l) => !(l.tags ?? []).includes("caption"));
+// build fresh caption layers from the current transcript
+const { layers: captionLayers } = buildCaptionLayers(transcript, doc.canvas, options);
+return { ...doc, layers: [...preserved, ...captionLayers] };
+```
+
+`silence-trim` layers, `overlay` layers, and your untagged layers all fall into `preserved` and pass through unchanged. Only the `caption` set is dropped and rebuilt. `atelier trim` does the identical thing for its `silence-trim` tag. Two pipelines, two namespaces, zero overlap.
+
+The same care extends to deltas: when captions are rebuilt, only the deltas keyed to the caption layers being replaced are dropped — every other delta in the state survives.
+
+## Proven by tests, not just by convention
+
+Layer-tag isolation isn't an honor system. The test suite asserts the invariant directly: it seeds a document with a user-authored layer plus one pipeline's tagged layers, re-runs the *other* pipeline, and checks that the user layer and the sibling pipeline's layers are byte-for-byte present afterward. A regression that let `transcribe` clobber a `silence-trim` layer — or a hand-authored title — would turn the suite red.
+
+That's the contract you get to lean on: tag a layer with a pipeline's namespace and that pipeline owns it; leave a layer untagged and it's untouchable. Regenerate as often as you like. The machine only ever cleans up after itself.