contour-deck 0.1.0 → 0.2.0

package/dist/remote/tilt.js

@@ -0,0 +1,148 @@
+/**
+ * Pointing with the phone: from device orientation to a point on the screen. Pure math, no sensors:
+ * the phone is held like a laser pointer, its top edge towards the screen, and five aimed samples
+ * (centre and four corners) calibrate where the screen is in the room.
+ */
+/** The order the guided calibration asks for. */
+export const CALIBRATION_TARGETS = ["centre", "topLeft", "topRight", "bottomRight", "bottomLeft"];
+const RAD = Math.PI / 180;
+/** A screen edge closer than this to the centre means the samples were not aimed at corners. */
+const MIN_RANGE = 2 * RAD;
+const MAX_RANGE = 80 * RAD;
+/** An angle difference brought into (-π, π], so 358° to 2° is +4° and not -356°. */
+export function wrap(angle) {
+    const turn = 2 * Math.PI;
+    const reduced = ((angle % turn) + turn) % turn;
+    return reduced > Math.PI ? reduced - turn : reduced;
+}
+/**
+ * The direction the top of the screen points at, from a sensor reading.
+ * The reading becomes the rotation matrix R = Rz(alpha)·Rx(beta)·Ry(gamma) of the W3C specification, and
+ * the pointing axis is the edge at the top of the screen as it is turned now (`screenAngle`, the value of
+ * `screen.orientation.angle`): the device's +Y in portrait, +X after a quarter turn. Reading the axis in
+ * the room, and not the three angles one by one, keeps the aim independent of how the wrist is rolled.
+ */
+export function aimOf({ alpha, beta, gamma }, screenAngle = 0) {
+    const [a, b, g, s] = [alpha * RAD, beta * RAD, gamma * RAD, screenAngle * RAD];
+    const [cA, sA, cB, sB, cG, sG] = [Math.cos(a), Math.sin(a), Math.cos(b), Math.sin(b), Math.cos(g), Math.sin(g)];
+    // Columns 1 and 2 of R: the device's X and Y axes in room coordinates (east, north, up).
+    const xAxis = [cA * cG - sA * sB * sG, cG * sA + cA * sB * sG, -cB * sG];
+    const yAxis = [-cB * sA, cA * cB, sB];
+    const [east, north, up] = [0, 1, 2].map(i => Math.sin(s) * xAxis[i] + Math.cos(s) * yAxis[i]);
+    return { yaw: Math.atan2(-east, north), pitch: Math.asin(Math.min(1, Math.max(-1, up))) };
+}
+const mean = (a, b) => (a + b) / 2;
+/** The average of a few readings taken close together (the hand shakes when the thumb taps), across the yaw seam. */
+export function meanAim(aims) {
+    const last = aims[aims.length - 1];
+    let yaw = 0;
+    let pitch = 0;
+    for (const aim of aims) {
+        yaw += wrap(aim.yaw - last.yaw);
+        pitch += aim.pitch;
+    }
+    return { yaw: wrap(last.yaw + yaw / aims.length), pitch: pitch / aims.length };
+}
+/**
+ * The calibration from the five aimed samples, or `null` when they cannot be a screen:
+ * an edge too close to the centre, or both sides of the centre on the same side.
+ */
+export function calibrate(aims) {
+    const { centre } = aims;
+    const yaw = (target) => wrap(aims[target].yaw - centre.yaw);
+    const pitch = (target) => aims[target].pitch - centre.pitch;
+    const calibration = {
+        yaw: centre.yaw,
+        pitch: centre.pitch,
+        left: mean(yaw("topLeft"), yaw("bottomLeft")),
+        right: mean(yaw("topRight"), yaw("bottomRight")),
+        top: mean(pitch("topLeft"), pitch("topRight")),
+        bottom: mean(pitch("bottomLeft"), pitch("bottomRight")),
+    };
+    return isCalibration(calibration) ? calibration : null;
+}
+/** True for a calibration that maps to a screen; also the check for one read back from storage. */
+export function isCalibration(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const c = value;
+    const numbers = [c.yaw, c.pitch, c.left, c.right, c.top, c.bottom];
+    if (!numbers.every((n) => typeof n === "number" && Number.isFinite(n)))
+        return false;
+    const [, , left, right, top, bottom] = numbers;
+    const inRange = (edge) => Math.abs(edge) >= MIN_RANGE && Math.abs(edge) <= MAX_RANGE;
+    return [left, right, top, bottom].every(inRange) && left * right < 0 && top * bottom < 0;
+}
+/** A calibration for a screen of ordinary size seen from the middle of a room: ±20° wide, ±12° high around `centre`. */
+export function defaultCalibration(centre) {
+    return { yaw: centre.yaw, pitch: centre.pitch, left: 20 * RAD, right: -20 * RAD, top: 12 * RAD, bottom: -12 * RAD };
+}
+/** Half the screen on each side of the centre, each side with its own range: 0 at the `low` edge, 1 at the `high` edge. */
+const along = (delta, low, high) => 0.5 + (delta * low > 0 ? -delta / low : delta / high) / 2;
+/** The aimed point in screen coordinates, origin at the top left; outside [0, 1] when the aim is past an edge. */
+export function project(calibration, aim) {
+    return {
+        x: along(wrap(aim.yaw - calibration.yaw), calibration.left, calibration.right),
+        y: along(aim.pitch - calibration.pitch, calibration.top, calibration.bottom),
+    };
+}
+/** The same screen size, with the centre where the phone points now: the answer to drift, or to a step sideways. */
+export function recentre(calibration, aim) {
+    return { ...calibration, yaw: aim.yaw, pitch: aim.pitch };
+}
+/**
+ * Drift correction while pointing: an aim past an edge drags the calibration along, so the edge stays
+ * under the aim and the pointer answers at once when the hand comes back, as a mouse does at the screen edge.
+ */
+export function follow(calibration, aim) {
+    const { x, y } = project(calibration, aim);
+    let { yaw, pitch } = calibration;
+    if (x < 0)
+        yaw = aim.yaw - calibration.left;
+    else if (x > 1)
+        yaw = aim.yaw - calibration.right;
+    if (y < 0)
+        pitch = aim.pitch - calibration.top;
+    else if (y > 1)
+        pitch = aim.pitch - calibration.bottom;
+    return yaw === calibration.yaw && pitch === calibration.pitch ? calibration : { ...calibration, yaw, pitch };
+}
+/**
+ * The 1€ filter (Casiez, Roussel, Vogel 2012): a low-pass whose cutoff rises with speed, so a still hand
+ * gives a still pointer and a fast sweep is not held back. `t` is in seconds.
+ */
+export function oneEuro(minCutoff = 1.2, beta = 8, derivativeCutoff = 1) {
+    const share = (cutoff, dt) => 1 / (1 + 1 / (2 * Math.PI * cutoff * dt));
+    let held = null;
+    let speed = 0;
+    let last = 0;
+    return (value, t) => {
+        if (held === null) {
+            held = value;
+            last = t;
+            return value;
+        }
+        const dt = Math.max(1e-3, t - last);
+        last = t;
+        speed += share(derivativeCutoff, dt) * ((value - held) / dt - speed);
+        held += share(minCutoff + beta * Math.abs(speed), dt) * (value - held);
+        return held;
+    };
+}
+const unit = (value) => Math.min(1, Math.max(0, value));
+/** Calibration, drift correction, and smoothing in one: feed it aims, read points. */
+export function createPointer(calibration) {
+    let filters = [oneEuro(), oneEuro()];
+    return {
+        calibration,
+        update(aim, t) {
+            this.calibration = follow(this.calibration, aim);
+            const { x, y } = project(this.calibration, aim);
+            return { x: unit(filters[0](unit(x), t)), y: unit(filters[1](unit(y), t)) };
+        },
+        recentre(aim) {
+            this.calibration = recentre(this.calibration, aim);
+            filters = [oneEuro(), oneEuro()];
+        },
+    };
+}

