fb-slides 0.8.0 → 0.9.1

package/runtime/edit.js

@@ -14,11 +14,18 @@
 // the URL hash puts the deck back on this slide, and the full pipeline —
 // mermaid, fragments, highlight steps — runs over the saved source.
 //
+// The slide box is written in markdown, so it is coloured like markdown: the
+// textarea sits over a highlighted copy of itself (syntax.js).
+//
 // The `+` over the slide box — or `/` on an empty line — opens the block
 // picker, which writes the markup nobody should have to remember (snippets.js).
+// Files dragged onto the deck while the drawer is open go into assets/ and come
+// back as paths to copy or write into the slide (assets.js).
 // ---------------------------------------------------------------------------
 
+import { createAssets, DROP_ICON } from './assets.js';
 import { createSnippets, PLUS_ICON } from './snippets.js';
+import { createSyntax } from './syntax.js';
 
 // Where the slide came from, stamped on every section by deck.js: the .md file
 // and the slide's index within it, counted the way the server counts.
@@ -49,10 +56,6 @@ const joinNotes = ({ content, label, notes }) =>
 // one without a CORS preflight, which the dev server never answers.
 const API_HEADERS = { 'x-fb-slides': '1' };
 
-// The last stop on the tools' QWER row — pen, arrow, spotlight, pointer, and
-// then this. Reveal answers nothing on T.
-const KEY_CODE = 84;
-
 const EDIT_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="M11 5H6a2 2 0 0 0-2 2v11a2 2 0 0 0 2 2h11a2 2 0 0 0 2-2v-5" />
@@ -88,13 +91,15 @@ const RevealEdit = () => ({
     fetch('/api/editable', { headers: API_HEADERS, cache: 'no-cache' })
       .then((response) => response.json())
       .then((answer) => {
-        if (answer?.editable === true) build(deck);
+        // `assets` is the folder a drop lands in — a string, or null for a
+        // server that mounts the editing but no place to put a file.
+        if (answer?.editable === true) build(deck, answer.assets ?? null);
       })
       .catch(() => {});
   },
 });
 
