@a-company/atelier 0.29.0 → 0.37.0

package/university/content/quizzes/Q-atel-301-visual-system.yaml

@@ -0,0 +1,66 @@
+id: Q-atel-301-visual-system
+title: 'ATEL-301: Visual System'
+description: Verify the visual surface — shapes, text, images/video, effects (fills/strokes/shadows/blends/clips/motion paths/tints), composition (groups/refs), and the overlay namespace.
+author: atelier
+created: '2026-05-18'
+updated: '2026-05-18'
+tags:
+  - course
+  - atel-301
+difficulty: intermediate
+passThreshold: 0.7
+questions:
+  - id: q1
+    question: 'For text to render consistently across the browser studio and the CLI PNG export, what is the recommended pattern?'
+    choices:
+      A: Set `fontFamily` to a generic name like `sans-serif` and let each renderer pick
+      B: 'Ship the font as an asset (`atelier_add_asset({ kind: "font", src: "fonts/Inter.woff2" })`) and reference it by PostScript name in `fontFamily`'
+      C: Use only system fonts that ship with macOS, Windows, and Linux
+      D: Convert all text to SVG paths before rendering
+    correct: B
+    explanation: Without font assets, the studio uses browser-available fonts and the CLI PNG export uses node-canvas with whatever's installed on the machine. Renders diverge. Registering the font as an asset and referencing its PostScript name in `fontFamily` makes the renderer load the same font everywhere. The CSS-style fallback chain still works for graceful degradation.
+  - id: q2
+    question: 'You want to crop an image to show only its center 50% in a layer that sits in a 1080×1080 layout. The source image is 2000×1500. Which approach fits the "cropping vs scaling" model best?'
+    choices:
+      A: Pre-process the image with a tool like ImageMagick and ship the cropped version
+      B: 'Set `sourceRect: {x: 500, y: 375, width: 1000, height: 750}` to pick the center 50% from the source; the layer''s bounds and the image''s drawn region handle the rest'
+      C: 'Set `Layer.scale.x: 2.0` and `Layer.scale.y: 2.0` to zoom in'
+      D: Resize the layer's `bounds` to be smaller than the image
+    correct: B
+    explanation: '`sourceRect` is the right tool — it picks a sub-rectangle from the source image in source pixels. The center 50% of a 2000×1500 image is `{x: 500, y: 375, width: 1000, height: 750}`. Layer.scale stretches the rendered layer (lossy zoom). Layer.bounds changes the destination size (the renderer fits per objectFit). Pre-processing forfeits the ability to animate the crop later (ken-burns pan/zoom via deltas on sourceRect).'
+  - id: q3
+    question: A `motionPath` is set on a layer that also has a delta animating `frame.x`. What happens?
+    choices:
+      A: The delta wins; the motion path is ignored
+      B: 'The motion path wins; the frame.x delta is ignored — animate `motionProgress` instead'
+      C: They additively combine, producing a sum trajectory
+      D: 'The schema rejects the document at validate time'
+    correct: B
+    explanation: When a motion path is present, the layer's frame.x and frame.y are overridden — the path is the trajectory. Deltas on frame.x conflict with the path and are ignored at render time. To control speed along the path, animate `motionProgress` (0..1). If you want a custom trajectory, you've already chosen the motion path — express speed/timing through motionProgress + easings, not through frame deltas.
+  - id: q4
+    question: 'Why do overlay layers (handle, page-number) carry `tags: ["overlay"]` instead of being plain text layers?'
+    choices:
+      A: For sidebar grouping in the studio's layer panel only
+      B: 'So the `applyRecipeToOverlay` translator can drop only overlay-tagged layers when re-running — user-authored layers and other pipelines'' tagged outputs are never touched'
+      C: 'For pricing tier enforcement — overlay layers count toward a quota'
+      D: 'Because TextVisual without the tag has reduced rendering quality'
+    correct: B
+    explanation: 'The `overlay` tag is part of the layer-tag isolation invariant. Each pipeline owns a tag namespace; re-running a pipeline drops only its own tagged layers. Without the tag, re-applying a recipe would either destroy the user''s authored text layers (bad) or fail to clear stale overlay layers (also bad). With the tag, recipes are idempotent and human edits survive re-runs.'
+  - id: q5
+    question: 'A `RefVisual` layer references `./lower-third.atelier`. You edit the referenced file in another editor. What does `atelier studio` do?'
+    choices:
+      A: 'Nothing — refs are resolved once at load time'
+      B: The studio file-watches every referenced file; on change, it re-renders the parent composition with the updated ref
+      C: It throws a stale-ref error and forces a reload
+      D: 'It requires the user to re-import the ref manually'
+    correct: B
+    explanation: '`RefVisual` is how Atelier expresses single-source-of-truth for reusable scenes (lock-ups, lower-thirds, carousel templates). The studio file-watches every referenced `.atelier` file and re-renders parent compositions automatically. Editing the source once updates every composition that uses it.'
+  - id: q6
+    question: 'A `page_number` overlay rule has `format: "{current:02d}/{total:02d}"`. You apply the recipe to a single-frame composition (no carousel context). What happens?'
+    choices:
+      A: The page-number layer is created with content `"{current:02d}/{total:02d}"` (template not rendered)
+      B: 'The applyRecipeToOverlay translator skips the page-number layer (logger warns) — page-numbers don''t make sense on standalone compositions; handle still gets added if configured'
+      C: It throws an error halting the whole apply-recipe pipeline
+      D: It picks defaults (`current=1`, `total=1`) and renders `"01/01"`
+    correct: B
+    explanation: 'Page-numbers require carousel context (`currentIndex`, `totalCount`). On single-frame applies, the translator skips the page-number layer with a logger warning — by design, since `01/01` on a standalone post is misleading. The handle overlay is unconditional and still gets added. When the carousel batch driver eventually applies the same recipe per page, it threads the current/total values into the apply context and the page-number renders correctly.'

