reveal.js-phone-remote 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jan Huege
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+# reveal.js-phone-remote
+
+Control a [reveal.js](https://revealjs.com) deck from your phone – no app, no
+cloud, no second server. Scan a QR code in the terminal and the phone shows:
+
+- slide number, title, next slide and speaker notes (A−/A+ for size)
+- timer (▶ to start, ↺ to reset; otherwise starts with the first navigation) and clock
+- Next / Back, Up / Down for vertical slides, black screen (reveal's pause), jump to any slide
+- swipe over the notes to change slides
+- **Spotlight** – a trackpad like the Logitech Spotlight: touch and everything
+  but a circle dims, move and the circle follows, lift and it's gone. "Hold"
+  keeps it, S/M/L sets the size. Turns off by itself when the phone
+  disconnects.
+
+It runs on your existing Vite dev/preview server (or any Connect/Express/
+node:http server) via Server-Sent Events. Only dependency: `qrcode-terminal`.
+
+## Try it
+
+The repository has a demo deck in two flavours:
+
+```sh
+git clone https://github.com/JanHuege/reveal.js-phone-remote.git && cd reveal.js-phone-remote
+npm install
+npm run example        # Vite            – http://localhost:5173/
+npm run example:node   # plain node:http – http://localhost:8000/
+```
+
+Open the deck on the laptop and scan the QR code in the terminal with your
+phone. Details: [`examples/vite`](examples/vite/), [`examples/node`](examples/node/).
+
+## Install
+
+```sh
+npm install reveal.js-phone-remote
+```
+
+## Usage with Vite
+
+```js
+// vite.config.js
+import { defineConfig } from 'vite';
+import phoneRemote from 'reveal.js-phone-remote/vite';
+
+export default defineConfig({
+  plugins: [phoneRemote()],
+  // Listen on all interfaces so the phone can reach the laptop.
+  // '::' = dual stack (IPv4 + IPv6), needed in IPv6-only phone hotspots.
+  server: { host: '::' },
+  preview: { host: '::' },
+});
+```
+
+```js
+// main.js
+import Reveal from 'reveal.js';
+import PhoneRemote from 'reveal.js-phone-remote';
+
+Reveal.initialize({
+  plugins: [PhoneRemote],
+});
+```
+
+Start `vite` (or `vite build && vite preview`), open the deck on the laptop and
+scan the QR code in the terminal with the phone camera. Both devices must be in
+the same network – a phone hotspot is the safest bet in lecture halls, where
+Wi-Fi often isolates clients.
+
+Without the server (static hosting, PDF export, speaker view iframes) the deck
+plugin stays silent.
+
+## Usage without Vite
+
+See [`examples/node`](examples/node/) for a complete, bundler-free setup.
+
+```js
+import http from 'node:http';
+import { createRemote, printConnectInfo } from 'reveal.js-phone-remote/server';
+
+const remote = createRemote();
+const server = http.createServer((req, res) =>
+  remote.handle(req, res, () => serveYourDeck(req, res)),
+);
+server.listen(8000, '::');
+printConnectInfo(server, remote);
+```
+
+`remote.handle(req, res, next)` is a Connect-style middleware, so
+`app.use(remote.handle)` works with Express and Connect.
+
+## Options
+
+### Server (`phoneRemote(options)` / `createRemote(options)`)
+
+| Option | Default | |
+| --- | --- | --- |
+| `key` | `$REMOTE_KEY` or random | Access key, embedded in the QR code. Set a fixed one to keep a home-screen bookmark valid across restarts. |
+| `prefix` | `'/_remote'` | URL prefix of all endpoints and the phone page. |
+| `lang` | `'en'` | Phone UI language: `'en'`, `'de'`. |
+| `strings` | `{}` | Override single UI strings, see `src/phone/i18n.js`. |
+| `title` | `'Remote'` | Page title and home-screen name. |
+| `themeColor` | `'#0b1020'` | Browser chrome colour on the phone. |
+| `css` | – | Path to an extra stylesheet for the phone page. |
+| `qr` | `true` | Vite only: print the QR code. |
+
+### Deck (`phoneRemote` key in the reveal config)
+
+```js
+Reveal.initialize({
+  plugins: [PhoneRemote],
+  phoneRemote: {
+    prefix: '/_remote',         // must match the server
+    slideLabel: 'Slide',        // fallback title: "Slide 3"
+    title: (slide, index) => …, // custom title extraction, falsy = default
+  },
+});
+```
+
+Default slide title: first `h1`–`h3` of the slide.
+
+## Theming
+
+The phone page uses CSS custom properties. Override them in a stylesheet
+passed as `css`:
+
+```css
+:root {
+  --bg: #07102b;
+  --panel: #0e1b42;
+  --accent: #418fde;
+  --highlight: #c0ba00;
+  --font: 'Inter', system-ui, sans-serif;
+  --radius: 0 14px 0 14px;
+}
+```
+
+All properties: see the top of `src/phone/remote.css`.
+
+The spotlight's dim colour on the deck: `.reveal-spotlight { --spotlight-dim: rgb(0 0 0 / 0.8); }`.
+
+## Standalone spotlight
+
+The spotlight overlay can be driven by something else too:
+
+```js
+import { createSpotlight } from 'reveal.js-phone-remote/spotlight';
+
+const spot = createSpotlight(Reveal);
+spot.update({ on: true, x: 0.5, y: 0.3, r: 0.14 }); // normalised to the slide
+```
+
+`x`, `y` in 0..1 of the slide, `r` as fraction of the slide height.
+
+## Security
+
+Everyone in the same network reaches the server. Commands, state and notes
+require the key, which is rolled at start and only travels in the QR code.
+Plain HTTP – use it in networks you trust, or a phone hotspot.
+
+## Notes on iOS
+
+- "Add to Home Screen" in Safari turns the page into a full-screen web app.
+- Over `http://` in the LAN there is no Wake Lock API – set Auto-Lock to
+  "Never" for the talk.
+- A gyroscope pointer like the original Logitech Spotlight isn't possible:
+  iOS only exposes motion sensors to HTTPS pages.
+- In an iPhone hotspot, the QR code uses the Mac's Bonjour name (`….local`):
+  the iPhone would route the Mac's global IPv6 address over cellular instead of
+  the hotspot. Start the server *after* joining the network.
+
+## Protocol
+
+| | |
+| --- | --- |
+| `GET <prefix>/` | phone page |
+| `GET <prefix>/ping` | deck checks for the server |
+| `GET <prefix>/events?role=deck` | commands to the deck (SSE) |
+| `GET <prefix>/events?role=remote&key=…` | deck state to the phone (SSE) |
+| `POST <prefix>/state` | deck reports its state |
+| `POST <prefix>/command` (`X-Remote-Key`) | `next`, `prev`, `left`, `right`, `up`, `down`, `first`, `last`, `pause`, `goto {h, v}`, `spot {on, x, y, r}` |
+
+## License
+
+[MIT](LICENSE)

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "reveal.js-phone-remote",
+  "version": "0.1.0",
+  "description": "Control a reveal.js deck from your phone: speaker notes, timer, slide jump and a Logitech-style spotlight. No app, no cloud.",
+  "type": "module",
+  "author": "Jan Huege",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JanHuege/reveal.js-phone-remote.git"
+  },
+  "homepage": "https://github.com/JanHuege/reveal.js-phone-remote#readme",
+  "bugs": "https://github.com/JanHuege/reveal.js-phone-remote/issues",
+  "keywords": [
+    "reveal.js",
+    "reveal.js-plugin",
+    "remote",
+    "presenter",
+    "spotlight",
+    "speaker-notes",
+    "vite-plugin"
+  ],
+  "exports": {
+    ".": "./src/deck/plugin.js",
+    "./spotlight": "./src/deck/spotlight.js",
+    "./server": "./src/server/index.js",
+    "./vite": "./src/server/vite.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "example": "npm run dev -w examples/vite",
+    "example:preview": "npm run preview -w examples/vite",
+    "example:node": "npm start -w examples/node"
+  },
+  "workspaces": [
+    "examples/*"
+  ],
+  "dependencies": {
+    "qrcode-terminal": "^0.12.0"
+  },
+  "peerDependencies": {
+    "reveal.js": ">=4",
+    "vite": ">=5"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  }
+}

