fb-slides 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -7,6 +7,80 @@ 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.9.0 — 2026-09-08
+
+- **The editor answers `Shift+E`, not `T`.** The drawer's shortcut moved off
+  the QWERT row: `Shift+E` opens it now, and the toolbar badge, the tooltip
+  and reveal's help overlay all say so. Plain `E` still belongs to the
+  spotlight.
+
+- **The slide box colours its markdown.** In the edit drawer, the slide's
+  textarea now sits over a highlighted copy of itself: headings, bold, fences,
+  links and the `<!-- .element -->` comments that steer reveal take colour as
+  you type. What you edit is still a plain textarea — caret, selection, undo
+  and drag untouched — and the palette is the theme's own, not the monokai the
+  slides wear. The grammar comes from reveal's highlight plugin, already in
+  the bundle; a deck without that plugin keeps the plain textarea.
+
+- **Drag a file onto the deck and it lands in `assets/`.** With the edit drawer
+  open, dropping files anywhere over the slide — images, video, a PDF, anything
+  — raises the folders `assets/` already has, and they go into the one they are
+  dropped on; `＋ new folder…` asks for a name and makes it, and the button
+  beside the `+` opens the same panel for files you would rather pick than drag.
+  What comes back is the path to use, with a button that copies it and one that
+  writes the markup at the cursor: `![](…)` for an image, a `<video>` with the
+  attributes that make it behave for a clip, a link for the rest. Names are
+  folded to something a URL can carry — `Schermata città (1).PNG` becomes
+  `Schermata-citta-1.png` — and nothing is overwritten, a second `clip.mp4`
+  lands as `clip-2.mp4`. A row's third button deletes the file — the wrong
+  screenshot, dropped a moment ago — and that one asks: **Delete** stays dead
+  until `CONFIRM` is typed, because it is the only thing in the drawer a reload
+  cannot undo. The folder is published with the deck whatever `static:` says, so
+  the path survives the build; `assets:` in `slides.config.js` moves it. Dev
+  server only, like the drawer it belongs to.
+
+- **The block picker grew into the whole vocabulary.** The `+` in the edit
+  drawer — and `/` on an empty line — now offers every block the theme knows,
+  under group headers: the section divider, the table with its muted first
+  column, the blockquote, a sequence diagram beside the flowchart, an autoplay
+  video — `data-autoplay muted loop`, the clip that plays itself when the slide
+  shows — and a second fragment — the `<!-- .element: class="fragment" -->`
+  comment that tags any block above it, image or list or
+  box, where the old one only wrapped a paragraph. The demo markers now bring
+  their fallback along — the heading and iframe GitHub and Marp show where the
+  live demo would be — and the external-page marker's row says how `| src:`
+  hitches the source button to a folder. Each row
+  also carries the words you would actually type looking for it — `img`,
+  `mermaid`, `appear` — so the filter answers to those too, and a pane under
+  the list shows the markup the highlighted row is about to write, before it
+  lands. A project's own `snippets:` sit under their own header — `group:`
+  names it, `keys:` joins the search — and a filter that matches nothing now
+  says so instead of showing an empty list.
+
+## 0.8.0 — 2026-09-07
+
+- **`npm run kill` — everything the talk left running, gone.** `dev` starts more
+  than itself, and it takes its side processes down with it only when it is asked
+  politely: killed outright, or with its terminal window closed, it leaves a
+  `vite` or an `ng serve` under the npm that started it and a `code serve-web`,
+  all holding the ports the next run wants. `fb-slides kill` clears them. It goes
+  by port rather than by process tree, because the ports are the one thing
+  already written down: the deck's, `preview`'s one above it, the `url:` of every
+  `servers:` entry, and the editor's 7100–7109 — the whole walk `dev` makes when
+  something holds the first one. Whatever is listening there is named, asked to
+  stop, and made to; the npm above it exits on its own once its server is gone. A
+  `servers:` entry with no `url:` is the one thing it cannot reach. New talks get
+  the script from `create`; a talk that already exists adds
+  `"kill": "fb-slides kill"` to its `scripts`.
+
+- **`dev` says when a port is already taken.** Each `servers:` port is probed
+  before anything is spawned, so a port that answers before its demo has started
+  is a leftover from a run that did not come down cleanly — and it is named under
+  the deck's URL, where the demo servers' own banners cannot bury it, instead of
+  turning up as a slide showing yesterday's build. The deck's own port, which has
+  always failed outright rather than moved, now names the way out in the same
+  breath: ``port 4000 is already in use — `npx fb-slides kill` ``.
+
 ## 0.7.0 — 2026-09-07
 
 - **A `source ↗` button on demo slides.** `editor: true` in `slides.config.js`

