diff --git a/docs/authoring/animations.md b/docs/authoring/animations.md
new file mode 100644
index 00000000..3658a65f
--- /dev/null
+++ b/docs/authoring/animations.md
@@ -0,0 +1,130 @@
+# Animations
+
+An animation reveals, hides, or emphasizes a single element as you advance through a slide.
+Each one targets an element by its `id`, with no leading `#`:
+
+```python
+from inkflow import Slide, animations
+
+Slide(
+    "title",
+    animations=[
+        animations.FadeIn("headline"),
+        animations.FadeIn("subtitle"),
+        animations.FadeIn("byline"),
+    ],
+)
+```
+
+The three fades take one keypress each.
+*When* a cue fires is decided by its [trigger](steps.md#animation-triggers),
+and this page is about *what* it does.
+
+Elements with no animation declared start **visible**.
+An element targeted by an entrance animation starts **hidden**
+and appears when its step arrives.
+Stepping backward plays each animation in reverse.
+
+## The built-in types
+
+Every type accepts `duration`, `easing`, `delay` and `iterations` as keyword arguments.
+`element` and `trigger` are the two positional slots.
+The [animations reference](../reference/animations.md) has the full signatures.
+
+| Class | Effect | Starts |
+|---|---|---|
+| `FadeIn` | Opacity 0 to 1, with a subtle upward drift | Hidden |
+| `FadeOut` | Opacity 1 to 0 | Visible |
+| `Bounce` | Springs up into place from just below (`distance`) | Hidden |
+| `SlideIn` / `SlideOut` | Travels from or to an edge (`direction`, `distance`) | Hidden / Visible |
+| `ZoomIn` / `ZoomOut` | Scales into or out of place (`scale`) | Hidden / Visible |
+| `Highlight` | Pulses a glow (`color`, `iterations`) without hiding | Visible |
+
+```python
+from inkflow import Direction, animations
+
+animations.SlideIn("box", direction=Direction.LEFT, duration=0.6)
+animations.ZoomIn("logo", scale=0.6)
+animations.Highlight("total", color="#cba6f7", iterations=2)
+```
+
+## Enter, exit, emphasis
+
+Every type has a **kind**, fixed by the semantic base it subclasses:
+
+- **`Enter`** reveals the element and leaves it visible.
+- **`Exit`** hides it and leaves it hidden.
+- **`Emphasis`** fires momentarily without changing visibility.
+
+The kind is what lets one element carry several cues across a slide.
+It can enter, be emphasized, leave, and come back, each on its own step:
+
+```python
+animations = [
+    animations.FadeIn("hero"),  # step 1: enters
+    animations.Highlight("hero"),  # step 2: emphasized
+    animations.SlideOut("hero", direction=Direction.DOWN),  # step 3: exits
+    animations.Bounce("hero"),  # step 4: returns
+]
+```
+
+At any step the element is shown or hidden by its most recent enter or exit,
+while emphasis cues just pulse.
+
+Two enters, or two exits, on one element with no opposing cue between them
+is almost always a mistake.
+inkflow warns about it when it builds the slide.
+
+## Playing a video
+
+`PlayVideo` is a cue with no animation of its own.
+It starts a [`Video`](slides.md#video-playback) on a step
+instead of on load, targeting the video's zone key:
+
+```python
+from inkflow import Slide, Video, animations
+
+Slide(
+    "media-right",
+    zones={"media": Video("assets/demo.mp4")},
+    animations=[animations.PlayVideo("media")],
+)
+```
+
+It takes a trigger like any other cue.
+
+## Writing your own
+
+A custom animation is a dataclass and a `@keyframes` rule.
+No JavaScript is involved.
+
+Subclass one of the semantic bases and name the keyframes `anim-<slug>`,
+where the slug is the kebab-cased class name (`Glow` becomes `anim-glow`):
+
+```python
+from dataclasses import dataclass
+from inkflow import animations
+
+
+@dataclass
+class Glow(animations.Emphasis):
+    intensity: float = 1.0
+```
+
+```css
+/* styles.css, next to deck.py */
+@keyframes anim-glow {
+    50% {
+        filter: drop-shadow(0 0 calc(8px * var(--anim-intensity)) var(--inkflow-accent));
+    }
+}
+```
+
+The step engine reads the keyframes and drives them.
+Any extra field on the class is substituted wherever it appears
+as `var(--anim-<field>)`, so `intensity=2.0` on one cue
+and `intensity=0.5` on another reuse the same rule.
+
+A `styles.css` next to `deck.py` is loaded automatically.
+Your class is usable straight away, in `deck.py`
+and as a [`type=`](steps.md#choosing-the-animation-with-type) in a Markdown reveal.
diff --git a/docs/authoring/inkscape.md b/docs/authoring/inkscape.md
new file mode 100644
index 00000000..c487e38d
--- /dev/null
+++ b/docs/authoring/inkscape.md
@@ -0,0 +1,216 @@
+# Working in Inkscape
+
+inkflow never opens your editor and never rewrites your SVGs while serving.
+That keeps the pipeline simple, but it leaves a few gaps
+between what Inkscape shows you and what the browser will show.
+
+Four commands close them.
+All of them are optional, and all of them are safe to re-run.
+
+| Command | Closes the gap between |
+|---|---|
+| [`inkflow sync`](#previewing-the-full-slide-sync) | a bare slide file and the composed slide |
+| [`inkflow label2id`](#naming-elements-label2id) | Inkscape's labels and SVG ids |
+| [`inkflow colorize`](#theme-colors-in-the-editor-colorize-and-palette) | hardcoded hex fills and theme tokens |
+| [`inkflow verify`](#checking-a-deck-verify) | a deck that looks fine and one that is |
+
+## Previewing the full slide (`sync`)
+
+A slide that inherits a [layout](../design/layouts.md) is mostly empty on its own.
+The background, the frame and the zone positions all live in its ancestors,
+and the [chrome](../design/overlays.md) lives in the overlays.
+Open the file in Inkscape and you see none of it.
+
+`inkflow sync` writes them in as locked layers:
+
+```bash
+inkflow sync
+```
+
+Bottom to top, a synced slide holds its ancestor chain, its own content, then the overlays.
+You can see how much room the footer needs and where the content zone actually sits.
+
+These layers are authoring reference only.
+The pipeline strips them before serving, so they never reach the browser.
+
+To find stale files without rewriting anything:
+
+```bash
+inkflow sync --check
+```
+
+It exits 1 if any file needs updating, which makes it usable in CI.
+
+### Which overlays a file previews
+
+`sync` works on files, but overlays are declared on slides,
+and one layout can back many slides that disagree about their chrome.
+The answer is resolved in three steps:
+
+1. An explicit `inkflow:preview-overlays` attribute on the file wins.
+   Space-separated names, or `""` for none.
+2. Otherwise, what every slide backed by this file agrees on.
+3. Otherwise the deck default.
+
+`sync` prints which rule fired for each file, so the third is never silent:
+
+```
+    Injected  slides/intro.svg (1 overlay layer, slides agree)
+    Injected  layouts/content.svg (1 overlay layer, deck default overlays)
+    Injected  overlays/footer.svg (overlay file)
+```
+
+The third rule is a guess, and it leans toward *showing* chrome.
+The question you are answering in Inkscape is how much room to leave,
+so a preview with chrome a slide will not have costs you some empty space,
+while the reverse causes overlap.
+
+When the guess is wrong for a file, pin it:
+
+```xml
+<svg xmlns="http://www.w3.org/2000/svg"
+     xmlns:inkflow="urn:inkflow"
+     inkflow:parent="content"
+     inkflow:preview-overlays="footer logo"
+     viewBox="0 0 1920 1080">
+```
+
+### Drawing an overlay
+
+An overlay file gets no chrome of its own,
+otherwise `sync` would stamp the deck's footer onto the footer you are drawing.
+
+It can name a **backdrop** instead: something drawn behind it purely as reference,
+so you are positioning against a real slide rather than a checkerboard.
+
+```xml
+<!-- overlays/footer.svg -->
+<svg xmlns="http://www.w3.org/2000/svg"
+     xmlns:inkflow="urn:inkflow"
+     inkflow:preview="content"
+     viewBox="0 0 1920 1080">
+```
+
+`inkflow:preview` takes a layout name, any of the
+[prefixes](../design/layouts.md#finding-a-layout-by-name), or a relative path.
+A path is the useful form for a deck of hand-drawn SVGs with no layouts at all,
+where the honest backdrop is an actual slide:
+
+```xml
+     inkflow:preview="../slides/01-title.svg"
+```
+
+That slide's own layout chain comes along with it.
+
+A backdrop is a preview choice, not a structural claim.
+Picking `content` while the overlay lands on `two-cols` at runtime is fine.
+
+Without the attribute an overlay previews against nothing, and `sync` says so:
+
+```
+    Injected  overlays/footer.svg (overlay file, no backdrop)
+    Injected  overlays/logo.svg (overlay file, backdrop: content)
+```
+
+A file counts as an overlay when it lives in an `overlays/` directory,
+or when the deck references it as one.
+
+### Working on a theme
+
+Theme files have no `deck.py` to consult.
+Use `--no-deck`:
+
+```bash
+inkflow sync --no-deck layouts/*.svg
+```
+
+With no deck there is no slide-to-overlay mapping to derive,
+so overlay previews come from `inkflow:preview-overlays` alone
+and everything else is synced without chrome.
+A theme overlay still gets whatever backdrop it names.
+
+`local:` and `theme:` references need a project context,
+so using them with `--no-deck` is an immediate error.
+
+## Naming elements (`label2id`)
+
+Animations and [morph](morph.md) match elements by `id`.
+Inkscape's Layers & Objects panel edits an element's *label* (`inkscape:label`),
+which is not the same field.
+Setting an `id` means opening the XML editor for every element.
+
+`label2id` promotes every label to the `id`:
+
+```bash
+inkflow label2id slides/*.svg          # rewrite in place
+inkflow label2id -n slides/three.svg   # preview, write nothing
+```
+
+Name things in the panel as you draw, run it once, then wire up `deck.py`.
+
+A label that is already a valid id is used verbatim.
+Anything else is slugified: spaces become hyphens, accents and symbols are dropped.
+Labels are allowed to repeat but ids are not,
+so a clash is reported and skipped rather than overwriting an existing id.
+Elements inside the locked preview layers are left alone.
+
+## Theme colors in the editor (`colorize` and `palette`)
+
+Inkscape cannot read CSS custom properties,
+so an element painted with a [semantic class](../design/themes.md#svg-element-utility-classes)
+appears unstyled in the editor without help.
+
+```bash
+# 1. Install the theme's palette as Inkscape swatches, once per machine
+inkflow palette --deck deck.py > ~/.config/inkscape/palettes/inkflow.gpl
+
+# 2. Convert hardcoded hex fills and strokes into semantic classes
+inkflow colorize slides/*.svg
+
+# 3. Refresh the editor preview
+inkflow sync
+```
+
+Step 3 injects hex fallbacks that Inkscape can render.
+They are stripped at serve time and never reach the browser,
+so the slide still follows the live theme and its light/dark switch.
+
+`inkflow palette` derives the swatches from the active theme,
+so a custom theme exports its own colors.
+
+## Checking a deck (`verify`)
+
+`inkflow verify` checks a deck before you present it,
+printing one line per slide:
+
+```bash
+inkflow verify
+inkflow verify --strict   # exit 1 on warnings too
+```
+
+**Errors** are things that will not render:
+a missing SVG, `.md`, notes file or media file,
+a zone id or animation element id that is not in the composed slide,
+or an overlay that paints an opaque full-canvas rect and would hide the deck.
+
+**Warnings** are things that are probably wrong:
+animation steps that are not contiguous from 1,
+a zone id declared twice after composition,
+or layout layers that are stale and need `inkflow sync`.
+
+Hidden slides (`visible=False`) are skipped unless you pass `--all`.
+
+## Keeping SVGs clean in git
+
+Inkscape stores viewport position, zoom level and window size inside the file,
+so every save produces a diff even when nothing visual changed.
+
+`inkflow setup-git` installs a pre-commit hook that strips that metadata
+from staged SVGs, plus a diff driver so `git diff` and GitHub show only visual changes.
+[`inkflow init`](../getting-started.md#git-integration) does this for new projects.
+
+To clean files committed before the hook was in place:
+
+```bash
+inkflow clean slides/*.svg
+```
diff --git a/docs/authoring/markdown.md b/docs/authoring/markdown.md
new file mode 100644
index 00000000..e3f32d21
--- /dev/null
+++ b/docs/authoring/markdown.md
@@ -0,0 +1,205 @@
+# Markdown content
+
+Pointing `md=` at a Markdown file fills a slide's [zones](slides.md#zones) with its content:
+
+```python
+from inkflow import Deck, Slide
+
+
+def main() -> Deck:
+    return Deck(
+        slides=[
+            Slide("content", md="intro"),
+        ]
+    )
+```
+
+`md` takes the same kind of reference as `Slide.src`.
+A bare name like `"intro"` resolves to `slides/intro.md`,
+or you can write out a full path.
+`Inline("# Title\n\nBody")` passes Markdown directly instead of reading a file.
+
+Here `"content"` happens to be a [built-in layout](../design/layouts.md#built-in-layouts),
+but nothing about `md=` requires one.
+It fills whatever zones the referenced SVG defines.
+
+## Where the content goes
+
+inkflow routes a Markdown file into zones in two ways.
+
+### Automatic
+
+With no markers at all:
+
+- a leading `# H1` goes to `zone-title`
+- an `## H2` immediately after it goes to `zone-subtitle`
+- everything else goes to the [default zone](../design/layouts.md#the-default-zone)
+
+```markdown
+# My slide title
+## Optional subtitle
+
+The body content goes here.
+```
+
+### Explicit markers
+
+`::zone-name::` routes everything after it to that zone,
+until the next marker:
+
+```markdown
+::left::
+
+## Left column
+
+Content for the left side.
+
+::right::
+
+## Right column
+
+Content for the right side.
+```
+
+Explicit markers always win over the automatic routing.
+
+## Alignment inside a zone
+
+Zone markers take optional `key=value` parameters:
+
+```markdown
+::content align=center valign=center padding=60::
+
+Horizontally and vertically centered, with 60 units of padding.
+```
+
+| Parameter | Values | Controls |
+|---|---|---|
+| `align` | `left`, `center`, `right`, `justify` | Horizontal text alignment |
+| `valign` | `top`, `center`, `bottom` | Vertical position of the content block |
+| `padding` | number, in SVG user units | Inner spacing on all sides |
+
+All three are optional and combine freely.
+
+These are the most specific of three layers.
+A marker parameter beats a CSS variable set in the layout SVG,
+which beats the built-in default (`left`, `top`, `0`):
+
+```css
+/* in the layout SVG's <defs><style> — applies to every slide using it */
+#zone-title   { --inkflow-valign: center; }
+#zone-content { --inkflow-padding: 40px; }
+```
+
+From `deck.py`, pass `align`, `valign` and `padding` to
+[`TextBox`](../reference/manifest.md#inkflow.manifest.TextBox) instead.
+
+## Revealing content in steps
+
+`::step::` and `::steps::` split a zone into chunks that appear on successive keypresses.
+They share one timeline with the slide's animations,
+so they are covered together on [Steps](steps.md#markdown-reveals).
+
+## Code blocks
+
+Fenced code blocks are syntax-highlighted automatically with Pygments.
+Write a standard fence with a language tag, and nothing else is needed:
+
+````markdown
+```python
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+```
+````
+
+A `{…}` spec after the language name walks the block line by line as you advance,
+which is a step feature: see [code walkthroughs](steps.md#code-walkthroughs).
+
+## Images
+
+Standard Markdown syntax works:
+
+```markdown
+![A diagram](assets/diagram.png)
+```
+
+**A path resolves relative to the file it is written in.**
+This is what every editor already assumes, so there is no separate convention:
+
+| Reference in | Points at |
+|---|---|
+| `![](assets/diagram.png)` in `slides/intro.md` | `slides/assets/diagram.png` |
+| `<image href="../assets/diagram.png">` in `slides/intro.svg` | `assets/diagram.png` |
+| `Image("assets/diagram.png")` in `deck.py` | `assets/diagram.png` |
+
+A slide SVG keeps rendering in Inkscape
+and a Markdown file keeps previewing in your editor.
+
+The file itself must live inside the project directory,
+or inside the active theme's asset directory.
+Anything outside both cannot be served or exported,
+and is reported as a warning naming the file and the reference.
+To use a directory elsewhere, symlink it in:
+
+```bash
+ln -s ../shared/assets assets
+```
+
+Local files are copied into the output of
+[`inkflow build` and `inkflow export`](../presenting/export.md).
+Remote `https://` and `data:` URIs are left alone.
+
+## Linking to another slide
+
+A link with the `slide:` scheme jumps to the slide with that `id`:
+
+```markdown
+See the [architecture overview](slide:overview) for the full picture.
+```
+
+Clicking it cuts straight to that slide at its first step,
+and the browser's Back button returns you.
+
+A slide's `id` is inferred from its `.md` filename,
+or from the `src` filename when there is no Markdown,
+and you can set it explicitly:
+
+```python
+Slide("diagram", md="architecture", id="overview")
+```
+
+IDs must be unique across the deck.
+Collisions get `-2`, `-3` appended.
+A link to an id that does not exist is left inert.
+
+## Speaker notes
+
+`::notes::` routes everything after it to the speaker notes
+rather than onto the slide:
+
+```markdown
+# My slide title
+
+The visible slide body goes here.
+
+::notes::
+
+These are my private notes. They support **Markdown** and appear
+only in the presenter panel.
+```
+
+You can also set notes from `deck.py`:
+
+```python
+from inkflow import Inline, Slide
+
+Slide("title", notes=Inline("Remember to greet the audience."))
+Slide("content", md="bullets", notes="notes/bullets.md")
+```
+
+A bare `str` is a path, `Inline(...)` is the text itself.
+Either way the content is rendered as Markdown.
+When a slide has both `notes=` and a `::notes::` marker, the two are concatenated,
+`notes=` first.
+
+Notes show in the [presenter panel](../presenting/presenter-panel.md).
diff --git a/docs/authoring/morph.md b/docs/authoring/morph.md
new file mode 100644
index 00000000..cb448c08
--- /dev/null
+++ b/docs/authoring/morph.md
@@ -0,0 +1,86 @@
+# Morph in depth
+
+Morph animates the difference between two slides.
+Elements with the same `id` on both sides travel to their new position, size and colour.
+Elements only in the outgoing slide fade out,
+elements only in the incoming slide fade in.
+
+```python
+from inkflow import Slide, transitions
+
+Slide("architecture-2", transition=transitions.Morph(duration=1.0))
+```
+
+It is the one transition that depends on how you drew the slides,
+which is why it gets its own page.
+For the other seven, see [Transitions](transitions.md).
+
+## The rule
+
+**Matching is by `id`, and nothing else.**
+
+Give the same `id` to the "same" thing on two consecutive slides
+and it becomes one object that moves between them.
+Leave an element un-`id`'d and it crossfades.
+
+Each matched pair is interpolated by its resolved on-screen pose:
+position, size and rotation.
+That resolution is what makes it work inside translated, scaled or rotated groups,
+rather than only at the top level of the document.
+
+## What can morph
+
+Any leaf shape:
+
+| Element | Interpolates |
+|---|---|
+| `<rect>` | position, size, rotation, corner radius (`rx`/`ry`) |
+| `<circle>`, `<ellipse>` | position, size |
+| `<line>` | endpoints |
+| `<path>`, `<polygon>`, `<image>`, … | position, size, rotation of the bounding box |
+| `<text>` | position, rotation and font size, with no stretching or shearing of glyphs |
+
+`fill`, `stroke` and opacity are interpolated on all of them.
+
+## Groups
+
+A `<g>` is never animated as a rigid block.
+It only decides **what to match**.
+
+- `id` on the **group**: the elements inside it morph individually to their new positions.
+- `id` on an **individual element**: only that element morphs.
+
+For a card, meaning a shape with a label on top of it,
+group the two and put the `id` on the `<g>`.
+They travel together while each stays crisp,
+because the text is still typeset rather than scaled.
+
+Unchanged chrome such as backgrounds and footers is left untouched entirely.
+
+## Naming elements for Morph
+
+Morph needs stable ids across two files,
+which is exactly the thing Inkscape's UI makes awkward:
+the Layers & Objects panel edits an element's *label*, not its `id`.
+
+[`inkflow label2id`](inkscape.md#naming-elements-label2id) closes that gap.
+Name a group "headline" in the panel on both slides, run it, and both get `id="headline"`.
+
+## Going backward
+
+Pressing <kbd>←</kbd> replays the morph in reverse automatically.
+There is nothing to declare for it.
+
+## Tips
+
+- Keep ids stable between the two slides.
+  A renamed id turns a morph into a crossfade with no error,
+  which is the usual reason "the morph stopped working".
+- `id` a `<text>` element to move it, leave it un-`id`'d to crossfade it.
+- Build a sequence by copying the slide and editing the copy,
+  so ids survive by default instead of being retyped.
+- A slow morph reads as deliberate.
+  `transitions.Morph(duration=1.5)` across a big repositioning is a reveal in itself.
+- [`inkflow verify`](inkscape.md#checking-a-deck-verify) will not catch an
+  unmatched id, since a crossfade is valid.
+  Step through the pair to check.
diff --git a/docs/authoring/slides.md b/docs/authoring/slides.md
new file mode 100644
index 00000000..62e55450
--- /dev/null
+++ b/docs/authoring/slides.md
@@ -0,0 +1,231 @@
+# Slides
+
+Every slide is one SVG file.
+You draw it in your editor and inkflow serves it as-is.
+
+`Slide` is how `deck.py` refers to that file.
+It also carries everything inkflow adds on top:
+content injected into zones,
+animations on individual elements,
+and the transition into the slide.
+
+## The smallest deck
+
+```python
+from inkflow import Deck, Slide
+
+
+def main() -> Deck:
+    return Deck(
+        slides=[
+            Slide("title"),
+        ]
+    )
+```
+
+A bare name like `"title"` is looked up in `slides/` first, as `slides/title.svg`.
+If it is not there, inkflow searches the layouts
+(see [Layouts](../design/layouts.md#finding-a-layout-by-name)).
+You can also write a full path, or point anywhere else.
+
+That is a complete slide.
+The SVG is loaded, stripped of editor metadata, and served.
+
+## Element IDs
+
+The one convention a slide must follow:
+**anything you want to animate or morph needs an `id`.**
+
+In Inkscape, set it in the XML editor (<kbd>Ctrl+Shift+X</kbd>)
+or in Object Properties (<kbd>Ctrl+Shift+O</kbd>).
+Other editors have an equivalent field.
+
+IDs can be anything without spaces.
+`headline`, `box-a`, `arrow-pipeline` are all fine.
+Elements you never animate do not need one.
+
+!!! tip "Naming many elements at once"
+    Inkscape's Layers & Objects panel edits an element's *label*, not its `id`.
+    Label things there and run [`inkflow label2id`](inkscape.md#naming-elements-label2id)
+    to promote every label to an `id` in one pass.
+
+Nothing else is required.
+The file stays a standard vector graphic that opens anywhere.
+
+## Zones
+
+Two things SVG editors handle badly: formatted text and video.
+Text reflow, bullet lists, tables and code blocks have no real SVG equivalent,
+and video is not something an SVG file can hold at all.
+
+A **zone** is how you leave room for both.
+Give any shape in the SVG an `id` starting with `zone-`,
+and inkflow replaces that shape with your content when it builds the slide:
+
+```xml
+<rect id="zone-content" x="120" y="200" width="1680" height="760"/>
+```
+
+Any SVG can define zones,
+whether it is a one-off slide or a [layout](../design/layouts.md) shared by many slides.
+The full zone rules, including non-rectangular shapes and reserved names,
+live on the [Layouts](../design/layouts.md#zones) page.
+
+### Filling zones from `deck.py`
+
+Pass content into named zones with the `zones` dict.
+Keys are zone names *without* the `zone-` prefix:
+
+```python
+from inkflow import Image, MediaFit, Slide
+
+Slide(
+    "title",
+    zones={
+        "title": "My talk title",
+        "media": Image("assets/headshot.jpg", fit=MediaFit.COVER),
+    },
+)
+```
+
+| Value | Result |
+|---|---|
+| `str` | Rendered as inline Markdown |
+| `TextBox` | Text with explicit `align`, `valign` and `padding` |
+| `Image` / `Video` | Media, fitted and cropped to the zone |
+
+A zone the slide never fills is removed from the output rather than left empty.
+
+### Filling zones from Markdown
+
+When most of a slide is text, writing it in a `.md` file beats filling zones by hand.
+Point `md=` at one and inkflow routes its sections into the slide's zones:
+
+```python
+Slide("content", md="intro")
+```
+
+That is the subject of its own page: [Markdown content](markdown.md).
+
+## Media zones
+
+For an image or a video that should *fill* a zone rather than sit inline in text,
+pass `Image` or `Video` through `zones`:
+
+```python
+from inkflow import Image, MediaFit, Slide
+
+Slide(
+    "media-right",
+    md="feature",
+    zones={"media": Image("assets/screenshot.png", fit=MediaFit.COVER)},
+)
+```
+
+Both share the same placement fields:
+`fit`, `align`, `x`, `y`, and `alt_src` (a different file for the other color mode).
+The [manifest reference](../reference/manifest.md#inkflow.manifest.Image) lists them all.
+
+### Video playback
+
+`Video` adds playback control on top of those:
+
+```python
+from inkflow import Slide, Video
+
+Slide(
+    "media-right",
+    md="demo",
+    zones={"media": Video("assets/demo.mp4", autoplay=True, loop=True)},
+)
+```
+
+`controls`, `autoplay`, `muted`, `loop`, `poster`, and `start`/`end` trim points
+are all documented in the
+[manifest reference](../reference/manifest.md#inkflow.manifest.Video).
+
+**Starting a clip on a step.**
+To play a video partway through a slide instead of on load,
+add a `PlayVideo` cue targeting the video's zone key:
+
+```python
+from inkflow import Slide, Video, animations
+
+Slide(
+    "media-right",
+    zones={"media": Video("assets/demo.mp4")},
+    animations=[animations.PlayVideo("media")],  # plays on the next click
+)
+```
+
+It joins the [step timeline](steps.md) like any other cue.
+Leaving the slide pauses and rewinds the clip,
+and stepping back past the cue resets it to the start.
+
+**Muting.**
+Browsers refuse to autoplay video with sound until the viewer has interacted with the page.
+`Muted.AUTO`, the default, mutes a clip *only* when it autoplays,
+so autoplay always works while a `PlayVideo` cue keeps its audio.
+`Muted.ON` always mutes.
+`Muted.OFF` never does, which means an autoplaying clip may be blocked on a cold load.
+
+!!! note "Zones only"
+    Playback control applies to `Video` passed through `zones`.
+    A video written into Markdown as `![](clip.mp4)` renders as a plain element.
+
+## Slide dimensions
+
+inkflow does not enforce a canvas size.
+Draw at whatever suits the talk: 16:9, 4:3, square, portrait.
+The presenter scales the slide to fill the available screen area.
+
+The built-in layouts are authored at **1920 × 1080**,
+so slides built on them share that coordinate space.
+For a different aspect ratio, draw your own layouts at matching dimensions.
+The pipeline treats them identically.
+
+PDF export reads the page size from the first slide's `viewBox`,
+and [`--size`](../presenting/export.md#slide-dimensions) overrides it.
+
+## Per-slide CSS
+
+`extra_style` injects a `<style>` block into one slide.
+Use it for one-off tweaks.
+For anything systematic, use a [theme](../design/themes.md).
+
+A bare string is read as a **path to a CSS file**,
+so wrap literal CSS in `Inline(...)`:
+
+```python
+from inkflow import Inline, Slide
+
+Slide(
+    "title",
+    extra_style=Inline("#headline { font-size: 72px; fill: var(--inkflow-accent); }"),
+)
+
+Slide("diagram", extra_style="styles/diagram.css")  # a path, relative to deck.py
+```
+
+The same rule holds for `Deck(style=...)`, `Slide(md=...)` and `Slide(notes=...)`:
+a bare `str` is a path, `Inline(...)` is the content itself.
+
+## Hiding a slide
+
+`visible=False` drops a slide from the presentation without deleting it:
+
+```python
+Slide("backup-numbers", md="numbers", visible=False)
+```
+
+Useful for backup slides and for cutting a section down to time.
+[`inkflow verify`](inkscape.md#checking-a-deck-verify) skips hidden slides
+unless you pass `--all`.
+
+## Tips
+
+- Keep IDs short and semantic: `title`, `diagram-step-1`, `callout`.
+- The pipeline strips editor metadata on every load,
+  so there is nothing to clean up by hand.
+- SVGs from any editor work without pre-processing:
+  Figma exports, Affinity Designer, hand-written files.
diff --git a/docs/authoring/steps.md b/docs/authoring/steps.md
new file mode 100644
index 00000000..78661234
--- /dev/null
+++ b/docs/authoring/steps.md
@@ -0,0 +1,244 @@
+# Steps
+
+A **slide** is one SVG file.
+A **step** is one keypress within it.
+
+Steps are what makes a slide build itself:
+a bullet appears, a box fades in, a code walkthrough moves to the next line.
+You never write step numbers by hand.
+You declare *when* each thing should happen and inkflow works out the numbering.
+
+Three things create steps, and they all feed the same counter:
+
+| Source | Written in | Covered below |
+|---|---|---|
+| Markdown reveals | the `.md` file | [Markdown reveals](#markdown-reveals) |
+| Code walkthrough stages | a fenced code block | [Code walkthroughs](#code-walkthroughs) |
+| Animation cues | `animations=[...]` in `deck.py` | [Animation triggers](#animation-triggers) |
+
+Because they share one counter, a slide can mix all three.
+How they interleave is [the last section](#one-timeline).
+
+## Markdown reveals
+
+### One chunk at a time with `::step::`
+
+`::step::` marks a boundary inside a zone.
+Content before the first marker is visible on arrival,
+and each marker reveals the next chunk:
+
+```markdown
+# Build up a concept
+
+First point, visible immediately.
+
+::step::
+
+Second point, revealed on the first keypress.
+
+::step::
+
+Third point, revealed on the second keypress.
+```
+
+### Every item at once with `::steps::`
+
+`::steps::` opens a block where each list item and each paragraph steps on its own,
+so you do not write a marker before every bullet:
+
+```markdown
+# Why inkflow?
+
+Intro text, always visible.
+
+::steps::
+
+- First bullet reveals on keypress 1.
+- Second bullet reveals on keypress 2.
+
+A paragraph inside the block steps too.
+
+::steps end::
+
+Footer text, visible from the start again.
+```
+
+`::steps end::` is optional.
+Without it the block runs to the end of the zone.
+
+A `::step::` inside a `::steps::` block is ignored, since every item already steps.
+
+### Choosing the animation with `type=`
+
+A reveal fades in by default.
+`type=<ClassName>` picks a different one,
+using the same class and parameter names you would write in `deck.py`:
+
+```markdown
+::step type=SlideIn direction=right distance=200::
+
+Slides in from the right.
+
+::step type=Bounce::
+
+Bounces in.
+```
+
+The same grammar works on `::steps::`,
+where the type applies to every item in the block:
+
+```markdown
+::steps type=SlideIn direction=up::
+
+- Each bullet slides up
+- one after another
+::steps end::
+```
+
+`type=` resolves against the [built-in animations](../reference/animations.md)
+and any `Animation` subclass your `deck.py` defines, matched by class name.
+Parameters are coerced to each field's type,
+so `distance=200` becomes a number and `direction=right` becomes a `Direction`.
+
+Values cannot contain spaces,
+so `easing=ease-in-out` works in a marker
+while a `cubic-bezier(...)` curve is a `deck.py`-only thing.
+
+### Changing the step with `trigger=`
+
+A reveal takes its own keypress by default.
+`trigger=` changes that, with the same meanings as the
+[animation triggers](#animation-triggers) below:
+
+```markdown
+::step::
+First point.
+
+::step trigger=with-previous::
+Appears together with the first point.
+
+::step trigger=after-previous::
+Reveals on its own, right after the first point finishes.
+
+::step trigger=3::
+Pinned to step 3.
+```
+
+## Code walkthroughs
+
+A `{…}` spec after the language name highlights different lines on each keypress.
+Each `|`-separated stage is one step:
+
+````markdown
+```python {1|2-3|all}
+def greet(name: str) -> str:
+    message = f"Hello, {name}!"
+    return message
+
+print(greet("world"))
+```
+````
+
+On arrival the first stage is active, with line 1 highlighted and the rest dimmed.
+Each keypress moves to the next stage.
+
+| Stage | Effect |
+|---|---|
+| `1` | That line highlighted, the rest dimmed |
+| `1,3,5` | Several lines highlighted |
+| `2-4` | An inclusive range |
+| `1,3-5` | Lines and ranges combined |
+| `all` or `*` | No dimming, every line at full opacity |
+| `none` | Every line dimmed |
+
+A block with three stages uses two steps beyond the one it arrives on.
+Whatever follows in the slide picks up after the last stage:
+
+````markdown
+# Walk through the code
+
+```python {1|2-3}
+def foo():
+    return 42
+```
+
+::step::
+
+This paragraph appears after the block's second stage.
+````
+
+A code block with no `{…}` spec is still syntax-highlighted.
+It just adds no steps.
+
+## Animation triggers
+
+Every cue in `animations=[...]` carries a `Trigger` that decides its step.
+`trigger` is the second positional argument, after the element id:
+
+```python
+from inkflow import Trigger, animations
+
+animations = [
+    animations.FadeIn("left-panel"),  # step 1
+    animations.FadeIn("right-panel", Trigger.WITH_PREVIOUS),  # step 1, together
+    animations.FadeIn("caption", Trigger.AFTER_PREVIOUS),  # step 1, then on its own
+    animations.FadeIn("footnote"),  # step 2
+]
+```
+
+| Trigger | Meaning |
+|---|---|
+| `Trigger.ON_CLICK` (default) | Takes the next step and waits for a keypress |
+| `Trigger.WITH_PREVIOUS` | Shares the previous cue's step, firing at the same moment |
+| `Trigger.AFTER_PREVIOUS` | Shares the previous cue's step, playing once the previous one finishes |
+| `Trigger.at(n)` | Pins the cue to step `n` |
+
+### Building on arrival
+
+A `WITH_PREVIOUS` or `AFTER_PREVIOUS` cue that comes *first* in the list
+falls to the slide-entry step.
+It is not shown in its resting state and then animated.
+It animates on entry, right after the transition settles,
+so a slide can build itself the moment you arrive with no keypress at all.
+
+### Self-playing sequences
+
+`AFTER_PREVIOUS` turns one keypress into a cascade.
+The cues share a step and play as a single run along one timeline:
+the first fires on the press, and each following cue starts as the one before it ends.
+
+One press forward plays the whole cascade.
+A second press while it is still running snaps it to the end.
+One press back mirrors it, last stage out first.
+
+## One timeline
+
+When a slide has both Markdown reveals and an `animations=[...]` list,
+they number in one continuous sequence.
+**Markdown reveals come first, in reading order, then the animation list continues.**
+
+With two reveals and two animations, the reveals take steps 1 and 2
+and the animations take 3 and 4:
+
+```python
+from inkflow import Trigger, animations
+
+Slide(
+    "mixed",
+    md="bullets",  # two ::steps:: bullets → steps 1, 2
+    animations=[
+        animations.FadeIn("badge-a"),  # step 3
+        animations.FadeIn("badge-b", Trigger.at(5)),  # pinned to step 5
+    ],
+)
+```
+
+`Trigger.WITH_PREVIOUS` works across that boundary too.
+A first-in-list animation carrying it fires together with the last bullet.
+
+To land an animation on a specific reveal's step, pin it with `Trigger.at(n)`.
+
+!!! tip "Checking the numbering"
+    [`inkflow verify`](inkscape.md#checking-a-deck-verify) warns when a slide's steps
+    are not contiguous from 1, which usually means a `Trigger.at(n)` has drifted
+    after content was added or removed above it.
diff --git a/docs/guides/transitions.md b/docs/authoring/transitions.md
similarity index 53%
rename from docs/guides/transitions.md
rename to docs/authoring/transitions.md
index ba2ba3d8..87d901ea 100644
--- a/docs/guides/transitions.md
+++ b/docs/authoring/transitions.md
@@ -2,6 +2,17 @@
 
 A transition controls how a slide enters from the previous one.
 
+| Transition | Effect | Own parameters |
+|---|---|---|
+| [`Cut`](#cut) | Instant switch | |
+| [`Crossfade`](#crossfade) | Dissolves one slide into the other | |
+| [`Push`](#push) | Both slides travel together | `direction` |
+| [`Cover`](#cover) | The new slide slides over the old one | `direction` |
+| [`Wipe`](#wipe) | The new slide is revealed from an edge | `direction` |
+| [`Zoom`](#zoom) | Scales one slide out and the other in | `amount` |
+| [`Fade`](#fade) | Fades through a solid colour | `color` |
+| [`Morph`](#morph) | Matching elements travel to their new positions | |
+
 ## Setting transitions
 
 Set a default transition for the whole deck on the `Deck` object,
@@ -29,7 +40,7 @@ All transition types share two parameters:
 | Parameter | Default | Description |
 |---|---|---|
 | `duration` | `0.5` | Duration in seconds (`Cut` defaults to `0.0`) |
-| `easing` | `None` | Any CSS easing string. `None` keeps the handler's built-in default |
+| `easing` | `Easing.EASE` | An [`Easing`](../reference/enums.md) preset, or a custom curve via `Easing.cubic_bezier(...)`. `Push`, `Cover`, `Zoom`, and `Wipe` default to `Easing.EASE_IN_OUT` |
 
 ## Cut
 
@@ -88,9 +99,11 @@ The incoming slide scales into place while the outgoing slide keeps zooming past
 `amount` controls how far they scale past their normal size.
 
 ```python
+from inkflow import Easing
+
 transitions.Zoom()
 transitions.Zoom(amount=0.4)  # gentler
-transitions.Zoom(amount=0.6, duration=0.6, easing="ease-in-out")
+transitions.Zoom(amount=0.6, duration=0.6, easing=Easing.EASE_IN_OUT)
 ```
 
 | Parameter | Default | Description |
@@ -129,76 +142,55 @@ transitions.Wipe(direction=Direction.UP, duration=0.7)
 
 ## Morph
 
-Smoothly interpolates matching elements between two slides.
-Elements with the same ID in the outgoing and incoming slides move and reshape to their new positions.
-Elements that exist only in the outgoing slide fade out.
-Elements only in the incoming slide fade in.
+Interpolates matching elements between the two slides.
+Anything with the same `id` on both sides travels to its new position, size and colour,
+and anything unmatched crossfades.
 
 ```python
 transitions.Morph()  # default 0.5s
-transitions.Morph(duration=1.0)  # slower morph
+transitions.Morph(duration=1.0)  # slower
 ```
 
-### What morphs
-
-Each element is matched to its counterpart in the other slide by `id` and
-interpolated by its resolved on-screen pose — position, size, and rotation — so it
-animates correctly even inside translated, scaled, or rotated groups.
-
-Any leaf shape can morph:
-
-| Element | Morphs |
-|---|---|
-| `<rect>` | position, size, rotation, corner radius (`rx`/`ry`) |
-| `<circle>`, `<ellipse>` | position, size |
-| `<line>` | endpoints |
-| `<path>`, `<polygon>`, `<image>`, … | position, size, rotation (bounding box) |
-| `<text>` | position, rotation, and font size — glyphs never stretch or shear |
-
-Colors (`fill`, `stroke`) and opacities are interpolated too.
+Morph is the one transition that depends on how the slides themselves are drawn,
+so it has a page of its own: **[Morph in depth](morph.md)**.
 
-### Groups
+## Writing your own
 
-A `<g>` is never animated as a rigid block — it only decides *what to match*.
-Give the **group** an `id` and the elements inside it morph individually to their
-new positions. Give an **individual element** an `id` to morph just that element.
+A custom transition is a Python dataclass plus a render function in JavaScript.
 
-Content with no matched `id` crossfades: elements only in the outgoing slide fade out,
-elements only in the incoming slide fade in. Unchanged chrome (backgrounds, footers) is left untouched.
+Subclass `Transition` in `deck.py`.
+Every field you add is serialized and handed to the render function,
+and the kebab-cased class name becomes the handler key (`MyWarp` becomes `my-warp`):
 
-### Backward navigation
-
-When navigating backward (pressing `←`), Morph plays in reverse automatically.
-
-### Naming elements from Inkscape
+```python
+from dataclasses import dataclass
+from inkflow import transitions
 
-Morph matches elements by `id`,
-but Inkscape's Layers & Objects panel only ever edits an element's *label*
-(`inkscape:label`), not its `id`.
 
-`inkflow label2id` bridges the two:
-name a group "headline" in the panel on both slides,
-run `inkflow label2id slides/*.svg`,
-and each element's label becomes its `id`.
-A label that is already a valid id is used verbatim,
-anything else is slugified (spaces to `-`, accents and symbols dropped).
-Labels do not have to be unique but ids do,
-so a clash is reported and skipped rather than overwriting an existing id.
+@dataclass
+class MyWarp(transitions.Transition):
+    twist: float = 1.0
+```
 
-```bash
-inkflow label2id slides/*.svg          # rewrite ids in place
-inkflow label2id -n slides/three.svg   # preview the changes, write nothing
+Register the matching handler from a `scripts.js` next to `deck.py`,
+which is loaded automatically:
+
+```javascript
+// scripts.js
+window.inkflow.registerProgressTransition("my-warp", (ctx, progress, params) => {
+    // progress runs 0 (old slide shown) to 1 (new slide shown), already eased.
+    // ctx.oldLayer sits on top of ctx.newLayer.
+    ctx.oldLayer.style.opacity = String(1 - progress);
+    ctx.oldLayer.style.transform = `rotate(${progress * params.twist * 20}deg)`;
+});
 ```
 
-Elements inside the locked preview layers that `inkflow sync` injects are left
-untouched. Run this before wiring up `deck.py` animations too, not just for Morph.
+The render function is called once per frame with the eased progress,
+so it only has to paint a single still frame.
+Reversing, interrupting and settling are handled for you.
 
-### Tips for Morph slides
+Use it like any built-in:
 
-- Keep element IDs stable between slides — the morph links elements by matching `id`.
-- `id` a `<text>` element to morph it (it moves, rotates, and changes size); leave it
-  un-`id`'d to crossfade it instead.
-- For a card-like object (a shape with a label), group them and put the `id` on the
-  `<g>` so they travel together while each stays crisp.
-- For dramatic reveal effects, try a slow `transitions.Morph(duration=1.5)` combined with
-  repositioned elements.
+```python
+Slide("diagram", transition=MyWarp(twist=2.0, duration=0.8))
+```
diff --git a/docs/built-in-theme/index.md b/docs/built-in-theme/index.md
index 46642797..568a70ef 100644
--- a/docs/built-in-theme/index.md
+++ b/docs/built-in-theme/index.md
@@ -11,27 +11,11 @@ light/dark mode in the presenter to see both palette variants.
 
 [Launch showcase](./presentation/index.html){ .md-button .md-button--primary target="_blank" }
 
-## Built-in layouts
-
-Each layout is a bare name you can pass to `Slide(...)`. They resolve through the
-active theme first, then fall back to these built-ins.
-
-| Layout | Purpose |
-|---|---|
-| `cover` | Title slide — large title, subtitle, and an optional full-bleed `media` zone |
-| `section` | Section divider — title and subtitle |
-| `title` | Bare title, no content zone — shared ancestor of `content` and `two-cols` |
-| `content` | Standard content slide — title and a content zone for bullets/prose |
-| `center` | Single centered block — ideal for one statement or image |
-| `two-cols` | Two independent content columns beneath a shared title |
-| `fact` | A single large fact with a supporting caption |
-| `quote` | A blockquote with an attribution line |
-| `media-left` | Image on the left, text on the right |
-| `media-right` | Image on the right, text on the left |
-| `end` | Closing slide — thank-you / wrap-up |
-
-In addition, `base` is the no-parent base layout (background + frame) that the others
-extend, and `numbered` is a variant that adds slide-number zones.
+## The layouts
+
+The theme ships eleven layouts plus two building blocks,
+listed with their zones in [Layouts](../design/layouts.md#built-in-layouts).
+The showcase above walks through each one.
 
 ## Using a built-in layout
 
@@ -51,9 +35,8 @@ def main() -> Deck:
     )
 ```
 
-Markdown zone markers (e.g. `::left::`, `::right::`, `::quote::`) target the named
-zones in each layout. See the showcase deck's slide files for the exact markers each
-layout expects.
+[Markdown zone markers](../authoring/markdown.md#explicit-markers)
+such as `::left::` and `::quote::` target the named zones in each layout.
 
-For styling the theme — palette variables, semantic SVG classes, and authoring colors
-in Inkscape — see the [Themes guide](../guides/themes.md).
+For restyling the theme, its palette variables and its semantic SVG classes,
+see [Themes](../design/themes.md).
diff --git a/docs/concepts.md b/docs/concepts.md
index 1c5e7e8e..89ced6b4 100644
--- a/docs/concepts.md
+++ b/docs/concepts.md
@@ -7,10 +7,8 @@ Reading it first makes everything else click faster.
 
 **Your drawings:** SVG files, one per slide.
 Open them in any editor, draw freely, save.
-Plain `Slide` files carry no Inkflow-specific markup at all.
-The one exception is slides that use the layout system: they carry an `inkflow:parent` attribute on the SVG root
-that tells Inkflow which layout SVG to inherit from.
-This is covered in the layout system section below.
+A slide carries no inkflow-specific markup beyond an `id` on anything you animate.
+Slides built on a [layout](#the-layout-system) add one attribute, `inkflow:parent`.
 
 **Your deck:** `deck.py`, a plain Python file.
 It says which slides to show, in what order, and which elements to animate.
@@ -54,10 +52,10 @@ The above example is a single slide with two animated elements: `headline` and `
 
 A **slide** maps to one SVG file.
 A **step** is a keypress within a slide.
-Each animation declares a `Trigger` (the default `ON_CLICK` takes the next
-step, `WITH_PREVIOUS` shares the previous one, `AFTER_PREVIOUS` shares it but
-plays itself once the previous cue finishes), and Inkflow works out the step
-numbers from the triggers and order.
+You never number steps by hand.
+Each animation and each Markdown reveal declares *when* it should fire,
+and inkflow works out the numbering from those declarations and their order.
+See [Steps](authoring/steps.md).
 
 ## Zones and Markdown
 
@@ -91,7 +89,7 @@ Slide("content", md="intro")
 ```
 
 This uses `slides/intro.md` to fill the zones defined in a slide or layout (see below) called `content.svg`.
-See the [guide](guides/slides.md) for details on what these Markdown files can contain and how they map to zones.
+See [Markdown content](authoring/markdown.md) for what these files can contain and how they map to zones.
 
 ## The layout system
 
@@ -109,7 +107,7 @@ theme/main.svg          ← background, brand elements (chain ends here)
 
 Inkflow resolves the full chain at build time and composites the layers in memory.
 The SVG files on disk are not modified.
-[`inkflow sync`](reference/cli.md#inkflow-sync) can optionally write locked preview layers into each SVG
+[`inkflow sync`](authoring/inkscape.md#previewing-the-full-slide-sync) can optionally write locked preview layers into each SVG
 so you can see the inherited background while editing in Inkscape.
 
 ## Overlays
@@ -129,7 +127,7 @@ Deck(
 ```
 
 Overlays can inherit from other overlays.
-See the [layout system guide](guides/layout-system.md#overlays) for the full picture.
+See [Overlays](design/overlays.md) for the full picture.
 
 ## Themes
 
@@ -159,19 +157,15 @@ injecting zone content, and annotating animated elements.
 The result is served to the browser.
 Nothing on disk is touched.
 
-## No SVG editor at runtime
+## The presenter
 
-The pipeline reads plain SVG with lxml.
-No editor subprocess, no GUI window, no spawned processes.
-Any SVG editor that exports well-formed SVG works as an authoring environment.
+The deck runs in the browser.
+Navigation and animation happen client-side,
+and a WebSocket pushes changed slides in place as you save,
+without a full reload and without losing your place.
 
-## The presenter
+Any number of windows can be open at once and they
+[stay in sync](presenting/sync.md),
+which is how a second screen with speaker notes works.
 
-The browser presenter is a single HTML file with vanilla JavaScript.
-No framework is used.
-Slides are embedded as JSON.
-Navigation and step animation are handled client-side.
-The WebSocket connection listens for file changes and swaps slide content in place
-(preserving the current slide index) without a full page reload.
-Launching multiple browser windows connects them all to the same WebSocket and stay in sync by default.
-Open a second window and press `p` to see the presenter view with notes and upcoming slides.
+See [Presenting a deck](presenting/index.md).
diff --git a/docs/guides/fonts.md b/docs/design/fonts.md
similarity index 100%
rename from docs/guides/fonts.md
rename to docs/design/fonts.md
diff --git a/docs/design/layouts.md b/docs/design/layouts.md
new file mode 100644
index 00000000..f808fde6
--- /dev/null
+++ b/docs/design/layouts.md
@@ -0,0 +1,290 @@
+# Layouts
+
+A layout is a reusable slide template, the same idea as a master slide.
+It is an ordinary SVG holding the parts every slide of that kind shares,
+with named **zones** left empty for the content.
+
+Layouts are optional.
+A deck of hand-drawn SVGs never needs one.
+They earn their place the moment two slides should look identical
+apart from their text.
+
+## Zones
+
+A zone is any shape whose `id` starts with `zone-`.
+A `<rect>` is the usual choice:
+
+```xml
+<rect id="zone-content" x="120" y="200" width="1680" height="760"/>
+```
+
+When inkflow builds the slide it replaces that shape with a `<foreignObject>`
+of the same bounding box, holding the rendered content.
+A zone that the slide never fills is removed rather than left showing.
+
+!!! tip
+    Inkscape's Layers & Objects panel edits an element's *label*, not its `id`.
+    Label the rect `zone-content` there and run
+    [`inkflow label2id`](../authoring/inkscape.md#naming-elements-label2id).
+
+### Non-rectangular zones
+
+`<polygon>`, `<ellipse>`, `<circle>` and `<path>` work too.
+
+For **media** zones, inkflow generates a `<clipPath>` from the exact shape,
+so an image or video is cropped to the outline.
+For **text** zones only the bounding box is used,
+since text reflows in a rectangle whatever the shape.
+
+### Reserved names
+
+| ID | Filled with |
+|---|---|
+| `zone-title` | The leading `# H1` from Markdown, when the zone exists |
+| `zone-subtitle` | The `## H2` right after it, when the zone exists |
+| `zone-slide-number` | The current slide number. Must be a `<text>` element |
+| `zone-slide-total` | The total slide count. Must be a `<text>` element |
+
+Every other `zone-*` name is yours.
+Pick names your Markdown will use: `zone-content`, `zone-left`, `zone-media`.
+
+### The default zone
+
+The default zone takes all the Markdown that nothing else claimed,
+meaning everything outside an explicit `::zone::` marker
+and outside the title and subtitle extraction.
+
+A layout containing `zone-content` uses it as the default automatically.
+For anything else, declare it:
+
+```xml
+<svg xmlns="http://www.w3.org/2000/svg"
+     xmlns:inkflow="urn:inkflow"
+     inkflow:parent="builtin:content"
+     inkflow:default-zone="quote"
+     viewBox="0 0 1920 1080" width="1920" height="1080">
+  <rect id="zone-quote" x="120" y="200" width="1680" height="720"/>
+</svg>
+```
+
+A layout with no text zone at all, like `cover` or `section`, needs no default.
+
+If a slide has unrouted Markdown and its layout declares no default zone,
+the build fails with a red overlay in the browser naming the slide.
+
+### When the title zone is missing
+
+If a layout has no `zone-title` or `zone-subtitle`,
+a leading `# H1` or `## H2` is not discarded.
+It falls through into the default zone as rendered HTML.
+
+```markdown
+# This is a Quote
+And this is the attribution line.
+```
+
+On the `quote` layout, which has no `zone-title`, both lines land in `zone-quote`.
+On `content`, which has one, the `# H1` routes to `zone-title` as usual.
+
+To bypass the question entirely, mark the zones explicitly:
+
+```markdown
+::quote::
+This text always goes to zone-quote.
+::attribution::
+— Author name
+```
+
+## Inheritance
+
+A layout points at its parent with `inkflow:parent` on the root `<svg>`:
+
+```xml
+<svg xmlns="http://www.w3.org/2000/svg"
+     xmlns:inkflow="urn:inkflow"
+     inkflow:parent="theme:main"
+     viewBox="0 0 1920 1080" width="1920" height="1080">
+  <!-- zones specific to this layout -->
+</svg>
+```
+
+Chains can be any depth:
+
+```
+slides/bullets.svg
+  └─ inkflow:parent="content"         → layouts/content.svg
+       └─ inkflow:parent="theme:main" → theme/main.svg  (no parent, chain ends)
+```
+
+inkflow resolves the whole chain in memory and composites the layers
+from root to leaf, behind the slide's own content.
+**The files on disk are never modified.**
+
+To see the composed result while drawing,
+run [`inkflow sync`](../authoring/inkscape.md#previewing-the-full-slide-sync).
+
+## Finding a layout by name
+
+A bare name is searched in three places, first match winning:
+
+1. the project's `layouts/` directory
+2. the active theme's `layouts/` directory
+3. the built-in layouts
+
+So a project `layouts/content.svg` shadows the built-in `content`
+without any configuration.
+
+A prefix skips the search:
+
+| Written as | Resolves to |
+|---|---|
+| `"content"` | The three-level search |
+| `"local:content"` | `{project}/layouts/content.svg` |
+| `"theme:content"` | `{theme}/layouts/content.svg` |
+| `"builtin:content"` | The built-in layout |
+| `"./relative/path.svg"` | Relative to the current SVG file |
+
+To see what is available in your project right now:
+
+```bash
+inkflow layouts
+```
+
+It prints every layout and overlay with its parent chain and its zones.
+
+## Built-in layouts
+
+The built-in theme ships eleven layouts, usable by bare name in any deck:
+
+| Name | Zones | For |
+|---|---|---|
+| `cover` | title, subtitle, media | The opening slide |
+| `section` | title, subtitle | A section divider |
+| `title` | title | A bare title, no content zone |
+| `content` | title, content | The standard text slide |
+| `center` | content | A single centered block |
+| `two-cols` | title, left, right | Two-column comparison |
+| `fact` | fact, caption | One big number or claim |
+| `quote` | quote, attribution | A pull quote |
+| `media-left` | title, content, media | Text with an image or video on the left |
+| `media-right` | title, content, media | The same, media on the right |
+| `end` | title, subtitle | The closing slide |
+
+Two more exist as building blocks: `base` is the parentless background,
+and `numbered` adds the slide-number zones.
+
+```python
+Slide("cover", md="title")
+Slide("two-cols", md="compare")
+```
+
+The [built-in theme page](../built-in-theme/index.md) has a live showcase of all of them.
+
+They take your theme's palette automatically,
+because they paint through the token classes rather than hardcoded colours.
+See [Themes](themes.md#built-in-layouts-recolored).
+
+## Creating a slide from a layout
+
+`inkflow add` writes a new SVG already wired to a parent:
+
+```bash
+inkflow add slides/new.svg -p content
+```
+
+It creates the file with `inkflow:parent="content"`
+and runs `inkflow sync` so the preview layers are there when you open it.
+Omit `-p` for a blank slide with no parent.
+
+Then add it to `deck.py`:
+
+```python
+Slide("slides/new.svg")
+```
+
+To rewire or detach an existing slide:
+
+```bash
+inkflow parent set slides/new.svg builtin:content
+inkflow parent strip slides/new.svg
+```
+
+## Writing your own
+
+1. Create `layouts/my-layout.svg`.
+2. Point `inkflow:parent` at a base layout, or leave it off for a standalone one.
+3. Add `zone-*` shapes where content belongs.
+4. Set `inkflow:default-zone` unless the layout has a `zone-content`.
+5. Reference it by name: `Slide("my-layout", md="custom")`.
+
+A narrower content column:
+
+```xml
+<svg xmlns="http://www.w3.org/2000/svg"
+     xmlns:inkflow="urn:inkflow"
+     inkflow:parent="builtin:content"
+     inkflow:default-zone="content"
+     viewBox="0 0 1920 1080" width="1920" height="1080">
+
+  <rect id="zone-content" x="300" y="200" width="1320" height="720"/>
+</svg>
+```
+
+Two columns, where unmarked Markdown flows into the left one:
+
+```xml
+<svg xmlns="http://www.w3.org/2000/svg"
+     xmlns:inkflow="urn:inkflow"
+     inkflow:parent="builtin:content"
+     inkflow:default-zone="left"
+     viewBox="0 0 1920 1080" width="1920" height="1080">
+
+  <rect id="zone-left"  x="80"   y="200" width="840" height="720"/>
+  <rect id="zone-right" x="1000" y="200" width="840" height="720"/>
+</svg>
+```
+
+```markdown
+# Two Columns
+
+Left column content here.
+
+::right::
+Right column content here.
+```
+
+Set per-layout defaults for alignment with CSS variables in the layout's own `<defs>`:
+
+```css
+#zone-title   { --inkflow-valign: center; }
+#zone-content { --inkflow-padding: 40px; }
+```
+
+## Hiding an element on one slide
+
+To drop an inherited element from a single slide, style it away.
+The CSS is already scoped to that slide:
+
+```python
+Slide("content", extra_style=Inline("#logo { display: none }"))
+```
+
+## Layouts within a theme
+
+A theme's layouts live outside any project and have no `deck.py`,
+so `local:` and `theme:` are unavailable there.
+Use `builtin:` or a relative path:
+
+```xml
+<!-- theme/layouts/content.svg -->
+<svg xmlns="http://www.w3.org/2000/svg"
+     xmlns:inkflow="urn:inkflow"
+     inkflow:parent="builtin:content"
+     viewBox="0 0 1920 1080" width="1920" height="1080">
+  ...
+</svg>
+```
+
+See [Themes](themes.md#shipping-a-theme-as-a-package) for packaging,
+and [`sync --no-deck`](../authoring/inkscape.md#working-on-a-theme)
+for previewing them while you work.
diff --git a/docs/design/overlays.md b/docs/design/overlays.md
new file mode 100644
index 00000000..25799384
--- /dev/null
+++ b/docs/design/overlays.md
@@ -0,0 +1,110 @@
+# Overlays
+
+[Inheritance](layouts.md#inheritance) answers "what am I built on"
+and composites *behind* a slide.
+
+A logo, a footer, a conference badge ask a different question:
+"what goes on top of every slide, whatever it is built on".
+That is an **overlay**, and it is the second composition axis.
+
+Keeping them separate is what lets chrome reach every layout
+without a duplicate layout for each combination.
+
+## Using one
+
+An overlay is an SVG at slide dimensions, drawn above the finished slide.
+Declare them on the deck:
+
+```python
+from inkflow import Deck, Overlay, Slide
+
+Deck(
+    overlays=[Overlay("footer"), Overlay("logo")],
+    slides=[
+        Slide("title.svg", overlays=[]),  # a bare title, no chrome
+        Slide("content", md="intro"),  # inherits the deck's two
+    ],
+)
+```
+
+List order is paint order.
+
+Resolution runs `Slide.overlays` → `Deck.overlays` → `Theme.overlays`.
+Each level **overrides** rather than merges:
+`None` inherits the level above, and `[]` means no chrome at all.
+That is the same rule as `transition` and `font_size`.
+
+## What overlays can do
+
+Overlays are composited before slide numbering and content injection,
+so they behave like any other part of the slide:
+
+- A `zone-slide-number` inside a footer is filled like any other zone.
+- A zone the overlay declares can be filled from `zones={...}` on a slide,
+  and is pruned on slides that leave it empty.
+- Animations can target elements inside an overlay,
+  so chrome can be revealed on a step.
+
+They also travel with the slide during a transition.
+A footer slides along with a `Push` and dips through a `Crossfade`.
+
+## Finding an overlay by name
+
+Overlays live in `overlays/` and use the same three-level search
+and prefix grammar as [layouts](layouts.md#finding-a-layout-by-name),
+against `overlays/` instead of `layouts/`:
+
+| Written as | Resolves to |
+|---|---|
+| `"footer"` | The three-level search |
+| `"local:footer"` | `{project}/overlays/footer.svg` |
+| `"theme:footer"` | `{theme}/overlays/footer.svg` |
+| `"builtin:footer"` | A built-in overlay |
+| `"./chrome/footer.svg"` | Relative to the project directory |
+
+Layouts and overlays are separate namespaces,
+so a bare name resolves to one or the other and never both.
+
+## Overlays can inherit
+
+`inkflow:parent` on an overlay means "drawn behind me, within this overlay".
+The overlay as a whole still lands on top of the slide,
+so the two axes stay independent:
+
+```
+overlays/brand.svg     the rule line and the mark
+overlays/chrome.svg    inkflow:parent="brand", adds the event name
+```
+
+This is how a theme ships `theme:brand` that a project extends
+without copying it.
+
+A bare name in an overlay's `inkflow:parent` resolves in the overlay namespace,
+so chrome can only ever inherit chrome.
+
+!!! warning "Do not point an overlay's parent at a layout"
+    Layouts paint a full-bleed background.
+    On top of a slide, that hides the entire deck.
+
+    A bare name cannot reach a layout from an overlay,
+    so this needs an explicit path to happen at all.
+    [`inkflow verify`](../authoring/inkscape.md#checking-a-deck-verify)
+    reports it as an error and names the file.
+
+## Shipping chrome with a theme
+
+Set `overlays` on the theme class and every deck using it gets the chrome:
+
+```python
+class Corporate(Theme):
+    overlays = [Overlay("theme:brand")]
+```
+
+A deck opts out with `Deck(overlays=[])`, a slide with `Slide(overlays=[])`.
+
+## Drawing one
+
+An overlay file previews differently from a slide,
+since it has no idea what it will land on.
+See [drawing an overlay](../authoring/inkscape.md#drawing-an-overlay)
+for the backdrop attribute that makes it workable in Inkscape.
diff --git a/docs/guides/themes.md b/docs/design/themes.md
similarity index 81%
rename from docs/guides/themes.md
rename to docs/design/themes.md
index e24a5d96..ae6379ae 100644
--- a/docs/guides/themes.md
+++ b/docs/design/themes.md
@@ -104,7 +104,7 @@ class Corporate(Theme):
     overlays = [Overlay("theme:brand")]
 ```
 
-See the [layout system guide](layout-system.md#overlays) for how overlays compose.
+See [Overlays](overlays.md) for how they compose.
 
 `mode` sets the `data-theme` attribute the presenter reads:
 `ColorMode.DARK` leaves it empty (the `:root` palette applies) and
@@ -162,39 +162,29 @@ Each token has a fill and a stroke variant, e.g.:
 <rect class="inkflow-fill-accent inkflow-stroke-surface" .../>
 ```
 
-Available for every palette token: `inkflow-fill-<token>` and
+Available for these tokens: `inkflow-fill-<token>` and
 `inkflow-stroke-<token>` (`bg`, `surface`, `border`, `text`, `text-muted`, `accent`,
 `accent-fg`, `code-bg`, `code-text`, and the named colors `red` … `grey`).
 The presenter's light/dark switch updates all of them automatically.
 
-## Authoring theme colors in Inkscape
-
-Inkscape can't read CSS custom properties, so semantically-classed elements appear
-unstyled in the editor without help.
-Three commands bridge the gap:
-
-```bash
-# 1. Install the palette as Inkscape swatches (once per machine):
-inkflow palette --deck deck.py > ~/.config/inkscape/palettes/inkflow.gpl
-
-# 2. Convert hardcoded hex fills/strokes to semantic classes:
-inkflow colorize slides/*.svg
-
-# 3. Refresh the editor preview (injects hex fallbacks Inkscape can render;
-#    stripped at serve time, never shipped to the browser):
-inkflow sync
-```
-
-`inkflow palette` derives the swatches from the active theme's palette,
-so a custom theme exports its own colors.
+Inkscape cannot read CSS custom properties,
+so a classed element looks unstyled in the editor until you install the palette
+and refresh the preview.
+See [theme colors in the editor](../authoring/inkscape.md#theme-colors-in-the-editor-colorize-and-palette).
 
 ## Per-deck and per-slide CSS
 
-Beyond the theme you can inject CSS at two levels:
+Beyond the theme you can inject CSS at two levels.
+A bare string is read as a **path to a CSS file**,
+so wrap literal CSS in `Inline(...)`:
 
 ```python
-Deck(style='text { font-family: "Inter", sans-serif; }')  # every slide
-Slide("title", style="#headline { fill: hotpink; }")  # one slide
+from inkflow import Deck, Inline, Slide
+
+Deck(style=Inline('text { font-family: "Inter", sans-serif; }'))  # every slide
+Slide("title", extra_style=Inline("#headline { fill: hotpink; }"))  # one slide
+
+Deck(style="styles/deck.css")  # or point at a file, relative to deck.py
 ```
 
 Slide style beats deck style, which beats the theme.
@@ -205,7 +195,21 @@ The full stylesheet order, each layer overriding the ones before it:
 3. the built-in layout styling
 4. the active theme's `styles.css`
 5. the project's `styles.css` next to `deck.py`
-6. `Deck(style=...)`, then `Slide(style=...)`
+6. `Deck(style=...)`, then `Slide(extra_style=...)`
+
+## Project files
+
+Two files next to `deck.py` are picked up automatically, with no wiring:
+
+| File | Used for |
+|---|---|
+| `styles.css` | Deck-wide CSS, and `@keyframes` for [custom animations](../authoring/animations.md#writing-your-own) |
+| `scripts.js` | JavaScript, including [custom transitions](../authoring/transitions.md#writing-your-own) |
+
+`styles.css` sits at level 5 of the cascade above,
+so it overrides the theme and is overridden by the per-deck and per-slide styles.
+
+A theme can ship its own pair of both, which load before the project's.
 
 ## Font size
 
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 5574d290..8b96ac0a 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -146,5 +146,7 @@ teammates run `inkflow setup-git` once in their own clone to activate it.
 ## Next steps
 
 - [Concepts](concepts.md): understand the mental model before writing more slides
-- [Authoring slides](guides/slides.md): animations, element IDs, zones, and Markdown content
-- [Layout system](guides/layout-system.md): reusable slide templates
+- [Slides](authoring/slides.md): element IDs, zones, and media
+- [Markdown content](authoring/markdown.md): filling a slide from a `.md` file
+- [Steps](authoring/steps.md): building a slide up one keypress at a time
+- [Layouts](design/layouts.md): reusable slide templates
diff --git a/docs/guides/layout-system.md b/docs/guides/layout-system.md
deleted file mode 100644
index 4bbf8f10..00000000
--- a/docs/guides/layout-system.md
+++ /dev/null
@@ -1,462 +0,0 @@
-# Layout system
-
-Layouts are reusable SVG templates.
-They define the visual frame (background, typography regions, brand elements)
-while leaving named rectangular **zones** for content to be injected at build time.
-
-## Zones
-
-A zone is any SVG shape with an `id` that starts with `zone-`.
-`<rect>` is the most common:
-
-```xml
-<rect id="zone-content" x="120" y="200" width="1680" height="760"/>
-```
-
-At build time the pipeline replaces each zone element with a `<foreignObject>`
-sized to the shape's bounding box, containing the rendered HTML.
-Zone elements that aren't filled by the slide are silently removed.
-
-Inkscape's Layers & Objects panel edits an element's *label*, not its `id`.
-Label the rect `zone-content` there and run `inkflow label2id` to promote the
-label to the `id` (see [Transitions](transitions.md#naming-elements-from-inkscape)).
-
-### Non-rectangular zones
-
-`<polygon>`, `<ellipse>`, `<circle>`, and `<path>` are also valid zone shapes.
-For **Media zones**, the pipeline auto-generates a `<clipPath>` from the exact shape
-and applies it to the `<foreignObject>`, so images and videos are cropped to the
-zone boundary.
-
-For **TextBox zones**, only the bounding box is used.
-Text reflows in a rectangle regardless of zone shape, and no clip is applied.
-
-Alignment CSS variables set on a non-rect zone id work the same as on a rect:
-
-```css
-#zone-media { --inkflow-valign: center; }
-```
-
-### Reserved zone names
-
-| ID | Pipeline behaviour |
-|---|---|
-| `zone-title` | Receives the leading `# H1` from Markdown auto-extraction (when the zone exists) |
-| `zone-subtitle` | Receives the `## H2` immediately after the title (when the zone exists) |
-| `zone-slide-number` | `<text>` element. Replaced with the current slide number |
-| `zone-slide-total` | `<text>` element. Replaced with the total slide count |
-
-Any `zone-*` name beyond these is valid.
-Name it to match what your Markdown files use (`zone-content`, `zone-left`, `zone-right`, `zone-media`, etc.).
-
-### Default zone
-
-The **default zone** receives all unrouted Markdown content — everything not claimed
-by an explicit `::zone-name::` marker or by `zone-title` / `zone-subtitle` auto-extraction.
-
-Layouts declare their default zone with the `inkflow:default-zone` attribute:
-
-```xml
-<svg xmlns="http://www.w3.org/2000/svg"
-     xmlns:inkflow="urn:inkflow"
-     inkflow:parent="builtin:content"
-     inkflow:default-zone="content"
-     viewBox="0 0 1920 1080" width="1920" height="1080">
-  <rect id="zone-content" x="120" y="200" width="1680" height="720"/>
-</svg>
-```
-
-When the layout contains `zone-content`, that zone is the implicit default and
-the attribute is not needed.
-Set `inkflow:default-zone` only when you want a different zone to be the default
-(e.g. `zone-quote`, `zone-left`).
-
-Layouts that have no text content zone at all — like `cover.svg` (media + title/subtitle)
-or `section.svg` (title/subtitle only) — do not need the attribute.
-
-If a slide's Markdown contains unrouted content and the layout has no `inkflow:default-zone`,
-the pipeline raises an error and shows a red overlay in the browser.
-
-#### Auto-extraction fall-through
-
-When `zone-title` or `zone-subtitle` are **absent** from a layout, any leading
-`# H1` / `## H2` auto-extracted from the Markdown falls through to the default zone
-as rendered HTML, rather than being silently discarded.
-
-```markdown
-# This is a Quote
-And this is the attribution line.
-```
-
-On the `quote` layout (`inkflow:default-zone="quote"`, no `zone-title`),
-both lines above land in `zone-quote`.
-On the `content` layout (`inkflow:default-zone="content"`, has `zone-title`),
-`# H1` still routes to `zone-title` as usual.
-
-To route content to a specific zone regardless of the default, use an explicit marker:
-
-```markdown
-::quote::
-This text always goes to zone-quote.
-::attribution::
-— Author name
-```
-
-## Layout inheritance
-
-Layouts chain to their parents via an `inkflow:parent` attribute on the SVG root:
-
-```xml
-<svg xmlns="http://www.w3.org/2000/svg"
-     xmlns:inkflow="https://inkflow.dev/ns"
-     inkflow:parent="theme:main"
-     viewBox="0 0 1920 1080" width="1920" height="1080">
-  <!-- layout-specific zones -->
-</svg>
-```
-
-A typical chain looks like:
-
-```
-slides/bullets.svg
-  └─ inkflow:parent="content"         → layouts/content.svg
-       └─ inkflow:parent="theme:main" → theme/main.svg  (chain terminates — no parent)
-```
-
-The pipeline resolves the full chain and composites all layers from root to leaf.
-The SVG files on disk stay unmodified.
-
-## Overlays
-
-`inkflow:parent` answers "what am I built on" and composites *behind* a slide.
-Chrome that cuts across layouts asks a different question:
-"what goes on top of every slide, regardless of what it is built on".
-A logo, a footer, a header.
-That is an **overlay**.
-
-An overlay is an SVG at slide dimensions,
-composited above the finished slide:
-
-```python
-from inkflow import Deck, Overlay, Slide
-
-Deck(
-    overlays=[Overlay("footer"), Overlay("logo")],
-    slides=[
-        Slide("title.svg", overlays=[]),  # bare title, no chrome
-        Slide("content", md="intro.md"),  # inherits the deck's two
-    ],
-)
-```
-
-List order is paint order.
-Resolution runs `Slide.overlays` → `Deck.overlays` → `Theme.overlays`,
-each an override rather than a merge:
-`None` inherits the next level up,
-and `[]` means no chrome at all.
-
-Because overlays composite before zone numbering and content injection,
-three things follow without extra work:
-
-- A `zone-slide-number` inside a footer overlay is filled like any other.
-- A zone the overlay declares can be filled from `zones={...}` on a slide,
-  and is pruned on slides that leave it empty.
-- Animations can target elements inside an overlay,
-  so chrome can be revealed on a step.
-
-Overlays live in their own `overlays/` directory
-and resolve through the same three-level search and prefix grammar as layouts,
-against `overlays/` instead of `layouts/`:
-
-| Syntax | Resolves to |
-|---|---|
-| `"footer"` | Three-level search for `overlays/footer.svg` |
-| `"local:footer"` | `{project}/overlays/footer.svg` |
-| `"theme:footer"` | `{theme_dir}/overlays/footer.svg` |
-| `"builtin:footer"` | Inkflow built-in overlays |
-| `"./chrome/footer.svg"` | Relative to the project directory |
-
-Layouts and overlays are separate namespaces,
-so a bare name always means one or the other and never both.
-
-`inkflow sync` previews chrome in your SVG editor too,
-see [Which overlays a file previews](#which-overlays-a-file-previews).
-
-### Overlays can inherit too
-
-`inkflow:parent` on an overlay means "drawn behind me *within this overlay*".
-The overlay as a whole still lands on top of the slide,
-so the two axes stay independent:
-
-```
-overlays/brand.svg           the rule line and mark
-overlays/chrome.svg          inkflow:parent="brand", adds the event name
-```
-
-This is how a theme can ship `theme:brand`
-that a project extends locally without copying it.
-Bare names in an overlay's `inkflow:parent` resolve in the overlay namespace,
-so chrome can only ever inherit chrome.
-
-!!! warning "Do not point an overlay's parent at a layout"
-
-    Layouts paint a full-bleed background,
-    which on top of a slide hides the entire deck.
-    Bare names cannot reach a layout from an overlay,
-    so this takes an explicit path to trigger.
-    `inkflow verify` reports it as an error and names the offending file.
-
-### Removing an element from a layout
-
-There is no mechanism for this, because it is styling rather than structure.
-Hide it with CSS, which is already scoped per slide:
-
-```python
-Slide("content", extra_style=Inline("#logo { display: none }"))
-```
-
-## Path resolution
-
-Inkflow resolves layout names using a three-level search:
-
-1. Project `layouts/` directory
-2. Active theme `layouts/` directory (if `Deck(theme=...)` is set)
-3. Inkflow built-in layouts
-
-First match wins.
-Prefixes bypass the search entirely:
-
-| Syntax | Resolves to |
-|---|---|
-| `"content"` | Three-level search for `content.svg` |
-| `"local:content"` | `{project}/layouts/content.svg` |
-| `"theme:content"` | `{theme_dir}/layouts/content.svg` |
-| `"builtin:content"` | Inkflow built-in layouts |
-| `"./relative/path.svg"` | Relative to the current SVG file |
-
-## Creating a new slide from a layout
-
-The `inkflow add` command creates a new SVG file, optionally wired to a layout
-parent via `-p/--parent`:
-
-```bash
-inkflow add slides/new.svg -p content
-```
-
-This creates `slides/new.svg` with `inkflow:parent="content"` set,
-then automatically runs `inkflow sync` to add preview layers.
-Omit `-p` to create a blank slide with no parent.
-
-Add it to the `slides` list in `deck.py`:
-
-```python
-Slide("slides/new.svg")
-```
-
-## Changing or removing a parent
-
-To rewire an existing slide to a different layout:
-
-```bash
-inkflow parent set slides/new.svg builtin:content
-```
-
-To detach a slide from all layout parents:
-
-```bash
-inkflow parent strip slides/new.svg
-```
-
-## Previewing layouts in Inkscape
-
-`inkflow sync` writes each ancestor as a locked layer into the slide SVG,
-and the overlays the slide gets at runtime as locked layers on top of it,
-so you can see the inherited background, the zone positions,
-and how much room the chrome needs while editing in your SVG editor:
-
-```bash
-inkflow sync
-```
-
-Bottom to top, a synced slide holds the ancestor chain, its own content, then the overlays.
-These layers are for authoring reference only.
-The pipeline strips them before serving. They never appear in the browser.
-
-To check if any layers are stale without rewriting:
-
-```bash
-inkflow sync --check
-```
-
-Exits with code 1 if any files need updating (useful in CI).
-
-### Which overlays a file previews
-
-`sync` works on files, overlays are declared on slides,
-and one file can back many slides that disagree,
-so the answer is resolved in three steps:
-
-1. An explicit `inkflow:preview-overlays` attribute on the file wins.
-   Space-separated names, `""` for none.
-2. Otherwise, if every slide backed by this file agrees, that.
-   A slide backs its own `src` and every layout in that file's chain.
-3. Otherwise the deck default.
-
-`sync` prints which rule fired next to each file,
-so step 3 is never silent:
-
-```
-    Injected  slides/intro.svg (1 overlay layer, slides agree)
-    Injected  layouts/content.svg (1 overlay layer, deck default overlays)
-    Injected  overlays/footer.svg (overlay file)
-```
-
-Step 3 is a guess, and it deliberately errs toward *showing* chrome:
-the question you are answering in Inkscape is how much room to leave,
-and a preview showing chrome a slide will not have costs you some empty space,
-while the opposite causes overlap.
-When the guess is wrong for a given file, pin it with the attribute:
-
-```xml
-<svg xmlns="http://www.w3.org/2000/svg"
-     xmlns:inkflow="urn:inkflow"
-     inkflow:parent="content"
-     inkflow:preview-overlays="footer logo"
-     viewBox="0 0 1920 1080">
-```
-
-### Authoring an overlay itself
-
-An overlay file never receives chrome,
-otherwise `sync` would stamp the deck's footer onto the footer you are drawing.
-It can name a *backdrop* instead:
-something rendered behind it purely as reference,
-so you are not positioning chrome against a checkerboard.
-
-```xml
-<!-- overlays/footer.svg -->
-<svg xmlns="http://www.w3.org/2000/svg"
-     xmlns:inkflow="urn:inkflow"
-     inkflow:preview="content"
-     viewBox="0 0 1920 1080">
-```
-
-`inkflow:preview` takes a layout name, any of the prefixes,
-or a relative path.
-A path is the useful form for a deck of hand-drawn SVGs with no layouts at all,
-where the honest backdrop is a real slide:
-
-```xml
-     inkflow:preview="../slides/01-title.svg"
-```
-
-The slide's own layout chain comes along with it,
-exactly as when you edit that slide.
-
-There is **no default**.
-Without the attribute an overlay gets the preview styles and nothing behind it,
-and `sync` says so:
-
-```
-    Injected  overlays/footer.svg (overlay file, no backdrop)
-    Injected  overlays/logo.svg (overlay file, backdrop: content)
-```
-
-An overlay cannot know what it lands on,
-and guessing at the theme's `base` would be wrong in exactly the case that matters:
-a deck built on no layouts gets chrome positioned against a canvas of the wrong size
-in a background colour the deck never paints.
-
-The name says what it is: a preview choice, not a structural claim.
-Picking `content` as a backdrop while the overlay lands on `two-cols` at runtime
-is not a contradiction.
-
-Both attributes are authoring hints.
-Neither is ever read by the serve or build pipeline.
-
-A file counts as an overlay when it lives in an `overlays/` directory
-or the deck references it as an overlay.
-The first half covers drafts not yet added to `deck.py`,
-the second covers overlays parked outside the convention by a relative path.
-
-## Authoring a theme
-
-Theme layouts live outside any project and have no `deck.py`.
-Within a theme, layouts may still chain to each other or to built-in layouts —
-but `local:` and `theme:` references are not available (they require a project context).
-Use `builtin:` or relative paths instead:
-
-```xml
-<!-- theme/layouts/content.svg -->
-<svg xmlns="http://www.w3.org/2000/svg"
-     xmlns:inkflow="urn:inkflow"
-     inkflow:parent="builtin:content"
-     viewBox="0 0 1920 1080" width="1920" height="1080">
-  ...
-</svg>
-```
-
-To refresh injected layout layers while working on theme files, use `--no-deck`:
-
-```bash
-inkflow sync --no-deck layouts/*.svg
-```
-
-Attempting to use `local:` or `theme:` with `--no-deck` raises an error immediately.
-
-With no deck there is no slide-to-overlay mapping to derive,
-so overlay previews come from `inkflow:preview-overlays` alone
-and every other file is synced without chrome.
-A theme overlay still gets whatever backdrop it names.
-
-## Writing a custom layout
-
-1. Create `layouts/my-layout.svg` in your project directory.
-2. Set `inkflow:parent` to point at your base theme or another layout.
-3. Add `<rect id="zone-*">` elements where you want content (or any supported shape — see [Non-rectangular zones](#non-rectangular-zones)).
-4. Set `inkflow:default-zone` to the zone that should receive unrouted Markdown text.
-5. Reference it in `deck.py`:
-
-```python
-Slide("my-layout", md="custom")
-```
-
-### Example layout
-
-```xml
-<svg xmlns="http://www.w3.org/2000/svg"
-     xmlns:inkflow="urn:inkflow"
-     inkflow:parent="builtin:content"
-     inkflow:default-zone="content"
-     viewBox="0 0 1920 1080" width="1920" height="1080">
-
-  <!-- Narrower content column; unrouted Markdown goes here -->
-  <rect id="zone-content" x="300" y="200" width="1320" height="720"/>
-</svg>
-```
-
-### Two-column layout example
-
-```xml
-<svg xmlns="http://www.w3.org/2000/svg"
-     xmlns:inkflow="urn:inkflow"
-     inkflow:parent="builtin:content"
-     inkflow:default-zone="left"
-     viewBox="0 0 1920 1080" width="1920" height="1080">
-
-  <!-- Unrouted content goes left; use ::right:: to route to the right column -->
-  <rect id="zone-left"  x="80"   y="200" width="840" height="720"/>
-  <rect id="zone-right" x="1000" y="200" width="840" height="720"/>
-</svg>
-```
-
-In Markdown, unmarked text goes to `zone-left` automatically:
-
-```markdown
-# Two Columns
-
-Left column content here.
-
-::right::
-Right column content here.
-```
diff --git a/docs/guides/slides.md b/docs/guides/slides.md
deleted file mode 100644
index 838c8c7f..00000000
--- a/docs/guides/slides.md
+++ /dev/null
@@ -1,734 +0,0 @@
-# Authoring slides
-
-Every slide is a single SVG file.
-`Slide` wraps that SVG, declares which elements to animate,
-and sets how the slide transitions in from the previous one.
-
-You draw a slide in your SVG editor and serve it as-is.
-When part of a slide should hold formatted text, images, or video,
-mark a rectangular area in the SVG as a **zone** and fill it at build time —
-from `deck.py` with `TextBox`, `Image`, or `Video`, or by pointing `md=` at a Markdown file.
-A single slide can freely combine hand-drawn artwork, animated elements, and
-zones filled with Markdown.
-
-## Minimal example
-
-```python
-from inkflow import Deck, Slide
-
-
-def main() -> Deck:
-    return Deck(
-        slides=[
-            Slide("title"),
-        ]
-    )
-```
-
-A bare name like `"title"` is looked up in `slides/` first (as `slides/title.svg`),
-then searched across layouts if not found there — see the
-[`Slide.src`](../reference/manifest.md#inkflow.manifest.Slide) reference for the
-full order. You can also write the path out in full, or point elsewhere entirely.
-The SVG file is loaded as-is, stripped of editor metadata, and served.
-No animations, no transition. Just the slide.
-
-## Authoring in your SVG editor
-
-The only convention slides must follow:
-**any element you want to animate needs an ID.**
-
-Set the ID via the XML editor (<kbd>Ctrl+Shift+X</kbd>)
-or the Object Properties dialog (<kbd>Ctrl+Shift+O</kbd>) in Inkscape,
-or the equivalent in any other editor.
-IDs can be anything: `headline`, `box-a`, `arrow-pipeline`.
-Avoid spaces. Hyphens and underscores are fine.
-
-No other markup is required.
-The SVG is a standard vector file.
-
-## Animations
-
-Animations reveal (or hide) elements on successive keypresses.
-Each animation targets a single element by its `id` (no leading `#`):
-
-```python
-from inkflow import Slide, animations
-
-Slide(
-    "title",
-    animations=[
-        animations.FadeIn("headline"),
-        animations.FadeIn("subtitle"),
-        animations.FadeIn("byline"),
-    ],
-)
-```
-
-Each cue's `trigger` says *when* it fires, and inkflow works out the concrete
-steps from the triggers and the order of the list. The default trigger is
-`ON_CLICK`, so the three fades above take steps 1, 2, 3 — one per keypress.
-
-Elements with no animation declaration start **visible**.
-Elements targeted by an entrance animation (`FadeIn`, `Bounce`, `SlideIn`, `ZoomIn`) start
-**invisible** and appear when their step is reached.
-
-Every type has a **kind** — `enter`, `exit`, or `emphasis` — set by the semantic base
-it subclasses (`animations.Enter` / `Exit` / `Emphasis`). Enters reveal, exits hide, and
-emphasis (like `Highlight`) fires momentarily without changing visibility. Stepping
-backward plays each animation in reverse, mirroring the forward order.
-
-### Animation types
-
-Every type accepts `duration`, `easing`, `delay`, and `iterations` (keyword-only); some
-add their own parameters. `element` and `trigger` are the two shared positional slots. See
-the [animations reference](../reference/animations.md) for the full table.
-
-| Class | Effect | Starting state |
-|---|---|---|
-| `FadeIn` | Opacity 0 → 1, subtle upward drift | Hidden |
-| `FadeOut` | Opacity 1 → 0 | Visible |
-| `Bounce` | Spring up into place from just below (`distance`) | Hidden |
-| `SlideIn` / `SlideOut` | Slide from/to an edge (`direction`, `distance`) | Hidden / Visible |
-| `ZoomIn` / `ZoomOut` | Scale into/out of place (`scale`) | Hidden / Visible |
-| `Highlight` | Pulse a glow (`color`, `iterations`), without hiding | Visible |
-
-```python
-animations.SlideIn("box", direction="left", duration=0.6)
-animations.ZoomIn("logo", scale=0.6)
-animations.Highlight("total", color="#cba6f7", iterations=2)
-```
-
-### Multiple animations on one element
-
-Because each cue is driven independently, one element can carry several across the
-slide — it can enter, be emphasized, exit, and even re-enter, each on its own step:
-
-```python
-animations = [
-    animations.FadeIn("hero"),  # step 1: enters
-    animations.Highlight("hero"),  # step 2: emphasized
-    animations.SlideOut("hero", direction="down"),  # step 3: exits
-    animations.Bounce("hero"),  # step 4: returns
-]
-```
-
-The kinds decide how they compose: at any step the element is shown or hidden by its
-most recent enter/exit, while emphasis cues just pulse. Two enters (or two exits) on one
-element with no opposing cue between them is almost always a mistake, and inkflow warns
-about it at build time.
-
-### Custom animations
-
-Subclass a semantic base and write a matching `@keyframes anim-<slug>` (the kebab-cased
-type name) in a `styles.css` next to `deck.py`. No JavaScript: the step engine reads the
-keyframes and drives them, substituting each cue's own fields wherever they appear as
-`var(--anim-<field>)`.
-
-```python
-from dataclasses import dataclass
-from inkflow import animations
-
-
-@dataclass
-class Glow(animations.Emphasis):
-    intensity: float = 1.0  # → var(--anim-intensity)
-```
-
-```css
-/* styles.css */
-@keyframes anim-glow {
-    50% { filter: drop-shadow(0 0 calc(8px * var(--anim-intensity)) var(--accent)); }
-}
-```
-
-### Triggers — the step model
-
-Each cue carries a `Trigger` that decides its step:
-
-| Trigger | Meaning |
-|---|---|
-| `Trigger.ON_CLICK` (default) | Takes the next step, needs a keypress |
-| `Trigger.WITH_PREVIOUS` | Shares the previous cue's step, firing together |
-| `Trigger.AFTER_PREVIOUS` | Shares the previous cue's step, then plays automatically once it finishes (no keypress) |
-| `Trigger.at(n)` | Pins the cue to an absolute step `n` |
-
-`trigger` is the second positional argument (after `element`):
-
-```python
-from inkflow import Trigger
-
-animations = [
-    animations.FadeIn("left-panel"),  # step 1
-    animations.FadeIn("right-panel", Trigger.WITH_PREVIOUS),  # step 1, together
-    animations.FadeIn("caption", Trigger.AFTER_PREVIOUS),  # step 1, after right-panel
-    animations.FadeIn("footnote"),  # step 2
-]
-```
-
-A first-in-order `WITH_PREVIOUS` or `AFTER_PREVIOUS` falls to the slide-entry step.
-It is not shown pre-resting:
-it animates on entry, right after the slide transition settles,
-so a slide can build itself the moment you arrive with no keypress.
-
-`AFTER_PREVIOUS` turns one keypress into a self-playing sequence.
-The cues share one step and play as a single atomic run,
-scrubbed along one 0-to-1 timeline:
-the first cue fires on the press (or on entry, if it is first in order),
-and each following `AFTER_PREVIOUS` cue starts as the one before it finishes.
-So one press forward plays the whole cascade,
-a forward press while it is still playing snaps it to the end,
-and one press back mirrors it (last stage out first).
-`Trigger.at(n)` is the escape hatch for aligning cues on
-the shared step axis (see [combining reveals and animations](#combining-markdown-reveals-with-animations)).
-
-## Transitions
-
-A transition controls how the slide enters from the previous one.
-Set it per slide, or set a default on the `Deck`:
-
-```python
-from inkflow import Deck, Slide, transitions
-
-
-def main() -> Deck:
-    return Deck(
-        transition=transitions.Crossfade(),  # default for all slides
-        slides=[
-            Slide("title"),  # uses Crossfade
-            Slide("diagram", transition=transitions.Morph()),  # overrides to Morph
-        ],
-    )
-```
-
-See [Transitions](transitions.md) for details on each type.
-
-## Filling zones with content
-
-A **zone** is any SVG shape whose `id` starts with `zone-` (see
-[Layout system](layout-system.md) for the full rules).
-It marks an area the pipeline replaces with injected content at build time.
-This is how a slide carries what SVG editors handle poorly —
-reflowing text, bullet lists, tables, code blocks — and what an SVG can't hold at all, like video.
-
-Any SVG can define zones, whether it's a one-off slide file or a shared layout.
-Fill them the same way in either case.
-
-### From `deck.py` with the `zones` dict
-
-Pass content into named zones directly:
-
-```python
-from inkflow import Image, Slide
-
-Slide(
-    "title",
-    zones={
-        "title": "My talk title",
-        "media": Image("assets/headshot.jpg", fit="cover"),
-    },
-)
-```
-
-Keys in `zones` are zone names without the `zone-` prefix.
-A `str` value is rendered as inline Markdown.
-A `TextBox` value gives explicit control over alignment and padding from Python.
-An `Image` or `Video` value injects media.
-The pipeline replaces the matching `zone-*` element with the injected content at build time.
-
-### From a Markdown file with `md=`
-
-When most of a slide's content is text, it's easier to write it in a `.md` file
-than to fill each zone by hand.
-Point `md=` at a Markdown file and the pipeline routes its sections into the slide's zones:
-
-```python
-from inkflow import Deck, Slide
-
-
-def main() -> Deck:
-    return Deck(
-        slides=[
-            Slide("content", md="intro"),
-        ]
-    )
-```
-
-`"content"` is the name of a built-in layout — an SVG that defines zones and little
-else (see [Built-in layouts](#built-in-layouts) below).
-`md` takes the same kind of path as `Slide.src`: a bare name like `"intro"` resolves
-to `slides/intro.md`, or write the path out in full.
-Nothing about `md=` is special to layouts, though: it fills whatever zones the
-referenced SVG defines, one-off slide file or shared layout alike.
-
-## Writing Markdown content
-
-The rest of this section covers the Markdown routing grammar —
-how content in a `.md` file lands in the right zones, splits into steps, and more.
-
-### How content is placed
-
-The pipeline inspects the Markdown file for two things:
-
-**Auto-extraction** (no markers needed):
-if the file starts with a `# H1`, it is extracted into `zone-title`.
-An `## H2` immediately following goes to `zone-subtitle`.
-Everything else goes to `zone-content`.
-
-```markdown
-# My slide title
-## Optional subtitle
-
-The body content goes here.
-```
-
-**Explicit zone markers**: use `::zone-name::` to route content to a specific zone.
-Anything after the marker goes to that zone until the next marker.
-
-```markdown
-::left::
-
-## Left column
-
-Content for the left side.
-
-::right::
-
-## Right column
-
-Content for the right side.
-```
-
-Explicit markers always override auto-extraction.
-
-### Zone alignment parameters
-
-Zone markers accept optional `key=value` parameters that control how content is
-positioned inside the zone.
-
-```markdown
-::content align=center valign=center padding=60::
-
-This text is horizontally and vertically centered, with 60 SVG units of padding.
-```
-
-| Parameter | Values | Description |
-|---|---|---|
-| `align` | `left`, `center`, `right`, `justify` | Horizontal text alignment |
-| `valign` | `top`, `center`, `bottom` | Vertical alignment of the content block within the zone |
-| `padding` | number (SVG user units) | Inner spacing on all sides |
-
-All three are optional and can be combined freely.
-Parameters on the marker override CSS variables set in the layout SVG,
-which in turn override the built-in defaults (`align: left`, `valign: top`, `padding: 0`).
-
-For persistent defaults that apply to every slide using a layout,
-set CSS variables directly in the layout SVG's `<defs><style>` (see [Layout system](layout-system.md)):
-
-```css
-#zone-title   { --inkflow-valign: center; }
-#zone-content { --inkflow-padding: 40px; }
-```
-
-For programmatic control from `deck.py`, pass `align`, `valign`, and `padding` directly to `TextBox`.
-See the [manifest reference](../reference/manifest.md#inkflow.manifest.TextBox).
-
-### Step markers
-
-#### Explicit steps with `::step::`
-
-`::step::` inserts an animation step boundary within a zone.
-Content before the first `::step::` is visible from the start.
-Each marker reveals the next chunk on keypress.
-
-```markdown
-# Build up a concept
-
-First point — visible immediately.
-
-::step::
-
-Second point — revealed on first keypress.
-
-::step::
-
-Third point — revealed on second keypress.
-```
-
-#### Auto-stepping with `::steps::`
-
-`::steps::` opens a block where each list item and each paragraph reveals individually,
-without needing a `::step::` before every bullet.
-
-```markdown
-# Why inkflow?
-
-Intro text — always visible.
-
-::steps::
-
-- First bullet reveals on keypress 1.
-- Second bullet reveals on keypress 2.
-
-A paragraph inside the block also steps.
-
-::steps end::
-
-Footer text — always visible again.
-```
-
-`::steps end::` is optional.
-If omitted, the block extends to the end of the zone — everything after `::steps::` steps.
-
-```markdown
-# All bullets step
-
-::steps::
-
-- One
-- Two
-- Three
-```
-
-`::step::` markers inside a `::steps::` block are ignored — every item already steps.
-
-#### Choosing the animation with `type=`
-
-By default a reveal fades in. Give a marker a `type=<ClassName>` plus any of that
-type's parameters to use a different animation — the same class names and
-parameter names you'd write in `deck.py`:
-
-```markdown
-::step type=SlideIn direction=right distance=200::
-
-Slides in from the right.
-
-::step type=Bounce::
-
-Bounces in.
-```
-
-The same grammar works on `::steps::`, where the type and parameters apply to
-every item in the block:
-
-```markdown
-::steps type=SlideIn direction=up::
-
-- Each bullet slides up
-- one after another
-::steps end::
-```
-
-`type=` resolves against the [built-in animation types](../reference/animations.md)
-and any custom `Animation` subclass your `deck.py` defines (matched by class
-name). Parameters are coerced to each field's type, so `distance=200` becomes a
-number and `direction=right` becomes the [`Direction`](../reference/enums.md)
-value. Values cannot contain spaces, so an `easing=ease-in-out` preset works in a
-marker but a `cubic-bezier(...)` curve is a `deck.py`-only thing.
-
-#### Controlling the step with `trigger=`
-
-A reveal defaults to `ON_CLICK` (one keypress per reveal). Set `trigger=` to
-change that:
-`with-previous` fires a reveal together with the one before it,
-`after-previous` lets it reveal itself once the one before it finishes,
-and a number pins it to an absolute step:
-
-```markdown
-::step::
-First point.
-
-::step trigger=with-previous::
-Appears together with the first point.
-
-::step trigger=after-previous::
-Reveals on its own, right after the first point.
-
-::step trigger=3::
-Pinned to step 3.
-```
-
-### Code blocks
-
-All fenced code blocks are syntax-highlighted automatically using Pygments.
-No configuration is needed — just write standard Markdown fences with a language tag.
-
-````markdown
-```python
-def greet(name: str) -> str:
-    return f"Hello, {name}!"
-```
-````
-
-#### Step-based line highlighting
-
-Add a `{…}` spec after the language name to highlight specific lines on each keypress.
-Each `|`-separated stage is one step.
-
-````markdown
-```python {1|2-3|all}
-def greet(name: str) -> str:
-    message = f"Hello, {name}!"
-    return message
-
-print(greet("world"))
-```
-````
-
-On slide entry the first stage is active (line 1 highlighted, others dimmed).
-Each keypress advances to the next stage.
-When the spec ends, subsequent keypresses continue with whatever comes next in the slide.
-
-**Stage syntax:**
-
-| Stage | Effect |
-|---|---|
-| `1` | Single line highlighted, others dimmed |
-| `1,3,5` | Comma-separated lines highlighted |
-| `2-4` | Inclusive range highlighted |
-| `all` or `*` | No dimming — all lines at full opacity |
-| `none` | All lines dimmed |
-
-Stages can be combined: `1,3-5` highlights lines 1, 3, 4, and 5.
-
-#### Step counter integration
-
-Code block stages consume steps from the shared slide counter.
-A block with three stages (`{1|2-3|all}`) uses two extra steps beyond its entry step.
-`::step::` markers and `::steps::` blocks that follow pick up after the code block's last stage.
-
-````markdown
-# Walk through the code
-
-```python {1|2-3}
-def foo():
-    return 42
-```
-
-::step::
-
-This paragraph appears after the code block's second highlight stage.
-````
-
-A code block without a `{…}` spec gets syntax colouring but adds no steps.
-
-### Speaker notes
-
-Add a `::notes::` marker to route content to speaker notes instead of the slide body.
-Notes are not rendered on the slide — they are available in the presenter view.
-
-```markdown
-# My slide title
-
-The visible slide body goes here.
-
-::notes::
-
-These are my private notes. They support **markdown** and are only shown
-in the presenter view.
-```
-
-You can also set notes directly on `Slide` via the `notes=` parameter:
-
-```python
-Slide("title", notes="Remember to greet the audience.")
-Slide("content", md="bullets", notes=Path("notes/bullets.md"))
-```
-
-`str` is used as-is (inline HTML/text). `Path` pointing to a `.md` file is rendered as Markdown; any other extension is read as-is.
-When both `notes=` and `::notes::` are present, they are concatenated (`notes=` first, then `::notes::`).
-
-### Images
-
-Reference an image from Markdown with standard syntax:
-
-```markdown
-![A diagram](assets/diagram.png)
-```
-
-An image path is resolved relative to **the file it is written in**,
-which is what every editor assumes:
-a `![](assets/diagram.png)` in `<project-rood>/slides/intro.md` points at `<project-rood>/slides/assets/diagram.png`,
-an `<image href="../assets/diagram.png">` in `<project-rood>/slides/intro.svg` points at `<project-rood>/assets/diagram.png`,
-and an `Image("assets/diagram.png")` or an `Inline(...)` Markdown string in `<project-rood>/deck.py` points at `<project-rood>/assets/diagram.png`.
-So a slide SVG keeps rendering in Inkscape and a Markdown file keeps previewing in an editor,
-with no separate convention to remember.
-
-The asset itself must live inside the project directory,
-or inside the active theme's asset directory.
-Anything else cannot be served or exported,
-and is reported as a warning naming the file and the reference.
-To use a directory outside the project, symlink it in:
-
-```bash
-ln -s ../shared/assets assets
-```
-
-Local image paths are copied into the output of `inkflow build` and `inkflow export`. Remote (`https://`) and `data:` URIs are left as they are.
-
-## Media zones
-
-For images and video that should fill a zone (rather than sit inline in text),
-pass an `Image` or a `Video` through the `zones` dict:
-
-```python
-from inkflow import Image, Slide
-
-Slide(
-    "media-right",
-    md="feature",
-    zones={"media": Image("assets/screenshot.png", fit="cover")},
-)
-```
-
-`Image` and `Video` share placement fields (`fit`, `align`, `x`, `y`, `alt_src`);
-see the [manifest reference](../reference/manifest.md#inkflow.manifest.Image) for
-the full list.
-
-### Video playback
-
-`Video` adds playback control on top of those fields:
-
-```python
-from inkflow import Muted, Slide, Video
-
-Slide(
-    "media-right",
-    md="demo",
-    zones={"media": Video("assets/demo.mp4", autoplay=True, loop=True)},
-)
-```
-
-See the [manifest reference](../reference/manifest.md#inkflow.manifest.Video) for
-the full list of playback parameters (`controls`, `autoplay`, `muted`, `loop`,
-`poster`, `start`/`end`).
-
-**Play on a step.** To start a clip on a step rather than on load, add an
-`animations.PlayVideo` cue targeting the video's zone key to the slide's
-`animations=[...]`. It joins the step timeline like any other cue:
-
-```python
-from inkflow import Slide, Trigger, Video, animations
-
-Slide(
-    "media-right",
-    zones={"media": Video("assets/demo.mp4")},
-    animations=[animations.PlayVideo("media")],  # plays on the next click
-)
-```
-
-Leaving a slide pauses and rewinds its video, and stepping back below the cue's
-step resets it to the start. A video that both `autoplay`s and is targeted by a
-`PlayVideo` cue is contradictory — the cue wins (autoplay is dropped, with a
-warning), so the clip waits for its step and plays audibly on the gesture.
-
-**Muting and autoplay.** Browsers block autoplaying video with sound unless the
-user has interacted with the page. `Muted.AUTO` (the default) sidesteps that by
-muting a clip **only** when it autoplays, so autoplay always works and everything
-else (controls, a `PlayVideo` cue) keeps its sound. `Muted.ON` always mutes;
-`Muted.OFF` never mutes — with `autoplay=True` that clip may be blocked on a cold
-load, which you accept by opting in explicitly.
-
-!!! note "Zones only"
-    Playback control applies to `Video` passed through the `zones` dict. A video
-    embedded from Markdown with `![](clip.mp4)` renders as a plain, uncontrolled
-    element.
-
-## Built-in layouts
-
-Layout names like `"content"` above resolve to reusable layout SVGs.
-The built-in theme ships these:
-
-| Name | Zones | Use for |
-|---|---|---|
-| `cover` | title, subtitle, media | Title / opening slide |
-| `section` | title, subtitle | Section divider |
-| `title` | title | Bare title, no content zone |
-| `content` | title, content | Standard text slide |
-| `center` | content | Centered content |
-| `two-cols` | title, left, right | Two-column comparison |
-| `fact` | fact, caption | Big number or key fact |
-| `quote` | quote, attribution | Pull quote |
-| `media-left` | title, content, media | Text + image/video (image left) |
-| `media-right` | title, content, media | Text + image/video (image right) |
-| `end` | title, subtitle | Thank-you / closing slide |
-
-### Referencing project layouts
-
-Add layout SVGs to your project's own `layouts/` directory and reference them the
-same way as built-ins — by bare name, which shadows a built-in layout of the same
-name, or pin explicitly with `local:`/`theme:`/`builtin:`, or point at a path
-directly:
-
-```python
-Slide("local:my-layout", md="custom")
-```
-
-See [Layout system](layout-system.md#path-resolution) for the full resolution rules
-and how to build your own layouts.
-
-## Combining Markdown reveals with animations
-
-When a slide has both Markdown reveals and a deck `animations=[...]` list, they
-form **one continuous timeline**: the Markdown reveals number first (in reading
-order), then the `animations=[...]` list continues from there.
-
-So with two reveals and two animations, the reveals take steps 1–2 and the
-animations take steps 3–4:
-
-```python
-from inkflow import animations, Slide, Trigger
-
-Slide(
-    "mixed",
-    md="bullets",  # two ::steps:: bullets → steps 1, 2
-    animations=[
-        animations.FadeIn("badge-a"),  # step 3
-        animations.FadeIn("badge-b", Trigger.at(5)),  # pinned to step 5
-    ],
-)
-```
-
-`Trigger.WITH_PREVIOUS` works across the boundary too — a first-in-list animation
-with it fires together with the last bullet. To place an animation at a specific
-reveal's step, pin it with `Trigger.at(n)`.
-
-## Per-slide styling
-
-The `style` parameter injects a CSS `<style>` block into the slide's SVG at render time.
-Use it as an escape hatch for one-off tweaks.
-For systematic visual changes, use a theme.
-
-```python
-Slide(
-    "title",
-    style="""
-    #headline { font-size: 72px; fill: var(--inkflow-accent); }
-""",
-)
-```
-
-## Slide dimensions
-
-Inkflow does not enforce a fixed canvas size.
-Design your slides at whatever dimensions suit your presentation:
-16:9, 4:3, square, portrait — the presenter scales to fill the available screen area automatically.
-
-The built-in theme layouts are authored at **1920 × 1080** (16:9).
-Slides that use them must share that coordinate space.
-If you need a different aspect ratio, create layout SVGs at matching dimensions in your SVG editor;
-the pipeline treats them identically.
-
-PDF export auto-detects the page size from the first slide's `viewBox`.
-You can override it if needed:
-
-```bash
-inkflow export --size 2560x1440
-```
-
-## Tips
-
-- Keep element IDs short and semantic: `title`, `diagram-step-1`, `callout`.
-- Elements that should never animate don't need IDs.
-- The pipeline strips editor metadata on every load.
-  No need to clean manually if you have the git hook set up.
-- SVGs from any editor (Figma export, Affinity Designer, hand-coded) work without pre-processing.
diff --git a/docs/index.md b/docs/index.md
index 6ed1bdb2..7b9a8442 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -66,7 +66,7 @@ Markdown-filled zones for text-heavy slides,
 a presenter view with speaker notes,
 one-command export to static HTML or PDF,
 and more.
-Browse the [guides](guides/slides.md) or read [Concepts](concepts.md) for the full picture.
+Start with [Authoring slides](authoring/slides.md), or read [Concepts](concepts.md) for the full picture.
 
 ### An example `deck.py`
 
@@ -143,10 +143,3 @@ and serve the result to your browser.
 [Demo](demo/index.html){ .md-button .md-button--primary }
 [Get started](getting-started.md){ .md-button }
 </div>
-
----
-
-!!! note
-    All guides are currently AI-generated drafts and may contain inaccuracies or incomplete information.
-    I'll review them once the API stabilizes 
-
diff --git a/docs/guides/export.md b/docs/presenting/export.md
similarity index 90%
rename from docs/guides/export.md
rename to docs/presenting/export.md
index 898dbcbf..544fb2fe 100644
--- a/docs/guides/export.md
+++ b/docs/presenting/export.md
@@ -27,7 +27,7 @@ Fonts are embedded directly into the HTML, so they need no separate files.
 To embed the assets too and get a single file, see [`--inline-assets`](#one-file-instead-of-a-directory-inline-assets).
 
 Every reference is resolved relative to the file it was written in
-(see [Images](slides.md#images)),
+(see [Images](../authoring/markdown.md#images)),
 and the source tree is mirrored inside the output directory,
 so the build stays self-contained wherever it is copied.
 A theme's own assets are copied under `_theme/`.
@@ -130,12 +130,21 @@ To embed in an MkDocs page, place the built output in `docs/demo/` and add an if
 </iframe>
 ```
 
-To generate and place the demo as part of your docs build,
-add a `poe` task:
+Build the deck into place before building the site,
+so the embedded demo is always current:
 
-```toml
-[tool.poe.tasks.docs-build-demo]
-cmd = "inkflow build --deck src/inkflow/theme/showcase/deck.py --output docs/demo"
+```bash
+inkflow build --deck deck.py --output docs/demo
+mkdocs build
 ```
 
-Then run `poe docs-build-demo` before `mkdocs build` or `mkdocs gh-deploy`.
+Wire that pair into whichever task runner your project already uses.
+These docs do it with [mise](https://mise.jdx.dev/):
+
+```toml
+[tasks.docs-build]
+run = [
+  "uv run inkflow build --deck demo/deck.py --output docs/demo",
+  "uv run mkdocs build",
+]
+```
diff --git a/docs/presenting/index.md b/docs/presenting/index.md
new file mode 100644
index 00000000..fc4eb5da
--- /dev/null
+++ b/docs/presenting/index.md
@@ -0,0 +1,129 @@
+# Presenting a deck
+
+The presenter is the browser page `inkflow serve` opens,
+and it is the same page an [exported build](export.md) produces.
+Everything on this page works in both.
+
+Press <kbd>?</kbd> at any time for the full keybinding list.
+
+## Keybindings
+
+### Navigate
+
+| Key | Action |
+|---|---|
+| <kbd>→</kbd> <kbd>Space</kbd> <kbd>l</kbd> | Advance one step, or to the next slide |
+| <kbd>←</kbd> <kbd>Backspace</kbd> <kbd>h</kbd> | Back one step, or to the previous slide |
+| <kbd>↓</kbd> <kbd>j</kbd> | Next slide, skipping its remaining steps |
+| <kbd>↑</kbd> <kbd>k</kbd> | Previous slide |
+| <kbd>^</kbd> <kbd>Home</kbd> | First slide |
+| <kbd>$</kbd> <kbd>End</kbd> | Last slide |
+| <kbd>g</kbd> | Slide picker |
+| <kbd>o</kbd> | Slide overview |
+
+### Present
+
+| Key | Action |
+|---|---|
+| <kbd>.</kbd> | Laser pointer |
+| <kbd>Ctrl</kbd> + scroll | Zoom toward the pointer |
+| <kbd>Ctrl</kbd> + drag | Pan |
+| <kbd>+</kbd> <kbd>-</kbd> <kbd>0</kbd> | Zoom in, out, reset |
+| <kbd>b</kbd> | Blackout |
+| <kbd>w</kbd> | Whiteout |
+| <kbd>f</kbd> | Fullscreen |
+
+### View
+
+| Key | Action |
+|---|---|
+| <kbd>t</kbd> | Dark / light mode |
+| <kbd>p</kbd> | [Presenter panel](presenter-panel.md) |
+| <kbd>s</kbd> | [Cycle sync mode](sync.md#sync-modes) |
+| <kbd>d</kbd> | Diagnostics |
+| <kbd>n</kbd> | Notifications |
+| <kbd>?</kbd> | This help |
+
+<kbd>Esc</kbd> closes whatever is open.
+With nothing open it resets the zoom.
+
+## Moving around
+
+**Steps versus slides.**
+<kbd>→</kbd> advances the build on the current slide and moves on once it is finished.
+<kbd>↓</kbd> skips straight to the next slide.
+Use <kbd>↓</kbd> when you are running short on a slide you have already made your point on.
+
+**The picker** (<kbd>g</kbd>) is a search box over slide titles.
+Type a few letters, or a slide number, and press <kbd>Enter</kbd>.
+Matching is fuzzy, so `arc` finds "Architecture overview".
+It jumps to that slide with its build already complete,
+which is what you want when someone asks about an earlier diagram.
+
+**The overview** (<kbd>o</kbd>) shows the whole deck as a thumbnail grid.
+Arrow keys move the selection, <kbd>Enter</kbd> opens the highlighted slide,
+and <kbd>o</kbd> or <kbd>Esc</kbd> returns without moving.
+
+## Drawing attention
+
+**The laser** (<kbd>.</kbd>) replaces the cursor with a dot.
+Drag and it leaves a trail that fades on its own,
+so you can circle a term or underline a line of code without leaving anything behind.
+Press <kbd>.</kbd> again to go back to the normal cursor.
+
+**Zoom** magnifies part of a slide.
+Hold <kbd>Ctrl</kbd> and scroll to zoom toward the pointer, or drag to pan.
+<kbd>+</kbd>, <kbd>-</kbd> and <kbd>0</kbd> do the same from the keyboard.
+
+Zoom is local to the window.
+A second screen or a following window keeps its own view,
+so magnifying a detail on your laptop does not disturb the projector.
+Navigating while zoomed eases back to the full slide first.
+
+!!! note
+    This is the presenter's camera, unrelated to the
+    [`Zoom` transition](../authoring/transitions.md#zoom).
+
+**Blackout and whiteout** (<kbd>b</kbd> / <kbd>w</kbd>) cover the slide
+with a solid colour.
+Use them when the audience should be looking at you, or at a demo,
+rather than at the screen.
+Any key brings the slide back.
+
+## Adjusting the view
+
+**Dark and light** (<kbd>t</kbd>) switches the palette when the theme provides both.
+Every element painted with a
+[token class](../design/themes.md#svg-element-utility-classes) follows.
+Useful when the projector washes out a dark deck.
+
+**The presenter panel** (<kbd>p</kbd>) opens speaker notes, a next-slide preview
+and timers in a sidebar. It has [its own page](presenter-panel.md).
+
+**Diagnostics** (<kbd>d</kbd>) shows the warnings from the last rebuild,
+which is where a missing font or an unresolvable image reference appears.
+A banner surfaces automatically when new ones arrive under `inkflow serve`.
+
+**Notifications** (<kbd>n</kbd>) lists recent transient messages
+after their toast has gone.
+
+## Touch and mobile
+
+On a touchscreen, swipe left and right to move between slides,
+or tap the left and right edges of the stage.
+
+A floating control appears with buttons for dark/light, the step indicator
+and fullscreen.
+
+## Where you are in the deck
+
+The status bar carries the slide number, a ring showing progress through
+the current slide's steps, and buttons for the overview, the presenter panel,
+[sync mode](sync.md#sync-modes) and fullscreen.
+
+Under `inkflow serve` it also has an
+[Edit button](presenter-panel.md#editing-a-slide) for jumping to a slide's source.
+
+The position also lives in the URL as `#slide=7&steps=2`.
+Copy the link to send someone a specific slide,
+and a refresh keeps you where you were rather than jumping to the start.
diff --git a/docs/guides/presenter-view.md b/docs/presenting/presenter-panel.md
similarity index 51%
rename from docs/guides/presenter-view.md
rename to docs/presenting/presenter-panel.md
index 10a2dd60..a379c8d0 100644
--- a/docs/guides/presenter-view.md
+++ b/docs/presenting/presenter-panel.md
@@ -6,7 +6,7 @@ Press <kbd>p</kbd> to toggle it.
 
 ## Opening it
 
-While the deck is being served, open the panel in either of these ways:
+Open the panel in either of these ways:
 
 - Press <kbd>p</kbd> in the main view.
 - Click the presenter-icon button in the status bar.
@@ -61,11 +61,15 @@ They support **Markdown**, including lists and `code`.
 You can also pass notes directly via the `notes=` parameter on any `Slide`:
 
 ```python
-Slide("diagram", notes="Walk through the diagram top to bottom.")
-Slide("results", notes=Path("slides/results-notes.md"))
+from inkflow import Inline, Slide
+
+Slide("diagram", notes=Inline("Walk through the diagram top to bottom."))
+Slide("results", notes="notes/results.md")
 ```
 
-See [Authoring slides](slides.md#speaker-notes) and
+A bare `str` is a path to a file, `Inline(...)` is the text itself.
+
+See [Speaker notes](../authoring/markdown.md#speaker-notes) and
 [Manifest reference](../reference/manifest.md) for details.
 
 ## Editing a slide
@@ -87,64 +91,8 @@ including suggested commands for VS Code, Neovim, and Inkscape.
 
 This button only appears under `inkflow serve`, not in a static build.
 
-## Using a second screen
-
-To present on a projector while keeping the panel on your laptop screen,
-click the "Open a synced window" button in the status bar.
-It opens another window at the same position
-(see [Multi-window sync](#multi-window-sync) for what makes this work in a static build).
-In the window on your laptop screen, press <kbd>p</kbd> to open the panel.
-Leave the other window full-screen on the projector.
-
-Navigation in either window is broadcast to the other,
-so both stay in sync regardless of which one you use to advance.
-
-## Multi-window sync
-
-How position sync reaches other windows depends on how the deck is running:
-
-- **`inkflow serve`** relays it over the same WebSocket the main view uses for live reload.
-  Any number of windows can be open at once,
-  connected however you like: a fresh tab, another browser, even another device on the network.
-- **`inkflow build` output** (including a bare `file://` double-click, with no server at all)
-  has no WebSocket to relay over,
-  so it syncs exactly **two** windows directly:
-  the one you launch "Open a synced window" from, and the window it opens.
-  They talk to each other over a direct browser-to-browser link
-  that only exists between opener and opened window,
-  so a second window opened independently
-  (a fresh tab typed in by hand, rather than via the button) will not join the sync.
-
-Within either mode:
-
-- A navigation in one window is broadcast to the other(s).
-- A window opened at the bare URL (via the button) adopts the shared position on
-  connect, so it lands where the presenter already is (second-screen follow).
-- A window opened at a deliberate deep link (a URL naming a slide, such as
-  `#slide=5`) keeps that slide instead of being pulled to the shared position. A
-  browser refresh counts as a deep link, so reloading never yanks a window off its
-  slide. The slide lives in the URL fragment so the link works the same whether
-  the deck is served, hosted as a static build, or opened straight from disk.
-- Under `serve`, the position is preserved across a deck rebuild (clamped if the
-  slide count drops).
-
-The [sync modes](#sync-modes) below (two-way/present/follow/solo) work identically
-in both cases — only the transport between windows differs.
-
-### Sync modes
-
-Each window chooses how it participates, independent of the others. Cycle the mode
-with <kbd>s</kbd>, or click the sync button in the status bar and pick from the menu.
-The button shows the active mode and tints when it is anything but two-way.
-
-| mode | broadcasts its navigation | follows other windows |
-|------|:---:|:---:|
-| **Two-way** (default) | yes | yes |
-| **Present** | yes | no |
-| **Follow** | no | yes |
-| **Solo** | no | no |
-
-Use **Present** on the window you drive from and **Follow** on a screen that should
-only ever track it, so an accidental key press on the follower cannot move the deck.
-Switching a window into Follow (or Two-way) immediately catches it up to the current
-position. The choice is remembered per browser tab across reloads.
+## Presenting on a second screen
+
+Open the deck in two windows: the panel on your laptop, the stage on the projector.
+Both stay in sync as you navigate.
+See [Multi-window sync](sync.md).
diff --git a/docs/presenting/sync.md b/docs/presenting/sync.md
new file mode 100644
index 00000000..1ba44b77
--- /dev/null
+++ b/docs/presenting/sync.md
@@ -0,0 +1,66 @@
+# Multi-window sync
+
+Open the deck in more than one window and they follow each other.
+This is what makes a second screen work:
+the projector shows the stage full-screen
+while your laptop shows the same deck with the
+[presenter panel](presenter-panel.md) open.
+
+## Setting up a second screen
+
+1. Click **Open a synced window** in the status bar.
+   It opens a second window at the current position.
+2. Drag that window to the projector and press <kbd>f</kbd> for fullscreen.
+3. In the original window, press <kbd>p</kbd> to open the presenter panel.
+
+Navigating in either window moves both,
+so it does not matter which one you drive from.
+
+## How windows find each other
+
+The transport depends on how the deck is running,
+though the behaviour is the same either way.
+
+**Under `inkflow serve`,** position travels over the same WebSocket used for live
+reload. Any number of windows can join, in any browser, including another device
+on the network. Just open the URL.
+
+**In an exported build,** including a deck opened straight from disk with no
+server at all, there is no WebSocket. Two windows sync directly instead:
+the one you clicked the button in, and the one it opened.
+A window opened by hand in a new tab will not join,
+because the direct link only exists between opener and opened.
+
+## Which slide a new window lands on
+
+- A window opened at the bare URL adopts the shared position,
+  so a second screen lands where you already are.
+- A window opened at a link naming a slide, such as `#slide=5`, keeps that slide.
+  A refresh counts as such a link, so reloading never pulls a window off its slide.
+- Under `serve`, position survives a rebuild, clamped if the deck got shorter.
+
+The slide lives in the URL fragment, so a link behaves the same whether the deck
+is served, hosted as a static build, or opened from disk.
+
+## Sync modes
+
+Each window decides for itself how it participates.
+Cycle with <kbd>s</kbd>, or click the sync button in the status bar.
+The button shows the current mode and tints when it is anything but two-way.
+
+| Mode | Broadcasts its navigation | Follows other windows |
+|---|:---:|:---:|
+| **Two-way** (default) | yes | yes |
+| **Present** | yes | no |
+| **Follow** | no | yes |
+| **Solo** | no | no |
+
+Put the window you drive on **Present** and the projector on **Follow**,
+and a stray keypress on the projector cannot move the deck.
+
+Switching into Follow or Two-way catches that window up immediately.
+The choice is remembered per browser tab across reloads.
+
+!!! note
+    [Zoom](index.md#drawing-attention) is never synced.
+    Magnifying a detail on your own screen leaves the projector alone.
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index bdead89b..1d1281df 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -59,7 +59,7 @@ separate from these sinks; enabling the file sink also captures its traceback.
 
 ## Editing from the presenter
 
-The presenter's Edit button (see [Presenter panel](../guides/presenter-view.md))
+The presenter's Edit button (see [Presenter panel](../presenting/presenter-panel.md))
 copies the current slide's source path to the clipboard by default.
 Set `INKFLOW_EDIT_CMD` to launch an editor instead, for every file kind,
 with `{path}` substituted (appended as a final argument if the template has no
diff --git a/docs/reference/theme.md b/docs/reference/theme.md
index 6efc00f0..13cda874 100644
--- a/docs/reference/theme.md
+++ b/docs/reference/theme.md
@@ -19,7 +19,7 @@ class MyTheme(Theme):
 Deck(theme=MyTheme())
 ```
 
-See the [Themes guide](../guides/themes.md) for the full workflow, including how a
+See the [Themes guide](../design/themes.md) for the full workflow, including how a
 theme ships its own layouts and fonts.
 
 ::: inkflow.themes.Theme
diff --git a/mkdocs.yml b/mkdocs.yml
index b68a310e..38a1bee0 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -71,14 +71,25 @@ nav:
   - Demo: demo/index.html
   - Getting started: getting-started.md
   - Concepts: concepts.md
-  - Guides:
-    - Authoring slides: guides/slides.md
-    - Layout system: guides/layout-system.md
-    - Transitions: guides/transitions.md
-    - Themes: guides/themes.md
-    - Fonts: guides/fonts.md
-    - Export: guides/export.md
-    - Presenter view: guides/presenter-view.md
+  - Authoring:
+    - Slides: authoring/slides.md
+    - Markdown content: authoring/markdown.md
+    - Steps: authoring/steps.md
+    - Animations: authoring/animations.md
+    - Transitions: authoring/transitions.md
+    - Morph in depth: authoring/morph.md
+    - Working in Inkscape: authoring/inkscape.md
+  - Layouts and themes:
+    - Layouts: design/layouts.md
+    - Overlays: design/overlays.md
+    - Themes: design/themes.md
+    - Fonts: design/fonts.md
+    - Built-in theme: built-in-theme/index.md
+  - Presenting:
+    - Presenting a deck: presenting/index.md
+    - Presenter panel: presenting/presenter-panel.md
+    - Multi-window sync: presenting/sync.md
+    - Export: presenting/export.md
   - Reference:
     - Manifest: reference/manifest.md
     - Themes: reference/theme.md
@@ -86,4 +97,3 @@ nav:
     - Animations: reference/animations.md
     - Transitions: reference/transitions.md
     - CLI: reference/cli.md
-    - Built-in theme: built-in-theme/index.md
diff --git a/src/css/presenter/overlays.css b/src/css/presenter/overlays.css
index 0fef9c30..82c6dc5d 100644
--- a/src/css/presenter/overlays.css
+++ b/src/css/presenter/overlays.css
@@ -127,7 +127,7 @@ kbd {
     line-height: 1.6;
 }
 
-/* ── Message banner (non-modal, dismissible) ── */
+/* ── Diagnostics banner (non-modal, dismissible) ── */
 #log-banner {
     display: none;
     position: fixed;
@@ -206,14 +206,16 @@ kbd {
     color: var(--red);
 }
 
-/* ── Edit-action toast (non-modal) ──
-   Same corner and box treatment as #log-banner (surface/border/shadow), an
-   accent colour instead of its warning yellow. Times itself out (edit.ts) but
+/* ── Notification toast (non-modal) ──
+   Same corner and box treatment as #log-banner (surface/border/shadow); its
+   accent colour and icon are driven by data-style, the same green/yellow/red
+   vocabulary as inkflow.logging's report(). Always times itself out (ui.ts) but
    also offers a close button, like #log-banner, plus a bar along the bottom
    edge filling left-to-right as it approaches that — purely CSS (an animation
-   timed to match edit.ts's setTimeout), restarted by re-toggling .visible so a
-   second edit in quick succession doesn't inherit the first one's progress. */
-#edit-toast {
+   timed to match ui.ts's setTimeout), restarted by re-toggling .visible so a
+   second notification in quick succession doesn't inherit the first one's
+   progress. */
+#notify {
     display: none;
     position: fixed;
     right: 1rem;
@@ -231,24 +233,24 @@ kbd {
     overflow: hidden;
     pointer-events: none;
 }
-#edit-toast.visible {
+#notify.visible {
     display: flex;
 }
-#edit-toast-body {
+#notify-body {
     display: flex;
     align-items: flex-start;
     gap: 0.4rem;
     padding: 0.5rem 0.5rem 0.5rem 0.75rem;
 }
-#edit-toast svg {
+#notify svg {
     color: var(--green);
     flex-shrink: 0;
     margin-top: 0.15rem;
 }
-#edit-toast-text {
+#notify-text {
     word-break: break-word;
 }
-#edit-toast-close {
+#notify-close {
     background: none;
     border: none;
     color: var(--subtext);
@@ -259,16 +261,16 @@ kbd {
     flex-shrink: 0;
     pointer-events: auto;
 }
-#edit-toast-close:hover {
+#notify-close:hover {
     color: var(--text);
 }
-#edit-toast-progress {
+#notify-progress {
     height: 2px;
     background: var(--green);
     transform-origin: left;
-    animation: edit-toast-grow 3s linear forwards;
+    animation: notify-grow 3s linear forwards;
 }
-@keyframes edit-toast-grow {
+@keyframes notify-grow {
     from {
         transform: scaleX(0);
     }
@@ -276,24 +278,134 @@ kbd {
         transform: scaleX(1);
     }
 }
-/* Error state: launching the configured command failed (e.g. the binary isn't
-   on PATH) — red instead of green, the error glyph instead of the checkmark,
-   and no progress bar, since an error toast has no auto-dismiss timer to show
-   the progress of. Declared last so it reliably overrides the base rules above
-   regardless of its own (lower) specificity. */
-.edit-toast-icon-error {
+/* Non-default styles: yellow (warning) and red (error) each swap the border,
+   progress-bar colour and icon. Declared last so they reliably override the
+   base rules above regardless of their own (lower) specificity. */
+.notify-icon-warning,
+.notify-icon-error {
     display: none;
 }
-#edit-toast.error {
+#notify[data-style="yellow"] .notify-icon-ok,
+#notify[data-style="red"] .notify-icon-ok {
+    display: none;
+}
+#notify[data-style="yellow"] {
+    border-color: var(--yellow);
+}
+#notify[data-style="yellow"] #notify-progress {
+    background: var(--yellow);
+}
+#notify[data-style="yellow"] .notify-icon-warning {
+    display: block;
+    color: var(--yellow);
+}
+#notify[data-style="red"] {
     border-color: var(--red);
 }
-#edit-toast.error .edit-toast-icon-ok {
-    display: none;
+#notify[data-style="red"] #notify-progress {
+    background: var(--red);
 }
-#edit-toast.error .edit-toast-icon-error {
+#notify[data-style="red"] .notify-icon-error {
     display: block;
     color: var(--red);
 }
-#edit-toast.error #edit-toast-progress {
+
+/* ── Messages dialog (modal) ──
+   Same box treatment as #help-box. Its status-bar button is always visible
+   (unlike #log-indicator, which only appears once there's something to show) —
+   see ui.ts for why. */
+#notify-history {
     display: none;
+    position: fixed;
+    inset: 0;
+    z-index: 30;
+    background: rgba(0, 0, 0, 0.6);
+    align-items: center;
+    justify-content: center;
+}
+#notify-history.visible {
+    display: flex;
+}
+#notify-history-box {
+    background: var(--surface);
+    border: 1px solid var(--accent);
+    border-radius: 8px;
+    padding: 1.5rem 2rem;
+    min-width: 26rem;
+    max-width: 32rem;
+    max-height: 70vh;
+    display: flex;
+    flex-direction: column;
+}
+#notify-history-head {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    margin-bottom: 1rem;
+    flex-shrink: 0;
+}
+#notify-history-head h2 {
+    color: var(--accent);
+    font-size: 0.85rem;
+    letter-spacing: 0.05em;
+}
+#notify-history-close {
+    background: none;
+    border: none;
+    color: var(--subtext);
+    font-size: 1.1rem;
+    line-height: 1;
+    cursor: pointer;
+    padding: 0 0.25rem;
+}
+#notify-history-close:hover {
+    color: var(--text);
+}
+#notify-history-list {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+    overflow-y: auto;
+}
+/* .nh-row rather than a bare `li` selector: keeps this at least as specific as
+   #log-list's own `li + li` elsewhere in this file, so biome's
+   noDescendingSpecificity check (selector order across the whole file) has
+   nothing to flag. */
+#notify-history-list .nh-row {
+    display: flex;
+    gap: 0.5rem;
+    align-items: baseline;
+    font-size: 0.8rem;
+    line-height: 1.6;
+    color: var(--text);
+    padding: 0.3rem 0;
+}
+#notify-history-list .nh-row + .nh-row {
+    border-top: 1px solid var(--overlay);
+}
+#notify-history-list .nh-time {
+    flex-shrink: 0;
+    color: var(--subtext);
+    font-variant-numeric: tabular-nums;
+}
+#notify-history-list .nh-ico {
+    flex-shrink: 0;
+}
+#notify-history-list .nh-ico.nh-green {
+    color: var(--green);
+}
+#notify-history-list .nh-ico.nh-yellow {
+    color: var(--yellow);
+}
+#notify-history-list .nh-ico.nh-red {
+    color: var(--red);
+}
+#notify-history-list .nh-message {
+    word-break: break-word;
+}
+#notify-history-empty {
+    color: var(--subtext);
+    text-align: center;
+    justify-content: center;
+    padding: 1rem 0;
 }
diff --git a/src/inkflow/bundles/presenter.css b/src/inkflow/bundles/presenter.css
index e7b5cf6f..8a66b738 100644
--- a/src/inkflow/bundles/presenter.css
+++ b/src/inkflow/bundles/presenter.css
@@ -435,7 +435,7 @@ kbd {
 #log-list li.log-error {
   color: var(--red);
 }
-#edit-toast {
+#notify {
   display: none;
   position: fixed;
   right: 1rem;
@@ -453,24 +453,24 @@ kbd {
   overflow: hidden;
   pointer-events: none;
 }
-#edit-toast.visible {
+#notify.visible {
   display: flex;
 }
-#edit-toast-body {
+#notify-body {
   display: flex;
   align-items: flex-start;
   gap: 0.4rem;
   padding: 0.5rem 0.5rem 0.5rem 0.75rem;
 }
-#edit-toast svg {
+#notify svg {
   color: var(--green);
   flex-shrink: 0;
   margin-top: 0.15rem;
 }
-#edit-toast-text {
+#notify-text {
   word-break: break-word;
 }
-#edit-toast-close {
+#notify-close {
   background: none;
   border: none;
   color: var(--subtext);
@@ -481,16 +481,16 @@ kbd {
   flex-shrink: 0;
   pointer-events: auto;
 }
-#edit-toast-close:hover {
+#notify-close:hover {
   color: var(--text);
 }
-#edit-toast-progress {
+#notify-progress {
   height: 2px;
   background: var(--green);
   transform-origin: left;
-  animation: edit-toast-grow 3s linear forwards;
+  animation: notify-grow 3s linear forwards;
 }
-@keyframes edit-toast-grow {
+@keyframes notify-grow {
   from {
     transform: scaleX(0);
   }
@@ -498,21 +498,124 @@ kbd {
     transform: scaleX(1);
   }
 }
-.edit-toast-icon-error {
+.notify-icon-warning,
+.notify-icon-error {
   display: none;
 }
-#edit-toast.error {
+#notify[data-style=yellow] .notify-icon-ok,
+#notify[data-style=red] .notify-icon-ok {
+  display: none;
+}
+#notify[data-style=yellow] {
+  border-color: var(--yellow);
+}
+#notify[data-style=yellow] #notify-progress {
+  background: var(--yellow);
+}
+#notify[data-style=yellow] .notify-icon-warning {
+  display: block;
+  color: var(--yellow);
+}
+#notify[data-style=red] {
   border-color: var(--red);
 }
-#edit-toast.error .edit-toast-icon-ok {
-  display: none;
+#notify[data-style=red] #notify-progress {
+  background: var(--red);
 }
-#edit-toast.error .edit-toast-icon-error {
+#notify[data-style=red] .notify-icon-error {
   display: block;
   color: var(--red);
 }
-#edit-toast.error #edit-toast-progress {
+#notify-history {
   display: none;
+  position: fixed;
+  inset: 0;
+  z-index: 30;
+  background: rgba(0, 0, 0, 0.6);
+  align-items: center;
+  justify-content: center;
+}
+#notify-history.visible {
+  display: flex;
+}
+#notify-history-box {
+  background: var(--surface);
+  border: 1px solid var(--accent);
+  border-radius: 8px;
+  padding: 1.5rem 2rem;
+  min-width: 26rem;
+  max-width: 32rem;
+  max-height: 70vh;
+  display: flex;
+  flex-direction: column;
+}
+#notify-history-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 1rem;
+  flex-shrink: 0;
+}
+#notify-history-head h2 {
+  color: var(--accent);
+  font-size: 0.85rem;
+  letter-spacing: 0.05em;
+}
+#notify-history-close {
+  background: none;
+  border: none;
+  color: var(--subtext);
+  font-size: 1.1rem;
+  line-height: 1;
+  cursor: pointer;
+  padding: 0 0.25rem;
+}
+#notify-history-close:hover {
+  color: var(--text);
+}
+#notify-history-list {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  overflow-y: auto;
+}
+#notify-history-list .nh-row {
+  display: flex;
+  gap: 0.5rem;
+  align-items: baseline;
+  font-size: 0.8rem;
+  line-height: 1.6;
+  color: var(--text);
+  padding: 0.3rem 0;
+}
+#notify-history-list .nh-row + .nh-row {
+  border-top: 1px solid var(--overlay);
+}
+#notify-history-list .nh-time {
+  flex-shrink: 0;
+  color: var(--subtext);
+  font-variant-numeric: tabular-nums;
+}
+#notify-history-list .nh-ico {
+  flex-shrink: 0;
+}
+#notify-history-list .nh-ico.nh-green {
+  color: var(--green);
+}
+#notify-history-list .nh-ico.nh-yellow {
+  color: var(--yellow);
+}
+#notify-history-list .nh-ico.nh-red {
+  color: var(--red);
+}
+#notify-history-list .nh-message {
+  word-break: break-word;
+}
+#notify-history-empty {
+  color: var(--subtext);
+  text-align: center;
+  justify-content: center;
+  padding: 1rem 0;
 }
 
 /* src/css/presenter/picker.css */
diff --git a/src/inkflow/bundles/presenter.js b/src/inkflow/bundles/presenter.js
index 6b20d4ad..b7798fbf 100644
--- a/src/inkflow/bundles/presenter.js
+++ b/src/inkflow/bundles/presenter.js
@@ -27,17 +27,252 @@
     _laserMode: false
   };
 
+  // src/ts/presenter/ui.ts
+  var curtain = document.getElementById("curtain");
+  var help = document.getElementById("help");
+  var errorOverlay = document.getElementById("error-overlay");
+  var errorMsg = document.getElementById("error-msg");
+  var logBanner = document.getElementById("log-banner");
+  var logList = document.getElementById("log-list");
+  var logClose = document.getElementById("log-close");
+  var logIndicator = document.getElementById("log-indicator");
+  var statusBarEl = document.getElementById("statusbar");
+  var notify = document.getElementById("notify");
+  var notifyText = document.getElementById("notify-text");
+  var notifyClose = document.getElementById("notify-close");
+  var notifyHistoryBtn = document.getElementById("notify-history-btn");
+  var notifyHistoryEl = document.getElementById("notify-history");
+  var notifyHistoryList = document.getElementById("notify-history-list");
+  var notifyHistoryClose = document.getElementById("notify-history-close");
+  var _doc = document;
+  var _fsHideTimer;
+  function showCurtain(color) {
+    curtain.style.background = color;
+    curtain.classList.add("visible");
+  }
+  function hideCurtain() {
+    curtain.classList.remove("visible");
+  }
+  function toggleCurtain(color) {
+    curtain.classList.contains("visible") ? hideCurtain() : showCurtain(color);
+  }
+  function toggleHelp() {
+    help.classList.toggle("visible");
+  }
+  function showError(msg) {
+    errorMsg.textContent = msg;
+    errorOverlay.classList.add("visible");
+  }
+  function hideError() {
+    errorOverlay.classList.remove("visible");
+  }
+  var LOG_LEVEL_ORDER = {
+    debug: 0,
+    info: 1,
+    warning: 2,
+    error: 3
+  };
+  var LOG_ICON = {
+    debug: "\u25E6",
+    info: "\u2139\uFE0E",
+    warning: "\u26A0\uFE0E",
+    error: "\u2716\uFE0E"
+  };
+  function highestLevel(logs) {
+    return logs.reduce(
+      (top, e) => (LOG_LEVEL_ORDER[e.level] ?? 0) > (LOG_LEVEL_ORDER[top] ?? 0) ? e.level : top,
+      logs[0].level
+    );
+  }
+  var logSignature = "";
+  function showLogs(logs) {
+    if (logs.length === 0) {
+      hideLogs();
+      logSignature = "";
+      logIndicator.removeAttribute("data-level");
+      return;
+    }
+    const signature = JSON.stringify(logs);
+    const changed = signature !== logSignature;
+    logSignature = signature;
+    logList.replaceChildren(
+      ...logs.map((entry) => {
+        const li = document.createElement("li");
+        li.className = `log-${entry.level}`;
+        const ico = document.createElement("span");
+        ico.className = "log-ico";
+        ico.textContent = LOG_ICON[entry.level] ?? LOG_ICON.warning;
+        const msg = document.createElement("span");
+        msg.textContent = entry.message;
+        li.append(ico, msg);
+        return li;
+      })
+    );
+    logIndicator.dataset.level = highestLevel(logs);
+    if (changed) logBanner.classList.add("visible");
+  }
+  function hideLogs() {
+    logBanner.classList.remove("visible");
+  }
+  function toggleLogs() {
+    if (logBanner.classList.contains("visible")) {
+      hideLogs();
+    } else if (logIndicator.hasAttribute("data-level")) {
+      logBanner.classList.add("visible");
+    }
+  }
+  var notifyHistory = [];
+  var NOTIFY_DURATION_MS = 3e3;
+  var notifyTimeout = null;
+  function hideNotify() {
+    if (notifyTimeout) clearTimeout(notifyTimeout);
+    notify.classList.remove("visible");
+    notifyTimeout = null;
+  }
+  function showNotify(message, style = "green") {
+    notifyHistory.push({ message, style, time: Date.now() });
+    notifyText.textContent = message;
+    notify.dataset.style = style;
+    notify.classList.remove("visible");
+    void notify.offsetWidth;
+    notify.classList.add("visible");
+    if (notifyTimeout) clearTimeout(notifyTimeout);
+    notifyTimeout = setTimeout(hideNotify, NOTIFY_DURATION_MS);
+  }
+  var NOTIFY_HISTORY_ICON = {
+    green: "\u2713",
+    yellow: "\u26A0\uFE0E",
+    red: "\u2716\uFE0E"
+  };
+  function pad2(n) {
+    return String(n).padStart(2, "0");
+  }
+  function formatHistoryTime(time) {
+    const d = new Date(time);
+    return `${pad2(d.getHours())}:${pad2(d.getMinutes())}:${pad2(d.getSeconds())}`;
+  }
+  function renderNotifyHistory() {
+    if (notifyHistory.length === 0) {
+      const empty = document.createElement("li");
+      empty.id = "notify-history-empty";
+      empty.className = "nh-row";
+      empty.textContent = "No messages yet.";
+      notifyHistoryList.replaceChildren(empty);
+      return;
+    }
+    notifyHistoryList.replaceChildren(
+      ...notifyHistory.slice().reverse().map((entry) => {
+        const li = document.createElement("li");
+        li.className = "nh-row";
+        const time = document.createElement("span");
+        time.className = "nh-time";
+        time.textContent = formatHistoryTime(entry.time);
+        const ico = document.createElement("span");
+        ico.className = `nh-ico nh-${entry.style}`;
+        ico.textContent = NOTIFY_HISTORY_ICON[entry.style];
+        const msg = document.createElement("span");
+        msg.className = "nh-message";
+        msg.textContent = entry.message;
+        li.append(time, ico, msg);
+        return li;
+      })
+    );
+  }
+  function openNotifyHistory() {
+    renderNotifyHistory();
+    notifyHistoryEl.classList.add("visible");
+  }
+  function closeNotifyHistory() {
+    notifyHistoryEl.classList.remove("visible");
+  }
+  function toggleNotifyHistory() {
+    if (notifyHistoryEl.classList.contains("visible")) closeNotifyHistory();
+    else openNotifyHistory();
+  }
+  function toggleTheme() {
+    const html = document.documentElement;
+    html.dataset.theme = html.dataset.theme === "light" ? "" : "light";
+  }
+  function toggleFullscreen() {
+    if (!document.fullscreenElement)
+      document.documentElement.requestFullscreen();
+    else document.exitFullscreen();
+  }
+  function showFsBar() {
+    statusBarEl.classList.add("fs-visible");
+    clearTimeout(_fsHideTimer);
+    _fsHideTimer = void 0;
+  }
+  function scheduleFsHide() {
+    if (_fsHideTimer) return;
+    _fsHideTimer = setTimeout(() => {
+      statusBarEl.classList.remove("fs-visible");
+      _fsHideTimer = void 0;
+    }, 600);
+  }
+  function handleFullscreenChange() {
+    const isFS = !!(document.fullscreenElement || _doc.webkitFullscreenElement);
+    document.body.classList.toggle("is-fullscreen", isFS);
+    if (!isFS) {
+      statusBarEl.classList.remove("fs-visible");
+      clearTimeout(_fsHideTimer);
+      _fsHideTimer = void 0;
+    }
+  }
+  document.addEventListener("fullscreenchange", handleFullscreenChange);
+  document.addEventListener("webkitfullscreenchange", handleFullscreenChange);
+  document.addEventListener("mousemove", (e) => {
+    if (!document.fullscreenElement && !_doc.webkitFullscreenElement) return;
+    const inZone = e.clientX < window.innerWidth * 0.2 && e.clientY > window.innerHeight * 0.9;
+    if (inZone) showFsBar();
+    else scheduleFsHide();
+  });
+  statusBarEl.addEventListener("mouseenter", () => {
+    if (document.fullscreenElement || _doc.webkitFullscreenElement) showFsBar();
+  });
+  statusBarEl.addEventListener("mouseleave", () => {
+    if (document.fullscreenElement || _doc.webkitFullscreenElement)
+      scheduleFsHide();
+  });
+  var _mhudTimer;
+  function showMobileHud() {
+    document.body.classList.add("mobile-hud-visible");
+    clearTimeout(_mhudTimer);
+    _mhudTimer = setTimeout(() => {
+      document.body.classList.remove("mobile-hud-visible");
+      _mhudTimer = void 0;
+    }, 3e3);
+  }
+  function toggleMobileHud() {
+    if (document.body.classList.contains("mobile-hud-visible")) {
+      document.body.classList.remove("mobile-hud-visible");
+      clearTimeout(_mhudTimer);
+      _mhudTimer = void 0;
+    } else {
+      showMobileHud();
+    }
+  }
+  document.getElementById("mobile-hud").addEventListener("pointerdown", showMobileHud, { passive: true });
+  logClose.addEventListener("click", hideLogs);
+  logIndicator.addEventListener("click", () => {
+    logBanner.classList.add("visible");
+  });
+  notifyClose.addEventListener("click", hideNotify);
+  notifyHistoryBtn.addEventListener("click", toggleNotifyHistory);
+  notifyHistoryClose.addEventListener("click", closeNotifyHistory);
+  notifyHistoryEl.addEventListener("click", (e) => {
+    if (e.target === notifyHistoryEl) closeNotifyHistory();
+  });
+  curtain.addEventListener("click", hideCurtain);
+  help.addEventListener("click", (e) => {
+    if (e.target === help) toggleHelp();
+  });
+
   // src/ts/presenter/edit.ts
   var btnEdit = document.getElementById("btn-edit");
   var editMenu = document.getElementById("edit-menu");
   var editWrap = btnEdit.closest(".edit-wrap");
-  var editToast = document.getElementById("edit-toast");
-  var editToastText = document.getElementById("edit-toast-text");
-  var editToastClose = document.getElementById("edit-toast-close");
-  var TOAST_DURATION_MS = 3e3;
   var config = { default: false, svg: false };
-  var toastTimeout = null;
-  editToastClose.addEventListener("click", () => hideToast());
   var ROW_ICONS = {
     Layout: `<svg viewBox="0 0 16 16" width="14" height="14" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="2" y="3" width="12" height="10" rx="1"/></svg>`,
     Parent: `<svg viewBox="0 0 16 16" width="14" height="14" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M8 2 14 5.5 8 9 2 5.5 8 2Z"/><path d="M2 9 8 12.5 14 9"/></svg>`,
@@ -51,32 +286,15 @@
     }
     return config.default;
   }
-  function hideToast() {
-    if (toastTimeout) clearTimeout(toastTimeout);
-    editToast.classList.remove("visible");
-    toastTimeout = null;
-  }
-  function flashToast(message, kind = "success") {
-    editToastText.textContent = message;
-    editToast.classList.toggle("error", kind === "error");
-    editToast.classList.remove("visible");
-    void editToast.offsetWidth;
-    editToast.classList.add("visible");
-    if (toastTimeout) clearTimeout(toastTimeout);
-    toastTimeout = kind === "error" ? null : setTimeout(hideToast, TOAST_DURATION_MS);
-  }
-  function showEditError(message) {
-    flashToast(message, "error");
-  }
   function actOn(file) {
     if (isConfigured(file) && state.ws && state.ws.readyState === WebSocket.OPEN) {
       state.ws.send(JSON.stringify({ type: "edit", path: file.path }));
-      flashToast(`Opened ${file.name}`);
+      showNotify(`Opened ${file.name}`);
       return;
     }
     try {
       void navigator.clipboard.writeText(file.path);
-      flashToast(`Copied ${file.path}`);
+      showNotify(`Copied ${file.path}`);
     } catch (_) {
     }
   }
@@ -2671,166 +2889,6 @@
     });
   }
 
-  // src/ts/presenter/ui.ts
-  var curtain = document.getElementById("curtain");
-  var help = document.getElementById("help");
-  var errorOverlay = document.getElementById("error-overlay");
-  var errorMsg = document.getElementById("error-msg");
-  var logBanner = document.getElementById("log-banner");
-  var logList = document.getElementById("log-list");
-  var logClose = document.getElementById("log-close");
-  var logIndicator = document.getElementById("log-indicator");
-  var statusBarEl = document.getElementById("statusbar");
-  var _doc = document;
-  var _fsHideTimer;
-  function showCurtain(color) {
-    curtain.style.background = color;
-    curtain.classList.add("visible");
-  }
-  function hideCurtain() {
-    curtain.classList.remove("visible");
-  }
-  function toggleCurtain(color) {
-    curtain.classList.contains("visible") ? hideCurtain() : showCurtain(color);
-  }
-  function toggleHelp() {
-    help.classList.toggle("visible");
-  }
-  function showError(msg) {
-    errorMsg.textContent = msg;
-    errorOverlay.classList.add("visible");
-  }
-  function hideError() {
-    errorOverlay.classList.remove("visible");
-  }
-  var LOG_LEVEL_ORDER = {
-    debug: 0,
-    info: 1,
-    warning: 2,
-    error: 3
-  };
-  var LOG_ICON = {
-    debug: "\u25E6",
-    info: "\u2139\uFE0E",
-    warning: "\u26A0\uFE0E",
-    error: "\u2716\uFE0E"
-  };
-  function highestLevel(logs) {
-    return logs.reduce(
-      (top, e) => (LOG_LEVEL_ORDER[e.level] ?? 0) > (LOG_LEVEL_ORDER[top] ?? 0) ? e.level : top,
-      logs[0].level
-    );
-  }
-  var logSignature = "";
-  function showLogs(logs) {
-    if (logs.length === 0) {
-      hideLogs();
-      logSignature = "";
-      logIndicator.removeAttribute("data-level");
-      return;
-    }
-    const signature = JSON.stringify(logs);
-    const changed = signature !== logSignature;
-    logSignature = signature;
-    logList.replaceChildren(
-      ...logs.map((entry) => {
-        const li = document.createElement("li");
-        li.className = `log-${entry.level}`;
-        const ico = document.createElement("span");
-        ico.className = "log-ico";
-        ico.textContent = LOG_ICON[entry.level] ?? LOG_ICON.warning;
-        const msg = document.createElement("span");
-        msg.textContent = entry.message;
-        li.append(ico, msg);
-        return li;
-      })
-    );
-    logIndicator.dataset.level = highestLevel(logs);
-    if (changed) logBanner.classList.add("visible");
-  }
-  function hideLogs() {
-    logBanner.classList.remove("visible");
-  }
-  function toggleLogs() {
-    if (logBanner.classList.contains("visible")) {
-      hideLogs();
-    } else if (logIndicator.hasAttribute("data-level")) {
-      logBanner.classList.add("visible");
-    }
-  }
-  function toggleTheme() {
-    const html = document.documentElement;
-    html.dataset.theme = html.dataset.theme === "light" ? "" : "light";
-  }
-  function toggleFullscreen() {
-    if (!document.fullscreenElement)
-      document.documentElement.requestFullscreen();
-    else document.exitFullscreen();
-  }
-  function showFsBar() {
-    statusBarEl.classList.add("fs-visible");
-    clearTimeout(_fsHideTimer);
-    _fsHideTimer = void 0;
-  }
-  function scheduleFsHide() {
-    if (_fsHideTimer) return;
-    _fsHideTimer = setTimeout(() => {
-      statusBarEl.classList.remove("fs-visible");
-      _fsHideTimer = void 0;
-    }, 600);
-  }
-  function handleFullscreenChange() {
-    const isFS = !!(document.fullscreenElement || _doc.webkitFullscreenElement);
-    document.body.classList.toggle("is-fullscreen", isFS);
-    if (!isFS) {
-      statusBarEl.classList.remove("fs-visible");
-      clearTimeout(_fsHideTimer);
-      _fsHideTimer = void 0;
-    }
-  }
-  document.addEventListener("fullscreenchange", handleFullscreenChange);
-  document.addEventListener("webkitfullscreenchange", handleFullscreenChange);
-  document.addEventListener("mousemove", (e) => {
-    if (!document.fullscreenElement && !_doc.webkitFullscreenElement) return;
-    const inZone = e.clientX < window.innerWidth * 0.2 && e.clientY > window.innerHeight * 0.9;
-    if (inZone) showFsBar();
-    else scheduleFsHide();
-  });
-  statusBarEl.addEventListener("mouseenter", () => {
-    if (document.fullscreenElement || _doc.webkitFullscreenElement) showFsBar();
-  });
-  statusBarEl.addEventListener("mouseleave", () => {
-    if (document.fullscreenElement || _doc.webkitFullscreenElement)
-      scheduleFsHide();
-  });
-  var _mhudTimer;
-  function showMobileHud() {
-    document.body.classList.add("mobile-hud-visible");
-    clearTimeout(_mhudTimer);
-    _mhudTimer = setTimeout(() => {
-      document.body.classList.remove("mobile-hud-visible");
-      _mhudTimer = void 0;
-    }, 3e3);
-  }
-  function toggleMobileHud() {
-    if (document.body.classList.contains("mobile-hud-visible")) {
-      document.body.classList.remove("mobile-hud-visible");
-      clearTimeout(_mhudTimer);
-      _mhudTimer = void 0;
-    } else {
-      showMobileHud();
-    }
-  }
-  document.getElementById("mobile-hud").addEventListener("pointerdown", showMobileHud, { passive: true });
-  logClose.addEventListener("click", hideLogs);
-  logIndicator.addEventListener("click", () => {
-    logBanner.classList.add("visible");
-  });
-  curtain.addEventListener("click", hideCurtain);
-  help.addEventListener("click", (e) => {
-    if (e.target === help) toggleHelp();
-  });
-
   // src/ts/presenter/websocket.ts
   var wsDot = document.getElementById("ws-dot");
   var overviewEl = document.getElementById("overview");
@@ -2960,8 +3018,8 @@
         renderPv();
       } else if (msg.type === "error") {
         showError(msg.message);
-      } else if (msg.type === "edit-error") {
-        showEditError(msg.message);
+      } else if (msg.type === "notify") {
+        showNotify(msg.message, msg.style);
       } else if (msg.type === "position") {
         if (receives() && !msg.snap && firstPositionPending) {
           firstPositionPending = false;
@@ -3097,7 +3155,7 @@
       if (wsPort === null && state.windowLink) return;
       const child = window.open(location.href);
       if (!child) {
-        showLogs([{ level: "warning", message: POPUP_BLOCKED_MESSAGE }]);
+        showNotify(POPUP_BLOCKED_MESSAGE, "yellow");
         return;
       }
       if (wsPort === null) attachLink(child);
@@ -3696,7 +3754,8 @@
     "?": { action: toggleHelp },
     t: { action: toggleTheme },
     p: { action: togglePv },
-    m: { action: toggleLogs },
+    d: { action: toggleLogs },
+    m: { action: toggleNotifyHistory },
     s: { action: cycleSyncMode }
   };
   var helpEl = document.getElementById("help");
@@ -3704,6 +3763,7 @@
   var pickerEl = document.getElementById("picker");
   var curtainEl = document.getElementById("curtain");
   var logBannerEl = document.getElementById("log-banner");
+  var notifyHistoryEl2 = document.getElementById("notify-history");
   document.addEventListener("keydown", (e) => {
     if (helpEl.classList.contains("visible")) {
       if (e.key === "?" || e.key === "Escape" || e.key === "q") {
@@ -3712,6 +3772,12 @@
       }
       if (e.key !== "t") return;
     }
+    if (notifyHistoryEl2.classList.contains("visible")) {
+      if (e.key === "Escape" || e.key === "q" || e.key === "m") {
+        toggleNotifyHistory();
+      }
+      return;
+    }
     if (overviewEl2.classList.contains("visible")) {
       if (e.key === "Escape" || e.key === "q") {
         closeOverview();
diff --git a/src/inkflow/presenter.html b/src/inkflow/presenter.html
index c33073ad..b70999ee 100644
--- a/src/inkflow/presenter.html
+++ b/src/inkflow/presenter.html
@@ -18,25 +18,30 @@ <h2>BUILD ERROR</h2>
   </div>
   <div id="log-banner" role="status">
     <div id="log-head">
-      <span id="log-title">MESSAGES</span>
-      <button type="button" id="log-close" title="Dismiss" aria-label="Dismiss messages">×</button>
+      <span id="log-title">DIAGNOSTICS</span>
+      <button type="button" id="log-close" title="Dismiss" aria-label="Dismiss diagnostics">×</button>
     </div>
     <ul id="log-list"></ul>
   </div>
-  <div id="edit-toast" role="status">
-    <div id="edit-toast-body">
-      <svg class="edit-toast-icon-ok" viewBox="0 0 16 16" width="15" height="15" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+  <div id="notify" role="status">
+    <div id="notify-body">
+      <svg class="notify-icon-ok" viewBox="0 0 16 16" width="15" height="15" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
         <path d="M3 8.5 6.5 12 13 4.5"/>
       </svg>
-      <svg class="edit-toast-icon-error" viewBox="0 0 16 16" width="15" height="15" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+      <svg class="notify-icon-warning" viewBox="0 0 16 16" width="15" height="15" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+        <path d="M8 2.2 15.2 14H0.8z"/>
+        <line x1="8" y1="6.5" x2="8" y2="10"/>
+        <circle cx="8" cy="11.8" r="0.5" fill="currentColor" stroke="none"/>
+      </svg>
+      <svg class="notify-icon-error" viewBox="0 0 16 16" width="15" height="15" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
         <circle cx="8" cy="8" r="6.5"/>
         <line x1="5.8" y1="5.8" x2="10.2" y2="10.2"/>
         <line x1="10.2" y1="5.8" x2="5.8" y2="10.2"/>
       </svg>
-      <span id="edit-toast-text"></span>
-      <button type="button" id="edit-toast-close" title="Dismiss" aria-label="Dismiss">×</button>
+      <span id="notify-text"></span>
+      <button type="button" id="notify-close" title="Dismiss" aria-label="Dismiss">×</button>
     </div>
-    <div id="edit-toast-progress"></div>
+    <div id="notify-progress"></div>
   </div>
   <div id="curtain"></div>
   <div id="help" role="dialog" aria-modal="true">
@@ -62,6 +67,7 @@ <h2>KEYBINDINGS</h2>
         <tr class="kb-group"><td colspan="2">View</td></tr>
         <tr><td>t</td><td>Dark / light mode</td></tr>
         <tr><td>p</td><td>Presenter panel</td></tr>
+        <tr><td>d</td><td>Diagnostics</td></tr>
         <tr><td>m</td><td>Messages</td></tr>
         <tr id="help-sync-row"><td>s</td><td>Cycle sync mode</td></tr>
         <tr><td>?</td><td>This help</td></tr>
@@ -69,6 +75,15 @@ <h2>KEYBINDINGS</h2>
       <p>Press <kbd>?</kbd> or <kbd>Esc</kbd> to close</p>
     </div>
   </div>
+  <div id="notify-history" role="dialog" aria-modal="true" aria-label="Messages">
+    <div id="notify-history-box">
+      <div id="notify-history-head">
+        <h2>MESSAGES</h2>
+        <button type="button" id="notify-history-close" title="Close" aria-label="Close">×</button>
+      </div>
+      <ul id="notify-history-list"></ul>
+    </div>
+  </div>
   <div id="picker" role="dialog" aria-modal="true">
     <div id="picker-box">
       <input id="picker-input" type="text" placeholder="Go to slide…" autocomplete="off" spellcheck="false">
@@ -263,7 +278,7 @@ <h2>KEYBINDINGS</h2>
     <span class="sep">|</span>
     <span id="step-info">step –</span>
     <span class="hud-sep"></span>
-    <button type="button" class="hud-btn" id="log-indicator" data-tooltip="Show messages" aria-label="Show messages">
+    <button type="button" class="hud-btn" id="log-indicator" data-tooltip="Diagnostics" aria-label="Diagnostics">
       <svg class="log-ic log-ic-debug" viewBox="0 0 16 16" width="17" height="17" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" style="pointer-events:none">
         <circle cx="8" cy="8" r="4"/>
       </svg>
@@ -283,6 +298,16 @@ <h2>KEYBINDINGS</h2>
         <line x1="10.2" y1="5.8" x2="5.8" y2="10.2"/>
       </svg>
     </button>
+    <button type="button" class="hud-btn" id="notify-history-btn" data-tooltip="Messages" aria-label="Messages">
+      <svg viewBox="0 0 16 16" width="17" height="17" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" style="pointer-events:none">
+        <circle cx="2.5" cy="4" r="0.75" fill="currentColor" stroke="none"/>
+        <line x1="5.5" y1="4" x2="14" y2="4"/>
+        <circle cx="2.5" cy="8" r="0.75" fill="currentColor" stroke="none"/>
+        <line x1="5.5" y1="8" x2="14" y2="8"/>
+        <circle cx="2.5" cy="12" r="0.75" fill="currentColor" stroke="none"/>
+        <line x1="5.5" y1="12" x2="14" y2="12"/>
+      </svg>
+    </button>
     <span id="ws-dot"></span>
   </div>
 
diff --git a/src/inkflow/server.py b/src/inkflow/server.py
index 97bcb936..2cb47854 100644
--- a/src/inkflow/server.py
+++ b/src/inkflow/server.py
@@ -16,7 +16,7 @@
 from collections.abc import Awaitable, Callable
 from html import escape as escape_html
 from pathlib import Path
-from typing import TypedDict, cast
+from typing import Literal, TypedDict, cast
 from urllib.parse import unquote
 
 from rich.console import Console
@@ -193,6 +193,26 @@ async def broadcast(msg: str, sender: ServerConnection | None = None) -> None:
     _state["ws_clients"] -= dead
 
 
+NotifyStyle = Literal["green", "yellow", "red"]
+
+
+async def notify(
+    target: ServerConnection | None, message: str, *, style: NotifyStyle = "green"
+) -> None:
+    """Push a transient, colour-coded notification: to one client (a reply) when
+    `target` is given, otherwise to every connected client.
+
+    A pure transport primitive, independent of the rebuild-cycle log banner
+    (`collect_logs`) above. Whether the event is also worth a `logger` call is the
+    caller's decision, not this function's — the two are separate concerns.
+    """
+    payload = json.dumps({"type": "notify", "message": message, "style": style})
+    if target is None:
+        await broadcast(payload)
+    else:
+        await target.send(payload)
+
+
 # ── WebSocket handler ─────────────────────────────────────────────────────────
 
 
@@ -302,9 +322,7 @@ async def handler(websocket: ServerConnection) -> None:
                     if request is not None:
                         error = open_in_editor(*request)
                         if error is not None:
-                            await websocket.send(
-                                json.dumps({"type": "edit-error", "message": error})
-                            )
+                            await notify(websocket, error, style="red")
         finally:
             _state["ws_clients"].discard(websocket)
             logger.debug(f"client disconnected ({len(_state['ws_clients'])} total)")
diff --git a/src/ts/presenter/edit.test.ts b/src/ts/presenter/edit.test.ts
index 4163703b..37bc8e2f 100644
--- a/src/ts/presenter/edit.test.ts
+++ b/src/ts/presenter/edit.test.ts
@@ -7,18 +7,19 @@ import { afterEach, beforeEach, expect, test, vi } from "vitest";
 // per page load. So each test gets a fresh DOM fragment *and* a fresh module
 // instance via vi.resetModules() + dynamic import, mirroring transitions.test.ts,
 // rather than reusing one initEditMenu() call across tests.
+//
+// edit.ts imports ./ui (for showNotify), which captures its own DOM references
+// at module-evaluation time too, so the fixture needs ui.ts's required elements
+// as well as edit.ts's own — mirrors picker.test.ts / overview.test.ts.
 
 let initEditMenu: typeof import("./edit").initEditMenu;
 let renderEditButton: typeof import("./edit").renderEditButton;
-let showEditError: typeof import("./edit").showEditError;
 let menuOpened: typeof import("./menus").menuOpened;
 let state: typeof import("./state").state;
 let btnEdit: HTMLButtonElement;
 let editMenu: HTMLElement;
 let editWrap: HTMLElement;
-let editToast: HTMLElement;
-let editToastText: HTMLElement;
-let editToastClose: HTMLButtonElement;
+let notifyText: HTMLElement;
 
 beforeEach(async () => {
     document.body.innerHTML = `
@@ -26,28 +27,32 @@ beforeEach(async () => {
             <button id="btn-edit"></button>
             <div id="edit-menu"></div>
         </span>
-        <div id="edit-toast">
-            <div id="edit-toast-body">
-                <span id="edit-toast-text"></span>
-                <button id="edit-toast-close"></button>
+        <div id="curtain"></div>
+        <div id="help"></div>
+        <div id="error-overlay"></div>
+        <div id="error-msg"></div>
+        <div id="log-banner"><ul id="log-list"></ul><button id="log-close"></button></div>
+        <button id="log-indicator"></button>
+        <div id="statusbar"></div>
+        <div id="mobile-hud"></div>
+        <div id="notify">
+            <div id="notify-body">
+                <span id="notify-text"></span>
+                <button id="notify-close"></button>
             </div>
-            <div id="edit-toast-progress"></div>
+            <div id="notify-progress"></div>
         </div>
+        <button id="notify-history-btn"></button>
+        <div id="notify-history"><button id="notify-history-close"></button></div>
     `;
     vi.resetModules();
-    ({ initEditMenu, renderEditButton, showEditError } = await import(
-        "./edit"
-    ));
+    ({ initEditMenu, renderEditButton } = await import("./edit"));
     ({ menuOpened } = await import("./menus"));
     ({ state } = await import("./state"));
     btnEdit = document.getElementById("btn-edit") as HTMLButtonElement;
     editMenu = document.getElementById("edit-menu")!;
     editWrap = btnEdit.closest(".edit-wrap") as HTMLElement;
-    editToast = document.getElementById("edit-toast")!;
-    editToastText = document.getElementById("edit-toast-text")!;
-    editToastClose = document.getElementById(
-        "edit-toast-close",
-    ) as HTMLButtonElement;
+    notifyText = document.getElementById("notify-text")!;
     state.slides = [];
     state.slideIndex = 0;
     state.ws = null;
@@ -132,7 +137,9 @@ test("a single editable file still opens a (one-row) dropdown", () => {
     expect(editMenu.querySelectorAll(".edit-row").length).toBe(1);
 });
 
-test("clicking the lone row copies the full path and flashes a confirmation", () => {
+test("clicking the lone row copies the full path and shows a confirmation", () => {
+    // Timer/dismiss/style mechanics of the notification itself are covered by
+    // notify.test.ts — this only checks edit.ts hands showNotify the right text.
     state.slides = [
         slideWith({
             label: "Layout",
@@ -147,73 +154,9 @@ test("clicking the lone row copies the full path and flashes a confirmation", ()
         "/deck/slide.svg",
     );
     expect(editMenu.classList.contains("open")).toBe(false);
-    expect(editToast.classList.contains("visible")).toBe(true);
     // The full path, not just the filename — a bare "slide.svg" would read as
     // though only the name had been copied.
-    expect(editToastText.textContent).toBe("Copied /deck/slide.svg");
-});
-
-test("clicking the toast's close button dismisses it early", () => {
-    vi.useFakeTimers();
-    state.slides = [
-        slideWith({
-            label: "Layout",
-            name: "slide.svg",
-            path: "/deck/slide.svg",
-        }),
-    ];
-    initEditMenu({ svg: false, default: false }, 7778);
-    btnEdit.click();
-    editMenu.querySelector<HTMLButtonElement>(".edit-row")!.click();
-    expect(editToast.classList.contains("visible")).toBe(true);
-    editToastClose.click();
-    expect(editToast.classList.contains("visible")).toBe(false);
-    // The pending auto-hide timeout must also be cleared, not just overridden by
-    // the manual dismiss, otherwise it could re-fire (harmlessly, but sloppily)
-    // or clobber a *later* toast's own timer.
-    vi.advanceTimersByTime(3000);
-    expect(editToast.classList.contains("visible")).toBe(false);
-    vi.useRealTimers();
-});
-
-test("a second copy in quick succession restarts the auto-hide timer", () => {
-    vi.useFakeTimers();
-    state.slides = [
-        slideWith(
-            { label: "Layout", name: "a.svg", path: "/deck/a.svg" },
-            { label: "Content", name: "b.md", path: "/deck/b.md" },
-        ),
-    ];
-    initEditMenu({ svg: false, default: false }, 7778);
-    btnEdit.click();
-    editMenu.querySelectorAll<HTMLButtonElement>(".edit-row")[0].click();
-    vi.advanceTimersByTime(2000); // most of the way to the first toast's timeout
-    btnEdit.click();
-    editMenu.querySelectorAll<HTMLButtonElement>(".edit-row")[1].click();
-    vi.advanceTimersByTime(2000); // would have closed the first toast by now
-    expect(editToast.classList.contains("visible")).toBe(true);
-    expect(editToastText.textContent).toBe("Copied /deck/b.md");
-    vi.advanceTimersByTime(1000); // completes the second toast's own 3000ms
-    expect(editToast.classList.contains("visible")).toBe(false);
-    vi.useRealTimers();
-});
-
-test("the copy confirmation times itself out", () => {
-    vi.useFakeTimers();
-    state.slides = [
-        slideWith({
-            label: "Layout",
-            name: "slide.svg",
-            path: "/deck/slide.svg",
-        }),
-    ];
-    initEditMenu({ svg: false, default: false }, 7778);
-    btnEdit.click();
-    editMenu.querySelector<HTMLButtonElement>(".edit-row")!.click();
-    expect(editToast.classList.contains("visible")).toBe(true);
-    vi.advanceTimersByTime(3000);
-    expect(editToast.classList.contains("visible")).toBe(false);
-    vi.useRealTimers();
+    expect(notifyText.textContent).toBe("Copied /deck/slide.svg");
 });
 
 test("multiple editable files open a dropdown instead of acting directly", () => {
@@ -282,8 +225,7 @@ test("a configured command with a live WS connection sends an edit message inste
         JSON.stringify({ type: "edit", path: "/deck/slide.svg" }),
     );
     expect(navigator.clipboard.writeText).not.toHaveBeenCalled();
-    expect(editToast.classList.contains("visible")).toBe(true);
-    expect(editToastText.textContent).toBe("Opened slide.svg");
+    expect(notifyText.textContent).toBe("Opened slide.svg");
 });
 
 test("a configured command falls back to clipboard when the WS is not open", () => {
@@ -342,41 +284,3 @@ test("the general command also applies to SVG files when no SVG-specific overrid
     );
     expect(navigator.clipboard.writeText).not.toHaveBeenCalled();
 });
-
-test("showEditError shows a red, non-auto-dismissing toast", () => {
-    vi.useFakeTimers();
-    showEditError("failed to launch edit command 'nope': not found");
-    expect(editToast.classList.contains("visible")).toBe(true);
-    expect(editToast.classList.contains("error")).toBe(true);
-    expect(editToastText.textContent).toBe(
-        "failed to launch edit command 'nope': not found",
-    );
-    // Unlike a success toast, an error stays until dismissed — it's diagnostic
-    // text worth reading, not a transient confirmation.
-    vi.advanceTimersByTime(10_000);
-    expect(editToast.classList.contains("visible")).toBe(true);
-    vi.useRealTimers();
-});
-
-test("the close button dismisses an error toast too", () => {
-    showEditError("something went wrong");
-    editToastClose.click();
-    expect(editToast.classList.contains("visible")).toBe(false);
-});
-
-test("a success toast after an error clears the error styling", () => {
-    state.slides = [
-        slideWith({
-            label: "Layout",
-            name: "slide.svg",
-            path: "/deck/slide.svg",
-        }),
-    ];
-    showEditError("something went wrong");
-    expect(editToast.classList.contains("error")).toBe(true);
-    initEditMenu({ svg: false, default: false }, 7778);
-    btnEdit.click();
-    editMenu.querySelector<HTMLButtonElement>(".edit-row")!.click();
-    expect(editToast.classList.contains("error")).toBe(false);
-    expect(editToast.classList.contains("visible")).toBe(true);
-});
diff --git a/src/ts/presenter/edit.ts b/src/ts/presenter/edit.ts
index 06aab484..81c77009 100644
--- a/src/ts/presenter/edit.ts
+++ b/src/ts/presenter/edit.ts
@@ -1,6 +1,7 @@
 import type { EditableFile, EditCommandsConfig } from "../shared/types";
 import { menuClosed, menuOpened } from "./menus";
 import { state } from "./state";
+import { showNotify } from "./ui";
 
 // Status-bar control for editing the current slide's source file(s). Owns the
 // button + dropdown DOM (structurally mirrors syncmenu.ts).
@@ -22,17 +23,8 @@ import { state } from "./state";
 const btnEdit = document.getElementById("btn-edit")!;
 const editMenu = document.getElementById("edit-menu")!;
 const editWrap = btnEdit.closest<HTMLElement>(".edit-wrap")!;
-const editToast = document.getElementById("edit-toast")!;
-const editToastText = document.getElementById("edit-toast-text")!;
-const editToastClose = document.getElementById("edit-toast-close")!;
-
-// Must match the CSS animation duration on #edit-toast-progress (overlays.css).
-const TOAST_DURATION_MS = 3000;
 
 let config: EditCommandsConfig = { default: false, svg: false };
-let toastTimeout: ReturnType<typeof setTimeout> | null = null;
-
-editToastClose.addEventListener("click", () => hideToast());
 
 // One small icon per editableFiles label — a plain signifier, not decoration, so
 // entries with the same generic label (several "Parent" rows) still read apart at
@@ -54,43 +46,6 @@ function isConfigured(file: EditableFile): boolean {
     return config.default;
 }
 
-function hideToast(): void {
-    if (toastTimeout) clearTimeout(toastTimeout);
-    editToast.classList.remove("visible");
-    toastTimeout = null;
-}
-
-// Flashes a confirmation styled like the #log-banner message boxes (same
-// surface/border/shadow treatment, an accent colour instead of its warning
-// yellow), with its own close button and (for a success message) a shrinking
-// progress bar (pure CSS, see overlays.css) showing time left before it
-// dismisses itself. An error stays until manually dismissed — it's diagnostic
-// text the click that triggered it didn't expect, worth more than a glance.
-function flashToast(
-    message: string,
-    kind: "success" | "error" = "success",
-): void {
-    editToastText.textContent = message;
-    editToast.classList.toggle("error", kind === "error");
-    // Drop .visible and force a reflow before re-adding it, even if the toast is
-    // already showing (two edits in quick succession) — otherwise the browser
-    // never sees the class go away and won't restart the progress-bar animation.
-    editToast.classList.remove("visible");
-    void editToast.offsetWidth;
-    editToast.classList.add("visible");
-    if (toastTimeout) clearTimeout(toastTimeout);
-    toastTimeout =
-        kind === "error" ? null : setTimeout(hideToast, TOAST_DURATION_MS);
-}
-
-// Called from websocket.ts when the server replies with an "edit-error"
-// message: the configured command failed to launch (e.g. the binary isn't on
-// PATH). Without this, a failed launch was only ever logged server-side —
-// invisible from the browser tab where the click actually happened.
-export function showEditError(message: string): void {
-    flashToast(message, "error");
-}
-
 function actOn(file: EditableFile): void {
     if (
         isConfigured(file) &&
@@ -98,14 +53,14 @@ function actOn(file: EditableFile): void {
         state.ws.readyState === WebSocket.OPEN
     ) {
         state.ws.send(JSON.stringify({ type: "edit", path: file.path }));
-        flashToast(`Opened ${file.name}`);
+        showNotify(`Opened ${file.name}`);
         return;
     }
     try {
         void navigator.clipboard.writeText(file.path);
         // The full path, not just file.name: a bare filename here would read as
         // though only the name (not the whole path) had been copied.
-        flashToast(`Copied ${file.path}`);
+        showNotify(`Copied ${file.path}`);
     } catch (_) {}
 }
 
diff --git a/src/ts/presenter/keyboard.ts b/src/ts/presenter/keyboard.ts
index 77179b52..21a0bef7 100644
--- a/src/ts/presenter/keyboard.ts
+++ b/src/ts/presenter/keyboard.ts
@@ -26,6 +26,7 @@ import {
     toggleHelp,
     toggleLogs,
     toggleMobileHud,
+    toggleNotifyHistory,
     toggleTheme,
 } from "./ui";
 import { keyZoom, smoothResetCamera } from "./zoom";
@@ -140,7 +141,8 @@ const KEYBINDINGS: Record<
     "?": { action: toggleHelp },
     t: { action: toggleTheme },
     p: { action: togglePv },
-    m: { action: toggleLogs },
+    d: { action: toggleLogs },
+    m: { action: toggleNotifyHistory },
     s: { action: cycleSyncMode },
 };
 
@@ -150,6 +152,7 @@ const overviewEl = document.getElementById("overview")!;
 const pickerEl = document.getElementById("picker")!;
 const curtainEl = document.getElementById("curtain")!;
 const logBannerEl = document.getElementById("log-banner")!;
+const notifyHistoryEl = document.getElementById("notify-history")!;
 
 document.addEventListener("keydown", (e) => {
     if (helpEl.classList.contains("visible")) {
@@ -159,6 +162,12 @@ document.addEventListener("keydown", (e) => {
         }
         if (e.key !== "t") return;
     }
+    if (notifyHistoryEl.classList.contains("visible")) {
+        if (e.key === "Escape" || e.key === "q" || e.key === "m") {
+            toggleNotifyHistory();
+        }
+        return;
+    }
     if (overviewEl.classList.contains("visible")) {
         if (e.key === "Escape" || e.key === "q") {
             closeOverview();
diff --git a/src/ts/presenter/logs.test.ts b/src/ts/presenter/logs.test.ts
index fa31fa99..b52b7ec6 100644
--- a/src/ts/presenter/logs.test.ts
+++ b/src/ts/presenter/logs.test.ts
@@ -27,6 +27,9 @@ beforeAll(async () => {
         <button id="log-indicator"></button>
         <div id="statusbar"></div>
         <div id="mobile-hud"></div>
+        <button id="notify-close"></button>
+        <button id="notify-history-btn"></button>
+        <div id="notify-history"><button id="notify-history-close"></button></div>
     `;
     vi.resetModules();
     ({ showLogs, hideLogs, toggleLogs } = await import("./ui"));
diff --git a/src/ts/presenter/notify.test.ts b/src/ts/presenter/notify.test.ts
new file mode 100644
index 00000000..18f341be
--- /dev/null
+++ b/src/ts/presenter/notify.test.ts
@@ -0,0 +1,169 @@
+// @vitest-environment happy-dom
+import { beforeEach, expect, test, vi } from "vitest";
+
+// ui.ts captures DOM references and binds listeners at module-evaluation time, and
+// notifyHistory is a plain append-only in-memory array with no reset hook (by
+// design — see ui.ts) — so unlike logs.test.ts, each test needs a fresh module
+// instance via vi.resetModules() + dynamic import, mirroring edit.test.ts, rather
+// than sharing one module across tests.
+let showNotify: typeof import("./ui").showNotify;
+let openNotifyHistory: typeof import("./ui").openNotifyHistory;
+let closeNotifyHistory: typeof import("./ui").closeNotifyHistory;
+let toggleNotifyHistory: typeof import("./ui").toggleNotifyHistory;
+
+const notify = () => document.getElementById("notify")!;
+const notifyText = () => document.getElementById("notify-text")!;
+const notifyClose = () => document.getElementById("notify-close")!;
+const visible = () => notify().classList.contains("visible");
+
+const historyEl = () => document.getElementById("notify-history")!;
+const historyList = () => document.getElementById("notify-history-list")!;
+const historyBtn = () => document.getElementById("notify-history-btn")!;
+const historyClose = () => document.getElementById("notify-history-close")!;
+const historyOpen = () => historyEl().classList.contains("visible");
+const historyRows = () =>
+    Array.from(historyList().querySelectorAll("li")).filter(
+        (li) => li.id !== "notify-history-empty",
+    );
+
+beforeEach(async () => {
+    document.body.innerHTML = `
+        <div id="curtain"></div>
+        <div id="help"></div>
+        <div id="error-overlay"></div>
+        <div id="error-msg"></div>
+        <div id="log-banner"><ul id="log-list"></ul><button id="log-close"></button></div>
+        <button id="log-indicator"></button>
+        <div id="statusbar"></div>
+        <div id="mobile-hud"></div>
+        <div id="notify">
+            <div id="notify-body">
+                <span id="notify-text"></span>
+                <button id="notify-close"></button>
+            </div>
+            <div id="notify-progress"></div>
+        </div>
+        <div id="notify-history">
+            <div id="notify-history-box">
+                <button id="notify-history-close"></button>
+                <ul id="notify-history-list"></ul>
+            </div>
+        </div>
+        <button id="notify-history-btn"></button>
+    `;
+    vi.resetModules();
+    ({
+        showNotify,
+        openNotifyHistory,
+        closeNotifyHistory,
+        toggleNotifyHistory,
+    } = await import("./ui"));
+});
+
+test("shows the message and, by default, a green style", () => {
+    showNotify("Copied /deck/slide.svg");
+    expect(visible()).toBe(true);
+    expect(notifyText().textContent).toBe("Copied /deck/slide.svg");
+    expect(notify().dataset.style).toBe("green");
+});
+
+test("a warning or error notification carries its own style", () => {
+    showNotify("missing font", "yellow");
+    expect(notify().dataset.style).toBe("yellow");
+    showNotify("failed to launch edit command 'nope': not found", "red");
+    expect(notify().dataset.style).toBe("red");
+});
+
+test("clicking the close button dismisses it early", () => {
+    vi.useFakeTimers();
+    showNotify("Copied /deck/slide.svg");
+    expect(visible()).toBe(true);
+    notifyClose().click();
+    expect(visible()).toBe(false);
+    // The pending auto-hide timeout must also be cleared, not just overridden by
+    // the manual dismiss, otherwise it could re-fire (harmlessly, but sloppily)
+    // or clobber a *later* notification's own timer.
+    vi.advanceTimersByTime(3000);
+    expect(visible()).toBe(false);
+    vi.useRealTimers();
+});
+
+test("every style auto-dismisses, including red/yellow — there is no manual-only state", () => {
+    vi.useFakeTimers();
+    showNotify("failed to launch edit command 'nope': not found", "red");
+    expect(visible()).toBe(true);
+    vi.advanceTimersByTime(3000);
+    expect(visible()).toBe(false);
+    vi.useRealTimers();
+});
+
+test("a second notification in quick succession restarts the auto-hide timer", () => {
+    vi.useFakeTimers();
+    showNotify("Copied /deck/a.svg");
+    vi.advanceTimersByTime(2000); // most of the way to the first one's timeout
+    showNotify("Copied /deck/b.md");
+    vi.advanceTimersByTime(2000); // would have closed the first one by now
+    expect(visible()).toBe(true);
+    expect(notifyText().textContent).toBe("Copied /deck/b.md");
+    vi.advanceTimersByTime(1000); // completes the second one's own 3000ms
+    expect(visible()).toBe(false);
+    vi.useRealTimers();
+});
+
+// ── Message history ──
+
+test("opens to an empty state before any notification has fired", () => {
+    openNotifyHistory();
+    expect(historyOpen()).toBe(true);
+    expect(historyRows().length).toBe(0);
+    expect(historyList().textContent).toContain("No messages yet");
+});
+
+test("every showNotify call is recorded, newest first", () => {
+    showNotify("Copied /deck/a.svg");
+    showNotify("missing font", "yellow");
+    openNotifyHistory();
+    const rows = historyRows();
+    expect(rows.length).toBe(2);
+    expect(rows[0].textContent).toContain("missing font");
+    expect(rows[1].textContent).toContain("Copied /deck/a.svg");
+});
+
+test("a dismissed or auto-dismissed notification stays in history", () => {
+    vi.useFakeTimers();
+    showNotify("Copied /deck/a.svg");
+    vi.advanceTimersByTime(3000);
+    expect(visible()).toBe(false);
+    vi.useRealTimers();
+    openNotifyHistory();
+    expect(historyRows().length).toBe(1);
+});
+
+test("the history button toggles the dialog open and closed", () => {
+    historyBtn().click();
+    expect(historyOpen()).toBe(true);
+    historyBtn().click();
+    expect(historyOpen()).toBe(false);
+});
+
+test("the close button and clicking the backdrop both dismiss the dialog", () => {
+    openNotifyHistory();
+    historyClose().click();
+    expect(historyOpen()).toBe(false);
+    openNotifyHistory();
+    historyEl().dispatchEvent(new Event("click", { bubbles: true }));
+    expect(historyOpen()).toBe(false);
+});
+
+test("clicking inside the dialog box does not close it", () => {
+    openNotifyHistory();
+    historyList().dispatchEvent(new Event("click", { bubbles: true }));
+    expect(historyOpen()).toBe(true);
+    closeNotifyHistory();
+});
+
+test("toggleNotifyHistory is exported for the keyboard/click wiring", () => {
+    expect(historyOpen()).toBe(false);
+    toggleNotifyHistory();
+    expect(historyOpen()).toBe(true);
+});
diff --git a/src/ts/presenter/overview.test.ts b/src/ts/presenter/overview.test.ts
index 8463db36..30710192 100644
--- a/src/ts/presenter/overview.test.ts
+++ b/src/ts/presenter/overview.test.ts
@@ -49,7 +49,9 @@ beforeAll(async () => {
             <button id="btn-edit"></button>
             <div id="edit-menu"></div>
         </span>
-        <button id="edit-toast-close"></button>
+        <button id="notify-close"></button>
+        <button id="notify-history-btn"></button>
+        <div id="notify-history"><button id="notify-history-close"></button></div>
     `;
 
     // computeStageFlip() divides stage/thumbnail rect sizes; happy-dom has no
diff --git a/src/ts/presenter/picker.test.ts b/src/ts/presenter/picker.test.ts
index 1c6e6833..91e0b82d 100644
--- a/src/ts/presenter/picker.test.ts
+++ b/src/ts/presenter/picker.test.ts
@@ -43,7 +43,9 @@ beforeAll(async () => {
             <button id="btn-edit"></button>
             <div id="edit-menu"></div>
         </span>
-        <button id="edit-toast-close"></button>
+        <button id="notify-close"></button>
+        <button id="notify-history-btn"></button>
+        <div id="notify-history"><button id="notify-history-close"></button></div>
     `;
     vi.resetModules();
     ({ filterPicker } = await import("./picker"));
diff --git a/src/ts/presenter/ui.ts b/src/ts/presenter/ui.ts
index 010cf106..f64db3da 100644
--- a/src/ts/presenter/ui.ts
+++ b/src/ts/presenter/ui.ts
@@ -1,4 +1,4 @@
-import type { LogEntry } from "../shared/types";
+import type { LogEntry, NotifyStyle } from "../shared/types";
 
 const curtain = document.getElementById("curtain")!;
 const help = document.getElementById("help")!;
@@ -9,6 +9,13 @@ const logList = document.getElementById("log-list")!;
 const logClose = document.getElementById("log-close")!;
 const logIndicator = document.getElementById("log-indicator")!;
 const statusBarEl = document.getElementById("statusbar")!;
+const notify = document.getElementById("notify")!;
+const notifyText = document.getElementById("notify-text")!;
+const notifyClose = document.getElementById("notify-close")!;
+const notifyHistoryBtn = document.getElementById("notify-history-btn")!;
+const notifyHistoryEl = document.getElementById("notify-history")!;
+const notifyHistoryList = document.getElementById("notify-history-list")!;
+const notifyHistoryClose = document.getElementById("notify-history-close")!;
 
 // biome-ignore lint/suspicious/noExplicitAny: webkit prefix not in TS DOM lib
 const _doc = document as any;
@@ -119,6 +126,120 @@ export function toggleLogs(): void {
     }
 }
 
+// ── Notification toast ──
+// A transient, self-dismissing confirmation/warning/error, styled by the same
+// green/yellow/red vocabulary as inkflow.logging's report(). Pushed by the server
+// (websocket.ts's "notify" message) or called directly by a client-only action
+// (edit.ts's clipboard-copy confirmation, which never touches the server). Every
+// call is also recorded to the message history below, so a toast that
+// auto-dismissed unseen can still be found.
+
+interface NotifyHistoryEntry {
+    message: string;
+    style: NotifyStyle;
+    time: number;
+}
+
+const notifyHistory: NotifyHistoryEntry[] = [];
+
+// Must match the CSS animation duration on #notify-progress (overlays.css).
+const NOTIFY_DURATION_MS = 3000;
+
+let notifyTimeout: ReturnType<typeof setTimeout> | null = null;
+
+export function hideNotify(): void {
+    if (notifyTimeout) clearTimeout(notifyTimeout);
+    notify.classList.remove("visible");
+    notifyTimeout = null;
+}
+
+export function showNotify(
+    message: string,
+    style: NotifyStyle = "green",
+): void {
+    notifyHistory.push({ message, style, time: Date.now() });
+    notifyText.textContent = message;
+    notify.dataset.style = style;
+    // Drop .visible and force a reflow before re-adding it, even if a notification
+    // is already showing (two in quick succession) — otherwise the browser never
+    // sees the class go away and won't restart the progress-bar animation.
+    notify.classList.remove("visible");
+    void notify.offsetWidth;
+    notify.classList.add("visible");
+    if (notifyTimeout) clearTimeout(notifyTimeout);
+    notifyTimeout = setTimeout(hideNotify, NOTIFY_DURATION_MS);
+}
+
+// ── Messages (notification history) ──
+// An append-only record of every showNotify() call, in memory only (cleared on
+// reload — this answers "what did I just miss", not "what happened yesterday").
+// Deliberately named and keybound apart from #log-banner ("Diagnostics", d) so
+// the two don't read as the same feature: diagnostics are current build health
+// (repopulated wholesale each rebuild, only exist in relation to one that just
+// ran), this is a history of what *you* did (repopulated never — only grows),
+// and its own status-bar button is always visible rather than appearing on the
+// first message — it's a plain utility, not an alert.
+
+const NOTIFY_HISTORY_ICON: Record<NotifyStyle, string> = {
+    green: "✓",
+    yellow: "⚠︎",
+    red: "✖︎",
+};
+
+function pad2(n: number): string {
+    return String(n).padStart(2, "0");
+}
+
+function formatHistoryTime(time: number): string {
+    const d = new Date(time);
+    return `${pad2(d.getHours())}:${pad2(d.getMinutes())}:${pad2(d.getSeconds())}`;
+}
+
+function renderNotifyHistory(): void {
+    if (notifyHistory.length === 0) {
+        const empty = document.createElement("li");
+        empty.id = "notify-history-empty";
+        empty.className = "nh-row";
+        empty.textContent = "No messages yet.";
+        notifyHistoryList.replaceChildren(empty);
+        return;
+    }
+    notifyHistoryList.replaceChildren(
+        ...notifyHistory
+            .slice()
+            .reverse()
+            .map((entry) => {
+                const li = document.createElement("li");
+                li.className = "nh-row";
+                const time = document.createElement("span");
+                time.className = "nh-time";
+                time.textContent = formatHistoryTime(entry.time);
+                const ico = document.createElement("span");
+                ico.className = `nh-ico nh-${entry.style}`;
+                ico.textContent = NOTIFY_HISTORY_ICON[entry.style];
+                const msg = document.createElement("span");
+                msg.className = "nh-message";
+                msg.textContent = entry.message;
+                li.append(time, ico, msg);
+                return li;
+            }),
+    );
+}
+
+export function openNotifyHistory(): void {
+    renderNotifyHistory();
+    notifyHistoryEl.classList.add("visible");
+}
+
+export function closeNotifyHistory(): void {
+    notifyHistoryEl.classList.remove("visible");
+}
+
+export function toggleNotifyHistory(): void {
+    if (notifyHistoryEl.classList.contains("visible")) closeNotifyHistory();
+    else openNotifyHistory();
+}
+
 // ── Theme ──
 export function toggleTheme(): void {
     const html = document.documentElement;
@@ -207,6 +328,12 @@ logClose.addEventListener("click", hideLogs);
 logIndicator.addEventListener("click", () => {
     logBanner.classList.add("visible");
 });
+notifyClose.addEventListener("click", hideNotify);
+notifyHistoryBtn.addEventListener("click", toggleNotifyHistory);
+notifyHistoryClose.addEventListener("click", closeNotifyHistory);
+notifyHistoryEl.addEventListener("click", (e) => {
+    if (e.target === notifyHistoryEl) closeNotifyHistory();
+});
 curtain.addEventListener("click", hideCurtain);
 help.addEventListener("click", (e) => {
     if (e.target === help) toggleHelp();
diff --git a/src/ts/presenter/websocket.ts b/src/ts/presenter/websocket.ts
index 56a818f7..1c579c74 100644
--- a/src/ts/presenter/websocket.ts
+++ b/src/ts/presenter/websocket.ts
@@ -5,7 +5,6 @@ import type {
     TransitionData,
     WsMessage,
 } from "../shared/types";
-import { showEditError } from "./edit";
 import { renderPv, renderPvNext, updatePvInfo } from "./pv";
 import { state } from "./state";
 import {
@@ -15,7 +14,7 @@ import {
     snapStepRun,
 } from "./status";
 import { CUT, loadSlide, snapInflight } from "./transitions";
-import { hideError, showError, showLogs } from "./ui";
+import { hideError, showError, showLogs, showNotify } from "./ui";
 
 const wsDot = document.getElementById("ws-dot")!;
 // Direct DOM refs to avoid circular import with overview.ts
@@ -210,8 +209,8 @@ export function connectWS(wsPort: number | null, authoritative: boolean): void {
             renderPv();
         } else if (msg.type === "error") {
             showError(msg.message);
-        } else if (msg.type === "edit-error") {
-            showEditError(msg.message);
+        } else if (msg.type === "notify") {
+            showNotify(msg.message, msg.style);
         } else if (msg.type === "position") {
             // Discard exactly the stale connect-time push so an authoritative window
             // keeps its own position; later updates apply normally. Mirrors the
diff --git a/src/ts/presenter/windowsync.test.ts b/src/ts/presenter/windowsync.test.ts
index e1ae46d2..51c50953 100644
--- a/src/ts/presenter/windowsync.test.ts
+++ b/src/ts/presenter/windowsync.test.ts
@@ -41,7 +41,9 @@ beforeAll(async () => {
             <button id="btn-edit"></button>
             <div id="edit-menu"></div>
         </span>
-        <button id="edit-toast-close"></button>
+        <button id="notify-close"></button>
+        <button id="notify-history-btn"></button>
+        <div id="notify-history"><button id="notify-history-close"></button></div>
     `;
     ({ isSyncPayload } = await import("./windowsync"));
 });
diff --git a/src/ts/presenter/windowsync.ts b/src/ts/presenter/windowsync.ts
index 6118090a..c5cc4e4d 100644
--- a/src/ts/presenter/windowsync.ts
+++ b/src/ts/presenter/windowsync.ts
@@ -1,6 +1,6 @@
 import type { NavMessage } from "../shared/types";
 import { state } from "./state";
-import { showLogs } from "./ui";
+import { showNotify } from "./ui";
 import {
     applyIncomingPosition,
     currentNavMessage,
@@ -105,7 +105,7 @@ export function initWindowSync(wsPort: number | null): void {
         // whichever window happens to hold that name.
         const child = window.open(location.href);
         if (!child) {
-            showLogs([{ level: "warning", message: POPUP_BLOCKED_MESSAGE }]);
+            showNotify(POPUP_BLOCKED_MESSAGE, "yellow");
             return;
         }
         if (wsPort === null) attachLink(child);
diff --git a/src/ts/shared/types.ts b/src/ts/shared/types.ts
index d669fa16..c7ddcf1a 100644
--- a/src/ts/shared/types.ts
+++ b/src/ts/shared/types.ts
@@ -62,6 +62,11 @@ export interface NavMessage {
 // the two (or WsMessage's "position" variant below).
 export type SyncPosition = Omit<NavMessage, "type">;
 
+// The colour a notification carries — the same vocabulary as inkflow.logging's
+// report()/`_level_render` (green for a completed action, yellow for attention,
+// red for an error), so client and server never invent two severity dialects.
+export type NotifyStyle = "green" | "yellow" | "red";
+
 export type WsMessage =
     | {
           type: "update";
@@ -70,5 +75,5 @@ export type WsMessage =
           logs: LogEntry[];
       }
     | { type: "error"; message: string }
-    | { type: "edit-error"; message: string }
+    | { type: "notify"; message: string; style: NotifyStyle }
     | ({ type: "position" } & SyncPosition);