contour-deck 0.0.0-stage → 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/dist/shared/markers.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The hand-off between `contour-deck/remark` and `contour-deck/rehype`.
+ *
+ * The remark plugin writes these marker elements; the rehype plugin consumes them and
+ * removes every one, so none appears in the final HTML except `data-ct-notes`, which is
+ * already the contract's own attribute.
+ */
+/** hast property that names a marker (`data-ct-mark` in HTML). */
+export declare const MARK = "dataCtMark";
+/** hast property of a notes element (`data-ct-notes` in HTML). */
+export declare const NOTES = "dataCtNotes";
+export declare const MARK_BLOCK = "block";
+export declare const MARK_SLIDE = "slide";
+export declare const MARK_VERTICAL = "vertical";
+export declare const MARK_BUILD = "build";

package/dist/shared/markers.js

@@ -0,0 +1,15 @@
+/**
+ * The hand-off between `contour-deck/remark` and `contour-deck/rehype`.
+ *
+ * The remark plugin writes these marker elements; the rehype plugin consumes them and
+ * removes every one, so none appears in the final HTML except `data-ct-notes`, which is
+ * already the contract's own attribute.
+ */
+/** hast property that names a marker (`data-ct-mark` in HTML). */
+export const MARK = "dataCtMark";
+/** hast property of a notes element (`data-ct-notes` in HTML). */
+export const NOTES = "dataCtNotes";
+export const MARK_BLOCK = "block";
+export const MARK_SLIDE = "slide";
+export const MARK_VERTICAL = "vertical";
+export const MARK_BUILD = "build";