mdeck 3.10.1 → 3.11.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 3.11.0 — 2026-10-12
+
+- Time your talk. `time: 2m` in a slide's settings is how long to spend on it, `time: 20m` in the deck's the length of the talk; slides without a time share what is left. The presenter view counts down the time left on the slide and shows whether you are ahead of or behind the plan. `mdeck rehearse` (or **Rehearse** in the presenter view and on the launch page) times each slide as you go through the talk; at the end a table offers the times rounded to 15 seconds, to change in 15-second steps, and **Save to deck** writes them into the slides' settings without reloading the open windows. The editor has a Time field for each slide and a Length for the deck, and `mdeck check` reports a time it cannot read.
+- Under `mdeck run`, the presenter view has a button back to the launch page.
+- The presenter view's timer reads the clock instead of counting seconds, so it no longer falls behind, and carries on through a reload. **T** starts and pauses it.
+- mdeck's own words come in Arabic too: with `lang: ar`, or a file named `talk.ar.md`, the reader view, the control bar, polls, the phones' answer page and callout titles are Arabic.
+- Fixed on slides set from right to left: a palette-coloured drawing (an SVG mdeck places in the page) had its text run out of its box, and a citation in Latin script, such as (Roediger & Karpicke, 2006), was jumbled where it met Arabic text. Drawings now keep their own direction, and citations and references read in theirs.
+- The tour comes in English, German and Arabic (`examples/showcase/slides.en.md`, `.de.md`, `.ar.md`), each with its drawings in place; `mdeck run slides.en.md` switches between them with **L**. It now also shows citations and a word cloud for the room; the poll and citations examples it replaces are gone.
+- Fixed: on a slide with several areas (`:::slot`), a code block in one area turned the next area into code: its citations and footnotes showed as written, while those inside the code block were filled in. Citations and footnotes now leave code blocks and `inline code` alone, and the areas after one are prose again.
+- Deck components can share state across slides and windows: `import { useShared, useView } from 'mdeck/component'`. `useShared('count', 0)` works like `useState`, but every slide, the presenter's slide, the audience window, other windows in the browser and a paired iPad see the same value, and a window opened later gets it. `useView()` says which window a component is in. `mdeck/component` is the first part of mdeck that components may rely on; the authoring reference says what it promises and what stays mdeck's own.
+- A drawing that uses the palette (an SVG with `var(--…)`) builds up in the order its parts are numbered: `data-step="1"`, `data-step="2"` … reveal one press at a time, parts with the same number together, whatever their order in the file, which is also the order they are drawn in. Bare `data-step` parts still appear in document order. With hotspots on, `data-hotspot` on a part makes it a hotspot once it is shown.
+- Fixed: a drawing on two slides lost its arrowheads, gradients and `<use>` copies on the second, because `url(#…)` found the copy on the hidden first slide. Each copy in the page now gets ids of its own.
+- `mdeck check` looks at the deck's SVG drawings: palette names without a fallback, fixed colours that stay the same in every palette and in dark mode, style rules that reach the rest of the page, numbered and bare steps in one drawing, and `data-step` or `data-hotspot` in a drawing that uses no palette colour and so is shown as a picture.
+- The slide-writing skill draws diagrams as SVG in the palette's colours, builds them up with numbered steps and checks them in light and dark.
+- A deck shared in part, with `--slide` or `--no-polls`, keeps the time its slides were planned to take as its `time:`, so the presenter view's countdown fits the part. The note that slides with polls were left out now appears only when one of the chosen slides had a poll.
+- Fixed: a YouTube video in `<videoplayer>` showed "This video is unavailable" on a device that opened the deck through a server, such as a paired iPad. Such pages send no referrer, which YouTube requires of embedded players; the player now sends the deck's origin (never its path).
+- Fixed: in a deck with polls, every slide change in the presenter view read the whole deck several times over to find out whether it has any. On an iPad presenting a large deck, slides changed noticeably slower than in the audience window. The answer is now kept until the deck changes.
+- `--slide 3,5-7` for `mdeck send`, `mdeck build` and `mdeck pdf` keeps only these slides, for example the part of a deck shown in one lecture, with their drawings. The numbers count the slides as written, like `mdeck snapshot --slide` and `mdeck check --render`. A `<style>` written on a slide that is left out moves to the first slide kept, since it styles the whole deck; the same now holds for slides left out with `--no-polls`.
+- Fixed: a stroke or laser trail drawn on a paired iPad could stop short in the audience window. Two batches of ink could be on their way at once and arrive in the other order, and a batch lost to the network was gone; the window then dropped that piece and everything after it. Batches now go one after another, a lost one is sent again, and a piece that arrives early waits for the one before it. While the network or the server is gone, the iPad tries again less and less often, up to every five seconds, and keeps only the laser's and the zoom's last position.
+- Ink and the laser drawn on a paired iPad reach the audience window sooner: about 60 ms after the pen instead of 100 to 150 ms.
+- The laser's trail stays on the screen as long as the pen is down, also in the audience window and on paired devices, so a circle or an underline can be shown while you talk about it. Lifted, it retracts as before.
+- The presenter view's slide number is a field: type a number and press Enter (Go on an iPad) to jump to that slide, in the iPad's slide-only layout beside the arrows and in the speaker layout. The audience window and paired devices follow.
+
 ## 3.10.1 — 2026-10-11
 
 - Theme settings can be text: `type = "text"` for words a theme shows, such as Terminal's prompt. Authors write them as they should appear (`prompt: "~/demo $ "`), spaces included, and mdeck quotes them for the stylesheet; the editor shows a text box with the theme's own words. Before, such words could only be fixed in the theme.