package/dist/remote/transport.d.ts

@@ -0,0 +1,35 @@
+import type { Message } from "./protocol.js";
+export type TransportStatus = "connecting" | "open" | "closed";
+/** A decoded frame: an object with a string `t`. The receiver checks the rest. */
+export type Incoming = Record<string, unknown> & {
+    t: string;
+};
+export interface Transport {
+    readonly status: TransportStatus;
+    /** Close code of the last connection that ended (4004, 4009, …); 0 when none did. */
+    readonly code: number;
+    /** Sends a message; it is dropped unless the transport is open. */
+    send(message: Message): void;
+    subscribe(listener: (message: Incoming) => void): () => void;
+    /** Calls `listener` on every change of `status`. */
+    watch(listener: (status: TransportStatus) => void): () => void;
+    /** Ends the current connection and opens a new one at once. */
+    reconnect(): void;
+    close(): void;
+}
+export declare const channelName: (room: string) => string;
+/** Windows of the same browser and origin, through `BroadcastChannel`. No pairing: same browser, trusted. */
+export declare function broadcast(room: string): Transport;
+export interface RelayOptions {
+    room: string;
+    role: "host" | "guest";
+    /** The host key whose hash is `room`; the relay seats a host only with it. Guests have none. */
+    key?: string;
+}
+/** `https://relay.example` or `wss://relay.example` to the room endpoint. */
+export declare function relayUrl(base: string, { room, role, key }: RelayOptions): string;
+/**
+ * A WebSocket to the relay. A connection that ends is opened again with exponential backoff
+ * (0.5 s doubling to 15 s, with jitter), and at once when the page comes back or the network returns.
+ */
+export declare function relay(base: string, options: RelayOptions): Transport;