package/university/content/quizzes/Q-atel-401-state-machines.yaml

@@ -0,0 +1,66 @@
+id: Q-atel-401-state-machines
+title: 'ATEL-401: State Machines & Motion'
+description: 'Verify hierarchical states, transitions and the interaction layer, motion (springs, expressions, motion paths), and the preset-vs-template distinction.'
+author: atelier
+created: '2026-05-20'
+updated: '2026-05-20'
+tags:
+  - course
+  - atel-401
+difficulty: intermediate
+passThreshold: 0.7
+questions:
+  - id: q1
+    question: 'A state `hover` has `parent: default`. `default` animates `title:opacity` with a spring. `hover` adds its own `title:opacity` delta with a linear easing. What does `resolveFrame` use for the title''s opacity on `hover`?'
+    choices:
+      A: 'The child''s linear delta only — the parent''s spring delta for that layer+property is dropped entirely'
+      B: 'Both deltas, additively combined into one curve'
+      C: 'The parent''s spring, because parents take precedence over children'
+      D: 'A field-level merge: the child''s easing with the parent''s from/to values'
+    correct: A
+    explanation: 'Inheritance merges per layer+property group, not per field. Deltas are grouped by a `layer+property` key, and the most-derived state''s group wins outright. Because `hover` declares any `title:opacity` delta, the parent''s `title:opacity` group is dropped wholesale — there is no field-level patching. To keep the parent''s spring and add motion, the child must animate a different property or layer.'
+  - id: q2
+    question: 'You configured `atelier_configure_transition` from `default` to `hover`. Does the reverse transition (`hover` to `default`) now exist?'
+    choices:
+      A: 'Yes — configuring one direction auto-creates the symmetric reverse'
+      B: 'No — transitions are directional; you must configure `hover` to `default` separately'
+      C: 'Yes, but only if both states share a parent'
+      D: 'No — transitions cannot point back to a previously visited state'
+    correct: B
+    explanation: 'Transitions are directional. `default` to `hover` and `hover` to `default` are configured independently, and they usually differ in duration and easing — entrances ease-out, exits ease-in. There is no auto-symmetry.'
+  - id: q3
+    question: 'A layer has a `click` interaction whose action is `go-to-state` targeting `pressed`. No transition is configured from the current state to `pressed`. What happens on click?'
+    choices:
+      A: 'The click is ignored because the transition is missing'
+      B: 'It plays a default 300ms ease-in-out transition'
+      C: 'The runtime cuts directly to `pressed` frame 0 — the action fires, but there is no bridge to animate across'
+      D: 'The schema rejected the document at validate time, so the click never wired up'
+    correct: C
+    explanation: 'Interactions decide when; transitions decide how it looks getting there. A `go-to-state` action runs the configured transition for that state pair. With no transition configured, the action still fires but the runtime snaps to the target state''s frame 0. A click that appears to "do nothing" is almost always a missing transition for that pair, not a missing interaction.'
+  - id: q4
+    question: 'In a spring easing `{ type: spring, stiffness: 100, damping: 10 }`, what most directly determines whether the motion visibly overshoots and bounces?'
+    choices:
+      A: 'Damping relative to stiffness — low damping against high stiffness oscillates; high damping glides in with no overshoot'
+      B: 'The `mass` field alone — higher mass always adds bounce'
+      C: 'The delta''s frame range length'
+      D: 'Whether `position: start` or `position: end` is set'
+    correct: A
+    explanation: 'Bounce is governed by damping relative to stiffness. Low damping against high stiffness oscillates; raising damping at the same stiffness removes overshoot and the spring glides in. Mass adds inertia and lag, not bounce. `position` belongs to step easings, not springs.'
+  - id: q5
+    question: 'You want a layer to follow a defined curved trajectory and control its speed along that curve. Which approach matches Atelier''s model?'
+    choices:
+      A: 'Animate `frame.x` and `frame.y` with matching deltas; the engine infers the curve'
+      B: 'Use an expression on `frame.x` that returns the full 2D path'
+      C: 'Define the path as a preset and apply it to the layer'
+      D: 'Set a `motionPath` on the layer and animate the `motionPath.progress` property; `frame.x`/`frame.y` deltas would be overridden by the path'
+    correct: D
+    explanation: 'A motion path overrides the layer''s `frame.x`/`frame.y` — the path is the trajectory, so frame deltas conflict and are ignored at render time. You control position along the path by animating `motionPath.progress` (0 to 1); that delta''s easing shapes speed along the curve. `autoRotate` can additionally bank the layer into the tangent.'
+  - id: q6
+    question: 'What is the difference between a preset and a template in Atelier?'
+    choices:
+      A: 'A preset is a bundle of deltas applied to an existing layer; a template is a layer subtree instantiated (with variable bindings) into a new document'
+      B: 'A preset is for export; a template is for the studio editor'
+      C: 'A preset creates new layers; a template animates existing ones'
+      D: 'They are interchangeable names for the same reuse mechanism'
+    correct: A
+    explanation: 'Presets = delta bundles; templates = layer subtrees. `atelier_define_preset` then `atelier_apply_preset` stamp motion onto a layer that already exists (expanding `offset` windows relative to `startFrame`). `atelier_instantiate_template` resolves `{{variable}}` placeholders against bindings and creates a new document with the structure. Motion from one mechanism, structure from the other.'