package/README.md

@@ -34,6 +34,7 @@ its `servers:` entry and its slide come out together.
 | `npm run dev` | serves the deck on :4000 and opens it |
 | `npm run build` | `dist/` — self-contained, relative URLs, works offline |
 | `npm run preview` | build, then serve the result |
+| `npm run kill` | stops the deck, the demos and the editor — whatever is left holding their ports |
 
 ## Writing
 
@@ -107,7 +108,18 @@ Vite — copied into `demo/` as it is. It is embedded by **URL**, not by folder
 **real VS Code** in a new tab — `code serve-web`, the web server built into the editor you
 already have, started alongside the deck. Nothing is installed and nothing is embedded, and
 a built deck never carries it. Run `dev` once at your desk first: VS Code downloads its
-server half on the very first use. [docs/source-code.md](docs/source-code.md).
+server half on the very first use.
+
+> **It needs VS Code on the machine running the deck.** `serve-web` is a subcommand of
+> VS Code's own CLI, so the button exists only where that CLI does: `code`, or
+> `code-insiders`, or a fork that kept it — `editor: { command: 'cursor' }`. Without it
+> nothing breaks and nothing is missing from the talk; `dev` says so under the deck's URL
+> and every demo slide comes up as it always did, minus the button. The same is true when
+> `code` is installed but not on the `PATH` of the shell you start the deck from, which an
+> IDE's built-in terminal manages on its own — name the binary outright then:
+> `editor: { command: '/usr/local/bin/code' }`.
+
+[docs/source-code.md](docs/source-code.md).
 
 ### Stepped code highlighting
 
@@ -218,7 +230,7 @@ restarts every time the slide comes up.
 
 ### Editing in the browser
 
-On the dev server, `T` (or the last button on the toolbar) opens the slide you
+On the dev server, `Shift+E` (or the last button on the toolbar) opens the slide you
 are looking at in a drawer: its markdown in one box, its speaker notes in
 another. Typing re-renders the real slide in place — same renderer, same theme —
 and **Save** writes the text back into the slide's own lines of the `.md`,
@@ -230,23 +242,56 @@ file, after asking. Clicking into the notes box trades the room with the slide
 box, so both are comfortable to write in.
 
 The `+` over the slide box — or `/` typed on an empty line — opens the block
-picker: the demo marker, a framed embed, a video with the attributes that make
-it behave, two columns, a fenced block, the speaker page. The block lands where
-the cursor was, with its first placeholder selected so it is ready to type over;
-text already selected takes that placeholder's place, so picking **Fragment**
-wraps the paragraph that was highlighted. A block that only works at the top of
-a slide, like the demo marker, goes there whatever the cursor was doing.
+picker: every block the theme knows, under group headers — the demo markers,
+the section divider and the speaker page; columns, callout, caption and framed
+embed; image and video with the attributes that make them behave; plain,
+stepped and mermaid fences; fragments, table and quote. The filter also answers
+to the words you would actually type — `img`, `mermaid`, `appear` — and the
+pane under the list shows the markup the highlighted row is about to write.
+The block lands where the cursor was, with its first placeholder selected so it
+is ready to type over; text already selected takes that placeholder's place, so
+picking **Fragment** wraps the paragraph that was highlighted. A block that
+only works at the top of a slide, like the demo marker, goes there whatever the
+cursor was doing.
 
 `snippets:` in `slides.config.js` adds a project's own blocks to the list:
 
 ```js
 snippets: [
-  { label: 'Pricing table', hint: 'the three tiers', body: '<div class="tiers">${…}</div>' },
+  { label: 'Pricing table', hint: 'the three tiers', keys: 'plans price', body: '<div class="tiers">${…}</div>' },
 ],
 ```
 
