@a-company/atelier 0.36.0 → 0.38.0

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.'