package/university/content/quizzes/Q-atel-501-video-pipeline.yaml

@@ -0,0 +1,66 @@
+id: Q-atel-501-video-pipeline
+title: 'ATEL-501: Video Project Pipeline'
+description: 'Verify the video pipeline — silence trimming with parametric cuts, Whisper transcription and the transcript edit family, caption generation, and the two re-run safety aspects (detected-vs-user-edited, layer-tag-isolation).'
+author: atelier
+created: '2026-05-20'
+updated: '2026-05-20'
+tags:
+  - course
+  - atel-501
+difficulty: intermediate
+passThreshold: 0.7
+questions:
+  - id: q1
+    question: 'In a CutEntry, which two fields are the immutable AI detections, and which two are the user-tunable overrides?'
+    choices:
+      A: 'paddingPre/paddingPost are detected; rawStart/rawEnd are user-tunable'
+      B: 'rawStart/rawEnd are detected (immutable); paddingPre/paddingPost are the user-tunable overrides'
+      C: 'All four are detected; the user edits the layers directly'
+      D: 'All four are user-tunable; nothing is detected'
+    correct: B
+    explanation: 'rawStart and rawEnd are the detected speech boundaries from silencedetect — you do not edit them by hand. paddingPre and paddingPost are your editorial overrides; the effective cut is [rawStart - paddingPre, rawEnd + paddingPost]. Keeping them in separate fields is what lets a re-detect regenerate the raw boundaries while preserving your padding.'
+  - id: q2
+    question: 'You run `atelier trim ./proj --loosen 120`. What happens?'
+    choices:
+      A: 'The 120 is treated as seconds and added to every paddingPre/paddingPost'
+      B: 'Every cut padding increases by 120 milliseconds (0.12s), composing with any existing per-cut overrides; padding still floors at 0'
+      C: 'Only cut #120 is loosened'
+      D: 'The raw boundaries shift outward by 120 frames'
+    correct: B
+    explanation: '`--tighten` and `--loosen` take milliseconds. 120ms is converted to 0.12s and added to the current padding of every cut, so it composes with overrides you already set rather than clobbering them. `--tighten` subtracts; padding is floored at 0 so you cannot drive a cut negative. Per-cut targeting is done with `--cut <index>`, not `--loosen`.'
+  - id: q3
+    question: 'What does `atelier transcript delete ./proj --word 7` actually do?'
+    choices:
+      A: 'Removes word 7 from transcript.json entirely'
+      B: 'Deletes the caption layer at index 7'
+      C: 'Sets hidden=true on word 7 — it stays in the transcript but is skipped when captions are built'
+      D: 'Lowers word 7 confidence below the caption threshold'
+    correct: C
+    explanation: 'delete is a soft, reversible cut. It sets hidden on the word; the word remains in transcript.json (so a future re-transcribe can re-recognize it) but groupIntoPhrases skips hidden words, so it never appears in a caption. To truly remove it you would have to edit it back in — by design, nothing is destroyed.'
+  - id: q4
+    question: 'A re-transcribe must decide whether to carry your correction forward to a fresh detection. Both conditions must hold for the override to be re-attached. Which pair?'
+    choices:
+      A: 'Same word index AND same segment'
+      B: 'Timing within tolerance (0.3s) AND the detected string is unchanged'
+      C: 'Same confidence value AND same language'
+      D: 'Identical text AND identical start time to the millisecond'
+    correct: B
+    explanation: 'mergeTranscriptWithExisting matches a fresh detection to an old entry on timing within 0.3s AND an unchanged detected string. Timing alone is not enough — if Whisper now hears a different word at that timestamp, carrying the old fix forward would graft it onto the wrong word. Requiring the detected string to match guarantees you are editing the same finding. (Cuts use the same idea with a 0.5s tolerance on both raw boundaries.)'
+  - id: q5
+    question: 'You added a word with `atelier transcript add` that Whisper never heard. On the next `atelier transcribe`, what happens to it?'
+    choices:
+      A: 'It is dropped — there is no matching fresh detection'
+      B: 'It is converted into a detected word with confidence 1.0'
+      C: 'It blocks the re-transcribe until you remove it'
+      D: 'It is preserved as a userAdded orphan and re-inserted into the right segment by its timing'
+    correct: D
+    explanation: 'A userAdded word has no fresh detection to match against by definition — Whisper did not produce it. The merge collects these orphans and re-inserts each into the segment that contains its timing. Your manual additions survive a re-transcribe just like your text corrections do.'
+  - id: q6
+    question: 'You run `atelier transcribe`, which rewrites caption layers. You also have hand-authored title layers and silence-trim layers in the same document. Why are your titles safe?'
+    choices:
+      A: 'transcribe only ever appends; it never removes layers'
+      B: 'Layer-tag isolation — the rewrite drops only caption-tagged layers; untagged (user-authored) and silence-trim-tagged layers fall into the preserved set and pass through unchanged'
+      C: 'Title layers are stored in a separate file from caption layers'
+      D: 'The schema locks all non-caption layers during a transcribe run'
+    correct: B
+    explanation: 'rewriteCaptionLayers partitions the document: everything that is NOT caption-tagged is preserved, and only the caption set is dropped and rebuilt. Your untagged titles and the silence-trim-tagged cut layers are untouched. Each pipeline owns exactly one tag namespace and cleans up only after itself — the invariant the test suite asserts directly.'