package/README.md

@@ -31,6 +31,18 @@ Polls, scales, word clouds, open questions and numbers to guess. People scan the
 </tr>
 <tr>
 <td width="50%" valign="top">
+<a href="docs/site/images/features/hotspots.webp"><img src="docs/site/images/features/hotspots.webp" alt="The projector zoomed in on a table, and in front of it the presenter view showing the same slide with numbered keys on its code, table and formula"></a>
+<p><b><a href="https://gh.tschieber.de/mdeck/presenting.html#zoom-in-on-part-of-a-slide">Zoom into a chart, a table or a line of code</a></b><br>
+Turn on hotspots, and the presenter view puts a number on each picture, table, formula and code block. Press it, and the slide glides in until that part fills the projector; press it again to see the whole slide. The audience never sees the numbers.</p>
+</td>
+<td width="50%" valign="top">
+<a href="docs/site/images/features/languages.webp"><img src="docs/site/images/features/languages.webp" alt="The same slide with a Python example in English, German, Hindi and Farsi, the Farsi one running right to left"></a>
+<p><b><a href="https://gh.tschieber.de/mdeck/presenting.html#one-talk-in-several-languages">Give the talk in the room's language</a></b><br>
+Keep <code>talk.en.md</code> beside <code>talk.de.md</code>, and press <b>L</b> to switch languages in the middle of the talk: slides, notes and every screen change at once, and you stay on the same slide. Farsi, Arabic and Hebrew run right to left.</p>
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
 <a href="docs/site/images/features/citations.webp"><img src="docs/site/images/features/citations.webp" alt="A slide with author–year citations and the full references at its foot, over a slide that lists all references"></a>
 <p><b><a href="https://gh.tschieber.de/mdeck/more-content.html#cite-a-source">Cite your sources properly</a></b><br>
 Cite as in a paper, <code>[@knuth1984, p. 97]</code>, from the BibTeX, CSL-JSON or Hayagriva file you already keep. Each slide lists what it cites at its foot, in APA, Vancouver, Harvard or any CSL style.</p>
@@ -188,9 +200,8 @@ complete folder.
 
 | Example | Theme | What it demonstrates |
 |---|---|---|
-| [Tour](examples/showcase/slides.md) | Glass | Start here: each slide shows the Markdown beside what it becomes, from headings to layouts, live code, notes, drawing, zooming into a part, a poll and sharing |
+| [Tour](examples/showcase/slides.en.md) | Neue | Start here: each slide shows the Markdown beside what it becomes, from headings to layouts, live code, citations, notes, drawing, zooming into a part, timing the talk, a poll and a word cloud for the room, and sharing; in English, [German](examples/showcase/slides.de.md) and [Arabic](examples/showcase/slides.ar.md) |
 | [Python](examples/python/slides.en.md) | Academic | A real lesson: live code to try out, points revealed step by step, notes on every slide, a poll to check understanding; in English, [German](examples/python/slides.de.md), [Hindi](examples/python/slides.hi.md) and [Farsi](examples/python/slides.fa.md), switched in the presenter view |
-| [Poll](examples/poll/slides.md) | Neue | A join slide, then a poll, a scale, a word cloud and open questions; start it with `mdeck run slides.md --network` |
 | [Custom layouts](examples/custom-layouts/slides.md) | Neue | A deck-local comparison design and named regions |
 
 The docs home page embeds a short talk, and the screenshots above show Neue.

package/assets/base.css

@@ -183,7 +183,10 @@ deck-stage[data-ink-hidden] .slide-ink { display: none; }
 /* ── Code blocks ─────────────────────────────────────────────────────────── */
 .code-block { white-space: pre-wrap; overflow-x: hidden; }
 /* Code and maths read from left to right, also on a right-to-left slide. */
-.slide[dir="rtl"] :is(pre, code, kbd, samp, .katex, .code-block-wrapper) { direction: ltr; unicode-bidi: isolate; }
+.slide[dir="rtl"] :is(pre, code, kbd, samp, .katex, .code-block-wrapper, .themed-picture) { direction: ltr; unicode-bidi: isolate; }
+/* A citation and a reference read in their own direction: Latin names stay in
+   order beside Arabic text, and a reference list in Latin script stays left aligned. */
+.slide[dir="rtl"] .citation, .slide[dir="rtl"] .slide-citations .csl-entry { unicode-bidi: plaintext; }
 /* A bullet that points along the line points the other way. */
 .slide[dir="rtl"] .slide-body ul > li::before { scale: -1 1; }
 

package/docs/reference/authoring.md

@@ -67,6 +67,7 @@ Each `---` line starts a new slide. Frontmatter is only needed when you want a s
 | `csl` | `apa` | Citation style: `apa`, `vancouver`, `harvard1`, or a `.csl` file |
 | `nocite` | — | References to list without citing them; `['*']` lists the whole file |
 | `show.citations` | `true` | `false` leaves out each slide's own references above the footer |