package/dist/remote/transport.js

@@ -0,0 +1,162 @@
+/**
+ * How messages travel: `broadcast` between windows of one browser, `relay` between devices
+ * through the WebSocket relay of docs/PROTOCOL.md. Both carry the same messages.
+ */
+import { decode, MAX_FRAME } from "./protocol.js";
+function emitter() {
+    const listeners = new Set();
+    return {
+        add(listener) {
+            listeners.add(listener);
+            return () => void listeners.delete(listener);
+        },
+        emit: (value) => listeners.forEach(listener => listener(value)),
+    };
+}
+export const channelName = (room) => `contour-deck:${room}`;
+/** Windows of the same browser and origin, through `BroadcastChannel`. No pairing: same browser, trusted. */
+export function broadcast(room) {
+    const messages = emitter();
+    const channel = typeof BroadcastChannel === "undefined" ? null : new BroadcastChannel(channelName(room));
+    let status = channel ? "open" : "closed";
+    if (channel) {
+        channel.onmessage = event => {
+            const message = decode(event.data);
+            if (message)
+                messages.emit(message);
+        };
+    }
+    return {
+        get status() {
+            return status;
+        },
+        code: 0,
+        send(message) {
+            if (status === "open")
+                channel?.postMessage(JSON.stringify(message));
+        },
+        subscribe: messages.add,
+        watch: () => () => { },
+        reconnect() { },
+        close() {
+            status = "closed";
+            channel?.close();
+        },
+    };
+}
+const FIRST_RETRY = 500;
+const LAST_RETRY = 15_000;
+/** `https://relay.example` or `wss://relay.example` to the room endpoint. */
+export function relayUrl(base, { room, role, key }) {
+    return `${base.replace(/^http/, "ws").replace(/\/+$/, "")}/v1/room/${room}?role=${role}${key ? `&key=${key}` : ""}`;
+}
+/**
+ * Closes after which the connection is not opened again by itself: 4009, a newer connection with the same key
+ * took the host seat (the same session in another tab); 4003, the host removed this guest.
+ */
+const FINAL = [4003, 4009];
+/**
+ * A WebSocket to the relay. A connection that ends is opened again with exponential backoff
+ * (0.5 s doubling to 15 s, with jitter), and at once when the page comes back or the network returns.
+ */
+export function relay(base, options) {
+    const messages = emitter();
+    const statuses = emitter();
+    const encoder = new TextEncoder();
+    const abort = new AbortController();
+    let socket = null;
+    let status = "connecting";
+    let code = 0;
+    let attempt = 0;
+    let timer = 0;
+    let ended = false;
+    /** After a final close: waiting for `reconnect()`, not for a timer or the page coming back. */
+    let parked = false;
+    function set(next) {
+        if (next === status)
+            return;
+        status = next;
+        statuses.emit(next);
+    }
+    function open() {
+        clearTimeout(timer);
+        if (ended)
+            return;
+        const current = new WebSocket(relayUrl(base, options));
+        socket = current;
+        set("connecting");
+        current.onopen = () => {
+            if (socket === current)
+                set("open");
+        };
+        current.onmessage = event => {
+            if (socket !== current)
+                return;
+            const message = decode(event.data);
+            if (!message)
+                return;
+            // The relay greets every socket; a greeting means the room took us, so the backoff starts over.
+            if (message.t === "hello")
+                attempt = 0;
+            messages.emit(message);
+        };
+        current.onclose = event => {
+            if (socket !== current)
+                return;
+            socket = null;
+            code = event.code;
+            if (ended)
+                return;
+            set("closed");
+            parked = FINAL.includes(code);
+            if (parked)
+                return;
+            const delay = Math.min(LAST_RETRY, FIRST_RETRY * 2 ** attempt++) * (0.5 + Math.random() / 2);
+            timer = window.setTimeout(open, delay);
+        };
+    }
+    function reconnect() {
+        if (ended)
+            return;
+        const current = socket;
+        socket = null;
+        current?.close();
+        attempt = 0;
+        parked = false;
+        open();
+    }
+    /** Waiting for a retry while the page was hidden or offline: try now. */
+    const wake = () => {
+        if (!socket && !parked && !document.hidden)
+            reconnect();
+    };
+    addEventListener("online", wake, { signal: abort.signal });
+    document.addEventListener("visibilitychange", wake, { signal: abort.signal });
+    open();
+    return {
+        get status() {
+            return status;
+        },
+        get code() {
+            return code;
+        },
+        send(message) {
+            if (status !== "open" || !socket)
+                return;
+            const frame = JSON.stringify(message);
+            if (encoder.encode(frame).length <= MAX_FRAME)
+                socket.send(frame);
+        },
+        subscribe: messages.add,
+        watch: statuses.add,
+        reconnect,
+        close() {
+            ended = true;
+            abort.abort();
+            clearTimeout(timer);
+            socket?.close();
+            socket = null;
+            set("closed");
+        },
+    };
+}

