fb-slides 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -7,6 +7,62 @@ this — which makes it worth being able to see what arrived.
 Entries are written as the work lands, under **Unreleased**; the release commit
 that stamps the version renames that heading to the version and its date.
 
+## 0.11.0 — 2026-09-23
+
+- **Two named themes, and a picker to try them with.** `themePack:` in
+  slides.config.js takes one of the looks this package now ships —
+  `custom-aurora`, atmospheric, coloured light behind glass panels under a
+  display serif, and `custom-editoriale`, flat and typographic, hairlines and
+  almost no colour. They are neither reveal themes nor a second renderer: a pack
+  is written against the same tokens as the base theme and dresses the same slide
+  vocabulary, so both of them fit the *same Markdown*, and the three layers
+  compose — reveal's theme, then the pack, then your own `theme.css`, which still
+  has the last word. Neither pack fetches a webfont.
+- **A theme picker in the toolbar, under `dev`.** The last button on the strip
+  lists everything the deck could wear under two headings — the packs, then
+  reveal's fifteen, with the bare base theme above both. Picking one swaps a
+  single `<link>` (and, for a reveal theme, the `data-reveal-theme` the chrome
+  follows), with no reload and no restart, and a refresh keeps it. It is one
+  choice rather than two: the config will let you name a pack *and* a reveal
+  theme, but layering them gives neither look. It previews rather than saves —
+  the panel prints the `themePack:` or `revealTheme:` line to paste once you
+  have decided, because slides.config.js is a module with your comments in it.
+  It exists only under `dev` by construction: `build` renders the page without
+  the list the picker reads, so a published deck never has one.
+- Reveal's themes are now served one URL each, `reveal-themes/<name>.css`,
+  rather than all of them through a single `reveal-theme.css` whose contents
+  depended on the config. `dev` rewrites any of them on request — that is what
+  the picker switches between — while `build` still writes only the one the
+  config names, with only the font folders that one imports. A stylesheet whose
+  bytes change under a fixed URL is one a browser is right to keep serving
+  stale, and the picker changes it between two keystrokes.
+- **Four blocks the packs are built around**, all of them in the edit drawer's
+  `+` picker: `chips` (the line above the title), `rows` and `rows--cta` (two or
+  three things with a glyph and a sentence each, or the last slide's ways out),
+  and `<!-- file: cart.component.ts -->` above a fence, which draws a header bar
+  on the code block — the language comes from the file's own extension, so there
+  is nothing extra to write. A Markdown table with an empty header row is now
+  laid out as a definition list instead of drawing an empty grey bar.
+- **A published deck no longer asks for the edit API.** The edit button was
+  already dev-server only — a static host 404s the probe and the drawer never
+  exists — but the probe itself went out on every load, and on GitHub Pages
+  that was a red `404 /api/editable` in the console of a deck with nothing
+  wrong. The runtime now looks at the address bar first and asks only from
+  `localhost` (or `127.0.0.1`), the one place the server would answer; from a
+  LAN address or a tunnel it stays quiet, as the server would have refused it
+  anyway.
+- **The toolbar stays down until you put it away.** It still comes down when
+  the mouse goes for the top edge, a tool arms or focus lands on it — but it
+  no longer slides back up when the mouse wanders off, nor when the pen or the
+  spotlight is switched off. A presenter who has just picked a colour and moved
+  down to draw should not have the bar leave from under the next click. An `X`
+  chip at the end of the strip puts it away; the `X` key does the same, and
+  brings it back.
+- Docs: the key table said `T` for the drawer; it has been `Shift+E` since 0.9.0.
+- The starter deck gains an about-me deck of its own, `decks/02-author.md`, in
+  place of the two placeholder photos on the intro slide, and its demos deck
+  shows the chips, rows and file-headed code blocks the packs are built around.
+
 ## 0.10.0 — 2026-09-08
 
 - **A file in the assets panel opens on click.** The name on a row carries the

package/README.md

@@ -293,8 +293,10 @@ one layer per press.
 whatever else `static:` says, so a path the drawer hands out works in the build
 too.
 
-Both the drawer and the drop exist only under `fb-slides dev`: a built deck is
-static files and never shows the button.
+Both the drawer and the drop exist only under `fb-slides dev`, and only at
+`localhost` (or `127.0.0.1`): a built deck is static files and never shows the
+button, and from any other address — a phone on the LAN, a tunnel, GitHub
+Pages — the page does not even ask for the edit API.
 
 ## Presenting
 
@@ -305,7 +307,8 @@ static files and never shows the button.
 | `W` | the arrow — click the tail, then the tip; same colours as the pen |
 | `E` | the spotlight — drag a rectangle, the rest of the slide dims and blurs |
 | `R` | the pointer — replaces the cursor: a glowing halo, a dart aimed at the centre, or the normal mouse |
-| `T` | edit the slide — markdown and notes, saved back into the `.md` (dev server only) |
+| `X` | put the toolbar away, or bring it back — it comes down when the mouse goes for the top edge or a tool arms, and stays until this |
+| `Shift+E` | edit the slide — markdown and notes, saved back into the `.md` (dev server only) |
 | `S` | speaker view — notes, timer, next slide |
 | `Esc` / `O` | overview — the slides as a grid |
 | `V` | the vertical navigator — every slide by title, down the left edge |
@@ -330,7 +333,8 @@ export default {
   static: ['assets', 'demo'],    // served and published; auto-detected when omitted
   revealTheme: 'dracula',        // one of reveal.js's own themes; omit for this one
   webfonts: false,               // let the reveal themes fetch their Google fonts
-  theme: 'theme.css',            // loaded after the base theme; auto when it exists
+  themePack: 'custom-aurora',    // one of this package's own named themes
+  theme: 'theme.css',            // loaded last, over both; auto when it exists
   favicon: 'assets/favicon.png',
 
   signature: {                   // the corner logo. Omit the key, omit the logo
@@ -439,7 +443,8 @@ export default { revealTheme: 'dracula' };
 `serif` · `simple` · `sky` · `solarized` · `white` · `white-contrast`
 
 Only the chosen one is ever loaded — one `<link>`, ~7 KB — and the build copies that file
-and nothing else. Two things happen beyond the link:
+and nothing else. Under `dev` all fifteen are reachable, one URL each, so the picker below
+can try them without a restart. Two things happen beyond the link:
 
 **It is served from the deck, not from a CDN.** Six of the themes open with
 `@import url(https://fonts.googleapis.com/…)`. Those lines are stripped, so a talk still
@@ -454,6 +459,92 @@ deck. Every reveal 5 theme declares its palette as `--r-*` custom properties, an
 theme points its own tokens at them, so the whole page moves together. A `theme.css` in the
 project still has the last word over both.
 
+### The named themes
+
+Two whole looks ship with the package, picked by name:
+
+```js
+export default { themePack: 'custom-aurora' };
+```
+
+`custom-aurora` — atmospheric. Coloured light pooling behind the slide, glass panels
+floating on it, a display serif carrying the titles.
+
+`custom-editoriale` — flat and typographic. No panels and almost no colour: one serif,
+hairlines for dividing, and the accent kept for the two or three words a slide is about.
+
+They are not reveal themes and they are not a second renderer. A pack is written against
+the same `--bg` / `--accent` / `--text` tokens as the base theme and styles the same slide
+vocabulary, which is what lets both of them dress the *same Markdown*: the `chips` line
+that is a row of pills under `custom-aurora` is a `// LIKE THIS` rule under
+`custom-editoriale`, and the `.md` does not change a character.
+
+The three layers compose, in this order — reveal's theme, then the pack, then your
+`theme.css`. Wearing a pack and still overriding two of its colours is a two-line file.
+
+Neither pack fetches a webfont. The serif is whatever the machine already has, closest
+first; a talk that has to survive the conference wifi cannot open with a request to
+fonts.googleapis.com.
+
+### Switching themes while you work
+
+`fb-slides dev` puts a theme picker in the toolbar — the last button, next to the pen. It
+lists everything the deck could wear, under two headings: the packs above, reveal's fifteen
+below, with the bare base theme at the top. Picking swaps one `<link>`: no reload, no
+restart, and the choice survives a refresh.
+
+One choice, not two. The config will let you name a pack and a reveal theme at once, but
+layering them gives you neither look — only whichever rule happened to come last — so the
+picker treats them as one question. Your `theme.css` still lands on top of whatever is
+picked, as it always does.
+
+It is a preview, not a setting. Nothing is written to disk — `slides.config.js` is a module
+with your own comments in it, and a picker that rewrites it is a worse problem than the one
+it solves — so the panel prints the line to paste when you have decided.
+
+The picker exists only under `dev`, and by construction rather than by a flag: `dev` renders
+the page with the theme list in it and `build` does not, so a published deck has nothing for
+the switcher to read and it never builds itself. The fifteen are the same way: `dev` can
+rewrite any of them on request, `build` writes only the one the config names.
+
+### The slide vocabulary the packs dress
+
+Four blocks both packs know. All four are in the edit drawer's `+` picker, so none of this
+has to be remembered:
+
+```html
+<p class="chips"><span>Angular</span><span>Signals</span><span>v22</span></p>
+```
+
+The line above the title. The first chip is the loud one — in a row of equals nothing is
+being asked.
+
+```html
+<div class="rows">
+  <div class="row">
+    <span class="row-icon">( )</span>
+    <div><strong>Signals</strong><p>UI state, derived values, clean templates.</p></div>
+  </div>
+</div>
+```
+
+Two or three things, each with a glyph and one sentence. `class="rows rows--cta"` turns the
+same block into the last slide's ways out: every row grows an arrow, and the first is filled.
+
+````md
+<!-- file: cart.component.ts -->
+```ts
+…
+```
+````
+
+A header bar on the code block: the name on the left, the language on the right. The
+language is never written down — it is the file's own extension. The marker is a comment,
+in the shape the demo slides already use, so the `.md` still renders anywhere else.
+
+A two-column Markdown table with an **empty header row** is a definition list — the term on
+the left, one sentence on the right — and the empty bar is dropped rather than drawn.
+
 ## Publishing
 
 ```bash

package/lib/build.mjs

@@ -14,7 +14,7 @@ import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 import { assertUsable } from './config.mjs';
 import { listDecks } from './decks.mjs';
 import { renderIndex } from './render.mjs';
-import { REVEAL_THEME_URL, readRevealTheme } from './theme.mjs';
+import { readRevealTheme, revealThemeUrl } from './theme.mjs';
 import { VENDOR_FILES, VENDOR_MOUNTS, packageDir } from './vendor.mjs';
 
 const copyFile = async (from, to) => {
@@ -64,7 +64,9 @@ export const build = async (config, runtimeDir, { quiet = false } = {}) => {
   //     only those: source-sans-pro is 1.8 MB and most themes never ask for it.
   if (config.revealTheme) {
     const { css, fonts, dir } = await readRevealTheme(config.revealTheme, { webfonts: config.webfonts });
-    await writeFile(join(out, REVEAL_THEME_URL), css);
+    const themeFile = join(out, revealThemeUrl(config.revealTheme));
+    await mkdir(dirname(themeFile), { recursive: true });
+    await writeFile(themeFile, css);
     for (const font of fonts) {
       await cp(join(dir, 'fonts', font), join(out, 'vendor', VENDOR_MOUNTS['reveal.js'], 'dist/theme/fonts', font), {
         recursive: true,

package/lib/config.mjs

@@ -10,7 +10,7 @@ import { existsSync, statSync } from 'node:fs';
 import { basename, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 
-import { assertRevealTheme } from './theme.mjs';
+import { assertDeckTheme, assertRevealTheme } from './theme.mjs';
 
 const CONFIG_FILES = ['slides.config.js', 'slides.config.mjs', 'slides.config.json'];
 
@@ -110,8 +110,14 @@ export const loadConfig = async (root = process.cwd(), overrides = {}) => {
     // default — the deck is served whole or not at all — at the cost of falling
     // back to the theme's second-choice font stack.
     webfonts: user.webfonts ?? false,
-    // The project's own CSS, loaded *after* the base theme: an override, not a
-    // replacement. `theme.css` at the root is picked up without being declared.
+    // One of this package's own named themes — a whole skin over the base one,
+    // from runtime/themes/. It sits between reveal's theme and the project's CSS,
+    // so all three compose: a pack can be worn and still be overridden. Null is
+    // the base look, bare.
+    themePack: user.themePack ?? null,
+    // The project's own CSS, loaded *after* the base theme and after any pack:
+    // an override, not a replacement. `theme.css` at the root is picked up
+    // without being declared.
     theme: user.theme ?? (existsSync(join(root, 'theme.css')) ? 'theme.css' : null),
     favicon: user.favicon ?? null,
     signature: user.signature ?? null,
@@ -136,6 +142,7 @@ export const loadConfig = async (root = process.cwd(), overrides = {}) => {
   // Named early: a typo in the config should be a message, not a deck that
   // silently wears the wrong clothes.
   if (config.revealTheme) await assertRevealTheme(config.revealTheme);
+  if (config.themePack) await assertDeckTheme(config.themePack);
 
   // `--no-editor` is its own flag rather than a part of `--no-servers`: that one
   // is for skipping a demo's dev server, and a demo that is not running is

package/lib/dev.mjs

@@ -15,7 +15,7 @@ import { EDITOR_PORT_TRIES, assertUsable, portOf } from './config.mjs';
 import { createEditApi } from './edit.mjs';
 import { createDeckServer, listen } from './server.mjs';
 import { renderIndex } from './render.mjs';
-import { REVEAL_THEME_URL, readRevealTheme } from './theme.mjs';
+import { listDeckThemes, listRevealThemes, readRevealTheme, revealThemeUrl } from './theme.mjs';
 import { VENDOR_MOUNTS, packageDir } from './vendor.mjs';
 
 const OPEN = { darwin: 'open', win32: 'start' };
@@ -197,6 +197,9 @@ export const dev = async (config, runtimeDir, reload) => {
   assertUsable(config);
   const current = reader(config, reload);
   let editorUrl = null;
+  // Fixed for the life of the server: they come out of node_modules, which does
+  // not change while a talk is being given.
+  const revealThemes = await listRevealThemes();
 
   const mounts = [
     // The project first: a file next to the decks shadows the one this package
@@ -221,20 +224,38 @@ export const dev = async (config, runtimeDir, reload) => {
       // Read at request time, not at wiring time: the editor is started below,
       // after the port is bound, and the first page load comes later still.
       const editor = editorUrl ? { url: editorUrl, root: config.root, sources: now.demoSources } : null;
-      return renderIndex(now, runtimeDir, editor ? { editor } : {});
+      // The theme switcher's whole list, and what the config currently says. It
+      // rides in `extra` rather than behind an /api/ probe because that is what
+      // makes it dev-only *by construction*: `build` calls renderIndex without
+      // it, so a published page has no list, and the switcher never builds.
+      const themes = {
+        packs: await listDeckThemes(),
+        reveal: revealThemes,
+        // What the config says the deck is wearing. A project that names both —
+        // nothing stops it — is showing the pack, so that is what the switcher
+        // opens on.
+        current: now.themePack ?? now.revealTheme ?? null,
+      };
+      return renderIndex(now, runtimeDir, { ...(editor ? { editor } : {}), themes });
     },
     // Editing a slide in the browser saves it back into its .md, and dropping
     // a file on the deck puts it in assets/ — dev only, which is what makes the
     // edit button appear at all (the runtime probes /api/editable). Build and
     // preview never mount this.
     api: createEditApi(config.decksPath, { dir: config.assetsDir, path: config.assetsPath }),
-    generated: {
-      [`/${REVEAL_THEME_URL}`]: async () => {
-        const now = await current();
-        if (!now.revealTheme) return '/* no revealTheme in slides.config.js */';
-        return (await readRevealTheme(now.revealTheme, { webfonts: now.webfonts })).css;
-      },
-    },
+    // All fifteen, each at its own URL, rewritten on request. `build` writes only
+    // the one the config names — it has no switcher to feed — but here any of
+    // them can be asked for at any moment, and the rewrite is a string replace
+    // over a 7 KB file, so there is nothing to gain by being clever about it.
+    //
+    // `webfonts` is read per request like everything else: flipping it in the
+    // config and reloading changes what these hand back.
+    generated: Object.fromEntries(
+      revealThemes.map((name) => [
+        `/${revealThemeUrl(name)}`,
+        async () => (await readRevealTheme(name, { webfonts: (await current()).webfonts })).css,
+      ]),
+    ),
   });
 
   await listen(server, config.port);

package/lib/edit.mjs

@@ -78,7 +78,9 @@ const readBody = (req, limit = 1024 * 1024) =>
 // web page you have open can POST to it. Cross-origin requests cannot carry a
 // custom header without a CORS preflight — which is never answered — so
 // requiring one shuts that door; the Host check covers DNS rebinding, where
-// the request arrives same-origin under a name that is not ours.
+// the request arrives same-origin under a name that is not ours. The runtime
+// keeps a copy of this list (runtime/edit.js) and does not ask from anywhere
+// else: change one, change the other.
 const LOCAL_HOST = /^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/;
 
 // `assets` is `{ dir, path }` — the folder a dropped file lands in. Without it

package/lib/render.mjs

@@ -7,7 +7,7 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
-import { REVEAL_THEME_URL } from './theme.mjs';
+import { deckThemeUrl, revealThemeUrl } from './theme.mjs';
 
 const escapeHtml = (value) =>
   String(value).replace(/[&<>"']/g, (char) => `&#${char.charCodeAt(0)};`);
@@ -32,9 +32,21 @@ const headHtml = (config) => {
   if (config.favicon) tags.push(`<link rel="icon" href="${escapeHtml(config.favicon)}" />`);
   // After the base theme, before the project's: reveal's theme dresses the
   // slides, and whatever the project says still has the last word.
-  if (config.revealTheme) tags.push(`<link rel="stylesheet" href="${REVEAL_THEME_URL}" />`);
-  // After the base theme on purpose: the project's CSS overrides, it does not replace.
-  if (config.theme) tags.push(`<link rel="stylesheet" href="${escapeHtml(config.theme)}" />`);
+  // The id, like the pack's below, is the handle the dev-only switcher swaps.
+  if (config.revealTheme)
+    tags.push(
+      `<link id="deck-reveal-theme" rel="stylesheet" href="${escapeHtml(revealThemeUrl(config.revealTheme))}" />`,
+    );
+  // A named pack from this package, between reveal's theme and the project's.
+  // The id is the handle the dev-only switcher swaps; a built deck carries it
+  // too and simply never has anything that looks it up.
+  if (config.themePack)
+    tags.push(`<link id="deck-theme" rel="stylesheet" href="${escapeHtml(deckThemeUrl(config.themePack))}" />`);
+  // After the base theme and after any pack, on purpose: the project's CSS
+  // overrides, it does not replace. The id is what the switcher inserts a pack
+  // *before* on a deck that started with none — order is the whole contract here.
+  if (config.theme)
+    tags.push(`<link id="deck-theme-project" rel="stylesheet" href="${escapeHtml(config.theme)}" />`);
   return tags.join('\n    ');
 };
 

package/lib/theme.mjs

@@ -13,17 +13,28 @@
 // ---------------------------------------------------------------------------
 
 import { readdir, readFile } from 'node:fs/promises';
-import { basename, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import { VENDOR_MOUNTS, packageDir } from './vendor.mjs';
 
-export const REVEAL_THEME_URL = 'reveal-theme.css';
+// One URL per theme rather than one URL for "the theme". A single
+// `reveal-theme.css` was enough while the answer could only change by editing
+// the config and reloading; the dev switcher changes it between two keystrokes,
+// and a stylesheet whose bytes depend on state the browser cannot see is a
+// stylesheet the browser is right to keep serving stale.
+//
+// Relative, like every other URL the page holds: dist/ has to survive being
+// published in a subfolder.
+export const revealThemeUrl = (name) => `reveal-themes/${name}.css`;
 
 const themeDir = () => join(packageDir('reveal.js'), 'dist', 'theme');
 
-// The theme is served from the site root, so reveal's own `./fonts/…` would
-// resolve one folder too high: point it at the vendor mount instead.
-const FONT_BASE = `vendor/${VENDOR_MOUNTS['reveal.js']}/dist/theme/fonts/`;
+// A url() in a stylesheet resolves against the stylesheet, not the page. These
+// are served from `reveal-themes/`, one folder down from the deck, so the hop
+// back up is part of the path — reveal's own `./fonts/…` would otherwise look
+// for them inside that folder.
+const FONT_BASE = `../vendor/${VENDOR_MOUNTS['reveal.js']}/dist/theme/fonts/`;
 
 const REMOTE_IMPORT = /@import\s+url\(\s*['"]?https?:[^)]*\)\s*;?[ \t]*\n?/gi;
 const LOCAL_FONT_URL = /url\(\s*['"]?\.\/fonts\//gi;
@@ -55,3 +66,40 @@ export const readRevealTheme = async (name, { webfonts = false } = {}) => {
   const css = (webfonts ? source : source.replace(REMOTE_IMPORT, '')).replace(LOCAL_FONT_URL, `url(${FONT_BASE}`);
   return { css, fonts: fontDirs(source), dir: themeDir() };
 };
+
+// ---------------------------------------------------------------------------
+// This package's own named themes, as opposed to reveal's fifteen.
+//
+// The difference is what they dress. A reveal theme takes the slides and leaves
+// the chrome to the bridge at the top of theme.base.css; these are written
+// against that file's own tokens, so the whole page moves at once and nothing
+// has to be bridged. They add no markup either: everything they style is the
+// slide vocabulary theme.base.css already ships, which is what keeps a pack a
+// skin rather than a second renderer.
+//
+// They live in runtime/themes/, so they are served by the runtime mount in dev
+// and copied by the build's first step — a published deck carries the one it
+// wears without either command knowing they exist.
+// ---------------------------------------------------------------------------
+
+const deckThemeDir = () => join(dirname(fileURLToPath(import.meta.url)), '..', 'runtime', 'themes');
+
+// Relative like every other URL the page holds: dist/ has to survive being
+// published in a subfolder.
+export const deckThemeUrl = (name) => `themes/${name}.css`;
+
+export const listDeckThemes = async () =>
+  (await readdir(deckThemeDir()).catch(() => []))
+    .filter((file) => file.endsWith('.css'))
+    .map((file) => basename(file, '.css'))
+    .sort();
+
+export const assertDeckTheme = async (name) => {
+  const themes = await listDeckThemes();
+  if (themes.includes(name)) return name;
+  throw new Error(
+    `unknown themePack: ${name}\n` +
+      `  fb-slides ships: ${themes.join(', ')}\n` +
+      `  drop the key for the base look, or put your own CSS in \`theme:\``,
+  );
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fb-slides",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "module",
   "description": "Markdown-driven reveal.js decks: live demo embeds, annotation, mermaid, and a zero-config dev server",
   "keywords": [

package/runtime/annotate.js

@@ -76,6 +76,8 @@ const QUANTA = 24;
 // nothing between Q and R (P, H/J/K/L, B, V, F, G, A, C, O are all elsewhere).
 const PEN_KEY_CODE = 81; // Q
 const ARROW_KEY_CODE = 87; // W
+// The toolbar's own key, off the row: X puts the bar away, or brings it back.
+const CLOSE_KEY_CODE = 88; // X
 
 const PEN_ICON = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7"
   stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
@@ -87,6 +89,11 @@ const ARROW_ICON = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" s
   <path d="M5 19L19 5" /><path d="M9.5 5H19v9.5" />
 </svg>`;
 
+const CLOSE_ICON = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7"
+  stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+  <path d="M6 6l12 12" /><path d="M18 6L6 18" />
+</svg>`;
+
 // Black text on a light chip, light text on a dark one — the armed pen button
 // wears the ink's own colour, and two of the six are the extremes.
 const readable = (hex) => {
@@ -144,6 +151,9 @@ const RevealAnnotate = () => ({
       <button id="tool-arrow" class="deck-tool" type="button" aria-pressed="false"
               title="Arrow — click the tail, then the tip (W)" aria-label="Arrow">${ARROW_ICON}<span
               class="deck-key" aria-hidden="true">W</span></button>
+      <button id="tool-close" class="deck-tool deck-tools-close" type="button"
+              title="Put the toolbar away (X)" aria-label="Put the toolbar away">${CLOSE_ICON}<span
+              class="deck-key" aria-hidden="true">X</span></button>
       <div id="deck-swatches" role="radiogroup" aria-label="Ink colour" hidden>
         ${COLOURS.map(
           (colour, i) => `<button class="deck-swatch" type="button" role="radio"
@@ -156,9 +166,35 @@ const RevealAnnotate = () => ({
     document.body.append(canvas, toolbar);
     const penButton = toolbar.querySelector('#tool-pen');
     const arrowButton = toolbar.querySelector('#tool-arrow');
+    const closeButton = toolbar.querySelector('#tool-close');
     const swatches = toolbar.querySelector('#deck-swatches');
     const ctx = canvas.getContext('2d');
 
+    // ---- showing and hiding ---------------------------------------------
+    // The bar sleeps above the top edge and comes down when the pointer goes
+    // for it, a tool arms, or focus lands on it — and then it *stays*. Leaving
+    // with the mouse, or disarming the tool that brought it down, does not put
+    // it away: only the X chip and its key do. A latch rather than :hover,
+    // because a presenter who has just picked a colour and moved off to draw
+    // should not have the bar slide out from under the next click.
+    const showTools = () => toolbar.classList.add('is-open');
+    const hideTools = () => {
+      toolbar.classList.remove('is-open');
+      // Focus left on the X would bring it straight back through `focusin`.
+      if (toolbar.contains(document.activeElement)) document.activeElement.blur();
+    };
+    const toggleTools = () => (toolbar.classList.contains('is-open') ? hideTools() : showTools());
+    // `pointerenter` fires for the wake strip too — a pseudo-element is hit
+    // tested as its owner — which is how parking the mouse along the top edge
+    // still wakes the bar.
+    toolbar.addEventListener('pointerenter', showTools);
+    toolbar.addEventListener('focusin', showTools);
+    closeButton.addEventListener('click', hideTools);
+    // The other plugins' tools arm through the same handshake, so one listener
+    // covers the spotlight and the pointer as well as the pen and the arrow.
+    document.addEventListener('deck:tool-armed', showTools);
+    deck.addKeyBinding({ keyCode: CLOSE_KEY_CODE, key: 'X', description: 'Show or hide the toolbar' }, toggleTools);
+
     // ---- the canvas -----------------------------------------------------
 
     let width = 0;

package/runtime/deck.js

@@ -3,6 +3,7 @@ import RevealSpotlight from './spotlight.js';
 import RevealPointer from './pointer.js';
 import RevealOutline from './outline.js';
 import RevealEdit from './edit.js';
+import RevealThemes from './themes.js';
 
 // ---------------------------------------------------------------------------
 // The decks are the Markdown files. This file only assembles them into reveal.js
@@ -225,11 +226,55 @@ await Reveal.initialize({
   pdfSeparateFragments: false,
   // Anything the project wants to change, from `reveal:` in slides.config.js.
   ...(CFG.reveal ?? {}),
-  // Spotlight, Pointer and Edit after Annotate: they hang their buttons on
-  // the toolbar the pen builds, in this order.
-  plugins: [RevealMarkdown, RevealHighlight, RevealNotes, RevealAnnotate(), RevealSpotlight(), RevealPointer(), RevealOutline(), RevealEdit()],
+  // Spotlight, Pointer, Edit and Themes after Annotate: they hang their buttons
+  // on the toolbar the pen builds, in this order. Themes is last because it is
+  // the only one that is not there at all in a built deck.
+  plugins: [RevealMarkdown, RevealHighlight, RevealNotes, RevealAnnotate(), RevealSpotlight(), RevealPointer(), RevealOutline(), RevealEdit(), RevealThemes()],
 });
 
+// ---------------------------------------------------------------------------
+// `<!-- file: cart.component.ts -->` on the line above a fence puts a header bar
+// on that code block. It follows the `<!-- demo: … -->` marker the decks already
+// use rather than inventing a second shape, and being a comment it costs nothing
+// anywhere else: the same .md still renders in Marp, header and all ignored.
+//
+// The language on the right of the bar is never written down either: it is the
+// file's own extension. Reading it off the highlighter's class instead would
+// have meant `language-typescript` where the fence said `ts` — the name hljs
+// settled on rather than the one anybody types. The bar itself is CSS
+// (`pre[data-file]::before` in theme.base.css); all that happens here is the
+// move from a comment node onto the element the stylesheet can reach.
+// ---------------------------------------------------------------------------
+
+const FILE_MARKER = /^\s*file:\s*(.+?)\s*$/;
+
+const labelCode = (root) => {
+  if (!root) return;
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_COMMENT);
+  const markers = [];
+  while (walker.nextNode()) markers.push(walker.currentNode);
+
+  for (const comment of markers) {
+    const name = FILE_MARKER.exec(comment.nodeValue)?.[1];
+    if (!name) continue;
+    // The fence renders as the <pre> right after the comment. Anything else
+    // means the marker is floating on its own, with nothing to label.
+    const pre = comment.nextElementSibling;
+    comment.remove();
+    if (pre?.tagName !== 'PRE') continue;
+    pre.dataset.file = name;
+    const extension = /\.([a-z0-9]+)$/i.exec(name)?.[1];
+    if (extension) pre.dataset.lang = extension.toUpperCase();
+  }
+};
+
+// Straight away for the deck as the markdown plugin has just left it — not on
+// `ready`, which reveal has already fired by the time initialize() resolves and
+// this line runs — and again per slide, because the edit drawer re-renders the
+// one it is showing and would otherwise drop the bar.
+labelCode(slidesEl);
+Reveal.on('slidechanged', ({ currentSlide }) => labelCode(currentSlide));
+
 // ---------------------------------------------------------------------------
 // Embedded apps that measure their container once, at mount, come up blank in a
 // deck: reveal scales slides with a CSS transform, which fires no resize inside