-The drawer exists only under `fb-slides dev`: a built deck is static files and
-never shows the button.
+`keys` are extra words the filter answers to, and `group` names the header a
+block sits under — without one, a project's blocks gather under **Project**.
+
+### Dropping files into `assets/`
+
+While the drawer is open, dragging files anywhere over the deck — a screenshot,
+a clip, a PDF — raises the folders `assets/` already has. Drop on one and the
+files are saved there; drop on **＋ new folder…** and it asks for a name and
+makes it. The button next to the `+` opens the same panel for files you would
+rather pick than drag.
+
+Each file that lands is listed with the path to write in the slide, a button
+that copies it, and one that writes it for you at the cursor: `![](…)` for an
+image, a `<video>` with the attributes that make it behave for a clip, an
+`<audio>` for sound, a link for everything else. Names are folded to something
+a URL can carry — `Schermata città (1).PNG` becomes `Schermata-citta-1.png` —
+and nothing is ever overwritten: a second `clip.mp4` lands as `clip-2.mp4`.
+
+The third button on a row deletes the file — the wrong screenshot, dropped a
+moment ago. It is the one thing here a reload cannot undo, so it asks: the
+**Delete** button stays dead until `CONFIRM` is typed into the box, in capitals.
+`Esc` backs out of the question, then out of the panel, then out of the drawer —
+one layer per press.
+
+`assets:` in `slides.config.js` names the folder. It is published with the deck
+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.
 
 ## Presenting
 