package/dist/remote/view.d.ts

@@ -0,0 +1,48 @@
+import type { BlockNode, PageNode, Pos } from "../core/model.js";
+import type { RemoteLabels } from "./labels.js";
+import type { StateMessage } from "./protocol.js";
+export interface Outline {
+    blocks: BlockNode[];
+    skip: string[];
+}
+export declare const readOutline: (root: HTMLElement, skip?: string[]) => Outline;
+/** The position a `state` names, if this page has it: both sides load the same page, but one may be stale. */
+export declare function statePos({ blocks }: Outline, state: StateMessage): Pos | null;
+export declare const pageAt: ({ blocks }: Outline, pos: Pos) => PageNode;
+/** `三 · 4/6 · 頁 2/2 · 要點 1/4`, as DESIGN.md writes the position on the phone. */
+export declare function positionLabel({ blocks }: Outline, pos: Pos, state: StateMessage): string;
+export interface UpNext {
+    kind: "step" | "page" | "slide" | "end";
+    text: string;
+    /** The page the next advance shows, and how many of its steps are revealed then. */
+    pos: Pos;
+    step: number;
+}
+/** What the next advance does: one more step, the page below, the next slide, or nothing. */
+export declare function upNext(outline: Outline, pos: Pos, step: number): UpNext;
+export interface Preview {
+    el: HTMLElement;
+    /** Draws a page with its first `steps` steps revealed; `null` empties the sheet. */
+    show(page: PageNode | null, steps: number): void;
+    destroy(): void;
+}
+/**
+ * A page of this document drawn small: a copy laid out by the stage's own rules on a 1280 px wide sheet,
+ * then scaled to the box. A guide, not a mirror: it does not know how far the real page is scrolled.
+ */
+export declare function createPreview(root: HTMLElement): Preview;
+export interface Timers {
+    /** Whole-talk time, `3:12 / 12:00`. */
+    time: HTMLElement;
+    /** Block title and block time. */
+    block: HTMLElement;
+    /** Redraws from the last state; call it on every state and every half second. */
+    draw(state: StateMessage | null, receivedAt: number): void;
+}
+/**
+ * The two clocks. Between states they run on the local clock: a state every 15 s is enough to stay in step.
+ * The block title comes from this page's own outline, at the position the state names; the relay carries no text.
+ */
+export declare function createTimers(labels: RemoteLabels, outline: Outline): Timers;
+/** Keeps the screen awake while a view is open; the browser drops the lock when the page hides, so it is asked again. */
+export declare function keepAwake(signal: AbortSignal): void;