package/university/content/quizzes/Q-atel-601-recipes.yaml

@@ -0,0 +1,66 @@
+id: Q-atel-601-recipes
+title: 'ATEL-601: Recipes, Overlays & Carousel'
+description: 'Verify the Studio Recipe surface — what a recipe is and how partial recipes fall back, overlay_rules (handle + page_number, anchors, format templates), the CLI/MCP tooling and precedence, and the carousel batch driver.'
+author: atelier
+created: '2026-05-20'
+updated: '2026-05-20'
+tags:
+  - course
+  - atel-601
+difficulty: intermediate
+passThreshold: 0.7
+questions:
+  - id: q1
+    question: 'You author a recipe that sets only `caption_style.color`. What happens to the silence policy and the rest of the caption style when you apply it?'
+    choices:
+      A: 'The apply fails — a recipe must declare every Phase 1 section to be valid'
+      B: 'Omitted fields fall back to the code defaults (e.g. noise -30dB, font_size 84); the merge is shallow per section, so setting one caption field does not wipe the others'
+      C: 'Only the color is applied and all other styling is cleared to empty/zero'
+      D: 'The recipe silently does nothing because it is incomplete'
+    correct: B
+    explanation: 'Every section and every field is optional. Omitted fields fall back to the code defaults baked into renderRecipeWithDefaults, and the merge overlays your section over the defaults section — so setting one caption field leaves the rest of the defaults intact. Run `atelier recipe show <name> --with-defaults` to see the fully-resolved effective recipe.'
+  - id: q2
+    question: 'A recipe includes a `palette` section. You run `atelier recipe validate` on it. What is the result?'
+    choices:
+      A: 'FAIL — palette is not a recognized field'
+      B: 'PASS with no remarks — palette is fully implemented'
+      C: 'PASS, but with a forward-compat warning that palette is a reserved Phase 3 field that Phase 1 ignores'
+      D: 'It strips the palette section and rewrites the file'
+    correct: C
+    explanation: 'palette is one of the six reserved Phase 3 fields. They parse cleanly as opaque (unknown) values so recipes stay forward-compatible, but Phase 1 ignores their contents. validate emits a forward-compat warning (not an error) so you are not caught off-guard that the section is inert. Note overlay_rules was promoted to first-class Phase 1.5 and does NOT warn.'
+  - id: q3
+    question: 'A `page_number` rule has `format: "{current:02d}/{total:02d}"` and you apply the recipe to a single-frame composition via `atelier apply-recipe` (no carousel context). What renders?'
+    choices:
+      A: 'A page-number layer with the literal content `{current:02d}/{total:02d}` (template not substituted)'
+      B: 'The page-number layer is skipped with a warning; the handle is still applied if present'
+      C: 'It defaults to current=1, total=1 and renders `01/01`'
+      D: 'The whole apply-recipe pipeline throws and halts'
+    correct: B
+    explanation: 'applyRecipeToOverlay only emits the page-number layer when both currentIndex and totalCount are in its context. A single-frame apply has no carousel context, so the page-number is skipped with a one-shot warning — `01/01` on a standalone post would be misleading. The handle overlay is unconditional and still gets added. The carousel driver is what threads current/total in.'
+  - id: q4
+    question: 'In the four-corner anchor math, what does the `anchor` value `bottom-right` map to (with margin m on a canvas of width W and height H)?'
+    choices:
+      A: 'frame `{ x: m, y: m }`, anchorPoint `{ x: 0, y: 0 }`'
+      B: 'frame `{ x: W - m, y: H - m }`, anchorPoint `{ x: 1, y: 1 }`'
+      C: 'frame `{ x: W - m, y: m }`, anchorPoint `{ x: 1, y: 0 }`'
+      D: 'frame `{ x: W / 2, y: H / 2 }`, anchorPoint `{ x: 0.5, y: 0.5 }`'
+    correct: B
+    explanation: 'anchorToFrame pairs the frame position with a matching anchorPoint so the corner sticks. bottom-right places frame at `{ W - margin, H - margin }` and sets anchorPoint `{ 1, 1 }`, so the overlay anchors its own bottom-right corner at the canvas bottom-right-minus-margin point and grows inward regardless of text length. The anchor doubles as the rotation/scale pivot.'
+  - id: q5
+    question: 'How does `atelier_recipe_save` (MCP) differ from `atelier recipe new` (CLI), and why does it matter for an editing agent?'
+    choices:
+      A: 'They are identical; save is just the MCP alias for new'
+      B: 'new writes an always-valid scaffold template; save validates BEFORE writing and refuses to write an invalid recipe — so an agent persisting an edited recipe cannot land a malformed file on disk'
+      C: 'save writes without validating; new validates first'
+      D: 'new can only write YAML, save can only write JSON'
+    correct: B
+    explanation: 'recipe new scaffolds a starter template that is valid by construction and does not validate. atelier_recipe_save is how an agent persists an EDITED recipe, so it runs validateRecipe first and refuses to write if invalid, returning the issues instead. That validate-before-write guard is what keeps a malformed agent edit from ever reaching disk.'
+  - id: q6
+    question: 'The carousel driver loops over a sorted folder of N images. For image at loop position n (0-based), what index does it thread into the page-number overlay, and how is the output filename prefixed?'
+    choices:
+      A: 'index = n (0-based); filename prefixed with the raw loop counter, no padding'
+      B: 'index = n + 1 (1-based); filename prefixed with a zero-padded number of width max(2, digits-in-N)'
+      C: 'index is a random uuid; filename uses the original image name unchanged'
+      D: 'index = N - n (counts down); filename prefixed with the total count'
+    correct: B
+    explanation: 'The driver computes `const index = n + 1` (1-based) and passes `{ currentIndex: index, totalCount: total }` so the page-number renders i/N. The output name is zero-padded to `Math.max(2, String(total).length)` digits then carries the original stem, so files sort in deck order. Both the page-number content and the filename prefix derive from the same 1-based index, keeping what the viewer sees and how files sort in agreement.'