package/src/deck/plugin.js

@@ -0,0 +1,189 @@
+// reveal.js plugin – the deck side of the remote.
+//
+// Reports every slide change to the server and runs the remote's commands.
+// Stays silent when the server isn't there (static hosting, PDF export,
+// speaker view).
+//
+//   import PhoneRemote from 'reveal.js-phone-remote';
+//   Reveal.initialize({ plugins: [PhoneRemote], phoneRemote: { … } });
+
+import { createSpotlight } from './spotlight.js';
+
+const DEFAULTS = {
+  // Must match the server's prefix.
+  prefix: '/_remote',
+  // Fallback title for slides without h1–h3: "<slideLabel> <n>".
+  slideLabel: 'Slide',
+  // Custom title extraction: (slide, index) => string | null.
+  title: null,
+};
+
+const REPORT_ON = [
+  'slidechanged',
+  'fragmentshown',
+  'fragmenthidden',
+  'paused',
+  'resumed',
+  'overviewshown',
+  'overviewhidden',
+];
+
+export default function PhoneRemote() {
+  return {
+    id: 'phone-remote',
+    init(deck) {
+      const options = { ...DEFAULTS, ...deck.getConfig().phoneRemote };
+      // Not awaited: an unreachable server must not delay reveal's start.
+      if (deck.isReady()) connect(deck, options);
+      else deck.on('ready', () => connect(deck, options));
+    },
+  };
+}
+
+async function connect(deck, options) {
+  const { prefix } = options;
+  const params = new URLSearchParams(location.search);
+  // The speaker view loads the deck in iframes with ?receiver. Those must
+  // neither report nor run commands – every command would run twice.
+  if (params.has('print-pdf') || params.has('receiver')) return;
+  if (window.self !== window.top) return;
+
+  try {
+    const ping = await fetch(`${prefix}/ping`);
+    if (!ping.ok) return;
+  } catch {
+    return;
+  }
+
+  // At most one report in flight, the snapshot is taken when it leaves.
+  // Parallel POSTs can arrive out of order – an older state would then
+  // overwrite a newer one on the phone.
+  let inFlight = false;
+  let queued = false;
+  const report = async () => {
+    queued = true;
+    if (inFlight) return;
+    inFlight = true;
+    while (queued) {
+      queued = false;
+      await fetch(`${prefix}/state`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(snapshot(deck, options)),
+      }).catch(() => {});
+    }
+    inFlight = false;
+  };
+
+  REPORT_ON.forEach((type) => deck.on(type, report));
+
+  const spotlight = createSpotlight(deck);
+
+  const events = new EventSource(`${prefix}/events?role=deck`);
+  // Report after every (re)connect – the server may have restarted.
+  events.addEventListener('open', report);
+  events.addEventListener('command', (e) => {
+    const command = JSON.parse(e.data);
+    if (command.cmd === 'spot') spotlight.update(command);
+    else run(deck, command);
+  });
+}
+
+function run(deck, { cmd, h, v }) {
+  if (deck.isOverview() && cmd !== 'pause') deck.toggleOverview(false);
+
+  switch (cmd) {
+    case 'next':
+      deck.next();
+      break;
+    case 'prev':
+      deck.prev();
+      break;
+    // Left/right: fragments first, then the neighbouring main slide –
+    // subslides are skipped (that's what up/down are for).
+    case 'right':
+      deck.right();
+      break;
+    case 'left':
+      deck.left();
+      break;
+    case 'up':
+      deck.up();
+      break;
+    case 'down':
+      deck.down();
+      break;
+    case 'first':
+      deck.slide(0, 0);
+      break;
+    case 'last':
+      deck.slide(deck.getHorizontalSlides().length - 1, 0);
+      break;
+    case 'pause':
+      deck.togglePause();
+      break;
+    case 'goto':
+      deck.slide(Number(h) || 0, Number(v) || 0);
+      break;
+  }
+}
+
+function snapshot(deck, options) {
+  const slides = deck.getSlides();
+  const current = deck.getCurrentSlide();
+  const index = slides.indexOf(current);
+  const { h, v, f } = deck.getIndices();
+  const titleOf = (slide, i) => options.title?.(slide, i) || defaultTitle(slide, i, options);
+
+  const main = deck.getHorizontalSlides();
+  const nextMain = main[h + 1];
+  const nextSlide = nextMain && (nextMain.querySelector(':scope > section') || nextMain);
+
+  const fragments = current.querySelectorAll('.fragment');
+  const shown = current.querySelectorAll('.fragment.visible');
+
+  return {
+    h,
+    v,
+    f,
+    index,
+    total: slides.length,
+    title: titleOf(current, index),
+    notes: deck.getSlideNotes(current) || '',
+    fragments: fragments.length,
+    fragmentsShown: shown.length,
+    // "Next" on the phone goes right, so "up next" is the next main slide.
+    next: nextSlide ? titleOf(nextSlide, slides.indexOf(nextSlide)) : null,
+    paused: deck.isPaused(),
+    // Which ways lead somewhere – for the up/down buttons.
+    routes: routesOf(current, v),
+    aspect: aspectOf(deck),
+    // Outline for jumping to a slide.
+    outline: slides.map((slide, i) => ({
+      ...deck.getIndices(slide),
+      title: titleOf(slide, i),
+    })),
+  };
+}
+
+// Up/down from the current slide's own stack, so they always match h/v of
+// the same snapshot. deck.availableRoutes() reads reveal's .present classes
+// and turns up/down on for every slide when loop is set.
+function routesOf(slide, v = 0) {
+  const stack = slide.parentElement?.closest('section');
+  const count = stack ? stack.querySelectorAll(':scope > section').length : 1;
+  return { up: v > 0, down: v < count - 1 };
+}
+
+// Slide width / height, so the phone's trackpad moves the spot evenly.
+function aspectOf(deck) {
+  const { width, height } = deck.getConfig();
+  const ratio = Number(width) / Number(height);
+  return Number.isFinite(ratio) && ratio > 0 ? ratio : null;
+}
+
+function defaultTitle(slide, index, { slideLabel }) {
+  const heading = slide.querySelector('h1, h2, h3');
+  const text = heading?.textContent.replace(/\s+/g, ' ').trim();
+  return text || `${slideLabel} ${index + 1}`;
+}

