fb-slides 0.3.0 → 0.4.0

package/README.md

@@ -129,6 +129,8 @@ Note: a bad description is the most common reason a tool never gets used.
 | --- | --- |
 | `→` / `Space` | next step (fragments included) |
 | `P` | the pen — draw on the slide, the ink fades on its own |
+| `A` | the arrow — click the tail, then the tip; same colours as the pen |
+| `C` | the pointer — replaces the cursor: a glowing halo, a dart aimed at the centre, or the normal mouse |
 | `Shift` (tap) | the spotlight — drag a rectangle, the rest of the slide dims and blurs |
 | `S` | speaker view — notes, timer, next slide |
 | `Esc` / `O` | overview — the slides as a grid |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fb-slides",
-  "version": "0.3.0",
+  "version": "0.4.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

@@ -5,6 +5,10 @@
 // whole feature — its chrome, its canvas and its key bindings — and index.html
 // stays a page of slides. Register it in the `plugins:` array like any other.
 //
+// Two tools share everything here: the pen, and the arrow — click where it
+// starts, click (or release a drag) where it points. Same canvas, same
+// palette, same hold-then-fade; an arrow is just one more kind of stroke.
+//
 // The ink goes on one full-viewport canvas in screen pixels, which keeps it
 // clear of the CSS transform reveal scales a slide with: the pen follows the
 // pointer, not the slide's coordinate space.
@@ -46,6 +50,14 @@ const TENSION = 1 / 6;
 
 const WIDTH = 3.4; // px, the bright core of the line
 
+// The arrow's head: how far back along the shaft the wings reach, and how far
+// they open off it. A short arrow shrinks its head rather than being all head.
+const HEAD_LEN = 48;
+const HEAD_SPREAD = 0.55; // radians
+// Under this, a press-and-release is a click placing the tail, not a whole
+// arrow: the tip then follows the pointer until the second click.
+const MIN_ARROW = 12;
+
 // Two layers, each the same path stroked at a few widths: a soft halo, then the
 // core on top of it. Within a layer the passes stack additively, hence the low
 // alphas. Cheaper than a shadowBlur per segment.
@@ -64,8 +76,10 @@ const QUANTA = 24;
 // `P` is reveal's own previous-slide key, and a plugin binding wins over it —
 // which is the point: on stage the pen is reached for far more often than a key
 // ← and Shift+Space already do. Reveal's own row in the help overlay still
-// lists it, though, so it has to be corrected.
-const KEY_CODE = 80;
+// lists it, though, so it has to be corrected. `A` is reveal's auto-slide
+// toggle, idle in a deck that does not auto-advance — the arrow takes it.
+const PEN_KEY_CODE = 80;
+const ARROW_KEY_CODE = 65;
 const HELP_TAKEN_FROM = { key: 'P', from: /previous/i };
 
 const PEN_ICON = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7"
@@ -73,6 +87,11 @@ const PEN_ICON = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" str
   <path d="M15.2 4.6l4.2 4.2" /><path d="M4 20l4.7-1L19.8 7.9a2 2 0 0 0-2.8-2.8L5.9 16.3 4 20z" />
 </svg>`;
 
+const ARROW_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="M5 19L19 5" /><path d="M9.5 5H19v9.5" />
+</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) => {
@@ -126,7 +145,9 @@ const RevealAnnotate = () => ({
     toolbar.innerHTML = `
       <button id="tool-pen" class="deck-tool" type="button" aria-pressed="false"
               title="Pen — draw on the slide (P)" aria-label="Pen">${PEN_ICON}</button>