+| `time` | — | How long the talk takes, such as `20m`: slides without their own `time` share what is left (see [Time your talk](../site/content/presenting.md#time-your-talk)) |
 | `hotspots` | `off` | Number keys zoom in on parts of a slide while presenting: `auto` (pictures, code, tables, formulas, videos, callouts, columns, polls and `data-hotspot` elements), `marked` (only `data-hotspot` elements) or `off` (1–9 go to slides) |
 
 ### Theme params
@@ -172,6 +173,7 @@ description: A short description shown under the title.
 | `section` | Section label shown in the slide header (auto-propagated — see below) |
 | `title` | Name in the outline and reader navigation, for slides without a heading (not shown on the slide) |
 | `hotspots` | This slide's own hotspots: `auto`, `marked`, `off` or `false` (see the deck field) |
+| `time` | How long to spend on the slide: `90s`, `2m`, `1m30s` or `1.5m`. The presenter view counts it down; `mdeck rehearse` measures and saves it |
 
 ### Section labels
 
@@ -543,7 +545,7 @@ A title written after the type on the `:::` line still wins over both.
 
 ## Language
 
-`lang` is the language of the whole deck. The page is marked with it, so screen readers pronounce the slides correctly and browsers hyphenate them. It also picks the words mdeck itself shows the audience: the reader view's buttons, the deck's control bar, polls on the slide and on phones, and callout titles. German (`de`) and English (`en`) are built in; for any other language the words stay English. A regional code such as `de-CH` uses the German words.
+`lang` is the language of the whole deck. The page is marked with it, so screen readers pronounce the slides correctly and browsers hyphenate them. It also picks the words mdeck itself shows the audience: the reader view's buttons, the deck's control bar, polls on the slide and on phones, and callout titles. English (`en`), German (`de`) and Arabic (`ar`) are built in; for any other language the words stay English. A regional code such as `de-CH` uses the German words.
 
 The presenter view, the launch page and the editor are tools for the author and always stay English.
 
@@ -709,9 +711,33 @@ palette's custom properties (`--bg`, `--surface`, `--ink`, `--ink-soft`,
 `--muted`, `--rule`, `--accent`, `--accent-2`, `--accent-3`, `--on-accent`) and follows the
 theme, palette and appearance. Give each a fallback (`var(--accent, #1f3fd1)`)
 for places that show the file on its own, set `fit: contain` to keep the whole
-drawing, prefix class names in its `<style>` because inline styles apply to the
-page, and avoid `id`s, since a slide can be shown more than once. Such SVGs stay
-files in single-file builds and travel inside the deck's code instead.
+drawing, and start every rule in its `<style>` with a class of the drawing's
+own (`.flow-box`), because inline styles apply to the page. Each copy in the
+page gets ids of its own, and `url(#…)` and `href="#…"` inside it follow them,
+so markers, gradients and `<use>` work on every slide that shows the drawing;
+`#id` selectors in its `<style>` do not. Such SVGs stay files in single-file
+builds and travel inside the deck's code instead.
+
+Being part of the slide, such a drawing can build up: `data-step` on its parts
+reveals them one press at a time. Numbered parts (`data-step="1"`,
+`data-step="2"` …) appear in the order of their numbers, and parts with the
+same number together, whatever their order in the file, which is also the order
+they are drawn in; the drawing's steps come where its first step is in the
+slide. Bare `data-step` parts appear in document order. With hotspots on,
+`data-hotspot` on a part makes it a hotspot once it is shown.
+
+```svg
+<g data-step="1" data-hotspot>…input…</g>
+<g data-step="1">…output…</g>
+<g data-step="2">…the arrow, drawn under both…</g>
+```
+
+`mdeck check` warns about a palette name without a fallback (`svg-fallback`),
+fixed colours that do not follow the palette or dark mode (`svg-fixed-colour`),
+style rules that reach beyond the drawing (`svg-style`), numbered and bare steps
+in one drawing (`svg-steps`), and `data-step` or `data-hotspot` in an SVG that
+uses no palette colour, which is shown as a picture and so cannot build up
+(`svg-not-inline`).
 
 A normal build copies referenced local images, video, and audio next to the HTML
 while preserving their deck-relative paths. This is the recommended distribution
@@ -822,6 +848,8 @@ While `mdeck run` runs, the answers are kept beside the deck in `<slides>.result
 
 `--no-polls` leaves slides with an activity or a join code (`<qrcode join />`) out of `mdeck send`, `mdeck build --reader` and `mdeck pdf`; without it they show as a record of the talk. Saved drawings follow the remaining slides.
 
+`--slide 3,5-7` keeps only these slides in `mdeck send`, `mdeck build` and `mdeck pdf`, numbered by their place in the deck as written. Drawings follow their slides, and `<style>` elements on the slides left out move to the first slide kept, since they style the whole deck.
+
 Rooms run inside `mdeck run` (add `--network` so phones can reach it) or on a server started with `mdeck server`, set in the deck:
 
 ```yaml
@@ -909,6 +937,39 @@ stays out of every other deck's bundle. Install such dependencies in a
 > hooks from `preact/hooks`. The build resolves those imports back to the
 > framework's own Preact, so the deck folder needs no Preact install.
 
+### Shared state across slides and windows
+
+A component can keep a value that every slide and every window of the talk
+share: the presenter's slide, the audience window, other deck windows in the
+same browser, and a paired iPad. Import it from `mdeck/component`:
+
+```jsx
+import { h } from 'preact'
+import { useShared, useView } from 'mdeck/component'
+
+export default function Counter() {
+  const [count, setCount] = useShared('count', 0)
+  return <button onClick={() => setCount(n => n + 1)}>{count}</button>
+}
+```
+
+- `useShared(name, initial)` returns the value and a function to set it, like
+  `useState`. `initial` stands in until a window sets one. Values must survive
+  JSON (numbers, text, lists, plain objects). The latest change wins.
+- A window opened later, or reloaded, gets the current values from the others.
+  Nothing is saved: when every window of the talk is closed, the values are gone.
+- `useView()` says which window the component is in: `presenter` (the
+  presenter view's slide), `audience`, `deck`, `follow` (a phone following the
+  talk), `preview` (the next-slide preview and the editor) or `reader`.
+  Previews, followers and the reader see shared values but do not change them.
+- Choose names that belong to your component, such as `countdown` or
+  `quiz:round`: every component in the deck shares one set of names.
+
+`mdeck/component` is the part of mdeck that components may rely on; it is
+kept stable across versions. A component renders inside its slide. Anything
+else it reaches, such as the page outside its slide, the `<deck-stage>`, mdeck's
+events or the presenter view, is not part of it and may change without notice.
+
 ---
 
 ## Inline HTML

package/docs/site/assets/site.css

@@ -68,6 +68,8 @@ h1 { font-size: clamp(32px, 3vw, 46px); margin: 0 0 24px; max-width: 23ch; }
 .welcome h1 { font-size: clamp(40px, 4.5vw, 63px); line-height: 1.08; max-width: 14ch; letter-spacing: -.055em; }
 .welcome article > p:first-of-type { font-size: 20px; line-height: 1.55; color: var(--secondary); max-width: 53ch; }
 .welcome article > p:nth-of-type(3) > a { display: inline-block; background: var(--blue); color: white; text-decoration: none; padding: 10px 19px; border-radius: 5px; font-size: 15px; font-weight: 600; }
+.welcome article > p:nth-of-type(3) { display: flex; flex-wrap: wrap; gap: 8px; }
+.welcome article > p:nth-of-type(3) > a + a { background: none; color: var(--blue); box-shadow: inset 0 0 0 1.5px var(--blue); }
 .welcome article { max-width: 820px; }
 .welcome article > :not(.features) { max-width: 76ch; }
 .features { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 36px 32px; margin: 24px 0 32px; }

package/docs/site/content/commands.md

@@ -11,6 +11,7 @@ For how the commands, the views and the servers fit together, see [Views, comman
 | `mdeck skill --install claude` | Teach your AI assistant to write mdeck slides ([details](claude-skill.html)) |
 | `mdeck new` | Make a presentation with guided questions |
 | `mdeck run my-talk.md` | Open the launch page: present, edit, check and send from one place; slides reload when you save |
+| `mdeck rehearse my-talk.md` | Rehearse the talk: each slide is timed, and the times can be saved into the deck ([details](presenting.html#rehearse)) |
 | `mdeck edit my-talk.md` | Edit slides, colors and themes in the browser; saves to the file |
 | `mdeck themes search`, `install <theme>`, `remove`, `update`, `list` | Themes: install more (each with its palette), remove the ones you do not use; see [Install, remove or share a theme](theme-repository.html) |
 | `mdeck palettes search`, `install <palette>`, … | The same for palettes |
@@ -32,7 +33,7 @@ For how the commands, the views and the servers fit together, see [Views, comman
 `mdeck run my-talk.md` opens a page on your own computer with everything for this talk. It is what the preview's plain address, such as `http://localhost:5173/`, shows; the slides themselves are at `?view=deck`.
 
 - **Preview:** a small live copy of the deck to flip through; click it to open the audience window at that slide.
-- **Present:** the presenter view, audience window and reader view, each in a new tab. The presenter view has notes, drawing controls, a timer and next-slide preview; switch to its slide-only layout for a single screen. The audience window shows slides without notes. Fullscreen is a control inside either view, not a separate view.
+- **Present:** the presenter view, audience window and reader view, each in a new tab. The presenter view has notes, drawing controls, a timer and next-slide preview; **Rehearse** opens it timing each slide; switch to its slide-only layout for a single screen. The audience window shows slides without notes. Fullscreen is a control inside either view, not a separate view.
 - **Write and learn:** the visual editor, the theme editor (themes and palettes on a sample deck, see [Install, remove or share a theme](theme-repository.html)) and these guides. Each starts the first time you click it.
 - **Send:** buttons that make the `dist` folder, one file to send, or a PDF, next to your slide file, and show them in your file manager.
 - **Polls:** for a deck with polls: the server (built in, or the `server` setting and whether it answers), the join link and session code for phones, and for a server of your own the key that lets your browser move the phones along and reset polls (see below).
@@ -94,6 +95,7 @@ The design page shows themes and palettes on a sample deck with every kind of sl
 | `mdeck send my-talk.md` | One file for readers: the reader view, speaker notes removed, a PDF inside |
 | `mdeck send my-talk.md --notes` | The same, keeping the speaker notes |
 | `mdeck send my-talk.md --no-polls` | The same, leaving out the slides with polls and their join codes |
+| `mdeck send my-talk.md --slide 12-30` | The same with only slides 12 to 30 and their drawings; also for `build` and `pdf` |
 | `mdeck send my-talk.md --no-pdf` | The same, without rendering the PDF |
 | `mdeck pdf my-talk.md -o talk.pdf` | Render the slides to a PDF file (`--no-polls` leaves out the slides with polls) |
 | `--no-drawings` | Leave out the drawings from `my-talk.drawings.json`, for `build`, `send` and `pdf` |

package/docs/site/content/drawing.md

@@ -11,7 +11,7 @@ Press **D** in standalone slides or in the presenter view, or use the pen button
 | Pen | Thin to thick with the pencil's pressure. Kept. |
 | Highlighter | A wide, see-through stroke in its own colours, always below the pen's strokes. Kept. |
 | Select and move | Draw a loop around strokes, or tap one, to select it; a finger's tap on a stroke selects it with any tool. Drag inside the dashed box with the pen to move it; a straight line shows handles at its ends, which the pen moves. **Delete** (or the toolbar's bin) removes the selection. |
-| Laser pointer | A red dot with a white core and a short trail that disappears by itself, for pointing at something. With a pencil that can hover, the dot follows it without touching. Never kept. |
+| Laser pointer | A red dot with a white core and a trail that stays as long as the pen or finger is down and disappears by itself once it is lifted, for pointing at something or circling it. With a pencil that can hover, the dot follows it without touching. Never kept. |
 | Eraser | Removes whole strokes you touch. |
 
 **Zoom**: two fingers zoom into the slide and move around it, one finger moves a zoomed slide, and Ctrl + scroll (a trackpad pinch) zooms on a laptop. Only the slide grows; the bars and the toolbar keep their size. The audience window shows the same part of the slide. **1:1** at the top left shows the whole slide again, as does the next slide. To zoom straight to a picture or a table with a number key, see [hotspots](presenting.html#zoom-in-on-part-of-a-slide).

package/docs/site/content/install.md

@@ -0,0 +1,47 @@
+# Install mdeck
+
+Three commands in a terminal, a few minutes in all. mdeck is published on npm, the package registry for JavaScript tools, as [mdeck](https://www.npmjs.com/package/mdeck).
+
+## 1. Install Node.js
+
+mdeck runs on [Node.js](https://nodejs.org) 22 or newer, which brings npm along. Check whether you have it:
+
+```sh
+node --version
+```
+
+A number of 22 or higher is enough. If the command is not found or the number is lower, install the LTS version from [nodejs.org](https://nodejs.org).
+
+## 2. Install mdeck
+
+```sh
+npm install -g mdeck
+```
+
+Check that it is ready:
+
+```sh
+mdeck --help
+```
+
+## 3. Teach your AI assistant
+
+```sh
+mdeck skill --install claude
+```
+
+Write `codex`, `cursor`, `copilot` or `gemini` instead of `claude` for those assistants. [Work with an AI assistant](claude-skill.html) says more.
+
+Then [make your first presentation](getting-started.html).
+
+## Update, check or remove
+
+| To | Run |
+|---|---|
+| Update to the newest version | `npm install -g mdeck` |
+| See which version you have | `npm list -g mdeck` |
+| Remove mdeck | `npm uninstall -g mdeck` |
+
+What each version brings is in the [changelog](https://github.com/tilman-schieber/mdeck/blob/main/CHANGELOG.md) and the [releases](https://github.com/tilman-schieber/mdeck/releases). After an update, run `mdeck skill --install claude` again, so your assistant knows the new features.
+
+If `npm` or `mdeck` is not found, see [When something goes wrong](troubleshooting.html#the-command-is-not-recognized).

package/docs/site/content/media.md

@@ -59,7 +59,7 @@ For a cropped picture, use `fit: cover`. You can add `position: "left center"` o
 
 ## Pictures that follow the theme
 
-An SVG drawing can take its colours from the theme, so it matches every theme, palette, and light or dark. Colour it with the palette's names instead of fixed colours, for example `fill: var(--accent, #1f3fd1)`; the colour after the comma is used wherever the picture is shown on its own. The names are `--bg`, `--surface`, `--ink`, `--ink-soft`, `--muted`, `--rule`, `--accent`, `--accent-2` and `--on-accent`.
+An SVG drawing can take its colours from the theme, so it matches every theme, palette, and light or dark. Colour it with the palette's names instead of fixed colours, for example `fill: var(--accent, #1f3fd1)`; the colour after the comma is used wherever the picture is shown on its own. The names are `--bg`, `--surface`, `--ink`, `--ink-soft`, `--muted`, `--rule`, `--accent`, `--accent-2`, `--accent-3` and `--on-accent`.
 
 It works wherever a picture goes: in the slide text (`![…](./img/drawing.svg)`) or as the `image` of a layout. In a layout, add `fit: contain` so the whole drawing shows. The tour example's title picture, `examples/showcase/img/mdeck.svg`, works this way. An AI assistant can draw one for you:
 
@@ -68,6 +68,25 @@ Draw an SVG title picture for this talk that uses the palette's
 colours, with a transparent background, and put it on the title slide.
 ```
 
+### A drawing that builds up
+
+Such a drawing is part of the slide, so its parts can appear one at a time, like the points of a list. Put each part in a group and number it with `data-step`: the parts appear in the order of their numbers, and parts with the same number appear together.
+
+```html
+<g data-step="1">…the first box…</g>
+<g data-step="1">…the second box…</g>
+<g data-step="2">…the arrow between them…</g>
+```
+
+The numbers decide the order, not where a part is in the file, so an arrow can be drawn under the boxes and still appear after them. With hotspots on (see [Zoom in on part of a slide](presenting.html#zoom-in-on-part-of-a-slide)), `data-hotspot` on a group gives it a key of its own. The same drawing can be on several slides; each copy keeps its arrowheads and gradients.
+
+`mdeck check` looks at these drawings: it names colours that stay fixed in dark mode, palette names without a colour after the comma, and styles that would reach the rest of the slide. An assistant can do all of it for you:
+
+```prompt
+Draw the three stages of the pipeline as an SVG in the palette's colours
+that builds up one stage at a time, and make each stage a hotspot.
+```
+
 ## Add a video file
 
 Paste this line into a normal slide, or into one side of a split slide:

package/docs/site/content/presenting.md

@@ -65,10 +65,45 @@ To let people answer a question on their phones, put a poll on a slide. See [Ask
 | 1–9 | Zoom in on a part of the slide, with hotspots on (see below); without them, go to slide 1–9 |
 | 0 or Escape | Show the whole slide again |
 | H | Turn hotspots on or off for this talk, in the presenter view |
+| T | Start or pause the timer, in the presenter view |
+
+To jump to a slide, tap or click the slide number in the presenter view (beside the arrows on an iPad, at the top of the speaker layout), type the number and press Enter, or Go on an iPad's keyboard. Escape keeps the current slide.
 
 Click the slide area if your keys are not controlling it. Keys behave normally while you are typing in a text field.
 
-The timer is for your own reference; you can start, pause, and reset it in the presenter view.
+The timer is for your own reference; you can start, pause (**T**), and reset it in the presenter view. It keeps running through a reload of the page.
+
+## Time your talk
+
+Give a slide the time you want to spend on it with `time:` in its settings, and the whole talk a length with `time:` in the deck's settings:
+
+```markdown
+---
+time: 20m
+---
+
+---
+:::meta
+time: 2m
+:::
+# The results
+```
+
+Write times as `90s`, `2m`, `1m30s` or `1.5m`. Slides without a time share what the deck's time leaves over; without a deck time, they get none.
+
+Once the deck has times, the presenter view shows under the timer how much time is left on the slide (amber in its last 15 seconds, red once it is over), the length of the talk, and whether you are ahead of or behind your plan. In the slide-only layout the time left on the slide sits beside the timer.
+
+### Rehearse
+
+You do not have to guess the times. Rehearse the talk and mdeck measures them:
+
+```bash
+mdeck rehearse my-talk.md
+```
+
+This opens the presenter view rehearsing: the timer starts, and every second on a slide counts towards it, including when you come back to it. **Rehearse** in the presenter view, and the tile on the launch page, start a rehearsal too. Press **Finish**, or go on past the last slide, and a table shows for each slide the time it has, the time you spent and the new time, rounded to 15 seconds. Change a new time in 15-second steps with **−** and **+** (or **↑** and **↓** on its row), put back the time the slide had, or take the slide's time out. **Save to deck** writes the new times into the slides' settings, so you can see them in the file and change them like any other setting. The open windows do not reload, and the deck is copied to `.mdeck-backups/` first.
+
+Saving needs `mdeck run` or `mdeck rehearse`. A deck you built can still rehearse; **Copy** gives you the times to paste in yourself.
 
 ## Zoom in on part of a slide
 
@@ -96,6 +131,8 @@ A slide can have its own setting in its frontmatter, such as `hotspots: false` f
 The rate is <span data-hotspot>**2.4 %** a year</span>, for now.
 ```
 
+In a drawing that takes its colours from the theme, `data-hotspot` on a group makes that part of the drawing a hotspot.
+
 Parts that nearly fill the slide, or its whole width, get no key, since there is nothing to zoom; what is inside them may. A part inside another one shares its key: a column with a formula and a tip in it is one part. The keys follow reading order, up to nine on a slide. In the editor, the deck's settings and each slide's details have a **Hotspots** choice too. **H**, or the button beside **Draw**, turns hotspots on or off for the rest of the talk without changing the deck; a slide set to `false` stays without them.
 
 ## One talk in several languages
@@ -125,7 +162,7 @@ Wrap a list in a steps block:
 :::
 ```
 
-Each press of the next key reveals one point. Once all points are visible, the next press moves to the following slide. Printed slides show all the points.
+Each press of the next key reveals one point. Once all points are visible, the next press moves to the following slide. Printed slides show all the points. A drawing can build up the same way; see [A drawing that builds up](media.html#a-drawing-that-builds-up).
 
 ## Before the talk
 

package/docs/site/content/sharing.md

@@ -21,6 +21,7 @@ Send `my-talk.html` by email. It opens in a **reader view**: an outline of all s
 - Drawings from `my-talk.drawings.json` are part of every build and PDF; `--no-drawings` leaves them out. Readers can hide them with the **Drawings** button in the reader view. See [Draw on your slides](drawing.html).
 - Your speaker notes are removed. Add `--notes` to keep them in the file, for example when you also present from the same file. Readers only see notes if you put `reader:` with `notes: true` in the settings at the top of your slide file.
 - Slides with a poll, question, word cloud or scale stay as a record of the talk: the question and its options, marked as answered live. Add `--no-polls` to leave them out of the file and its PDF, together with slides showing the join code (`<qrcode join />`).
+- `--slide 12-30` sends only some slides, for example the part of a deck shown in today's lecture. The numbers are the slides' places in the deck, as `mdeck check --render` and `mdeck snapshot` count them, and may be listed, `3,5-7`. Drawings stay on their slides, and a `<style>` written on a slide that is left out still applies. A deck `time:` shrinks to what the kept slides were planned to take.
 - The PDF is made while sending, using Chrome or Chromium on your computer. If neither is found, the button offers the browser's own "Save as PDF" dialog instead. Set `MDECK_CHROME` to the browser's path if it is installed somewhere unusual. `--no-pdf` skips it.
 - `-o` chooses the name: `mdeck send my-talk.md -o handout.html`.
 - The file keeps your theme and colours; readers can only switch between light and dark. To keep that fixed too, put `reader:` with `themes: false` in the settings at the top of your slide file.

package/docs/site/content/welcome.md

@@ -4,7 +4,7 @@ Bring what you already have: old PowerPoint slides, a PDF, a Word document, a pa
 
 The content stays yours. The assistant works from your material, not from its own idea of the topic: it chooses layouts, tidies wording, moves detail into speaker notes and checks the file. You do not need to know how to program. The slides are a plain text file, so you can read every word, change any of it yourself, or ask for something different.
 
-[Make your first presentation](getting-started.html)
+[Make your first presentation](getting-started.html) [Install mdeck](install.html)
 
 ## What you can do with it
 
@@ -32,6 +32,26 @@ Polls, scales, word clouds, open questions and numbers to guess. People scan the
 
 <section>
 
+[![The projector zoomed in on a table, and in front of it the presenter view showing the same slide with numbered keys on its code, table and formula](images/features/hotspots.webp)](images/features/hotspots.webp)
+
+### Zoom into a chart, a table or a line of code
+
+Turn on hotspots, and the presenter view puts a number on each picture, table, formula and code block. Press it, or tap it on an iPad, and the slide glides in until that part fills the projector; press it again to see the whole slide. Phones following the talk zoom along, and the audience never sees the numbers. [Zoom in on part of a slide](presenting.html#zoom-in-on-part-of-a-slide)
+
+</section>
+
+<section>
+
+[![The same slide with a Python example in English, German, Hindi and Farsi, the Farsi one running right to left](images/features/languages.webp)](images/features/languages.webp)
+
+### Give the talk in the room's language
+
+Keep the talk once per language, `talk.en.md` beside `talk.de.md`, and press **L** to switch in the middle of it: the slides, your notes and every screen change at once, and you stay on the same slide and step. Farsi, Arabic and Hebrew run right to left, with code and formulas left to right. [One talk in several languages](presenting.html#one-talk-in-several-languages)
+
+</section>
+
+<section>
+
 [![A slide with author–year citations and the full references at its foot, next to a slide that lists all references](images/features/citations.webp)](images/features/citations.webp)
 
 ### Cite your sources properly

package/docs/site/pages.js

@@ -1,5 +1,6 @@
 export const pages = [
   { slug: 'index', title: 'Welcome to mdeck', group: 'Start here', file: 'welcome.md', description: 'Turn your existing slides, documents and notes into a deck with an AI assistant, then present and share it.', preview: 'first-talk' },
+  { slug: 'install', title: 'Install mdeck', group: 'Start here', file: 'install.md', description: 'Install Node.js and mdeck from npm, teach your AI assistant, and keep mdeck up to date.' },
   { slug: 'getting-started', title: 'Make your first presentation', group: 'Start here', file: 'getting-started.md', description: 'Set up mdeck and your AI assistant, hand over your material, and open the deck it makes.' },
   { slug: 'claude-skill', title: 'Work with an AI assistant', group: 'Start here', source: '../reference/claude-skill.md', description: 'Set up Claude Code, Codex, Cursor, Copilot or Gemini, turn PowerPoint, PDF, Word or notes into a deck, and change it by asking.' },
   { slug: 'writing', title: 'Read and adjust your slides', group: 'Make your presentation', file: 'writing.md', description: 'The simple marks in a slide file, so you can read what your assistant wrote and fix small things.' },

package/examples/custom-layouts/slides.md

@@ -25,7 +25,7 @@ props:
 ## Single HTML file
 
 :::tip
-Useful when transferring one file is operationally important.
+Handy when one file is easier to pass on than a folder.
 :::
 
 - All local assets embedded
@@ -33,7 +33,7 @@ Useful when transferring one file is operationally important.
 :::
 
 :::notes
-This layout is loaded from extensions/comparison beside this deck.
+This layout is not built into mdeck: it comes from `extensions/comparison/` beside this deck. `ratio` sets the widths of the two sides, `emphasis` which one stands out.
 :::
 
 ---
@@ -41,20 +41,32 @@ This layout is loaded from extensions/comparison beside this deck.
 layout: split
 id: built-in-regions
 props:
-  ratio: [1, 2]
+  ratio: [1, 1]
 :::
-# Built-in layouts use the same region model
+# A layout of your own
 
 :::slot left
-```js
-const template = 'comparison'
+```markdown
+:::meta
+layout: comparison
+props:
+  emphasis: right
+:::
+# Deployment options
+:::slot left
+## Directory bundle
+:::
 ```
 :::
 
 :::slot right
 :::steps
-- Define a manifest.
-- Write a Preact layout.
-- Use it from Markdown.
+- `extension.toml` names the layout, its areas and its settings.
+- `layout.jsx` places the areas, `styles.css` styles them.
+- A slide chooses it with `layout: comparison`.
 :::
 :::
+
+:::notes
+All three files are in `extensions/comparison/`. `mdeck list layouts` shows the deck's own layouts beside mdeck's, and `mdeck starter comparison` prints a slide to start from. To use the layout in other decks, install it once for all of them; the guide "Reusable layouts" shows how.
+:::

package/examples/showcase/refs.bib

@@ -0,0 +1,21 @@
+@article{roediger2006,
+  author  = {Roediger, Henry L. and Karpicke, Jeffrey D.},
+  title   = {Test-Enhanced Learning: Taking Memory Tests Improves Long-Term Retention},
+  journal = {Psychological Science},
+  year    = {2006},
+  volume  = {17},
+  number  = {3},
+  pages   = {249--255},
+  doi     = {10.1111/j.1467-9280.2006.01693.x}
+}
+
+@article{freeman2014,
+  author  = {Freeman, Scott and Eddy, Sarah L. and McDonough, Miles and Smith, Michelle K. and Okoroafor, Nnadozie and Jordt, Hannah and Wenderoth, Mary Pat},
+  title   = {Active Learning Increases Student Performance in Science, Engineering, and Mathematics},
+  journal = {Proceedings of the National Academy of Sciences},
+  year    = {2014},
+  volume  = {111},
+  number  = {23},
+  pages   = {8410--8415},
+  doi     = {10.1073/pnas.1319030111}
+}

package/examples/showcase/slides.ar.drawings.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "width": 1920,
+  "height": 1080,
+  "slides": {
+    "draw-on-any-slide": [
+      {"id":"tour:underline","tool":"pen","color":"#e11d48","size":7,"points":[[1253,489,0.45],[1267,491,0.48],[1280,493,0.52],[1293,494,0.55],[1307,495,0.58],[1320,496,0.61],[1333,496,0.64],[1347,495,0.66],[1360,494,0.68],[1373,492,0.7],[1387,491,0.72],[1400,489,0.73],[1413,487,0.74],[1427,486,0.75],[1440,485,0.75],[1453,485,0.75],[1467,486,0.74],[1480,487,0.73],[1493,488,0.72],[1507,490,0.71],[1520,492,0.69],[1533,494,0.67],[1547,496,0.64],[1560,497,0.62],[1573,498,0.59],[1587,499,0.56],[1600,499,0.53],[1613,498,0.49],[1627,497,0.46],[1640,495,0.43],[1653,494,0.39],[1667,492,0.36],[1680,491,0.33],[1693,489,0.3],[1707,489,0.27],[1720,488,0.25],[1733,489,0.22],[1747,489,0.2],[1760,491,0.19],[1773,493,0.17],[1787,495,0.16]]},
+      {"id":"tour:circle","tool":"pen","color":"#e11d48","size":6,"points":[[1690,520,0.5],[1694,520,0.54],[1699,520,0.57],[1703,521,0.6],[1707,523,0.64],[1711,526,0.66],[1714,529,0.69],[1716,533,0.71],[1718,537,0.73],[1719,541,0.74],[1720,545,0.75],[1719,549,0.75],[1718,553,0.75],[1716,557,0.74],[1714,561,0.73],[1711,563,0.71],[1708,566,0.69],[1704,568,0.66],[1701,570,0.63],[1697,571,0.6],[1693,572,0.57],[1689,572,0.54],[1685,572,0.5],[1681,572,0.46],[1677,570,0.43],[1673,569,0.4],[1670,567,0.36],[1667,564,0.34],[1664,560,0.31],[1662,557,0.29],[1660,552,0.27],[1660,548,0.26],[1660,544,0.25],[1661,539,0.25],[1663,535,0.25],[1665,532,0.26],[1668,529,0.27],[1671,526,0.29],[1675,524,0.31],[1679,523,0.34],[1683,522,0.37],[1687,522,0.4],[1691,522,0.43],[1695,522,0.47],[1699,524,0.5],[1703,525,0.54]]}
+    ]
+  }
+}