package/src/deck/spotlight.js

@@ -0,0 +1,100 @@
+// Styles are injected, so the module works without a CSS-aware bundler.
+// Override the dim colour with `--spotlight-dim` on `.reveal-spotlight`.
+
+const FOLLOW = 0.35; // share of the remaining distance per frame
+const STYLE_ID = "reveal.js-phone-remote-spotlight";
+const CSS = `
+.reveal-spotlight {
+  position: fixed;
+  inset: 0;
+  z-index: 100;
+  pointer-events: none;
+  background: radial-gradient(
+    circle at var(--x, 50%) var(--y, 50%),
+    transparent calc(var(--r, 150px) - 6px),
+    var(--spotlight-dim, rgb(0 0 0 / 0.8)) var(--r, 150px)
+  );
+  opacity: 0;
+  transition: opacity 0.18s ease-out;
+}
+.reveal-spotlight.on {
+  opacity: 1;
+}
+@media print {
+  .reveal-spotlight {
+    display: none;
+  }
+}
+`;
+
+export function createSpotlight(deck) {
+  if (!document.getElementById(STYLE_ID)) {
+    const style = document.createElement("style");
+    style.id = STYLE_ID;
+    style.textContent = CSS;
+    document.head.appendChild(style);
+  }
+
+  const el = document.createElement("div");
+  el.className = "reveal-spotlight";
+  el.setAttribute("aria-hidden", "true");
+  document.body.appendChild(el);
+
+  const target = { x: 0.5, y: 0.5, r: 0.14 };
+  const current = { ...target };
+  let visible = false;
+  let frame = 0;
+
+  function paint() {
+    const box = deck.getSlidesElement().getBoundingClientRect();
+    const x = box.left + current.x * box.width;
+    const y = box.top + current.y * box.height;
+    const r = current.r * box.height;
+    el.style.setProperty("--x", `${x}px`);
+    el.style.setProperty("--y", `${y}px`);
+    el.style.setProperty("--r", `${r}px`);
+  }
+
+  function step() {
+    let moving = false;
+    for (const k of ["x", "y", "r"]) {
+      const d = target[k] - current[k];
+      if (Math.abs(d) > 0.0005) {
+        current[k] += d * FOLLOW;
+        moving = true;
+      } else {
+        current[k] = target[k];
+      }
+    }
+    paint();
+    frame = moving ? requestAnimationFrame(step) : 0;
+  }
+
+  function update({ on, x, y, r }) {
+    if (Number.isFinite(x)) target.x = clamp(x);
+    if (Number.isFinite(y)) target.y = clamp(y);
+    if (Number.isFinite(r)) target.r = Math.min(0.5, Math.max(0.03, r));
+
+    const show = on !== false;
+    if (show && !visible) {
+      // Don't fly across the slide when fading in.
+      Object.assign(current, target);
+      paint();
+    }
+    visible = show;
+    el.classList.toggle("on", visible);
+
+    if (!frame) frame = requestAnimationFrame(step);
+  }
+
+  function destroy() {
+    cancelAnimationFrame(frame);
+    window.removeEventListener("resize", paint);
+    el.remove();
+  }
+
+  window.addEventListener("resize", paint);
+  return { update, destroy };
+}
+
+const clamp = (v) => Math.min(1, Math.max(0, v));