-      <div id="deck-swatches" role="radiogroup" aria-label="Pen colour" hidden>
+      <button id="tool-arrow" class="deck-tool" type="button" aria-pressed="false"
+              title="Arrow — click the tail, then the tip (A)" aria-label="Arrow">${ARROW_ICON}</button>
+      <div id="deck-swatches" role="radiogroup" aria-label="Ink colour" hidden>
         ${COLOURS.map(
           (colour, i) => `<button class="deck-swatch" type="button" role="radio"
              aria-checked="${i === 0}" data-colour="${i}" style="--ink:${colour.glow}"
@@ -137,6 +158,7 @@ const RevealAnnotate = () => ({
 
     document.body.append(canvas, toolbar);
     const penButton = toolbar.querySelector('#tool-pen');
+    const arrowButton = toolbar.querySelector('#tool-arrow');
     const swatches = toolbar.querySelector('#deck-swatches');
     const ctx = canvas.getContext('2d');
 
@@ -208,9 +230,12 @@ const RevealAnnotate = () => ({
     // ---- strokes --------------------------------------------------------
     // A stroke is its points, the colour it was drawn in, and the moment the
     // pointer left the slide: `releasedAt: null` is one still under the pen.
+    // An arrow rides the same list with `kind: 'arrow'` and two points, `from`
+    // and `to` — it holds and fades exactly like a line of ink.
 
     const strokes = [];
-    let drawing = null;
+    let drawing = null; // the pen's live stroke, or null
+    let placing = null; // an arrow whose tip still follows the pointer, or null
     let frame = 0;
     let holdTimer = 0;
 
@@ -285,6 +310,53 @@ const RevealAnnotate = () => ({
       return runs;
     };
 
+    // An arrow has no oldest end worth erasing first: it fades out whole, the
+    // shaft and its head together. The shaft ends where the head begins, so
+    // the glow's rounded cap never pokes past the tip.
+    const paintArrow = (stroke, progress) => {
+      const { from, to } = stroke;
+      const length = Math.hypot(to.x - from.x, to.y - from.y);
+      if (length < 1) return true;
+      const box = boundsOf([from, to]);
+      if (box.w <= 0 || box.h <= 0) return true;
+
+      const fade = progress === null ? 1 : 1 - progress;
+      const angle = Math.atan2(to.y - from.y, to.x - from.x);
+      const head = Math.min(HEAD_LEN, length * 0.6);
+      const wings = [HEAD_SPREAD, -HEAD_SPREAD].map((spread) => ({
+        x: to.x - head * Math.cos(angle + spread),
+        y: to.y - head * Math.sin(angle + spread),
+      }));
+      const base = {
+        x: to.x - head * 0.75 * Math.cos(angle),
+        y: to.y - head * 0.75 * Math.sin(angle),
+      };
+
+      for (const { ink, passes } of LAYERS) {
+        onLayer(box, stroke.ink[ink], (c) => {
+          c.lineCap = 'round';
+          for (const pass of passes) {
+            c.lineWidth = WIDTH * pass.width;
+            c.strokeStyle = c.fillStyle = `rgba(255, 255, 255, ${fade * pass.alpha})`;
+            c.beginPath();
+            c.moveTo(from.x, from.y);
+            c.lineTo(base.x, base.y);
+            c.stroke();
+            // The head is filled for its body and stroked for its glow: the
+            // stroke fattens it by the same width the shaft wears.
+            c.beginPath();
+            c.moveTo(to.x, to.y);
+            c.lineTo(wings[0].x, wings[0].y);
+            c.lineTo(wings[1].x, wings[1].y);
+            c.closePath();
+            c.fill();
+            c.stroke();
+          }
+        });
+      }
+      return true;
+    };
+
     // Returns false once the stroke has faded out and can be dropped.
     const paint = (stroke, now) => {
       // Clamped at 0 through the hold: a stroke waiting its turn paints exactly
@@ -295,6 +367,8 @@ const RevealAnnotate = () => ({
           : Math.max(0, (now - stroke.releasedAt - HOLD_MS) / FADE_MS);
       if (progress !== null && progress >= 1) return false;
 
+      if (stroke.kind === 'arrow') return paintArrow(stroke, progress);
+
       const box = boundsOf(stroke.points);
       if (box.w <= 0 || box.h <= 0) return true;
 
@@ -360,16 +434,18 @@ const RevealAnnotate = () => ({
 
     const clear = () => {
       drawing = null;
+      placing = null;
       strokes.length = 0;
       clearTimeout(holdTimer);
       holdTimer = 0;
       ctx.clearRect(0, 0, width, height);
     };
 
-    // ---- the pen --------------------------------------------------------
+    // ---- the tools ------------------------------------------------------
 
-    let penOn = false;
+    let tool = null; // null, 'pen' or 'arrow'
     let ink = COLOURS[0];
+    const toolButtons = { pen: penButton, arrow: arrowButton };
 
     const setInk = (colour) => {
       ink = colour;
@@ -381,29 +457,60 @@ const RevealAnnotate = () => ({
       }
     };
 
-    const setPen = (on) => {
-      penOn = on;
-      penButton.setAttribute('aria-pressed', String(on));
-      toolbar.classList.toggle('is-armed', on);
-      // The colours are only worth showing while there is a pen to apply them
-      // to, which makes arming it the one gesture that opens them.
-      swatches.hidden = !on;
+    const setTool = (next) => {
+      if (next === tool) return;
+      // Whatever was mid-gesture under the old tool does not survive the
+      // switch: a half-drawn line is released, a half-aimed arrow discarded.
+      if (drawing) {
+        drawing.releasedAt = performance.now();
+        drawing = null;
+      }
+      if (placing) {
+        strokes.splice(strokes.indexOf(placing), 1);
+        placing = null;
+        schedule();
+      }
+      tool = next;
+      for (const [name, button] of Object.entries(toolButtons)) {
+        button.setAttribute('aria-pressed', String(name === tool));
+      }
+      toolbar.classList.toggle('is-armed', tool !== null);
+      // The colours are only worth showing while there is a tool to apply them
+      // to, which makes arming one the gesture that opens them.
+      swatches.hidden = tool === null;
       // Only an armed canvas takes the pointer; the rest of the time clicks
       // fall through to the slide underneath.
-      canvas.classList.toggle('is-live', on);
-      if (on) document.dispatchEvent(new CustomEvent('deck:tool-armed', { detail: 'pen' }));
+      canvas.classList.toggle('is-live', tool !== null);
+      if (tool) document.dispatchEvent(new CustomEvent('deck:tool-armed', { detail: tool }));
       else clear();
     };
+    const toggleTool = (name) => setTool(tool === name ? null : name);
 
-    // Two tools, one pointer: arming either disarms the other. The handshake
+    // Several tools, one pointer: arming any disarms the rest. The handshake
     // is a DOM event rather than an import either way round, so each plugin
-    // works alone.
+    // works alone. Pen and arrow are both this plugin's, so only a foreign
+    // detail stands it down.
     document.addEventListener('deck:tool-armed', (event) => {
-      if (event.detail !== 'pen' && penOn) setPen(false);
+      if (event.detail !== 'pen' && event.detail !== 'arrow' && tool) setTool(null);
     });
 
     canvas.addEventListener('pointerdown', (event) => {
-      if (!penOn || event.button !== 0) return;
+      if (!tool || event.button !== 0) return;
+      if (tool === 'arrow') {
+        // Second click: the tip lands here. First click: the tail does, and
+        // the tip follows the pointer until the next one.
+        if (placing) {
+          placing.to = { x: event.clientX, y: event.clientY };
+          placing.releasedAt = performance.now();
+          placing = null;
+        } else {
+          const at = { x: event.clientX, y: event.clientY };
+          placing = { kind: 'arrow', from: at, to: { ...at }, releasedAt: null, ink };
+          strokes.push(placing);
+        }
+        schedule();
+        return;
+      }
       canvas.setPointerCapture(event.pointerId);
       // The colour is caught at the down-stroke, so a line already fading keeps
       // the one it was drawn in when you pick another.
@@ -414,6 +521,12 @@ const RevealAnnotate = () => ({
     });
 
     canvas.addEventListener('pointermove', (event) => {
+      // An arrow being aimed follows the bare pointer — no button held.
+      if (placing) {
+        placing.to = { x: event.clientX, y: event.clientY };
+        schedule();
+        return;
+      }
       if (!drawing || event.pointerId !== drawing.id) return;
       // A trackpad reports faster than the display refreshes, and the samples
       // in between are what keeps a quick curve smooth instead of faceted.
@@ -425,6 +538,19 @@ const RevealAnnotate = () => ({
     });
 
     const release = (event) => {
+      // A drag long enough to be deliberate is the whole gesture: down at the
+      // tail, up at the tip. Anything shorter was a click, and the arrow stays
+      // under the pointer waiting for the second one.
+      if (placing) {
+        const span = Math.hypot(event.clientX - placing.from.x, event.clientY - placing.from.y);
+        if (span >= MIN_ARROW) {
+          placing.to = { x: event.clientX, y: event.clientY };
+          placing.releasedAt = performance.now();
+          placing = null;
+          schedule();
+        }
+        return;
+      }
       if (!drawing || event.pointerId !== drawing.id) return;
       drawing.releasedAt = performance.now();
       drawing = null;
@@ -433,7 +559,8 @@ const RevealAnnotate = () => ({
     canvas.addEventListener('pointerup', release);
     canvas.addEventListener('pointercancel', release);
 
-    penButton.addEventListener('click', () => setPen(!penOn));
+    penButton.addEventListener('click', () => toggleTool('pen'));
+    arrowButton.addEventListener('click', () => toggleTool('arrow'));
     swatches.addEventListener('click', (event) => {
       const button = event.target.closest('.deck-swatch');
       if (button) setInk(COLOURS[button.dataset.colour]);
@@ -441,19 +568,22 @@ const RevealAnnotate = () => ({
 
     // `addKeyBinding` with a descriptor binds the key and lists it in reveal's
     // own help overlay, which `registerKeyboardShortcut` alone would not do.
-    deck.addKeyBinding({ keyCode: KEY_CODE, key: 'P', description: 'Toggle the pen' }, () =>
-      setPen(!penOn),
+    deck.addKeyBinding({ keyCode: PEN_KEY_CODE, key: 'P', description: 'Toggle the pen' }, () =>
+      toggleTool('pen'),
+    );
+    deck.addKeyBinding({ keyCode: ARROW_KEY_CODE, key: 'A', description: 'Toggle the arrow' }, () =>
+      toggleTool('arrow'),
     );
-    // Keys the pen borrows only while it is armed, taken in capture phase so
+    // Keys the tools borrow only while one is armed, taken in capture phase so
     // reveal's own bindings never see them: Escape (otherwise the overview
-    // toggle) disarms it, and the number row picks its ink — 1 to 6, in the
+    // toggle) disarms it, and the number row picks the ink — 1 to 6, in the
     // order the swatches sit in the toolbar. The rest of the time both fall
     // through untouched.
     document.addEventListener(
       'keydown',
       (event) => {
-        if (!penOn || event.metaKey || event.ctrlKey || event.altKey) return;
-        if (event.key === 'Escape') setPen(false);
+        if (!tool || event.metaKey || event.ctrlKey || event.altKey) return;
+        if (event.key === 'Escape') setTool(null);
         else {
           const index = '123456'.indexOf(event.key);
           if (index === -1 || index >= COLOURS.length) return;
@@ -471,7 +601,7 @@ const RevealAnnotate = () => ({
     // A new slide is a clean sheet — including a line still under the pointer.
     deck.on('slidechanged', clear);
     // The overview is a different surface; drawing over it would annotate nothing.
-    deck.on('overviewshown', () => setPen(false));
+    deck.on('overviewshown', () => setTool(null));
 
     window.addEventListener('resize', resize);
     setInk(ink);

package/runtime/deck.js

@@ -1,5 +1,6 @@
 import RevealAnnotate from './annotate.js';
 import RevealSpotlight from './spotlight.js';
+import RevealPointer from './pointer.js';
 import RevealOutline from './outline.js';
 
 // ---------------------------------------------------------------------------
@@ -161,8 +162,9 @@ await Reveal.initialize({
   pdfSeparateFragments: false,
   // Anything the project wants to change, from `reveal:` in slides.config.js.
   ...(CFG.reveal ?? {}),
-  // Spotlight after Annotate: it hangs its button on the toolbar the pen builds.
-  plugins: [RevealMarkdown, RevealHighlight, RevealNotes, RevealAnnotate(), RevealSpotlight(), RevealOutline()],
+  // Spotlight and Pointer after Annotate: they hang their buttons on the
+  // toolbar the pen builds.
+  plugins: [RevealMarkdown, RevealHighlight, RevealNotes, RevealAnnotate(), RevealSpotlight(), RevealPointer(), RevealOutline()],
 });
 
 // ---------------------------------------------------------------------------

package/runtime/pointer.js

@@ -0,0 +1,249 @@
+// ---------------------------------------------------------------------------
+// RevealPointer — swap the mouse cursor for a stage pointer.
+//
+// A reveal.js plugin, built like spotlight.js: `init()` gets the deck, the file
+// owns its chrome and key bindings, and index.html stays a page of slides.
+//
+// Armed, it hides the real cursor everywhere and hangs its own on the pointer
+// instead. Three kinds, picked from a popover like the pen's swatches:
+//
+//   halo    — a bright dot inside a glowing ring; the ring trails the dot on a
+//             short elastic, which is what makes it read as alive rather than
+//             as a cursor theme.
+//   compass — a dart that always aims at the centre of the slide, so wherever
+//             the hand wanders the audience is pointed back at the deck.
+//   native  — the system cursor again, without standing the tool down: a way
+//             back to a normal mouse that keeps the popover one keystroke away.
+//
+// Unlike the pen and the spotlight it survives a slide change: it is the
+// cursor now, not a mark on one slide.
+// ---------------------------------------------------------------------------
+
+const KEY_CODE = 67; // C
+
+const KINDS = [
+  {
+    id: 'halo',
+    label: 'Halo pointer',
+    icon: `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7"
+      aria-hidden="true"><circle cx="12" cy="12" r="7.5" /><circle cx="12" cy="12" r="1.6"
+      fill="currentColor" stroke="none" /></svg>`,
+  },
+  {
+    id: 'compass',
+    label: 'Compass pointer — aims at the centre',
+    icon: `<svg viewBox="0 0 24 24" fill="currentColor" stroke="none" aria-hidden="true">
+      <path d="M21 12L4.5 19.5 8.6 12 4.5 4.5z" /></svg>`,
+  },
+  {
+    id: 'native',
+    label: 'Normal cursor',
+    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="M4 4l7.07 17 2.51-7.39L21 11.07z" /></svg>`,
+  },
+];
+
+// How hard the halo's ring is pulled towards the dot each frame: 1 would pin
+// it, lower trails further behind. The loop stops once it has caught up.
+const CHASE = 0.28;
+const SETTLED = 0.4; // px of remaining lag that counts as caught up
+
+const POINTER_ICON = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7"
+  stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+  <circle cx="12" cy="12" r="7" /><path d="M12 2v3M12 19v3M2 12h3M19 12h3" />
+</svg>`;
+
+const RevealPointer = () => ({
+  id: 'pointer',
+
+  init(deck) {
+    // ---- chrome ---------------------------------------------------------
+    // Fixed overlays on <body>, outside `.reveal` and its transforms. The
+    // pointer rides above every other overlay — it stands in for the cursor,
+    // which is always on top of what it points at.
+    const layer = document.createElement('div');
+    layer.id = 'deck-pointer';
+    layer.setAttribute('aria-hidden', 'true');
+    layer.dataset.kind = KINDS[0].id;
+    layer.innerHTML = `
+      <div class="deck-pointer-halo"></div>
+      <div class="deck-pointer-dot"></div>
+      <svg class="deck-pointer-compass" viewBox="0 0 24 24" aria-hidden="true">
+        <path d="M21 12L4.5 19.5 8.6 12 4.5 4.5z" />
+      </svg>
+    `;
+    layer.hidden = true;
+    document.body.append(layer);
+    const halo = layer.querySelector('.deck-pointer-halo');
+    const dot = layer.querySelector('.deck-pointer-dot');
+    const compass = layer.querySelector('.deck-pointer-compass');
+
+    // The toolbar is annotate's; this plugin registers after it in deck.js and
+    // hangs its button there. A deck running without the pen still gets one.
+    let toolbar = document.querySelector('#deck-tools');
+    if (!toolbar) {
+      toolbar = document.createElement('div');
+      toolbar.id = 'deck-tools';
+      toolbar.setAttribute('role', 'toolbar');
+      toolbar.setAttribute('aria-label', 'Slide tools');
+      document.body.append(toolbar);
+    }
+    const button = document.createElement('button');
+    button.id = 'tool-pointer';
+    button.className = 'deck-tool';
+    button.type = 'button';
+    button.setAttribute('aria-pressed', 'false');
+    button.title = 'Pointer — replace the cursor (C)';
+    button.setAttribute('aria-label', 'Pointer');
+    button.innerHTML = POINTER_ICON;
+    toolbar.append(button);
+
+    // The kind picker, hanging under the toolbar exactly like the pen's
+    // swatches — the two are never open at once, since arming one tool
+    // disarms the other.
+    const picker = document.createElement('div');
+    picker.id = 'deck-pointer-kinds';
+    picker.setAttribute('role', 'radiogroup');
+    picker.setAttribute('aria-label', 'Pointer kind');
+    picker.hidden = true;
+    picker.innerHTML = KINDS.map(
+      (kind, i) => `<button class="deck-pointer-kind" type="button" role="radio"
+         aria-checked="${i === 0}" data-kind="${kind.id}"
+         title="${kind.label}" aria-label="${kind.label}">${kind.icon}</button>`,
+    ).join('');
+    toolbar.append(picker);
+
+    // ---- following the pointer ------------------------------------------
+
+    let armed = false;
+    let kind = KINDS[0].id;
+    let x = -100; // the pointer, in screen px; parked off-screen until a move
+    let y = -100;
+    let hx = -100; // where the halo's ring has got to on its way there
+    let hy = -100;
+    let frame = 0;
+
+    const aim = () => {
+      // The dart pivots on its own centre to face the middle of the viewport;
+      // right at the centre it just keeps its last heading.
+      const dx = window.innerWidth / 2 - x;
+      const dy = window.innerHeight / 2 - y;
+      if (dx || dy) compass.style.rotate = `${Math.atan2(dy, dx)}rad`;
+    };
+
+    const render = () => {
+      frame = 0;
+      hx += (x - hx) * CHASE;
+      hy += (y - hy) * CHASE;
+      // `translate` the individual property, not `transform`: the press effect
+      // scales through `transform` in CSS, and the two must not fight.
+      dot.style.translate = `${x}px ${y}px`;
+      compass.style.translate = `${x}px ${y}px`;
+      halo.style.translate = `${hx}px ${hy}px`;
+      if (Math.hypot(x - hx, y - hy) > SETTLED) schedule();
+    };
+
+    const schedule = () => {
+      frame ||= requestAnimationFrame(render);
+    };
+
+    const move = (event) => {
+      x = event.clientX;
+      y = event.clientY;
+      if (!armed || kind === 'native') return;
+      layer.hidden = false;
+      aim();
+      schedule();
+    };
+    document.addEventListener('pointermove', move);
+    // Falling off the window edge — or the window losing focus — leaves no
+    // cursor to stand in for; a stale pointer would sit there pointing at
+    // nothing until the mouse came back.
+    document.addEventListener('mouseleave', () => { layer.hidden = true; });
+    window.addEventListener('blur', () => { layer.hidden = true; });
+
+    // A click lands somewhere: the pointer acknowledges it — the dot swells,
+    // the ring snaps in, the dart lunges. Pure CSS off this class.
+    document.addEventListener('pointerdown', (event) => {
+      if (armed && event.button === 0) layer.classList.add('is-pressed');
+    });
+    document.addEventListener('pointerup', () => layer.classList.remove('is-pressed'));
+
+    // ---- arming ---------------------------------------------------------
+
+    // The real cursor stands down only while a stand-in is up: armed on the
+    // native kind, the mouse is its ordinary self and the overlay stays away.
+    const applyCursor = () => {
+      const standIn = armed && kind !== 'native';
+      document.documentElement.classList.toggle('deck-pointer-on', standIn);
+      layer.hidden = true; // shown again by the first move, in the right place
+      if (standIn) {
+        // Start the ring already caught up, not sprinting in from off-screen.
+        hx = x;
+        hy = y;
+      }
+    };
+
+    const setKind = (next) => {
+      kind = next;
+      layer.dataset.kind = kind;
+      for (const chip of picker.children) {
+        chip.setAttribute('aria-checked', String(chip.dataset.kind === kind));
+      }
+      applyCursor();
+      aim();
+    };
+
+    const setPointer = (on) => {
+      armed = on;
+      button.setAttribute('aria-pressed', String(on));
+      toolbar.classList.toggle('is-armed', on);
+      picker.hidden = !on;
+      applyCursor();
+      if (on) document.dispatchEvent(new CustomEvent('deck:tool-armed', { detail: 'pointer' }));
+    };
+
+    // Several tools, one pointer: arming any disarms the rest — same DOM-event
+    // handshake as the pen and the spotlight, so each plugin works alone.
+    document.addEventListener('deck:tool-armed', (event) => {
+      if (event.detail !== 'pointer' && armed) setPointer(false);
+    });
+
+    button.addEventListener('click', () => setPointer(!armed));
+    picker.addEventListener('click', (event) => {
+      const chip = event.target.closest('.deck-pointer-kind');
+      if (chip) setKind(chip.dataset.kind);
+    });
+
+    // `addKeyBinding` with a descriptor binds the key and lists it in reveal's
+    // own help overlay. `C` is unclaimed by reveal.
+    deck.addKeyBinding({ keyCode: KEY_CODE, key: 'C', description: 'Toggle the pointer' }, () =>
+      setPointer(!armed),
+    );
+    // While armed: Escape stands it down, the number row picks the kind — the
+    // same capture-phase borrowing the pen does with its colours.
+    document.addEventListener(
+      'keydown',
+      (event) => {
+        if (!armed || event.metaKey || event.ctrlKey || event.altKey) return;
+        if (event.key === 'Escape') setPointer(false);
+        else {
+          const index = '123'.indexOf(event.key);
+          if (index === -1 || index >= KINDS.length) return;
+          setKind(KINDS[index].id);
+        }
+        event.stopPropagation();
+        event.preventDefault();
+      },
+      true,
+    );
+
+    // No `slidechanged` hook on purpose: the pointer is the cursor, and the
+    // cursor does not vanish because the slide moved on. The overview is fair
+    // ground for it too.
+    window.addEventListener('resize', aim);
+  },
+});
+
+export default RevealPointer;

package/runtime/theme.base.css

@@ -449,10 +449,11 @@ html[data-reveal-theme] .reveal strong { color: var(--r-heading-color, var(--tex
 }
 
 /* Faded back until it is wanted: on stage the slide is the point, and the
-   toolbar sits in the one place the eye keeps returning to. */
+   toolbar keeps to the quiet strip along the bottom, between the arrows and
+   the signature. */
 #deck-tools {
   position: fixed;
-  top: 14px;
+  bottom: 14px;
   left: 50%;
   transform: translateX(-50%);
   z-index: 40;
@@ -505,10 +506,11 @@ html[data-reveal-theme] .reveal strong { color: var(--r-heading-color, var(--tex
     0 0 16px color-mix(in srgb, var(--pen, #ff8c1a) 55%, transparent);
 }
 
-/* The colours, hanging under the toolbar while the pen is armed. */
+/* The colours, floating above the toolbar while a tool is armed — the
+   toolbar sits on the bottom edge, so up is where the room is. */
 #deck-swatches {
   position: absolute;
-  top: calc(100% + 9px);
+  bottom: calc(100% + 9px);
   left: 50%;
   transform: translateX(-50%);
   display: flex;
@@ -821,6 +823,142 @@ body.outline-open #deck-outline { transform: none; }
   background: color-mix(in srgb, var(--text) 5%, transparent);
 }
 
+/* --- the pointer (pointer.js) -------------------------------------------- */
+
+/* The real cursor goes away everywhere while the pointer is armed — the
+   glowing stand-in below is the cursor now, toolbar included. */
+html.deck-pointer-on,
+html.deck-pointer-on * { cursor: none !important; }
+
+/* Above everything, spotlight and ink included: it stands in for the cursor,
+   which always rides on top of what it points at. Never touchable. */
+#deck-pointer {
+  position: fixed;
+  inset: 0;
+  z-index: 60;
+  pointer-events: none;
+}
+#deck-pointer[hidden] { display: none; }
+
+/* Each piece sits at 0,0 and is carried by the `translate` property pointer.js
+   writes per frame; `transform` is left free for the press effect, so the two
+   compose instead of overwriting each other. */
+/* The halo wears the pen's own orange (annotate.js's palette), not the
+   theme accent: on stage the pointer has to burn, not blend in. */
+#deck-pointer { --pointer-hot: #ff8c1a; }
+
+.deck-pointer-dot {
+  position: absolute;
+  left: -3.5px;
+  top: -3.5px;
+  width: 7px;
+  height: 7px;
+  border-radius: 999px;
+  background: #fff;
+  box-shadow:
+    0 0 6px 1px rgb(255 255 255 / 0.9),
+    0 0 14px 4px color-mix(in srgb, var(--pointer-hot) 70%, transparent);
+  transition: transform 0.12s ease;
+}
+/* The ring trails the dot on a short elastic (pointer.js lerps it), lit from
+   inside and haloed outside — the trailing is what makes it read as alive. */
+.deck-pointer-halo {
+  position: absolute;
+  left: -19px;
+  top: -19px;
+  width: 38px;
+  height: 38px;
+  border-radius: 999px;
+  border: 3px solid color-mix(in srgb, var(--pointer-hot) 90%, #fff);
+  background: radial-gradient(circle, color-mix(in srgb, var(--pointer-hot) 30%, transparent) 0%, transparent 68%);
+  box-shadow:
+    0 0 26px color-mix(in srgb, var(--pointer-hot) 75%, transparent),
+    inset 0 0 14px color-mix(in srgb, var(--pointer-hot) 55%, transparent);
+  transition: transform 0.16s ease, border-color 0.16s ease;
+}
+/* A click: the dot swells, the ring snaps in around it. */
+#deck-pointer.is-pressed .deck-pointer-dot { transform: scale(1.7); }
+#deck-pointer.is-pressed .deck-pointer-halo {
+  transform: scale(0.7);
+  border-color: #fff;
+}
+
+/* The compass dart. pointer.js sets `rotate` so it always aims at the centre
+   of the viewport; the pivot is its own middle, under the cursor's hotspot. */
+.deck-pointer-compass {
+  position: absolute;
+  left: -21px;
+  top: -21px;
+  width: 42px;
+  height: 42px;
+  fill: var(--pointer-hot);
+  filter:
+    drop-shadow(0 0 3px rgb(255 255 255 / 0.5))
+    drop-shadow(0 0 12px color-mix(in srgb, var(--pointer-hot) 75%, transparent));
+  transition: transform 0.12s ease;
+}
+#deck-pointer.is-pressed .deck-pointer-compass { transform: scale(1.22); }
+
+/* One kind on screen at a time; the native kind is the system cursor itself,
+   so it paints nothing at all. */
+#deck-pointer[data-kind='halo'] .deck-pointer-compass { display: none; }
+#deck-pointer[data-kind='compass'] .deck-pointer-dot,
+#deck-pointer[data-kind='compass'] .deck-pointer-halo { display: none; }
+#deck-pointer[data-kind='native'] > * { display: none; }
+
+/* The armed pointer button wears the accent, not the pen's ink — it draws in
+   nothing, it glows. The id outweighs the generic armed-tool rule above. */
+#tool-pointer[aria-pressed='true'] {
+  background: var(--accent);
+  color: #0d1626;
+  box-shadow:
+    0 0 0 1px color-mix(in srgb, var(--text) 30%, transparent),
+    0 0 16px color-mix(in srgb, var(--accent) 55%, transparent);
+}
+
+/* The kind picker, floating above the toolbar like the pen's swatches. */
+#deck-pointer-kinds {
+  position: absolute;
+  bottom: calc(100% + 9px);
+  left: 50%;
+  transform: translateX(-50%);
+  display: flex;
+  gap: 6px;
+  padding: 5px;
+  background: color-mix(in srgb, var(--card) 82%, transparent);
+  border: 1px solid var(--line);
+  border-radius: 999px;
+  backdrop-filter: blur(6px);
+}
+#deck-pointer-kinds[hidden] { display: none; }
+
+.deck-pointer-kind {
+  display: grid;
+  place-items: center;
+  width: 26px;
+  height: 26px;
+  padding: 0;
+  border: 0;
+  border-radius: 999px;
+  background: transparent;
+  color: var(--muted);
+  cursor: pointer;
+  transition: background 0.15s ease, color 0.15s ease;
+}
+.deck-pointer-kind svg {
+  display: block;
+  width: 15px;
+  height: 15px;
+}
+.deck-pointer-kind:hover {
+  background: color-mix(in srgb, var(--text) 10%, transparent);
+  color: var(--text);
+}
+.deck-pointer-kind[aria-checked='true'] {
+  background: var(--accent);
+  color: #0d1626;
+}
+
 /* --- the spotlight (spotlight.js) ---------------------------------------- */
 
 /* One veil over the slides, under the ink: spotlight.js punches the lit
@@ -878,6 +1016,7 @@ body.outline-open #deck-outline { transform: none; }
   #deck-ink,
   #deck-spot,
   #deck-spot-ring,
+  #deck-pointer,
   #deck-tools,
   #deck-menu,
   #deck-outline { display: none; }