fb-slides 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -7,6 +7,56 @@ 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

package/README.md

@@ -230,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`,
@@ -242,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
 
@@ -290,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

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

@@ -80,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,
@@ -93,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
@@ -143,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) };

package/lib/dev.mjs

@@ -223,10 +223,11 @@ export const dev = async (config, runtimeDir, reload) => {
       const editor = editorUrl ? { url: editorUrl, root: config.root, sources: now.demoSources } : null;
       return renderIndex(now, runtimeDir, editor ? { editor } : {});
     },
-    // Editing a slide in the browser saves it back into its .md — 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),
+    // 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();

package/lib/edit.mjs

@@ -11,6 +11,7 @@
 //   POST /api/slide               → { op?, file, index, expected, source }
 //     op 'save' (default) replaces the slide, 'add' inserts a new one right
 //     after it, 'delete' removes it — separator and all.
+//   /api/assets                   → dropping a file into assets/ (assets.mjs)
 //
 // The slide boundaries are computed here with the same split deck.js uses, so
 // the index the browser counted is the index this file finds. The splice
@@ -21,6 +22,8 @@
 import { readFile, writeFile } from 'node:fs/promises';
 import { resolve, sep } from 'node:path';
 
+import { createAssetApi } from './assets.mjs';
+
 // Kept in step with deck.js: front matter comes off first, then slides split on
 // `---` lines, are trimmed, and empty segments are dropped.
 const FRONT_MATTER = /^---\r?\n[\s\S]*?\r?\n---\r?\n/;
@@ -78,7 +81,11 @@ const readBody = (req, limit = 1024 * 1024) =>
 // the request arrives same-origin under a name that is not ours.
 const LOCAL_HOST = /^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/;
 
-export const createEditApi = (decksPath) => {
+// `assets` is `{ dir, path }` — the folder a dropped file lands in. Without it
+// the drawer keeps its editing, and says so in the probe, but drops nothing.
+export const createEditApi = (decksPath, assets = null) => {
+  const assetApi = assets ? createAssetApi(assets) : null;
+
   const deckFile = (name) => {
     if (typeof name !== 'string' || !FILE_NAME.test(name) || name.startsWith('.')) return null;
     const target = resolve(decksPath, name);
@@ -88,7 +95,13 @@ export const createEditApi = (decksPath) => {
   return async (req, res, pathname) => {
     if (!LOCAL_HOST.test(req.headers.host ?? '')) return json(res, 403, { error: 'forbidden' });
 
-    if (pathname === '/api/editable') return json(res, 200, { editable: true });
+    if (pathname === '/api/editable') {
+      return json(res, 200, { editable: true, assets: assetApi ? assets.dir : null });
+    }
+
+    if (pathname === '/api/assets') {
+      return assetApi ? assetApi(req, res) : json(res, 404, { error: 'not found' });
+    }
 
     if (pathname !== '/api/slide') return json(res, 404, { error: 'not found' });
 

package/package.json

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