package/dist/remote/view.js

@@ -0,0 +1,119 @@
+/** What the phone and the presenter window share: reading the deck of their own page, and drawing pages small. */
+import { h } from "../core/dom.js";
+import { defaultLabels } from "../core/labels.js";
+import { fitPos, parseAt, readModel } from "../core/model.js";
+import { neighbourBlock } from "../core/navigator.js";
+import { pageTitle } from "../core/notes.js";
+import { formatClock } from "./clock.js";
+export const readOutline = (root, skip = ["appendix"]) => ({
+    blocks: readModel(root, root.dataset.title || document.title),
+    skip,
+});
+/** The position a `state` names, if this page has it: both sides load the same page, but one may be stale. */
+export function statePos({ blocks }, state) {
+    const parsed = parseAt(state.at);
+    return parsed && fitPos(blocks, parsed);
+}
+export const pageAt = ({ blocks }, pos) => blocks[pos.b].slides[pos.s].pages[pos.p];
+/** `三 · 4/6 · 頁 2/2 · 要點 1/4`, as DESIGN.md writes the position on the phone. */
+export function positionLabel({ blocks }, pos, state) {
+    const block = blocks[pos.b];
+    const pages = block.slides[pos.s].pages.length;
+    return [
+        block.short,
+        `${pos.s + 1}/${block.slides.length}`,
+        pages > 1 ? defaultLabels.page(pos.p + 1, pages) : "",
+        state.steps ? defaultLabels.steps(state.step, state.steps) : "",
+    ]
+        .filter(Boolean)
+        .join(" · ");
+}
+const clip = (text) => text.replace(/\s+/g, " ").trim().slice(0, 80);
+/** What the next advance does: one more step, the page below, the next slide, or nothing. */
+export function upNext(outline, pos, step) {
+    const { blocks, skip } = outline;
+    const slide = blocks[pos.b].slides[pos.s];
+    const page = slide.pages[pos.p];
+    if (step < page.steps.length)
+        return { kind: "step", text: clip(page.steps[step].textContent ?? ""), pos, step: step + 1 };
+    if (pos.p + 1 < slide.pages.length) {
+        const below = { ...pos, p: pos.p + 1 };
+        return { kind: "page", text: pageTitle(slide.pages[below.p]) || slide.title, pos: below, step: 0 };
+    }
+    const nextBlock = neighbourBlock(blocks.map(block => block.kind), pos.b, 1, skip);
+    const next = pos.s + 1 < blocks[pos.b].slides.length ? { b: pos.b, s: pos.s + 1, p: 0 } : nextBlock >= 0 ? { b: nextBlock, s: 0, p: 0 } : null;
+    if (!next)
+        return { kind: "end", text: "", pos, step };
+    return { kind: "slide", text: blocks[next.b].slides[next.s].title, pos: next, step: 0 };
+}
+/** Width of the sheet a page is laid out on before it is scaled to the box. */
+const SHEET = 1280;
+/**
+ * A page of this document drawn small: a copy laid out by the stage's own rules on a 1280 px wide sheet,
+ * then scaled to the box. A guide, not a mirror: it does not know how far the real page is scrolled.
+ */
+export function createPreview(root) {
+    const el = h("div", "ct-pv");
+    const sheet = el.appendChild(h("div", "ct-stage", "", { "aria-hidden": "true" }));
+    const wrap = sheet.appendChild(h("div", `ct-pvw ${root.className}`.trim()));
+    sheet.inert = true;
+    const observer = new ResizeObserver(() => el.style.setProperty("--ct-k", String(el.clientWidth / SHEET)));
+    observer.observe(el);
+    let drawn = null;
+    return {
+        el,
+        show(page, steps) {
+            if (page !== drawn) {
+                drawn = page;
+                const copy = page?.el.cloneNode(true);
+                // A copy must not repeat ids, play media, or run frames a second time.
+                copy?.querySelectorAll("[id]").forEach(node => node.removeAttribute("id"));
+                copy?.querySelectorAll("iframe,video,audio,script,[data-ct-notes]").forEach(node => node.remove());
+                copy?.removeAttribute("id");
+                wrap.replaceChildren(...(copy ? [copy] : []));
+            }
+            wrap.querySelectorAll("[data-ct-step]").forEach((node, i) => node.toggleAttribute("data-ct-on", i < steps));
+        },
+        destroy: () => observer.disconnect(),
+    };
+}
+/**
+ * The two clocks. Between states they run on the local clock: a state every 15 s is enough to stay in step.
+ * The block title comes from this page's own outline, at the position the state names; the relay carries no text.
+ */
+export function createTimers(labels, outline) {
+    const time = h("b", "ct-rmt-time", "0:00");
+    const block = h("div", "ct-rmt-blk");
+    const title = block.appendChild(h("span"));
+    const spent = block.appendChild(h("b"));
+    return {
+        time,
+        block,
+        draw(state, receivedAt) {
+            if (!state)
+                return;
+            // `elapsed` is 0 until the talk starts and never 0 after, so it also says whether the clock runs.
+            const since = state.elapsed > 0 ? (performance.now() - receivedAt) / 1000 : 0;
+            const elapsed = state.elapsed + since;
+            time.textContent = formatClock(elapsed) + (state.total ? ` / ${formatClock(state.total)}` : "");
+            time.toggleAttribute("data-over", !!state.total && elapsed > state.total);
+            const budget = state.blockMinutes ? state.blockMinutes * 60 : 0;
+            const inBlock = state.blockElapsed + since;
+            const pos = statePos(outline, state);
+            title.textContent = `${labels.block}　${pos ? outline.blocks[pos.b].title : ""}`;
+            spent.textContent = formatClock(inBlock) + (budget ? ` / ${formatClock(budget)}` : "");
+            spent.toggleAttribute("data-over", !!budget && inBlock > budget);
+        },
+    };
+}
+/** Keeps the screen awake while a view is open; the browser drops the lock when the page hides, so it is asked again. */
+export function keepAwake(signal) {
+    let lock = null;
+    const ask = () => {
+        if (!document.hidden && !signal.aborted)
+            lock = navigator.wakeLock?.request("screen").catch(() => { }) ?? null;
+    };
+    document.addEventListener("visibilitychange", ask, { signal });
+    signal.addEventListener("abort", () => void lock?.then(held => held?.release()));
+    ask();
+}