-const build = (deck) => {
+const build = (deck, assetsDir) => {
   // ---- chrome -----------------------------------------------------------
   // The toolbar is annotate's; this plugin registers after the others in
   // deck.js and hangs its button last. A deck running without them still
@@ -112,9 +117,9 @@ const build = (deck) => {
   button.className = 'deck-tool';
   button.type = 'button';
   button.setAttribute('aria-pressed', 'false');
-  button.title = 'Edit — this slide’s markdown and notes (T)';
+  button.title = 'Edit — this slide’s markdown and notes (Shift+E)';
   button.setAttribute('aria-label', 'Edit the slide');
-  button.innerHTML = `${EDIT_ICON}<span class="deck-key" aria-hidden="true">T</span>`;
+  button.innerHTML = `${EDIT_ICON}<span class="deck-key" aria-hidden="true">⇧E</span>`;
   toolbar.append(button);
 
   const panel = document.createElement('aside');
@@ -129,7 +134,11 @@ const build = (deck) => {
     </header>
     <div class="deck-edit-row">
       <label class="deck-edit-label" for="deck-edit-source">slide</label>
-      <button type="button" class="deck-edit-snip" title="Insert a block (/)" aria-label="Insert a block">${PLUS_ICON}</button>
+      <span class="deck-edit-row-acts">
+        <button type="button" class="deck-edit-drop" hidden
+          aria-label="Add a file to the assets folder">${DROP_ICON}</button>
+        <button type="button" class="deck-edit-snip" title="Insert a block (/)" aria-label="Insert a block">${PLUS_ICON}</button>
+      </span>
     </div>
     <textarea id="deck-edit-source" spellcheck="false"></textarea>
     <label class="deck-edit-label" for="deck-edit-notes">speaker notes</label>
@@ -177,12 +186,20 @@ const build = (deck) => {
 
   const markdownPlugin = deck.getPlugin('markdown');
   const highlightPlugin = deck.getPlugin('highlight');
+
+  // The same hljs that colours the slides' code blocks, colouring the markdown
+  // the slide is written in. It wraps the textarea, so it is built before
+  // anything else measures or positions itself against the drawer.
+  const syntax = createSyntax({ area: sourceArea, hljs: highlightPlugin?.hljs });
+
   const marked = markdownPlugin?.marked;
   const render = marked ? (marked.parse ?? marked).bind(marked) : null;
 
   let frame = 0;
   const paint = () => {
     frame = 0;
+    // The colours track the text even on a slide that has no live preview.
+    syntax.refresh();
     if (!editing?.preview) return;
     editing.slide.innerHTML = render(sourceArea.value);
     if (highlightPlugin?.hljs) {
@@ -206,6 +223,20 @@ const build = (deck) => {
   const snippets = createSnippets({ area: sourceArea, paint: schedulePaint });
   panel.append(snippets.element);
 
+  // ---- the assets drop ----------------------------------------------------
+  // Over the drawer like the picker, but the drop itself is the whole page:
+  // dragging a file onto the slide you are writing is the gesture, and the
+  // drawer being open is what says the file belongs to this deck.
+
+  const assets = createAssets({ paste: snippets.paste, active: () => Boolean(editing) });
+  panel.append(assets.element);
+
+  const dropButton = panel.querySelector('.deck-edit-drop');
+  if (assetsDir) {
+    dropButton.hidden = false;
+    dropButton.title = `Add a file to ${assetsDir}/ — or just drop it on the deck`;
+  }
+
   // ---- open and close ---------------------------------------------------
   // The deck is narrowed by CSS while the drawer is out (see theme.base.css);
   // reveal only rescales when told to, so layout() is driven for as long as
@@ -256,6 +287,8 @@ const build = (deck) => {
     cancelAnimationFrame(frame);
     frame = 0;
     snippets.close({ restore: false });
+    assets.close();
+    assets.hideSheet();
     confirmBox.hidden = true;
     editing.slide.innerHTML = editing.html;
     // The original fragments are back; reveal counts them again.
@@ -309,6 +342,9 @@ const build = (deck) => {
     fileLabel.textContent = src.file;
     sourceArea.value = content;
     notesArea.value = notes;
+    // Setting `value` fires no input event, and the slide is already rendered:
+    // only the colours need catching up.
+    syntax.refresh();
     snippets.reset();
     status.textContent = '';
     saveButton.disabled = false;
@@ -398,6 +434,7 @@ const build = (deck) => {
     setWide(!document.body.classList.contains('edit-wide')),
   );
   panel.querySelector('.deck-edit-snip').addEventListener('click', () => snippets.open());
+  dropButton.addEventListener('click', () => (assets.isOpen() ? assets.close() : assets.open()));
   saveButton.addEventListener('click', save);
   sourceArea.addEventListener('input', schedulePaint);
 
@@ -441,19 +478,32 @@ const build = (deck) => {
     }
   });
 
-  // `addKeyBinding` with a descriptor binds the key and lists it in reveal's
-  // help overlay. Reveal ignores the keyboard while a textarea has focus, so
+  // Shift+E opens the drawer — E alone belongs to the spotlight. Reveal drops
+  // any shifted key it doesn't whitelist before bindings run, so this listens
+  // on the document itself and only borrows reveal's help overlay for the
+  // listing. Reveal ignores the keyboard while a textarea has focus, so
   // closing from inside the drawer is Escape's job, taken in capture phase
   // before reveal reads it as the overview toggle.
-  deck.addKeyBinding({ keyCode: KEY_CODE, key: 'T', description: 'Edit the slide' }, toggle);
+  deck.registerKeyboardShortcut('SHIFT+E', 'Edit the slide');
+  document.addEventListener('keydown', (event) => {
+    if (event.code !== 'KeyE' || !event.shiftKey) return;
+    if (event.ctrlKey || event.altKey || event.metaKey) return;
+    const active = document.activeElement;
+    if (active && (active.isContentEditable || /input|textarea/i.test(active.tagName))) return;
+    event.preventDefault();
+    toggle();
+  });
   document.addEventListener(
     'keydown',
     (event) => {
       if (event.key !== 'Escape' || !editing) return;
-      // One layer at a time, innermost first: the picker, then a pending
-      // delete question, then the drawer itself.
+      // One layer at a time, innermost first: the picker, the assets panel
+      // (which has a layer of its own), then a pending delete question, then
+      // the drawer itself.
       if (snippets.isOpen()) snippets.close();
-      else if (confirmBox.hidden) close();
+      else if (assets.escape()) {
+        /* the panel took it */
+      } else if (confirmBox.hidden) close();
       else confirmBox.hidden = true;
       event.stopPropagation();
       event.preventDefault();

package/runtime/snippets.js

@@ -17,115 +17,205 @@
 const CFG = window.__FB_SLIDES__ ?? {};
 
 // `top: true` — the block only works as the first thing in a slide, so that is
-// where it goes, wherever the cursor happens to be.
+// where it goes, wherever the cursor happens to be. `keys` are the words the
+// filter also answers to — what someone types looking for the block ("img",
+// "mermaid") rather than what its row says. `group` is the header the block
+// sits under in the list.
 const BUILT_IN = [
   {
+    group: 'Slide',
     label: 'Demo, full slide',
-    hint: 'a folder in demo/, running on the slide',
+    hint: 'a folder in demo/ — below the marker, the GitHub fallback',
+    keys: 'iframe app live run fallback',
     top: true,
-    body: '<!-- demo: ${counter} -->',
+    body:
+      '<!-- demo: ${counter} -->\n\n' +
+      '## Live demo\n\n' +
+      '<iframe src="../demo/counter/" style="width:100%;height:60vh"></iframe>',
   },
   {
+    group: 'Slide',
     label: 'External page, full slide',
-    hint: 'any URL, taking the whole slide',
+    hint: 'any URL — add | src: demo/x for the source button',
+    keys: 'url website iframe embed src fallback',
+    top: true,
+    body:
+      '<!-- demo: ${https://example.com/} -->\n\n' +
+      '## Live demo\n\n' +
+      '<iframe src="https://example.com/" style="width:100%;height:60vh"></iframe>',
+  },
+  {
+    group: 'Slide',
+    label: 'Section divider',
+    hint: 'an h1 on its own — the gradient chapter break',
+    keys: 'title chapter heading h1 break',
+    top: true,
+    body: '# ${Section}',
+  },
+  {
+    group: 'Slide',
+    label: 'Speaker page',
+    hint: 'photos down the left edge, who you are on the right',
+    keys: 'author bio about photo intro',
     top: true,
-    body: '<!-- demo: ${https://example.com/} -->',
+    body:
+      '<!-- .slide: class="author-slide" -->\n\n' +
+      '<div class="author-photo">\n' +
+      '  <img src="assets/author/${portrait.jpg}" alt="" />\n' +
+      '  <img src="assets/author/on-stage.jpg" alt="" />\n' +
+      '</div>\n\n' +
+      '<div class="author-bio">\n' +
+      '  <h1>Your name</h1>\n' +
+      '  <ul>\n' +
+      '    <li>What you do</li>\n' +
+      '    <li>What you are known for</li>\n' +
+      '  </ul>\n' +
+      '  <p class="author-meta">The stack · you · work · with</p>\n' +
+      '  <p class="author-meta">❤️ Life outside work — <strong>yoursite.dev</strong></p>\n' +
+      '</div>',
   },
   {
+    group: 'Slide',
+    label: 'Disabled',
+    hint: 'keep the slide, leave it out of the talk',
+    keys: 'skip hide off draft',
+    top: true,
+    body: '<!-- disabled -->',
+  },
+  {
+    group: 'Slide',
+    label: 'Slide class',
+    hint: 'hand this slide a class of your own',
+    keys: 'css attribute custom style',
+    top: true,
+    body: '<!-- .slide: class="${name}" -->',
+  },
+  {
+    group: 'Layout',
+    label: 'Two columns',
+    hint: 'code on one side, words on the other',
+    keys: 'cols split side half layout',
+    body:
+      '<div class="cols">\n<div class="col">\n\n${left}\n\n</div>\n' +
+      '<div class="col">\n\n${right}\n\n</div>\n</div>',
+  },
+  {
+    group: 'Layout',
     label: 'Framed embed',
     hint: 'an iframe that shares the slide with the text',
+    keys: 'iframe url page window',
     body: '<div class="frame">\n  <iframe src="${https://example.com/}"></iframe>\n</div>',
   },
   {
-    label: 'Video',
-    hint: 'a clip from assets/, with the attributes that make it behave',
-    body:
-      '<video src="assets/${clip.mp4}" controls muted playsinline preload="metadata"\n' +
-      '  style="width: 78%; aspect-ratio: 16 / 9;"></video>',
+    group: 'Layout',
+    label: 'Callout',
+    hint: 'a bordered block — the point the slide comes back to',
+    keys: 'box border note highlight important',
+    body: '<div class="box">\n\n${text}\n\n</div>',
+  },
+  {
+    group: 'Layout',
+    label: 'Caption',
+    hint: 'a quiet line under a figure',
+    keys: 'figure label small muted aside',
+    body: '<p class="caption">${text}</p>',
   },
   {
+    group: 'Media',
     label: 'Image',
     hint: 'centred, no frame around it',
+    keys: 'img picture screenshot png photo',
     body: '![](assets/${shot.png})',
   },
   {
-    label: 'Two columns',
-    hint: 'code on one side, words on the other',
+    group: 'Media',
+    label: 'Video',
+    hint: 'a clip from assets/, with the attributes that make it behave',
+    keys: 'clip mp4 movie recording',
     body:
-      '<div class="cols">\n<div class="col">\n\n${left}\n\n</div>\n' +
-      '<div class="col">\n\n${right}\n\n</div>\n</div>',
+      '<video src="assets/${clip.mp4}" controls muted playsinline preload="metadata"\n' +
+      '  style="width: 78%; aspect-ratio: 16 / 9;"></video>',
+  },
+  {
+    group: 'Media',
+    label: 'Video, autoplay',
+    hint: 'plays when the slide shows, loops, no controls — a living screenshot',
+    keys: 'clip mp4 loop background silent animation',
+    body:
+      '<video src="assets/${clip.mp4}" data-autoplay muted loop playsinline\n' +
+      '  style="width: 78%; aspect-ratio: 16 / 9;"></video>',
   },
   {
+    group: 'Code',
     label: 'Code',
     hint: 'a fenced block, highlighted',
+    keys: 'fence snippet js ts source',
     body: '```${ts}\n${code}\n```',
   },
   {
+    group: 'Code',
     label: 'Code, stepped',
     hint: 'the block reveals itself a range of lines at a time',
+    keys: 'lines ranges walkthrough highlight steps',
     body: '```${ts} [1-3|5-7|9]\n${code}\n```',
   },
   {
+    group: 'Code',
     label: 'Diagram',
     hint: 'a mermaid graph, drawn at load',
+    keys: 'mermaid flowchart graph chart boxes',
     body: '```mermaid\nflowchart LR\n  A[${Client}] --> B[Server]\n```',
   },
   {
+    group: 'Code',
+    label: 'Diagram, sequence',
+    hint: 'who talks to whom, in order',
+    keys: 'mermaid sequence actors messages arrows',
+    body:
+      '```mermaid\nsequenceDiagram\n' +
+      '  participant A as ${Client}\n' +
+      '  participant B as Server\n' +
+      '  A->>B: request\n' +
+      '  B-->>A: response\n```',
+  },
+  {
+    group: 'Text',
     label: 'Fragment',
-    hint: 'appears on the next press, on its own',
+    hint: 'a paragraph that appears on the next press',
+    keys: 'appear step reveal click',
     body: '<p class="fragment">${text}</p>',
   },
   {
-    label: 'Callout',
-    hint: 'a bordered block — the point the slide comes back to',
-    body: '<div class="box">\n\n${text}\n\n</div>',
+    group: 'Text',
+    label: 'Fragment, any block',
+    hint: 'the comment tags whatever sits above it — an image, a list, a box',
+    keys: 'appear step reveal element attach',
+    body: '${content}\n<!-- .element: class="fragment" -->',
   },
   {
-    label: 'Caption',
-    hint: 'a quiet line under a figure',
-    body: '<p class="caption">${text}</p>',
+    group: 'Text',
+    label: 'Table',
+    hint: 'styled by the theme — first column muted, rows striped',
+    keys: 'grid rows columns data',
+    body: '| ${Column} | Column |\n| --- | --- |\n| value | value |\n| value | value |',
   },
   {
-    label: 'Speaker page',
-    hint: 'photos down the left edge, who you are on the right',
-    top: true,
-    body:
-      '<!-- .slide: class="author-slide" -->\n\n' +
-      '<div class="author-photo">\n' +
-      '  <img src="assets/author/${portrait.jpg}" alt="" />\n' +
-      '  <img src="assets/author/on-stage.jpg" alt="" />\n' +
-      '</div>\n\n' +
-      '<div class="author-bio">\n' +
-      '  <h1>Your name</h1>\n' +
-      '  <ul>\n' +
-      '    <li>What you do</li>\n' +
-      '    <li>What you are known for</li>\n' +
-      '  </ul>\n' +
-      '  <p class="author-meta">The stack · you · work · with</p>\n' +
-      '  <p class="author-meta">❤️ Life outside work — <strong>yoursite.dev</strong></p>\n' +
-      '</div>',
-  },
-  {
-    label: 'Disabled',
-    hint: 'keep the slide, leave it out of the talk',
-    top: true,
-    body: '<!-- disabled -->',
-  },
-  {
-    label: 'Slide class',
-    hint: 'hand this slide a class of your own',
-    top: true,
-    body: '<!-- .slide: class="${name}" -->',
+    group: 'Text',
+    label: 'Quote',
+    hint: 'a blockquote on the accent bar',
+    keys: 'blockquote citation pull saying',
+    body: '> ${The line worth quoting.}',
   },
 ];
 
-// The project's own blocks land after the built-in ones. A snippet without a
-// body would be an entry that inserts nothing, so it never reaches the list.
+// The project's own blocks land after the built-in ones, under their own
+// header unless the config names one. A snippet without a body would be an
+// entry that inserts nothing, so it never reaches the list.
 const catalog = () => [
   ...BUILT_IN,
-  ...(Array.isArray(CFG.snippets) ? CFG.snippets : []).filter(
-    (snippet) => snippet && typeof snippet.body === 'string',
-  ),
+  ...(Array.isArray(CFG.snippets) ? CFG.snippets : [])
+    .filter((snippet) => snippet && typeof snippet.body === 'string')
+    .map((snippet) => ({ group: 'Project', ...snippet })),
 ];
 
 const PLACEHOLDER = /\$\{([^}]*)\}/g;
@@ -173,21 +263,31 @@ export const createSnippets = ({ area, paint }) => {
   element.innerHTML = `
     <input class="deck-snip-filter" type="text" spellcheck="false" autocomplete="off"
       placeholder="Insert a block…" aria-label="Find a block" />
+    <p class="deck-snip-empty" hidden>No block answers to that.</p>
     <ul class="deck-snip-list" role="listbox"></ul>
+    <pre class="deck-snip-preview" aria-hidden="true"></pre>
   `;
 
   const filter = element.querySelector('.deck-snip-filter');
   const list = element.querySelector('.deck-snip-list');
+  const empty = element.querySelector('.deck-snip-empty');
+  const preview = element.querySelector('.deck-snip-preview');
 
+  // Every block under its group's header. A header is furniture, not an
+  // option: it carries no data-index, and the keyboard walks straight past it.
   const blocks = catalog();
+  let group = null;
   list.innerHTML = blocks
-    .map(
-      (snippet, index) =>
-        `<li role="option" data-index="${index}"><span>${snippet.label}</span>` +
-        `<small>${snippet.hint ?? ''}</small></li>`,
-    )
+    .map((snippet, index) => {
+      const head =
+        snippet.group !== group ? `<li class="deck-snip-head">${(group = snippet.group)}</li>` : '';
+      return (
+        `${head}<li role="option" data-index="${index}"><span>${snippet.label}</span>` +
+        `<small>${snippet.hint ?? ''}</small></li>`
+      );
+    })
     .join('');
-  const items = [...list.children];
+  const items = [...list.querySelectorAll('li[data-index]')];
 
   // Where the block goes, decided when the picker opens: the cursor at that
   // moment, or the `/` that summoned it. `take` says whether what that range
@@ -210,15 +310,21 @@ export const createSnippets = ({ area, paint }) => {
 
   const current = () => list.querySelector('.is-current');
 
+  // The pane under the list shows the markup the highlighted row would write,
+  // placeholders unwrapped — what lands in the slide, before it lands.
   const highlight = (item) => {
     current()?.classList.remove('is-current');
     item?.classList.add('is-current');
     item?.scrollIntoView({ block: 'nearest' });
+    preview.textContent = item ? fill(blocks[Number(item.dataset.index)].body, '').text : '';
   };
 
   const apply = () => {
     const shown = items.filter((item) => !item.hidden);
-    if (!shown.length) return;
+    empty.hidden = Boolean(shown.length);
+    list.hidden = !shown.length;
+    preview.hidden = !shown.length;
+    if (!shown.length) return highlight(null);
     highlight(shown.includes(current()) ? current() : shown[0]);
   };
 
@@ -226,7 +332,17 @@ export const createSnippets = ({ area, paint }) => {
     const query = filter.value.trim().toLowerCase();
     for (const item of items) {
       const snippet = blocks[Number(item.dataset.index)];
-      item.hidden = Boolean(query) && !`${snippet.label} ${snippet.hint ?? ''}`.toLowerCase().includes(query);
+      const words = `${snippet.label} ${snippet.hint ?? ''} ${snippet.keys ?? ''} ${snippet.group ?? ''}`;
+      item.hidden = Boolean(query) && !words.toLowerCase().includes(query);
+    }
+    // A header with nothing left under it goes with its blocks: walk the list,
+    // and show each one only if an option before the next header survived.
+    for (const head of list.querySelectorAll('.deck-snip-head')) {
+      let shown = false;
+      for (let li = head.nextElementSibling; li && li.dataset.index; li = li.nextElementSibling) {
+        if (!li.hidden) shown = true;
+      }
+      head.hidden = !shown;
     }
     apply();
   };
@@ -254,15 +370,19 @@ export const createSnippets = ({ area, paint }) => {
     filter.focus();
   };
 
+  // `literal: true` — the body is already the text, placeholders and all: what
+  // the assets panel writes is a path, not a template to type over.
   const insert = (snippet) => {
-    const { from, to, take } = target ?? { from: area.value.length, to: area.value.length };
+    const { from, to, take } = target ?? { from: caret[0], to: caret[1], take: false };
     // A block that only works at the top of a slide goes there whatever the
     // cursor was doing, and never swallows a selection on the way.
     const at = snippet.top ? { from: 0, to: 0, take: false } : { from, to, take };
 
     const before = area.value.slice(0, at.from);
     const after = area.value.slice(at.to);
-    const { text, range } = fill(snippet.body, at.take ? area.value.slice(at.from, at.to) : '');
+    const { text, range } = snippet.literal
+      ? { text: snippet.body, range: null }
+      : fill(snippet.body, at.take ? area.value.slice(at.from, at.to) : '');
 
     const lead = gap(before, true);
     const trail = gap(after, false);
@@ -296,11 +416,11 @@ export const createSnippets = ({ area, paint }) => {
   });
 
   list.addEventListener('click', (event) => {
-    const item = event.target.closest('li');
+    const item = event.target.closest('li[data-index]');
     if (item) insert(blocks[Number(item.dataset.index)]);
   });
   list.addEventListener('mousemove', (event) => {
-    const item = event.target.closest('li');
+    const item = event.target.closest('li[data-index]');
     if (item && item !== current()) highlight(item);
   });
 
@@ -313,7 +433,16 @@ export const createSnippets = ({ area, paint }) => {
     open({ from: at, to: at + 1, take: false });
   });
 
-  return { element, open, close, isOpen: () => !element.hidden, reset };
+  return {
+    element,
+    open,
+    close,
+    isOpen: () => !element.hidden,
+    reset,
+    // A block from somewhere other than the list — the assets panel — landing
+    // at the same cursor, with the same blank lines around it.
+    paste: (body) => insert({ body, literal: true }),
+  };
 };
 
 export default createSnippets;

package/runtime/syntax.js

@@ -0,0 +1,64 @@
+// ---------------------------------------------------------------------------
+// Markdown colour under the slide's textarea.
+//
+// A textarea paints its own text and nothing else — no spans, no colours. So
+// the box becomes two layers: a <pre> holding the same text run through
+// highlight.js, and the real textarea on top of it with transparent ink and a
+// visible caret. They share the font, the padding and the wrapping mode, so
+// every letter lands exactly on its coloured twin, and what you drag, select,
+// undo and type into is still a plain textarea — nothing here touches editing.
+//
+// highlight.js is not a new dependency: it arrives inside reveal's highlight
+// plugin, the one already colouring the code blocks on the slides, and its
+// markdown grammar is in that bundle. The colours themselves are this theme's
+// tokens (see .deck-edit-ink in theme.base.css), not the monokai the slides
+// wear — the drawer follows whatever palette the deck is dressed in.
+// ---------------------------------------------------------------------------
+
+export const createSyntax = ({ area, hljs, language = 'markdown' }) => {
+  // No highlight plugin, or a bundle without this grammar: the textarea stays
+  // exactly as it was, and the drawer never knows.
+  if (!hljs?.getLanguage?.(language)) return { refresh: () => {} };
+
+  const box = document.createElement('div');
+  box.className = 'deck-edit-code';
+  const layer = document.createElement('pre');
+  layer.className = 'deck-edit-ink';
+  layer.setAttribute('aria-hidden', 'true');
+  const ink = document.createElement('code');
+  layer.append(ink);
+
+  // The textarea keeps its id, its listeners and its place in the flex column
+  // — the wrapper takes that place, and the sizing rules with it.
+  area.replaceWith(box);
+  box.append(layer, area);
+
+  // The textarea's scrollbar eats width from its text but not from the layer's,
+  // and the two would then wrap at different columns. Measuring is the only
+  // portable answer: it comes out 0 wherever the bar is drawn as an overlay.
+  const gutter = () => {
+    box.style.setProperty('--code-gutter', `${area.offsetWidth - area.clientWidth}px`);
+  };
+
+  const sync = () => {
+    layer.scrollTop = area.scrollTop;
+    layer.scrollLeft = area.scrollLeft;
+  };
+
+  const refresh = () => {
+    // The trailing newline is the one the textarea keeps a line box for while a
+    // paragraph is being ended; without it the layer comes up a line short and
+    // the caret sits over nothing.
+    ink.innerHTML = hljs.highlight(`${area.value}\n`, { language, ignoreIllegals: true }).value;
+    gutter();
+    sync();
+  };
+
+  // Typing is the caller's `paint` (it re-renders the slide too); these are the
+  // ways the two layers can drift apart without a keystroke.
+  area.addEventListener('scroll', sync);
+  new ResizeObserver(gutter).observe(area);
+
+  refresh();
+  return { refresh };
+};