contour-deck 0.1.0 → 0.2.0

package/README.md

@@ -1,12 +1,40 @@
 # contour-deck
 
+<p align="center">
+  <a href="https://wayne930242.github.io/contour-deck/">
+    <picture>
+      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/wayne930242/contour-deck/main/docs/media/tour-light.gif">
+      <img src="https://raw.githubusercontent.com/wayne930242/contour-deck/main/docs/media/tour.gif" alt="Open a slide from the outline, move left and right, scroll down its pages, and return to the outline" width="800">
+    </picture>
+  </a>
+</p>
+
 Outline-first slide decks on real DOM.
 A deck is blocks, slides, and pages: it opens on an outline of every block, a block opens into a left-right track of slides, and each slide scrolls down one page at a time.
-The core is plain TypeScript with no runtime dependency (7 KB of JavaScript and 3 KB of CSS, gzipped).
+The core is plain TypeScript with no runtime dependency (7 KB of JavaScript and 3 KB of CSS, gzipped); the phone remote is a separate module that loads on first use.
 
-Status: M1 in progress, local only, not published, no licence yet.
+Status: 0.1.0 on npm (M1). The M2 client is on `main`, not yet released: phone remote, laser pointer, drawing, tilt pointing, and a presenter window ([Remote](#remote)); the relay it talks to is a separate small service ([docs/PROTOCOL.md](docs/PROTOCOL.md)). Live demo: https://wayne930242.github.io/contour-deck/
 The design is in [docs/DESIGN.md](docs/DESIGN.md) (Traditional Chinese); the HTML the core reads is in [docs/CONTRACT.md](docs/CONTRACT.md).
 
+## 看看它怎麼動
+
+[線上示範](https://wayne930242.github.io/contour-deck/)可以直接操作；[影片與截圖頁](https://wayne930242.github.io/contour-deck/media.html)有每一段的 mp4 與原尺寸截圖。
+下面的動畫是真實的鍵盤與滑鼠操作（圓圈是滑鼠，黑底小標是按下的鍵），用 `pnpm media` 重錄。
+
+| | |
+| --- | --- |
+| ![跨區塊移動：翻到區塊盡頭時拉遠再推進，位置列的圓點直接飛到另一個區塊](https://raw.githubusercontent.com/wayne930242/contour-deck/main/docs/media/move.gif) | ![3D 結構：輪廓傾斜、頁疊成層，仍可點進投影片](https://raw.githubusercontent.com/wayne930242/contour-deck/main/docs/media/structure.gif) |
+| 跨區塊移動：拉遠再推進，位置列的圓點直接飛到別的區塊 | 3D 結構：按 3，頁疊成層 |
+| ![步驟：表格一列一列出現，步驟用完才換頁](https://raw.githubusercontent.com/wayne930242/contour-deck/main/docs/media/build.gif) | ![手機：講稿檢視、輪廓、舞台與往上滑的換頁](https://raw.githubusercontent.com/wayne930242/contour-deck/main/docs/media/phone.gif) |
+| 步驟：空白鍵讓表格一列一列出現 | 手機：講稿檢視與往上滑換頁 |
+
+| | |
+| --- | --- |
+| ![輪廓：七個區塊的縮圖牆](https://raw.githubusercontent.com/wayne930242/contour-deck/main/docs/media/overview.png) | ![3D 結構](https://raw.githubusercontent.com/wayne930242/contour-deck/main/docs/media/overview-3d.png) |
+| 輪廓 | 3D 結構 |
+| ![舞台旁的講稿面板](https://raw.githubusercontent.com/wayne930242/contour-deck/main/docs/media/notes.png) | ![淺色主題的舞台](https://raw.githubusercontent.com/wayne930242/contour-deck/main/docs/media/light.png) |
+| 講稿面板（按 N） | 淺色主題 |
+
 ## Use
 
 ```ts
@@ -73,6 +101,7 @@ A page that is not Astro gets the same behaviour from `mountAll()` in `contour-d
 | `at` | from the URL | Entry position, such as `"4.4.2"` or a slide id. |
 | `url` | `true` | Read and write `?view=` and `?at=`. |
 | `labels` | Traditional Chinese | Interface text; pass the entries to replace. |
+| `remote` | none | A function the remote button and the `R` key call with the deck; it usually loads `contour-deck/remote`. Without it the deck has neither. See [Remote](#remote). |
 
 ### API
 
@@ -82,9 +111,12 @@ deck.prev();
 deck.open("4.2");       // put a block on the stage
 deck.go("4.4.2");       // or deck.go("slide-id")
 deck.overview();        // back to the outline
+deck.slideBy(1);        // the next slide, as the right arrow key; -1 for the one before
+deck.pageBy(1);         // one stop down inside the slide, as the down arrow key
 deck.state;             // { mode, block, slide, page, step }; ordinals are 1-based
 deck.on("change", ({ mode, at, step }) => {});
 deck.on("exit", () => deck.destroy()); // Esc on the outline, or the ✕ button of the bar
+deck.on("destroy", () => {});          // once, at the start of destroy()
 deck.destroy();
 ```
 
@@ -92,6 +124,72 @@ On opening, the focus moves into the shell: to the stage, to the current thumbna
 
 Each page receives `ct:enter` when it becomes the current page and `ct:leave` when it stops; both bubble.
 
+### Remote
+
+A phone controls the deck, points at it, and draws on it; a second window on the same computer shows the presenter's view.
+The code is `contour-deck/remote`, loaded on first use, so a reader who never presses `R` downloads none of it.
+
+```ts
+import { createDeck } from "contour-deck";
+
+const options = { relay: "wss://relay.example" }; // see "The relay" below
+const load = () => import("contour-deck/remote");
+const view = new URLSearchParams(location.search).get("view");
+
+if (view === "remote") load().then(remote => remote.remoteView(root, options)); // the phone
+else if (view === "presenter") load().then(remote => remote.presenterView(root, options)); // the presenter window
+else if (view) {
+  const deck = createDeck(root, { remote: deck => load().then(remote => remote.remoteHost(deck, root, options)).then(host => host.toggle()) });
+  deck.on("exit", () => deck.destroy());
+}
+```
+
+With Astro, `<Deck relay="wss://relay.example">` does all of this (`<Deck remote>` without a relay); so does `data-ct-relay` or `data-ct-remote` on a `[data-ct-host]` wrapper.
+
+How to connect:
+
+1. On the deck, press `R` (or the 遙控 button). The panel shows two QR codes.
+2. Scan 手機遙控 with the phone. It opens the same page as `?view=remote&room=…` and shows a 4-digit code.
+3. The deck shows the same code under 有手機要求控制. Compare the two screens and press 允許.
+4. The phone now has: position and clocks (whole talk and current block, from `data-minutes`), the notes, what the next step shows, 下一步 / 上一步 / 上一張 / 下一張 / 輪廓, and three pointing tools: 紅點 (drag on a small copy of the page), 畫筆 (draw on it; a page change clears the ink), and 傾斜 (hold a button and aim the phone like a laser pointer).
+5. 講稿, the other QR, is `?view=notes`: the script on the phone, turned by hand, with no connection at all.
+
+開啟講者視窗 in the panel opens `?view=presenter` in a second window of the same browser: the current page, the next step, the notes, and the clocks. It follows over `BroadcastChannel`, needs no relay, and takes the deck's keys; the mouse over its current page is the laser pointer.
+
+Tilt pointing reads the phone's orientation sensor (iOS asks for permission on the tap that enables it).
+校正 guides through five aims: the screen's centre, then its four corners, each marked by the dot on the deck. From these the phone knows where the screen is from where you stand, and keeps it for the session.
+Without calibration, the direction of the first press is the centre of a screen ±20° wide and ±12° high.
+When the pointer drifts, aim at the centre and press 重新置中; aiming past an edge also drags the calibration along, as a mouse at the edge of a screen.
+
+Security, in three lines: the relay only forwards small messages (position, commands, pointer coordinates) between the deck and at most four phones; notes, block titles, and slide content never pass through it, because the phone loads the page itself.
+The room in the QR lets a phone ask; only the deck's tab holds the key the room is hashed from, so nobody else can take the deck's seat at the relay and hear what the phones send.
+Control belongs to the one phone the presenter allowed on the deck after comparing the code; everything any other guest sends is ignored, and the relay removes a denied guest, so a QR photographed from the projector yields only a request to deny.
+
+| Option of `remoteHost`, `remoteView`, `presenterView` | Default | Meaning |
+| --- | --- | --- |
+| `relay` | none | Base URL of the relay, `wss://…` or `https://…`. Without it the remote stays on this computer: presenter window and notes link only. |
+| `qr` | built-in | `(text) => svgString`, for a site that already ships a QR library: `text => QRCode.toString(text, { type: "svg" })`. The built-in encoder takes links up to 287 bytes; a longer link shows as text. |
+| `skip` | `["appendix"]` | Block kinds whose minutes are not planned time; keep it equal to `linear.skip`. |
+| `labels` | Traditional Chinese | Interface text of the panel, the phone, and the presenter window. |
+| `nonce` | none | Nonce for the `<style>` the module injects, for a page with a `style-src` policy. |
+| `room` (views only) | `?room=` | The room to join. |
+
+`remoteHost(deck, root, options)` resolves to the session of that deck, creating it once: `toggle()` shows or hides the panel, `end()` takes control back and closes the room, `room` is its name.
+It is a promise because the room is the SHA-256 of the session's key (`crypto.subtle`, so with a relay the page needs https or localhost).
+The key, the paired phone's token, and the clock live in `sessionStorage`, so a reload of the deck or of the phone continues the same session; the Astro host and the demo restart it by themselves after a reload.
+With the Astro component, pass a QR encoder or labels through `configureRemote({ qr })` from `contour-deck/host`.
+The remote follows the first deck of a page.
+
+The clock starts with the first move on the stage (not when a slide is opened from the outline) and is reset from the panel.
+The laser dot eases towards its target and fades when released; with `prefers-reduced-motion` it jumps and does not fade.
+
+#### The relay
+
+The relay is a WebSocket forwarder, one room per talk, specified in [docs/PROTOCOL.md](docs/PROTOCOL.md): rooms, the pairing messages, close codes, and limits (2 KB frames, 60 messages a second, 4 guests).
+`relay(url, { room, role, key })` and `broadcast(room)` are the two `Transport`s (`send`, `subscribe`, `watch`, `reconnect`, `close`, `status`); the relay one reconnects with backoff, except after `4003` (removed by the host) and `4009` (another tab of the session took the host seat).
+The demo takes a relay from the query string, the deployed one or one on this machine: `https://wayne930242.github.io/contour-deck/?relay=wss://contour-relay.wayne930242.workers.dev&view=deck`, or `?relay=ws://localhost:8787`; it ignores any other.
+The phone must be able to open the page's URL, so a deck on `localhost` needs a tunnel or the LAN address for the phone part.
+
 ### Keys
 
 | Key | On the stage | On the outline |
@@ -102,6 +200,7 @@ Each page receives `ct:enter` when it becomes the current page and `ct:leave` wh
 | `↑` `↓` | previous, next stop | move between thumbnails |
 | `Home`, `End` | first, last slide of the block | |
 | `N` | notes panel | |
+| `R` | remote panel (with the `remote` option) | remote panel |
 | `Esc`, `O` | outline | `Esc` leaves the deck (`exit`) |
 | `3` | | 3D structure |
 
@@ -127,13 +226,15 @@ The core removes both parameters in `destroy()` and leaves the others alone.
 
 ```text
 src/core/      the core: model, stops, gestures, navigator, outline, rail, notes, transitions, deck
+src/remote/    contour-deck/remote: protocol, transports, pairing, clock, tilt math, QR, and the three views
 src/remark/    Markdown directives (block, vertical, summary, build)
 src/rehype/    builds the deck > block > slide > page HTML
 src/astro/     Deck.astro and the host script it runs (also contour-deck/host)
 styles/        index.css is the entry of contour-deck/style.css
-demo/          a plain-HTML deck that follows the contract
+demo/          a plain-HTML deck that follows the contract, and media.html (clips and stills)
+docs/media/    GIF, mp4, and PNG made by scripts/media.mjs (not in the npm package)
 tests/unit/    Vitest, tests/unit/**/*.test.ts
-tests/browser/ Playwright, tests/browser/**/*.spec.ts, run against demo/
+tests/browser/ Playwright, tests/browser/**/*.spec.ts, run against demo/; relay-stub.ts is the relay of docs/PROTOCOL.md in the test process
 ```
 
 Every module under `src/` is compiled to the same path under `dist/`, so a new subpath export only needs an entry in `package.json`.
@@ -150,8 +251,9 @@ Every module under `src/` is compiled to the same path under `dist/`, so a new s
 | `pnpm test` | Unit tests. |
 | `pnpm test:browser` | Build, then run the browser tests against the demo in Chromium. |
 | `CT_BROWSERS=all pnpm test:browser` | The same in Chromium, Firefox, and WebKit (`pnpm exec playwright install firefox webkit` once). |
-| `pnpm size` | Minified gzip size of the core and the CSS against the budgets (12 KB, 6 KB). |
+| `pnpm size` | Minified gzip size of the core and the CSS against the budgets (12 KB, 6 KB), and of the parts of the remote. |
 | `pnpm demo` | Build and serve the demo on `http://127.0.0.1:41731/demo/`. |
+| `pnpm media` | Record the clips and stills in `docs/media/` (needs `ffmpeg` and Chromium); the Pages workflow publishes the mp4 and png files next to the demo. |
 
 The demo also opens straight from the file system: `demo/index.html` after `pnpm build`.
 

package/dist/astro/Deck.astro

@@ -8,6 +8,7 @@
  *   <a href="?view=notes" data-ct-start="notes">Notes</a>
  *
  * `?view=deck` and `?view=notes` open the deck on load; so does any `[data-ct-start]` control.
+ * With `remote` or `relay`, the deck has a remote (R): `?view=remote` is the phone, `?view=presenter` the presenter window.
  *
  * The build copies this file to dist/astro/, and the import paths are the ones that hold there:
  * ../style.css is dist/style.css, ./host.js the compiled src/astro/host.ts.
@@ -28,9 +29,13 @@ interface Props {
   overview?: "flat" | "3d";
   /** Accept old reveal.js links, `?view=slides&slide=h.v`, through `data-legacy`. */
   legacy?: boolean;
+  /** The remote button and the `R` key: presenter window and notes link. Implied by `relay`. */
+  remote?: boolean;
+  /** Base URL of the relay (`wss://…`), so a phone can pair and control the deck. See docs/PROTOCOL.md. */
+  relay?: string;
 }
 
-const { class: className, docClass, paging, overview, legacy = false } = Astro.props;
+const { class: className, docClass, paging, overview, legacy = false, remote = false, relay } = Astro.props;
 ---
 
 <div
@@ -40,6 +45,8 @@ const { class: className, docClass, paging, overview, legacy = false } = Astro.p
   data-ct-paging={paging}
   data-ct-overview={overview}
   data-ct-legacy={legacy ? "" : undefined}
+  data-ct-remote={remote ? "" : undefined}
+  data-ct-relay={relay}
 >
   <slot />
 </div>

package/dist/astro/host.d.ts

@@ -1,4 +1,11 @@
 import type { Deck, DeckOptions } from "../core/index.js";
+import type { RemoteOptions } from "../remote/index.js";
+/**
+ * Options of the remote for every deck of the page, such as a QR encoder the site already ships:
+ * `configureRemote({ qr: text => QRCode.toString(text, { type: "svg" }) })`.
+ * A `data-ct-relay` on a wrapper wins over `relay` given here.
+ */
+export declare function configureRemote(options: RemoteOptions): void;
 export interface Host {
     /** The open deck, or `null` while the page shows the document. */
     readonly deck: Deck | null;

package/dist/astro/host.js

@@ -10,10 +10,32 @@
  * | `data-ct-paging`, `data-ct-overview`     | the `paging` and `overview` options of the core              |
  * | `data-ct-legacy`                         | accept `?view=slides&slide=h.v`                              |
  * | `[data-ct-start]`, `[data-ct-start="notes"]` | a control that opens the deck or its notes view: inside a host for that deck, elsewhere for the first deck of the page |
+ * | `data-ct-remote`, `data-ct-relay="wss://…"` | the remote button and the `R` key; with a relay URL a phone can pair (docs/PROTOCOL.md) |
+ *
+ * The remote (`contour-deck/remote`) is loaded on first use: on `R`, on `?view=remote` (the phone),
+ * and on `?view=presenter` (the presenter window).
  */
 import { createDeck } from "../core/index.js";
+import { hostKey } from "../remote/store.js";
 import { legacyAt, parseLegacy, readLegacy } from "./legacy.js";
+let remoteDefaults = {};
+/**
+ * Options of the remote for every deck of the page, such as a QR encoder the site already ships:
+ * `configureRemote({ qr: text => QRCode.toString(text, { type: "svg" }) })`.
+ * A `data-ct-relay` on a wrapper wins over `relay` given here.
+ */
+export function configureRemote(options) {
+    remoteDefaults = { ...remoteDefaults, ...options };
+}
 const mounted = new WeakMap();
+function stored(key) {
+    try {
+        return sessionStorage.getItem(key) !== null;
+    }
+    catch {
+        return false;
+    }
+}
 function optionsOf(host) {
     const { ctPaging, ctOverview } = host.dataset;
     return {
@@ -48,10 +70,21 @@ export function mount(host) {
     const docClasses = (host.dataset.ctDocClass ?? "").split(/\s+/).filter(Boolean);
     const abort = new AbortController();
     let deck = null;
+    let view = null;
     let opener = null;
+    const relayUrl = host.dataset.ctRelay;
+    const hasRemote = "ctRemote" in host.dataset || !!relayUrl;
+    const remoteOptions = () => ({ ...remoteDefaults, ...(relayUrl ? { relay: relayUrl } : {}) });
+    /** Starts the remote session of the open deck, or returns the one it has; `null` when the deck closed while the module loaded. */
+    const remoteOf = async (open) => {
+        const { remoteHost } = await import("../remote/session.js");
+        return deck === open ? remoteHost(open, root, remoteOptions()) : null;
+    };
     function close() {
+        view?.destroy();
+        view = null;
         if (!deck)
-            return;
+            return void host.classList.add(...docClasses);
         deck.destroy();
         deck = null;
         host.classList.add(...docClasses);
@@ -64,13 +97,31 @@ export function mount(host) {
         // Document-view classes (a prose class, say) would restyle the shell and the stage, so they wait outside.
         host.classList.remove(...docClasses);
         try {
-            deck = createDeck(root, { ...optionsOf(host), ...options });
+            deck = createDeck(root, {
+                ...optionsOf(host),
+                ...(hasRemote ? { remote: (open) => void remoteOf(open).then(remote => remote?.toggle()) } : {}),
+                ...options,
+            });
         }
         catch (error) {
             host.classList.add(...docClasses);
             throw error;
         }
         deck.on("exit", close);
+        // A remote session of this tab (a paired phone, a running clock) continues after a reload.
+        if (hasRemote && stored(hostKey()))
+            void remoteOf(deck);
+    }
+    /** The phone remote or the presenter window: this page as a view of a deck open elsewhere. */
+    async function openView(kind) {
+        host.classList.remove(...docClasses);
+        const made = kind === "remote"
+            ? (await import("../remote/phone.js")).remoteView(root, remoteOptions())
+            : (await import("../remote/presenter.js")).presenterView(root, remoteOptions());
+        if (abort.signal.aborted)
+            made.destroy();
+        else
+            view = made;
     }
     // In the capture phase: a client-side router that listens on the document would otherwise
     // take a start link as a navigation before this handler sees it.
@@ -90,9 +141,12 @@ export function mount(host) {
     }, { capture: true, signal: abort.signal });
     if ("ctLegacy" in host.dataset)
         adoptLegacyUrl(root);
-    const view = new URLSearchParams(location.search).get("view");
-    if (view === "deck" || view === "notes")
+    const asked = new URLSearchParams(location.search).get("view");
+    if (asked === "deck" || asked === "notes")
         open();
+    // The remote views follow the first deck of the page.
+    else if ((asked === "remote" || asked === "presenter") && document.querySelector("[data-ct-host]") === host)
+        void openView(asked);
     const api = {
         get deck() {
             return deck;

package/dist/core/deck.js

@@ -25,7 +25,7 @@ export function createDeck(root, options = {}) {
     const smooth = () => (reduced() ? "auto" : "smooth");
     const abort = new AbortController();
     const { signal } = abort;
-    const listeners = { change: new Set(), exit: new Set() };
+    const listeners = { change: new Set(), exit: new Set(), destroy: new Set() };
     let mode = "overview";
     let pos = { b: 0, s: 0, p: 0 };
     let busy = false;
@@ -52,7 +52,10 @@ export function createDeck(root, options = {}) {
     const rail = buildRail(blocks, labels);
     const threeDButton = button("3d", labels.threeD);
     const notesButton = button("notes", labels.notes);
-    bar.append(button("overview", labels.overview), titleEl, rail.el, threeDButton, button("script", labels.script), notesButton, button("exit", "✕", labels.exit));
+    bar.append(button("overview", labels.overview), titleEl, rail.el, threeDButton, button("script", labels.script), notesButton);
+    if (options.remote)
+        bar.append(button("remote", labels.remote));
+    bar.append(button("exit", "✕", labels.exit));
     const viewport = app.appendChild(h("main", "ct-vp"));
     const overview = buildOverview(blocks, labels);
     const stage = h("div", "ct-stage", "", { tabindex: -1 });
@@ -446,7 +449,8 @@ export function createDeck(root, options = {}) {
     }
     /** Leaving is the host's move: it usually answers `exit` with `destroy()`. */
     const exit = () => busy || listeners.exit.forEach(listener => listener());
-    const actions = { overview: toOverview, "3d": toggle3d, script: toScript, notes: toggleNotes, prev, next, exit };
+    const remote = () => options.remote?.(api);
+    const actions = { overview: toOverview, "3d": toggle3d, script: toScript, notes: toggleNotes, remote, prev, next, exit };
     app.addEventListener("click", event => {
         const target = event.target;
         const action = target.closest("[data-ct-act]")?.dataset.ctAct;
@@ -482,7 +486,9 @@ export function createDeck(root, options = {}) {
         const onControl = !!target.closest?.("button,a");
         const activates = key === " " || key === "Enter";
         let run;
-        if (mode === "overview") {
+        if (key === "r" && options.remote && mode !== "notes")
+            run = remote;
+        else if (mode === "overview") {
             if (key === "3")
                 run = toggle3d;
             else if (key === "Escape")
@@ -552,6 +558,7 @@ export function createDeck(root, options = {}) {
         if (!alive)
             return;
         alive = false;
+        listeners.destroy.forEach(listener => listener());
         abort.abort();
         cancelAnimationFrame(frame);
         clearTimeout(idle);
@@ -568,12 +575,15 @@ export function createDeck(root, options = {}) {
         document.documentElement.removeAttribute("data-ct-open");
         writeUrl(true);
     }
-    return {
+    const onStage = (move) => void (busy || mode !== "stage" || move());
+    const api = {
         overview: toOverview,
         open: at => goTo(resolve(at)),
         go: at => goTo(resolve(at)),
         next,
         prev,
+        slideBy: direction => onStage(() => slideBy(direction)),
+        pageBy: direction => onStage(() => stepV(direction)),
         on(type, listener) {
             const set = listeners[type];
             set.add(listener);
@@ -584,4 +594,5 @@ export function createDeck(root, options = {}) {
         },
         destroy,
     };
+    return api;
 }

package/dist/core/labels.js

@@ -6,6 +6,7 @@ export const defaultLabels = {
     prev: "上一步",
     next: "下一步",
     exit: "離開簡報",
+    remote: "遙控",
     here: "目前位置",
     appendix: "書面",
     rail: "整份簡報的位置",

package/dist/core/types.d.ts

@@ -22,6 +22,7 @@ export interface Labels {
     prev: string;
     next: string;
     exit: string;
+    remote: string;
     here: string;
     appendix: string;
     rail: string;
@@ -49,6 +50,11 @@ export interface DeckOptions {
     /** Read and write `?view=` and `?at=`. Default `true`. */
     url?: boolean;
     labels?: Partial<Labels>;
+    /**
+     * The remote: with this option the bar has a remote button, and the button and the `R` key call it.
+     * It usually loads `contour-deck/remote` on first use. Without it the deck has neither.
+     */
+    remote?: (deck: Deck) => void;
 }
 export interface Deck {
     /** Back to the outline. */
@@ -61,9 +67,15 @@ export interface Deck {
     prev(): void;
     /** Go to a position (`"4.4.2"` or an element id), with the transition that fits the distance. */
     go(at: string): Promise<void>;
+    /** The slide before or after, as the left and right arrow keys: it leaves the block at its ends. */
+    slideBy(direction: 1 | -1): void;
+    /** One stop up or down inside the slide, as the up and down arrow keys. */
+    pageBy(direction: 1 | -1): void;
     on(type: "change", listener: (change: DeckChange) => void): () => void;
     /** `exit` fires when the reader leaves: Esc on the outline, or the close button of the bar. The host usually calls `destroy()`. */
     on(type: "exit", listener: () => void): () => void;
+    /** `destroy` fires once, at the start of `destroy()`, while the shell is still in the document. */
+    on(type: "destroy", listener: () => void): () => void;
     readonly state: DeckState;
     /** Puts the deck element back where it was and removes everything the core added. */
     destroy(): void;

package/dist/remote/clock.d.ts

@@ -0,0 +1,35 @@
+/** The talk clock: time since the first move on the stage, and the time spent in each block. No DOM. */
+/** What the clock keeps; plain data, so the host can put it in `sessionStorage` and survive a reload. */
+export interface ClockState {
+    /** `Date.now()` of the start, or `null` while the talk has not started. */
+    started: number | null;
+    /** 0-based index of the block the deck is in. */
+    block: number;
+    /** When the deck entered that block. */
+    since: number;
+    /** Milliseconds already spent in each block before `since`, by block index. */
+    spent: Record<number, number>;
+}
+export interface ClockReading {
+    /** Seconds since the start, one decimal; 0 before the start and at least 0.1 after it. */
+    elapsed: number;
+    /** Seconds spent in the current block since the start, all visits together. */
+    blockElapsed: number;
+}
+export interface Clock {
+    readonly running: boolean;
+    readonly state: ClockState;
+    start(block: number, now: number): void;
+    /** The deck is in `block` now; a no-op before the start. */
+    enter(block: number, now: number): void;
+    reset(): void;
+    read(now: number): ClockReading;
+}
+export declare function createClock(restored?: ClockState | null): Clock;
+/** Planned seconds of the talk: the minutes of every block the linear advance enters, or `null` when none has any. */
+export declare function plannedSeconds(blocks: {
+    minutes: number;
+    kind: string;
+}[], skip: string[]): number | null;
+/** `m:ss`, or `h:mm:ss` from one hour. */
+export declare function formatClock(totalSeconds: number): string;

package/dist/remote/clock.js

@@ -0,0 +1,48 @@
+/** The talk clock: time since the first move on the stage, and the time spent in each block. No DOM. */
+const idle = () => ({ started: null, block: 0, since: 0, spent: {} });
+const seconds = (ms) => Math.round(ms / 100) / 10;
+export function createClock(restored) {
+    let state = restored ? { ...restored, spent: { ...restored.spent } } : idle();
+    return {
+        get running() {
+            return state.started !== null;
+        },
+        get state() {
+            return state;
+        },
+        start(block, now) {
+            state = { started: now, block, since: now, spent: {} };
+        },
+        enter(block, now) {
+            if (state.started === null || block === state.block)
+                return;
+            state.spent[state.block] = (state.spent[state.block] ?? 0) + now - state.since;
+            state.block = block;
+            state.since = now;
+        },
+        reset() {
+            state = idle();
+        },
+        read(now) {
+            if (state.started === null)
+                return { elapsed: 0, blockElapsed: 0 };
+            return {
+                elapsed: Math.max(0.1, seconds(now - state.started)),
+                blockElapsed: seconds((state.spent[state.block] ?? 0) + now - state.since),
+            };
+        },
+    };
+}
+/** Planned seconds of the talk: the minutes of every block the linear advance enters, or `null` when none has any. */
+export function plannedSeconds(blocks, skip) {
+    const minutes = blocks.reduce((sum, block) => sum + (skip.includes(block.kind) ? 0 : block.minutes), 0);
+    return minutes > 0 ? Math.round(minutes * 60) : null;
+}
+/** `m:ss`, or `h:mm:ss` from one hour. */
+export function formatClock(totalSeconds) {
+    const whole = Math.max(0, Math.floor(totalSeconds));
+    const two = (value) => String(value).padStart(2, "0");
+    const hours = Math.floor(whole / 3600);
+    const minutes = Math.floor((whole % 3600) / 60);
+    return hours ? `${hours}:${two(minutes)}:${two(whole % 60)}` : `${minutes}:${two(whole % 60)}`;
+}

package/dist/remote/guest.d.ts

@@ -0,0 +1,41 @@
+import type { Command, StateMessage } from "./protocol.js";
+import type { Transport } from "./transport.js";
+/**
+ * `connecting`: no answer from the room yet. `pairing`: showing a code, waiting for the presenter.
+ * `granted`: in control. `denied`, `revoked`: the presenter said no; the connection is closed until `retry()`.
+ * `offline`: the connection ended and is being retried.
+ */
+export type GuestPhase = "connecting" | "pairing" | "granted" | "denied" | "revoked" | "offline";
+export interface Stroke {
+    add(x: number, y: number): void;
+    end(): void;
+}
+export interface Guest {
+    readonly phase: GuestPhase;
+    /** The pairing code to show, while `phase` is `pairing`. */
+    readonly code: string;
+    /** Close code of the last connection (4004: no host, 4029: room full), 0 when none ended. */
+    readonly closeCode: number;
+    /** The last `state` from the host, and when it arrived on `performance.now()`. */
+    readonly state: StateMessage | null;
+    readonly stateAt: number;
+    command(c: Command, at?: string): void;
+    /** The laser pointer; at most one message every 33 ms, the last position always goes out. */
+    point(x: number, y: number, on: boolean): void;
+    /** Starts an ink stroke; its points go out in batches. */
+    stroke(): Stroke;
+    clearInk(): void;
+    /** After `denied` or `revoked`: connects again and asks anew. */
+    retry(): void;
+    /** Calls `listener` after every change of phase, code, or state. */
+    subscribe(listener: () => void): () => void;
+    close(): void;
+}
+export interface GuestOptions {
+    room: string;
+    /** Opens the transport; called again by `retry()`. */
+    open(): Transport;
+    /** Same browser as the host (BroadcastChannel): no pairing, control from the start. */
+    trusted?: boolean;
+}
+export declare function createGuest({ room, open, trusted }: GuestOptions): Guest;