package/university/content/quizzes/Q-atel-701-export.yaml

@@ -0,0 +1,66 @@
+id: Q-atel-701-export
+title: 'ATEL-701: Export & Delivery'
+description: Verify the export surface — single-frame raster (export-image / still), vector (export-svg / export-lottie), video (render via FFmpeg, studio via WebCodecs), the two canvas backends, and choosing a format by destination.
+author: atelier
+created: '2026-05-20'
+updated: '2026-05-20'
+tags:
+  - course
+  - atel-701
+difficulty: intermediate
+passThreshold: 0.7
+questions:
+  - id: q1
+    question: 'You run `atelier export-image hero.atelier --out card.png --width 400` on a 1920×1080 document. What dimensions is `card.png`?'
+    choices:
+      A: '400×400 — the missing dimension defaults to match the width'
+      B: '400×225 — the height is derived to preserve the document''s aspect ratio'
+      C: '1920×1080 — --width is ignored without a matching --height'
+      D: '400×1080 — width is overridden, height stays at the document value'
+    correct: B
+    explanation: 'When only one of --width/--height is set, the other is derived to preserve the document aspect ratio. 1920×1080 is 16:9, so a width of 400 gives a height of 225. Override both and the renderer uses both verbatim (which can squash); override one and the aspect ratio carries the other.'
+  - id: q2
+    question: 'A teammate says "PNG export needs cairo, so I have to run brew install before I can export a thumbnail." Are they right?'
+    choices:
+      A: 'Yes — all Atelier rendering goes through node-canvas, which needs cairo/pango'
+      B: 'No — the single-frame raster path uses @napi-rs/canvas, which ships prebuilt binaries and works on a plain npm install'
+      C: 'Only on Linux; macOS bundles cairo with the OS'
+      D: 'Yes, but only the first time — the binary is cached afterward'
+    correct: B
+    explanation: 'The raster path (export-image, still --format png, carousel) uses @napi-rs/canvas — prebuilt platform binaries, no node-gyp, no system libraries. PNG export works the moment npm install finishes. The cairo/pango requirement belongs to the separate node-canvas package used by the video render path, not to single-frame raster.'
+  - id: q3
+    question: 'Why does `atelier export-lottie` have no `--frame` flag when `atelier export-svg` does?'
+    choices:
+      A: 'An oversight — both should accept --frame'
+      B: 'Lottie exports the whole animated document (the entire timeline as keyframes); SVG exports a single resolved frame'
+      C: 'Lottie always exports frame 0 and ignores everything else'
+      D: 'Lottie requires the document to have exactly one frame'
+    correct: B
+    explanation: 'Scope is the difference. export-svg serializes one resolved frame as an SVG snapshot, so it needs a frame. export-lottie walks the whole document''s deltas and writes them as Lottie keyframes — it is the animation, not a still — so a single frame would make no sense.'
+  - id: q4
+    question: 'You run `atelier render intro.atelier -f webm` to get a WebM file. What happens?'
+    choices:
+      A: 'It renders a WebM via FFmpeg'
+      B: 'The CLI render command only supports mp4 and gif; webm is rejected. WebM comes from the studio Export button (WebCodecs)'
+      C: 'It silently falls back to MP4'
+      D: 'It renders WebM but warns that quality may be reduced'
+    correct: B
+    explanation: 'The CLI render path supports mp4 and gif only — its format type is literally "mp4" | "gif". WebM is a studio-only output, produced in the browser via WebCodecs. The two video surfaces have different format reach: CLI via FFmpeg (mp4/gif), studio via WebCodecs (commonly mp4 and webm).'
+  - id: q5
+    question: 'A user can export a PNG from a fresh `npm install` but `atelier render clip.atelier` fails. Which two things does the video path need that the raster path does not?'
+    choices:
+      A: 'A GPU and a license key'
+      B: 'FFmpeg on $PATH and the node-canvas (`canvas`) package with its cairo/pango system libraries'
+      C: 'A newer Node version and more RAM'
+      D: 'An internet connection and a registered asset'
+    correct: B
+    explanation: 'Video from the CLI asks for two things stills never do: FFmpeg on $PATH (render shells out to ffmpeg -version first) and the optional native `canvas` package with cairo/pango/etc. The raster path uses prebuilt @napi-rs/canvas and no encoder. A clean PNG install does not imply a clean MP4 install.'
+  - id: q6
+    question: 'You are handing an animation to a front-end team to drop into a product screen, and they want a small, scalable file they can play in a runtime. Which export fits best?'
+    choices:
+      A: 'A folder of PNG frames'
+      B: 'Lottie JSON via `atelier export-lottie`'
+      C: 'An MP4 via `atelier render`'
+      D: 'An SVG via `atelier export-svg`'
+    correct: B
+    explanation: 'Lottie is the motion-design / runtime handoff format — vector-crisp, tiny, and playable in every major runtime with a few lines of code. SVG is a single still (no motion); MP4 is heavier and not vector; PNG frames are neither animation nor small. Watch export-lottie''s stderr warnings, though — an unsupported feature is reported there, not silently dropped.'