@@ -278,6 +323,7 @@ export default {
 
   decks: 'decks',                // folder of .md
   demos: 'demo',                 // folder behind a bare `<!-- demo: name -->`
+  assets: 'assets',              // where a file dropped on the deck lands
   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
@@ -294,7 +340,7 @@ export default {
     { name: 'angular demo', cwd: 'demo/app', command: 'npm', args: ['start', '--', '--port', '4200'] },
   ],
 
-  editor: true,                  // a `source ↗` button on every demo slide
+  editor: true,                  // a `source ↗` button on every demo slide (needs VS Code)
 
   port: 4000,
   open: true,
@@ -314,9 +360,52 @@ Copying a real Angular or Vite app into `demo/` and wiring it up — including t
 Vite needs so a busy port fails instead of moving:
 [docs/framework-demos.md](docs/framework-demos.md).
 
-`editor: true` is a side process of the same kind, and fails the same way — a missing
-`code` in PATH, a port already taken, and you get a warning and demo slides without their
-`source ↗` button: [docs/source-code.md](docs/source-code.md).
+`editor: true` is a side process of the same kind, and fails the same way: no VS Code on
+the machine, or no `code` on the PATH of the shell that started the deck, and you get a
+warning under the deck's URL and demo slides without their `source ↗` button. It listens on
+7100, clear of the ports the demos want, and walks up from there if something holds it:
+[docs/source-code.md](docs/source-code.md).
+
+### When something survives
+
+`dev` starts more than itself, and it takes its side processes down with it — as long as it
+is asked politely. Killed outright, or with its terminal window closed, it leaves them: a
+`vite` or an `ng serve` under the npm that started it, `code serve-web`, all still holding
+the ports the next run wants.
+
+```bash
+npm run kill
+```
+
+It reads the ports out of this file — the deck's, `preview`'s one above it, the `url:` of
+every `servers:` entry, the editor's 7100–7109 — and stops whatever is listening on them,
+naming each one before it goes:
+
+```
+  ✗ 4000  deck           node …/bin/fb-slides.mjs dev (39190)
+  ✗ 4200  angular demo   ng serve (39212)
+  ✗ 7100  editor         …/Visual Studio Code.app/… (32669)
+
+  3 processes stopped.
+```
+
+Going by port rather than by process tree is what makes it work at all after the deck is
+gone: the port is the thing already written down, and the process holding it is the one in
+the way. The npm above it exits on its own once its server is stopped.
+
+A `servers:` entry with no `url:` is the one thing it cannot reach — that key is how the
+config says where the demo answers.
+
+`dev` also looks before it leaps: a port a `servers:` entry is about to use that is *already*
+answering is a leftover from a previous run, and it says so under the deck's URL rather than
+letting you find out from a demo slide showing yesterday's build.
+
+```
+  kill test
+  → http://localhost:4010/
+  ⚠  4201 is already in use — angular-hello from an earlier run?
+     That server is not this deck's: `npx fb-slides kill` frees the ports it uses.
+```
 
 ## Theming
 

package/bin/fb-slides.mjs

@@ -6,6 +6,7 @@
 //   fb-slides dev            serve it, open it
 //   fb-slides build          dist/, self-contained
 //   fb-slides preview        build, then serve dist/
+//   fb-slides kill           stop whatever `dev` left running
 // ---------------------------------------------------------------------------
 
 import { createRequire } from 'node:module';
@@ -38,6 +39,7 @@ const HELP = `
                                                                 [--no-servers] [--no-editor]
   fb-slides build             build dist/                       [--out dir] [--watch]
   fb-slides preview           build, then serve the result      [--port n]
+  fb-slides kill              stop the deck, the demos and the editor
 
   Run from a folder holding decks/*.md. slides.config.js is optional.
 `;
@@ -79,6 +81,11 @@ const run = async () => {
     return void (await dev(config, RUNTIME, reload));
   }
 
+  if (command === 'kill') {
+    const { kill } = await import('../lib/kill.mjs');
+    return void (await kill(config));
+  }
+
   if (command === 'build') {
     const { build, buildWatch } = await import('../lib/build.mjs');
     return void (await (flag('watch') ? buildWatch(config, RUNTIME) : build(config, RUNTIME)));

package/docs/framework-demos.md

@@ -158,6 +158,26 @@ only on the machine running the app. A framework demo is for presenting live. If
 has to stand on its own on the web, point that slide at a deployed URL — the marker takes
 any `http(s)` address.
 
+## When one outlives the deck
+
+`dev` kills the processes it spawned, but the process it spawned is npm and the one holding
+4200 is npm's child — and when the deck itself is killed outright, or its terminal window
+closed, no handler runs at all. What is left is a dev server nobody can see, on the port the
+next run needs.
+
+```bash
+npm run kill
+```
+
+Every port in `servers:` — that is what `url:` is read for — plus the deck's and the
+editor's, and whatever is listening there is stopped. A demo declared without a `url:` is
+the one this cannot reach.
+
+And `dev` warns rather than leaving you to it: it probes each `servers:` port before
+spawning anything, so a port that answers *before* its demo has started is reported under
+the deck's URL. Otherwise the demo's own dev server fails, or moves one port along, and the
+slide keeps showing the run you thought you had stopped.
+
 ## Removing one
 
 Three things, all yours: the folder, the `servers:` entry, the slide. Delete them and

package/docs/source-code.md

@@ -8,6 +8,12 @@ is `code serve-web` — the web server built into the VS Code on the machine
 running the talk — pointed at the demo's folder. The file tree, the search, the
 terminal, the extensions, the keybindings: the editor, in a tab.
 
+Which is also the one requirement: **VS Code has to be installed on the machine
+running the deck**, because `serve-web` is a subcommand of its CLI and nothing
+here reimplements it. A fork that kept the CLI does as well —
+`editor: { command: 'cursor' }`. On a machine without one the deck is unchanged
+except for the button, and `dev` says why under its own URL.
+
 ## Turning it on
 
 ```js
@@ -153,6 +159,15 @@ editor: { command: '/usr/local/bin/code' },
   table above is read from `servers:` as written in the config, so it still
   works when none of those servers were started.
 
+## When it outlives the deck
+
+`serve-web` is a side process, and it goes down with the deck — unless the deck goes down
+the hard way, killed outright or with its terminal window closed. Then it stays up, on
+7100, invisible, and the next run finds the port taken and walks past it to 7101.
+
+`npm run kill` sweeps the whole walk, 7100 through 7109, along with the deck's port and the
+demos'. Worth knowing before wondering why the editor is on a different port every day.
+
 ## It is your real filesystem
 
 The editor opens the actual folder, with write access, as an editor does. Saving

package/lib/assets.mjs

@@ -0,0 +1,201 @@
+// ---------------------------------------------------------------------------
+// The asset API — what lets the browser drop a file into assets/.
+//
+// Mounted alongside the edit API, by `dev` only, and behind the same guards: a
+// built deck is static files and never answers /api/ at all. Writing a slide
+// and putting the picture it points at next to it are the same job, so the
+// drawer that does one does the other.
+//
+//   GET  /api/assets   → { dir, dirs } — where files land, and the subfolders
+//                        that are already there to aim at
+//   POST /api/assets   → the file's own bytes, its name and folder riding in
+//                        headers (a filename is not latin-1, hence the encoding);
+//                        answers { path } — what the slide should say
+//   DELETE /api/assets?path=assets/x/y.png → that file, gone from disk. The
+//                        drawer asks the question; this only checks that what it
+//                        names is a file under the assets folder.
+//
+// The folder is created on the way in, so naming one that does not exist yet is
+// how you make it. Nothing is ever overwritten: a name already taken is walked
+// to `-2`, `-3`, and the answer says which one it became.
+// ---------------------------------------------------------------------------
+
+import { createWriteStream } from 'node:fs';
+import { access, mkdir, readdir, rm, stat } from 'node:fs/promises';
+import { extname, join, resolve, sep } from 'node:path';
+import { Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+
+// A screen recording is the big one; past this something has gone wrong on the
+// way in, and a dev server should not be filling a disk over it.
+const MAX_BYTES = 512 * 1024 * 1024;
+
+// How deep the folder list looks, and how deep a drop may aim.
+const MAX_DEPTH = 4;
+
+// A name that can be written in a slide without thinking about it: what lands
+// here ends up in a URL — `![](assets/screen shot.png)` is not even an image —
+// so everything else folds to a dash, and a leading dot (a hidden file, `..`)
+// does not survive at all.
+const slug = (raw) =>
+  raw
+    // `città.png` should be `citta.png`, not `citt.png`: the accent comes off
+    // the letter rather than taking it with it.
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .replace(/[^A-Za-z0-9._-]+/g, '-')
+    // `screen shot (1).png` has folded to `screen-shot-1-.png` by now: the
+    // dashes that ended up hugging the dot, and each other, are noise.
+    .replace(/-*\.-*/g, '.')
+    .replace(/-{2,}/g, '-')
+    .replace(/^[.-]+/, '')
+    .replace(/[.-]+$/, '');
+
+const json = (res, status, body) =>
+  res
+    .writeHead(status, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' })
+    .end(JSON.stringify(body));
+
+const decode = (value) => {
+  try {
+    return decodeURIComponent(String(value ?? ''));
+  } catch {
+    return '';
+  }
+};
+
+const exists = (path) => access(path).then(() => true, () => false);
+
+// The subfolder a drop aimed at, as `{ relative, path }` — or null for anything
+// that is not a folder under the assets root. A name typed into the drawer is
+// folded rather than refused, so `my folder` makes `my-folder`; a segment that
+// folds away to nothing — `..` — takes the whole path with it.
+const folderIn = (root, value) => {
+  const typed = value.split('/').map((part) => part.trim()).filter(Boolean);
+  const parts = typed.map(slug);
+  if (typed.length > MAX_DEPTH || parts.some((part) => !part)) return null;
+  const path = resolve(root, ...parts);
+  // Belt and braces: the folding above cannot produce a `..`, and this is what
+  // says so out loud.
+  if (path !== root && !path.startsWith(root + sep)) return null;
+  return { relative: parts.join('/'), path };
+};
+
+// The name the file is written under: its own, folded. The extension is kept
+// out of the folding and lowercased — it is what decides whether the browser
+// treats the file as a picture, so it is the one part that must survive a name
+// written in an alphabet this does not carry.
+const safeName = (raw) => {
+  const base = raw.split(/[\\/]/).pop().trim();
+  const ext = extname(base).toLowerCase();
+  const tail = /^\.[a-z0-9]+$/.test(ext) ? ext : '';
+  return `${slug(base.slice(0, base.length - ext.length)) || 'file'}${tail}`;
+};
+
+// Never overwrite: `clip.mp4` beside a `clip.mp4` becomes `clip-2.mp4`.
+const freeName = async (dir, name) => {
+  const ext = extname(name);
+  const stem = name.slice(0, name.length - ext.length) || 'file';
+  for (let n = 1; n < 1000; n += 1) {
+    const candidate = n === 1 ? `${stem}${ext}` : `${stem}-${n}${ext}`;
+    if (!(await exists(join(dir, candidate)))) return candidate;
+  }
+  return null;
+};
+
+const subfolders = async (root) => {
+  const walk = async (dir, prefix, left) => {
+    if (!left) return [];
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+    const found = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+      const path = prefix ? `${prefix}/${entry.name}` : entry.name;
+      found.push(path, ...(await walk(join(dir, entry.name), path, left - 1)));
+    }
+    return found;
+  };
+  return (await walk(root, '', MAX_DEPTH)).sort((a, b) => a.localeCompare(b, 'en', { numeric: true }));
+};
+
+// One file already in there, named the way the drawer was handed it —
+// `assets/clips/demo.mp4`, the assets folder included. Null for anything that is
+// not under that folder, and for the hidden files the server does not serve.
+const fileIn = (root, dir, value) => {
+  const parts = value.split('/').map((part) => part.trim()).filter(Boolean);
+  if (parts.shift() !== dir || !parts.length) return null;
+  if (parts.some((part) => part.startsWith('.') || part === '..')) return null;
+  const path = resolve(root, ...parts);
+  return path.startsWith(root + sep) ? path : null;
+};
+
+// Counted on the way through rather than trusted from Content-Length, and the
+// half-written file goes when the count runs over.
+const capped = (limit) => {
+  let size = 0;
+  return new Transform({
+    transform(chunk, _encoding, next) {
+      size += chunk.length;
+      if (size > limit) next(new Error(`over the ${Math.round(limit / (1024 * 1024))} MB limit`));
+      else next(null, chunk);
+    },
+  });
+};
+
+const receive = async (req, target) => {
+  try {
+    // `wx` rather than `w`: the free name was worked out a moment ago, and two
+    // files dropped together should not land on top of each other.
+    await pipeline(req, capped(MAX_BYTES), createWriteStream(target, { flags: 'wx' }));
+  } catch (error) {
+    await rm(target, { force: true });
+    throw error;
+  }
+};
+
+// `dir` is the folder as the browser will write it — `assets` — and `path` is
+// where that is on disk.
+export const createAssetApi = ({ dir, path: root }) => async (req, res) => {
+  if (req.method === 'GET') {
+    return json(res, 200, { dir, dirs: await subfolders(root).catch(() => []) });
+  }
+
+  if (req.method !== 'POST' && req.method !== 'DELETE') {
+    return json(res, 405, { error: 'method not allowed' });
+  }
+  if (!req.headers['x-fb-slides']) return json(res, 403, { error: 'forbidden' });
+
+  if (req.method === 'DELETE') {
+    const asked = new URL(req.url, 'http://localhost').searchParams.get('path') ?? '';
+    const path = fileIn(root, dir, asked);
+    if (!path) return json(res, 400, { error: `${asked} is not a file in ${dir}/` });
+    const info = await stat(path).catch(() => null);
+    // A folder is not what the drawer offers to delete, and a file that is
+    // already gone is the outcome asked for.
+    if (info && !info.isFile()) return json(res, 409, { error: 'that is a folder' });
+    await rm(path, { force: true });
+    return json(res, 200, { ok: true, path: asked });
+  }
+
+  const folder = folderIn(root, decode(req.headers['x-fb-dir']));
+  const name = safeName(decode(req.headers['x-fb-name']));
+  if (!folder) return json(res, 400, { error: 'that is not a folder name' });
+
+  await mkdir(folder.path, { recursive: true });
+  const unique = await freeName(folder.path, name);
+  if (!unique) return json(res, 409, { error: `too many files called ${name}` });
+
+  try {
+    await receive(req, join(folder.path, unique));
+  } catch (error) {
+    return json(res, 413, { error: `${name}: ${error.message}` });
+  }
+
+  return json(res, 200, {
+    name: unique,
+    dir: folder.relative,
+    // Relative, like everything else a slide points at: the deck is served from
+    // a root in dev and from wherever it was published in a build.
+    path: [dir, folder.relative, unique].filter(Boolean).join('/'),
+  });
+};

package/lib/config.mjs

@@ -29,6 +29,10 @@ export const ALWAYS_EXCLUDED = ['node_modules', '.git', '.angular', '.next', '.c
 // loses. Two decks at once are handled by walking up from here instead.
 const EDITOR_PORT = 7100;
 
+// How far up from there `dev` walks when something already holds it, and so how
+// far `kill` has to sweep to be sure it caught the editor of an earlier run.
+export const EDITOR_PORT_TRIES = 10;
+
 // `editor: true` turns the source button on with the defaults; `{ port, command }`
 // changes them; leaving the key out is no button at all. The command is a name in
 // PATH — `code-insiders` and `cursor` answer `serve-web` too — or a path, for a
@@ -42,6 +46,17 @@ const editorSpec = (value) => {
   };
 };
 
+// The port a `servers:` entry answers on, read out of its `url:`. Both `dev`
+// (is something already sitting there?) and `kill` (what do I stop?) ask this.
+export const portOf = (url) => {
+  try {
+    const { port, protocol } = new URL(url);
+    return Number(port || (protocol === 'https:' ? 443 : 80));
+  } catch {
+    return null;
+  }
+};
+
 export const findConfigFile = (root) => CONFIG_FILES.map((name) => join(root, name)).find(existsSync) ?? null;
 
 const importConfig = async (file) => {
@@ -65,11 +80,16 @@ export const loadConfig = async (root = process.cwd(), overrides = {}) => {
 
   const decksDir = user.decks ?? 'decks';
   const demosDir = user.demos ?? 'demo';
+  const assetsDir = user.assets ?? 'assets';
 
   // `static:` replaces the auto-detected list when given; the demos folder is
-  // added back regardless, because the deck's iframes point straight at it.
+  // added back regardless, because the deck's iframes point straight at it, and
+  // so is the assets folder, because the edit drawer drops files into it and a
+  // path it hands out has to survive the build.
   const declared = user.static ?? AUTO_STATIC.filter((dir) => existsSync(join(root, dir)));
-  const statics = [...new Set([...declared, demosDir])].filter((dir) => existsSync(join(root, dir)));
+  const statics = [...new Set([...declared, demosDir, assetsDir])].filter((dir) =>
+    existsSync(join(root, dir)),
+  );
 
   const config = {
     root,
@@ -78,6 +98,9 @@ export const loadConfig = async (root = process.cwd(), overrides = {}) => {
     lang: user.lang ?? 'en',
     decksDir,
     demosDir,
+    // Where a file dropped on the deck lands, and what the path it hands back
+    // is written against.
+    assetsDir,
     static: statics,
     // One of reveal's own fifteen — 'dracula', 'sky', 'white'. It lands after
     // the base theme and takes the slides; the chrome follows it through the
@@ -128,6 +151,7 @@ export const loadConfig = async (root = process.cwd(), overrides = {}) => {
       .map((spec) => [String(spec.url).replace(/\/$/, ''), spec.cwd]),
   );
   config.decksPath = resolve(root, config.decksDir);
+  config.assetsPath = resolve(root, config.assetsDir);
   config.outPath = resolve(root, config.outDir);
   // What the browser asks for, as opposed to where it is on disk.
   config.urls = { decks: asDirUrl(config.decksDir), demos: asDirUrl(config.demosDir) };