package/src/phone/i18n.js

@@ -0,0 +1,82 @@
+export const STRINGS = {
+  en: {
+    connection: "Connection",
+    connecting: "Connecting …",
+    upNext: "Up next:",
+    end: "End",
+    noNotes: "No notes.",
+    step: "Step {shown} / {total}",
+    slides: "Slides",
+    spot: "Spot",
+    black: "Black",
+    show: "Show",
+    prev: "Back",
+    next: "Next",
+    up: "Up",
+    down: "Down",
+    notesSmaller: "Smaller notes",
+    notesLarger: "Larger notes",
+    timerToggle: "Start/stop timer",
+    timerReset: "Reset timer",
+    jumpTo: "Jump to",
+    done: "Done",
+    spotlight: "Spotlight",
+    spotHint: "Touch – the spot appears.\nMove – the spot follows.",
+    spotSize: "Spot size",
+    hold: "Hold",
+    noAccess: "No access – scan the QR code in the terminal again.",
+    reconnecting: "Connection lost – reconnecting …",
+    unreachable: "Server unreachable.",
+    noDeck: "Presentation not connected – open the deck in the browser.",
+  },
+  de: {
+    connection: "Verbindung",
+    connecting: "Verbinde …",
+    upNext: "Als Nächstes:",
+    end: "Ende",
+    noNotes: "Keine Notizen.",
+    step: "Schritt {shown} / {total}",
+    slides: "Folien",
+    spot: "Spot",
+    black: "Schwarz",
+    show: "Zeigen",
+    prev: "Zurück",
+    next: "Weiter",
+    up: "Hoch",
+    down: "Runter",
+    notesSmaller: "Notizen kleiner",
+    notesLarger: "Notizen größer",
+    timerToggle: "Timer starten/anhalten",
+    timerReset: "Timer zurücksetzen",
+    jumpTo: "Springen zu",
+    done: "Fertig",
+    spotlight: "Spotlight",
+    spotHint:
+      "Finger auflegen – der Spot erscheint.\nBewegen – der Spot folgt.",
+    spotSize: "Spotgröße",
+    hold: "Halten",
+    noAccess: "Kein Zugriff – QR-Code im Terminal neu scannen.",
+    reconnecting: "Verbindung unterbrochen – verbinde neu …",
+    unreachable: "Server nicht erreichbar.",
+    noDeck: "Präsentation nicht verbunden – Deck im Browser öffnen.",
+  },
+};
+
+export function translator(lang, overrides = {}) {
+  const base = STRINGS[lang] || STRINGS[lang?.split("-")[0]] || STRINGS.en;
+  const strings = { ...STRINGS.en, ...base, ...overrides };
+  return (id, vars = {}) =>
+    strings[id].replace(/\{(\w+)\}/g, (_, k) => String(vars[k] ?? ""));
+}
+
+export function translate(root, t) {
+  root.querySelectorAll("[data-i18n]").forEach((el) => {
+    el.textContent = t(el.dataset.i18n);
+  });
+  root.querySelectorAll("[data-i18n-label]").forEach((el) => {
+    el.setAttribute("aria-label", t(el.dataset.i18nLabel));
+  });
+  root.querySelectorAll("[data-i18n-title]").forEach((el) => {
+    el.title = t(el.dataset.i18nTitle);
+  });
+}