package/university/content/quizzes/Q-atel-801-studio-loop.yaml

@@ -0,0 +1,66 @@
+id: Q-atel-801-studio-loop
+title: 'ATEL-801: Studio & the Live Agent Loop'
+description: 'Verify the live agent loop — `atelier studio` as a local-first editor, the autosave save-race fix, image drop and the layer-type picker, the WebSocket bridge + MCP-over-WS transport, the source-tagged-mutation aspect, and the symbiotic human-agent editing pattern.'
+author: atelier
+created: '2026-05-20'
+updated: '2026-05-20'
+tags:
+  - course
+  - atel-801
+difficulty: advanced
+passThreshold: 0.7
+questions:
+  - id: q1
+    question: 'When you switch files in the studio sidebar while an autosave is still pending in the 800ms debounce window, what stops the outgoing file''s bytes from being written to the newly-loaded file''s path?'
+    choices:
+      A: 'The save is dropped — switching files cancels the pending timer with no write'
+      B: 'The pending timer closure captures the target path AND serialized bytes, and `loadFile` flushes the pending save to its OWN path before switching'
+      C: 'The server rejects any write whose path differs from the currently-open file'
+      D: 'A CRDT merges the two files so neither is corrupted'
+    correct: B
+    explanation: 'This is the #cli-studio autosave-corruption bug. The original timer closed over the *doc* but read the GLOBAL current file at fire time — so editing A then opening B within 800ms wrote A''s bytes to B''s path. The fix is twofold: the timer captures both `pendingSavePath` and `pendingSaveContent` so a fired timer writes the bytes it was given to the file it was given; and `loadFile` calls `flushPendingSave()` at its very top to write any in-flight edit to its own path before switching. The extracted, testable version of this logic is the `SaveCoordinator` class; the inline browser app embeds the same manual debounce pattern.'
+  - id: q2
+    question: 'You drag two images from Finder onto the studio canvas of a freshly-scaffolded `welcome.atelier`. What happens to the welcome scaffold''s placeholder layer?'
+    choices:
+      A: 'Both images append on top of it; the placeholder stays visible underneath'
+      B: 'The FIRST dropped image replaces the layer whose id is `background` in-place; the second is unshifted onto the layers array (behind any overlays)'
+      C: 'Both images replace the placeholder, leaving only the second image'
+      D: 'The drop is rejected until you delete the placeholder manually'
+    correct: B
+    explanation: '`createImageLayerFromFile` is called with `replaceBackground: true` only for the FIRST image in a drop batch (`firstDrop` flips to false after the first). `buildImageLayer` swaps in-place only when `doc.layers[0]?.id === "background"` — a specific id contract, the welcome scaffold''s placeholder. Subsequent images are `unshift`-ed onto the layers array, which puts them at the bottom of the z-stack (the renderer paints index 0 first) so they sit behind any handle / page-number overlays.'
+  - id: q3
+    question: 'A property slider in the studio fires `onInput` continuously during a drag and `onChange` once on release. Why is the commit (undo snapshot) gated to `onChange` rather than `onInput`?'
+    choices:
+      A: '`onInput` is unreliable across browsers, so commits must wait for `onChange`'
+      B: 'So one slider drag produces exactly one undo entry — `onInput` does a cheap live-preview re-render with no snapshot, `onChange` commits and notifies the host'
+      C: 'Because `onInput` cannot read the slider''s value mid-drag'
+      D: 'To throttle autosave to once per second'
+    correct: B
+    explanation: 'The PropertyPanel splits the two events. `onPropertyPreview` (fired on `input`) does a cheap canvas re-render only — no undo snapshot, no host notification — so dragging gives live feedback. `onPropertyChange` (fired on `change`) snapshots undo history and notifies the host (which triggers autosave). The result: one drag = one undo, not one undo per pixel of slider travel. This was the slider-commit-flood bug, hidden while the client lived as an un-typechecked string.'
+  - id: q4
+    question: 'The studio binds the dev server to `127.0.0.1` and the WS upgrade handler re-runs an Origin check on `/bridge` and `/mcp`. Why does `/mcp` tolerate a MISSING Origin header while `/bridge` requires a strict same-origin match?'
+    choices:
+      A: '`/mcp` is unauthenticated by design and accepts any connection'
+      B: 'Non-browser MCP clients (e.g. Claude Desktop) send NO Origin header; rejecting them would make MCP-over-WS unreachable, so `/mcp` allows a missing Origin but still rejects a present-but-foreign one'
+      C: '`/bridge` carries secrets and `/mcp` does not'
+      D: 'The Origin check on `/mcp` is a bug that has not been fixed yet'
+    correct: B
+    explanation: 'WS upgrades bypass the connect middleware (Node fires `upgrade` before connect), so the bridge re-runs the Origin check itself via `isAllowedOrigin` / `isAllowedMcpOrigin`. `/bridge` is a real browser origin, so it demands strict same-origin. `/mcp` serves non-browser MCP clients that send no Origin — `isAllowedMcpOrigin` returns true for `undefined` but still rejects a present-but-foreign Origin (a tab on evil.com still cannot reach `/mcp`). The loopback bind to `127.0.0.1` remains the primary protection (^localhost-only).'
+  - id: q5
+    question: 'An MCP tool call mutates the shared `DocumentStore`, firing `onChange` with a source tag. Under the ~source-tagged-mutation aspect, which sources cause the bridge to broadcast an `llm:mutation` envelope to the browser?'
+    choices:
+      A: 'All three — human, llm, and system — so the browser always stays current'
+      B: 'Only `llm` — `human` (the browser is already current) and `system` (file-read hydration) stay silent to avoid echo loops and false attribution'
+      C: 'Only `human`, since human edits are the ones worth showing'
+      D: 'Only `system`, because that is the default tag'
+    correct: B
+    explanation: '`shouldBroadcastMutation(source)` returns true only for `source === "llm"`. Human edits arrive via `doc:patch` and are written with `source: "human"` so the filter skips them (otherwise the browser would echo its own edit back to itself). File-read hydration writes `source: "system"` — broadcasting it would fire a phantom "agent edited document" toast and a bogus undo entry on a plain file-open. Only genuine agent mutations broadcast, get persisted to disk, and surface a toast with a Cmd-Z undo affordance.'
+  - id: q6
+    question: 'In the symbiotic loop, an agent generates a batch of images by shelling out to an external generator (e.g. a Higgsfield CLI) and brings them into the open document. Which statement correctly describes Atelier''s role?'
+    choices:
+      A: 'Atelier runs the image generator in-process as one of its MCP tools'
+      B: 'Atelier owns no generation — the agent runs the external generator, then `atelier_import_images` ingests the results into the doc as ImageVisual layers + asset entries, which the human watches appear live and keeps or undoes'
+      C: 'The human must manually copy each generated file into the project before Atelier sees it'
+      D: 'Atelier regenerates the images itself to guarantee consistency'
+    correct: B
+    explanation: 'Atelier is an ingest-and-compose tool, not a generator. The agent runs the generation step in chat; `atelier_import_images` brings the results into the open document; the live bridge broadcasts the mutation so the human watches the layers appear and keeps or Cmd-Z-undoes each one; recipes and overlays compose the set; and `atelier carousel` exports it. Generation lives outside Atelier — the human and agent co-edit the same single-store document.'