package/docs/CONTRACT.md

@@ -122,6 +122,8 @@ The core removes all of them in `destroy()`.
 
 Every other `data-ct-*` name is reserved for later versions, except the [host attributes](#host-attributes).
 
+`contour-deck/remote`, when it loads, adds one `<style data-ct-remote>` at the start of `<head>` and leaves it there; its elements (`.ct-rp`, `.ct-laser`, `.ct-ink`, and the `.ct-app` of the phone and presenter views) go with the session or the view that made them.
+
 The core moves the deck element into its shell (`.ct-app .ct-stage`) while the deck is open and puts it back in `destroy()`; it does not clone it.
 The shell is inserted where the deck element was, so the deck keeps its ancestors and the styles it inherits from them.
 
@@ -147,6 +149,8 @@ The core does not read them, and a host that calls `createDeck` itself needs non
 | `data-ct-overview` | the wrapper | `flat` or `3d`: the `overview` option of the core. |
 | `data-ct-legacy` | the wrapper | Accept old reveal.js links: `?view=slides&slide=h.v` is rewritten to `?view=deck&at=…` through `data-legacy` and `data-legacy-v`. |
 | `data-ct-start` | any control in the page | A click opens the deck; with the value `notes`, its notes view. Inside a wrapper it opens that deck, elsewhere the first deck of the page. |
+| `data-ct-remote` | the wrapper | The deck has the remote button and the `R` key (`contour-deck/remote`, loaded on first use). |
+| `data-ct-relay` | the wrapper | Base URL of the relay (`wss://…`) for the phone remote; implies `data-ct-remote`. See [PROTOCOL.md](PROTOCOL.md). |
 
 ## Deep links
 
@@ -159,6 +163,16 @@ The core owns two query parameters while a deck is open, and removes both in `de
 | `at` | `b.s` or `b.s.p` | 1-based ordinals: block in the deck, slide in the block, page in the slide. `4.4.2` is the second page of the fourth slide of the fourth block. |
 | `at` | an element id | The slide, page, or block with that id, or the one that contains the element with that id. |
 
+`contour-deck/remote` owns two more values of `view`, on pages that are views of a deck open elsewhere; the host loads the module when it sees them.
+
+| Parameter | Value | Meaning |
+| --- | --- | --- |
+| `view` | `remote` | The phone remote of the first deck of the page. |
+| `view` | `presenter` | The presenter window, in the same browser as the deck. |
+| `room` | 26 characters of Crockford base32 | The room both sides meet in: the relay room of the phone, the `BroadcastChannel` of the presenter window. |
+
+The links to these views keep every other query parameter of the deck's page and drop `at` and the fragment.
+
 Without `at` the deck opens on the outline.
 The position is in the query string, not the fragment, because a restricted page on the blog drops the fragment on redirect.
 The slide `id` also works as a plain document anchor (`#s-4-6`) when the deck is closed.

package/docs/PROTOCOL.md

@@ -0,0 +1,99 @@
+# Remote protocol
+
+How a deck (the **host**) and phones (**guests**) talk through the relay. The relay is a per-room forwarder; it decides who may hold the host seat, and the host decides who may control the deck. Version 1.
+
+Version 1 changed before its first release (contour-deck 0.1.0 has no remote): the host seat needs a key, the relay removes a guest the host denied or revoked, it limits requests per client address, and `state` lost `block`. Nothing that spoke the earlier draft was published, so the version stays 1.
+
+## Transport
+
+```
+wss://<relay>/v1/room/<room>?role=host&key=<key>
+wss://<relay>/v1/room/<room>?role=guest
+```
+
+- `key`: the host key, 26 characters of Crockford base32 (128 random bits from `crypto.getRandomValues`). The host keeps it in `sessionStorage` and sends it to the relay only.
+- `room`: the first 26 characters of the Crockford base32 encoding of SHA-256 of the key (its UTF-8 bytes, upper case), bits taken most significant first. The QR and every link carry the room, never the key. Anything that is not 26 Crockford characters gets HTTP 400.
+- Test vector: key `0123456789ABCDEFGHJKMNPQRS` opens room `YQV9WCK1VFXD4486E3JKK6CYND`.
+- Frames are UTF-8 JSON text, at most **2048 bytes**. A larger or binary frame closes the socket with `1009`.
+- Every message has a string field `t` (its type). The relay reads only `t`, `to`, and the size; it never stores or logs message bodies.
+
+## Relay rules
+
+One Durable Object per room (`idFromName(room)`).
+
+| Event | Relay does |
+| --- | --- |
+| host opens without a key, or with a key whose room is not this room | HTTP 403 before the upgrade |
+| socket opens | sends `{ "t": "hello", "id": "<8 chars>", "role": "host" \| "guest" }` to it. `id` is assigned by the relay. |
+| host opens while a host is connected | the new host takes the seat: the old host is closed with `4009`, its guests with `4000`; the room stays |
+| guest opens with no host connected | closes it with `4004` |
+| guest opens when 4 guests are connected | closes it with `4029` |
+| guest opens / closes | sends `{ "t": "join", "id" }` / `{ "t": "leave", "id" }` to the host |
+| host sends a message with `to` | forwards it to that guest only (unknown `to` is dropped) |
+| host sends `deny` or `revoke` with `to` | forwards it, then closes that guest with `4003` (the guest leaves; the host gets `leave`) |
+| host sends a message without `to` | forwards it to every guest |
+| guest sends a message | forwards it to the host only, with `from` set to the guest's id (overwriting any `from` the guest sent) |
+| host closes | closes every guest with `4000`; the room is gone |
+| no message in the room for 2 hours | closes everyone with `4000` |
+| a socket exceeds 60 messages/s (burst 120) | extra messages are dropped; above 10 s of sustained excess, closes with `1008` |
+| request `Origin` not in `ALLOWED_ORIGINS` | HTTP 403 before the upgrade |
+| more than 60 requests to room paths a minute from one client address | HTTP 429 before anything else is checked |
+
+`ALLOWED_ORIGINS` is a comma-separated Worker variable (e.g. `https://www.wayneh.tw,https://wayne930242.github.io,http://localhost:4321`). Guests never reach other guests.
+
+Only the key holder can be host, so only the deck's own tab receives what guests send, the resume token included. A host that reconnects while the relay still counts its old connection as open takes the seat back at once. Of two tabs with the same key (a duplicated tab copies `sessionStorage`), the newer one holds the seat; the older one is closed with `4009` and does not reconnect by itself.
+
+`GET /v1/health` answers `200 ok` (no upgrade) for monitoring.
+
+## Application messages
+
+The relay does not interpret these, except that a `deny` or `revoke` with `to` removes that guest. Coordinates are normalised to the stage viewport: `x`, `y` in `[0, 1]`, origin at the top left.
+
+### Pairing
+
+1. Host opens the room with its key and shows a QR for `<page URL>?view=remote&room=<room>`.
+2. Guest connects; host gets `join` and sends `{ "t": "pair", "to": id, "code": "1234" }` — a fresh 4-digit code per guest.
+3. Guest shows the code large. Host shows "a phone asks for control: code 1234 — allow / deny".
+4. Presenter compares the two screens and answers:
+   - allow → `{ "t": "grant", "to": id, "token": "<22 chars>" }` (random, kept by the guest in `sessionStorage` for this room)
+   - deny → `{ "t": "deny", "to": id }`; the relay then closes that guest with `4003`, so a denied guest cannot keep a place
+5. A reconnecting guest sends `{ "t": "resume", "token" }`; if it matches a token the host granted in this room, the host grants again without asking.
+6. The host can take control back: `{ "t": "revoke", "to": id }`, which also removes the guest from the room (`4003`). At most one guest holds control; granting a second revokes the first.
+
+A guest that is not granted gets `state` messages only if the host chooses (default: none), and its commands are ignored. A projected QR scanned by the audience therefore only produces a request the presenter denies.
+
+### Host → granted guest
+
+| Message | Fields |
+| --- | --- |
+| `state` | `mode` (`overview` \| `stage`), `at` (`b.s.p`, 1-based), `step`, `steps`, `elapsed` (s), `total` (s or `null`), `blockElapsed` (s), `blockMinutes` (or `null`), `ratio` (optional: width over height of the stage) |
+
+Sent on every position change and every 15 s. No text of the page crosses the relay: the phone has the same page and reads the notes and the block title from its own DOM, at the position `at` names.
+
+### Granted guest → host
+
+| Message | Fields | Host does |
+| --- | --- | --- |
+| `cmd` | `c`: `next` \| `prev` \| `slideNext` \| `slidePrev` \| `pageNext` \| `pagePrev` \| `overview` \| `open`; `at` with `open` | same as the keyboard |
+| `ptr` | `x`, `y`, `on` (bool) | shows or hides the laser pointer |
+| `ink` | `s` (stroke id, number), `pts` ([x, y, x, y, …], at most 64 points), `end` (bool, optional) | draws the stroke on the overlay |
+| `ink-clear` | — | clears the overlay |
+| `ping` | — | answers `{ "t": "pong", "to": from }` |
+
+Ink is cleared when the page changes. The host rate-limits `ptr` rendering to one per animation frame.
+
+## Same machine
+
+The presenter window on the same computer uses `BroadcastChannel("contour-deck:<room>")` with the same messages, without `pair` (same browser, trusted).
+
+## Close codes
+
+| Code | Meaning |
+| --- | --- |
+| `4000` | room closed (host left or idle, or a new host took the seat) |
+| `4003` | removed by the host (after `deny` or `revoke`); the client does not reconnect by itself |
+| `4004` | no host in this room |
+| `4009` | host replaced: a newer connection with the same key holds the host seat; the client does not reconnect by itself |
+| `4029` | room full |
+| `1008` | rate limit |
+| `1009` | message too large |