@grafloria/element 0.3.18 → 0.3.20

package/src/libs/renderer/src/presence/presence-overlay.js

@@ -0,0 +1,465 @@
+"use strict";
+// Wave 9 (Collaboration) — Card 5, Part B: LIVE PRESENCE.
+//
+// Remote cursors, remote selections, name badges. And the single most important line in
+// this file is the one that is NOT here:
+//
+//     THE OVERLAY NEVER ENTERS THE VNODE TREE.
+//
+// =============================================================================
+// THE PERF TRAP, AND WHY THE OBVIOUS FIX IS THE WRONG ONE
+// =============================================================================
+//
+// Wave 8 gave the renderer a FRAME GATE: `render()` skips a frame entirely when the model
+// and the viewport are unchanged, handing the patcher back the SAME VNode object. That is
+// what makes an idle 10,000-node frame cost 0.0ms, and it is the headline result of the
+// previous wave.
+//
+// A remote cursor moving changes the PICTURE without changing the MODEL or the VIEWPORT.
+// So if cursors were VNodes, the gate would look at (epoch, viewport) — both unchanged —
+// and skip the frame, and the cursors would FREEZE. This exact bug bit three separate
+// branches last wave.
+//
+// The renderer exposes `invalidateFrame()` for precisely this, and calling it from the
+// cursor loop is the obvious fix. IT IS THE WRONG ONE, and the arithmetic says so:
+//
+//     4 peers × 60Hz = 240 cursor samples a second.
+//     Each one calls invalidateFrame() → the gate opens → render() runs.
+//     render() at 10k nodes = three whole-diagram geometry passes + a full VNode rebuild
+//     + a full patcher reconcile.
+//
+// That is a 10,000-node diagram being re-derived and re-reconciled 240 times a second TO
+// MOVE A 12-PIXEL ARROW. It would take the headline number of Wave 8 — an idle frame at
+// 0.0ms — and turn it into the worst frame in the engine, and it would do it precisely
+// when the CPU is busiest (four people editing at once).
+//
+// The cursors are not part of the diagram. They are not persisted, not exported, not
+// hit-tested, not selectable, not in the undo stack, not in the a11y tree and not in the
+// SVG. Routing them through a data structure whose entire job is to describe THE DOCUMENT
+// is a category error that happens to also be slow.
+//
+// SO: A SEPARATE DOM LAYER. `<div class="grafloria-presence-layer">`, a sibling of the SVG and
+// HTML layers, carrying the same camera transform. A cursor move writes one CSS transform
+// on one absolutely-positioned div. It touches no VNode, trips no epoch, calls no
+// `invalidateFrame()`, and schedules no frame. The diagram's frame gate stays shut, the
+// idle frame stays at 0.0ms, and 240 cursor samples a second cost 240 transform writes —
+// which is what the browser's compositor is for.
+//
+// MEASURED, not asserted: `perf-run.mjs` has an `idle-frame-presence` scenario — a 10k-node
+// diagram, idle, with four remote cursors moving at 60Hz — and it reports the same 0.0ms as
+// the plain idle frame. `presence-overlay.spec.ts` asserts the mechanism directly: with the
+// overlay live and cursors moving, `scheduler.stats.painted` does not move.
+//
+// =============================================================================
+// A11Y: aria-hidden, AND NOT BECAUSE IT IS CONVENIENT
+// =============================================================================
+// A remote cursor is not content. It is a live-updating, 60Hz decoration describing someone
+// else's mouse — announcing it to a screen reader would flood the buffer with noise that
+// changes faster than it can be read, and it is not the user's own pointer, so it is not
+// even actionable. The layer is `aria-hidden="true"` and `pointer-events: none`, so it is
+// invisible to AT and to hit-testing alike. The overlay is MOUNTED INSIDE the cell axe
+// scans in `a11y-harness.ts`, so this is audited rather than asserted — and that audit
+// immediately found a real bug the unit tests could not (see `contrastingTextColor`).
+//
+// The USEFUL a11y signal — "Bob has joined", "Bob selected 3 nodes" — is a job for the
+// existing aria-live region and belongs with the comments/roster card, not with a mouse
+// pointer moving at 60 frames a second.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PresenceOverlay = exports.PRESENCE_LAYER_CLASS = void 0;
+exports.actorColor = actorColor;
+exports.contrastingTextColor = contrastingTextColor;
+exports.actorInitials = actorInitials;
+exports.PRESENCE_LAYER_CLASS = 'grafloria-presence-layer';
+/**
+ * Deterministic per-actor colour.
+ *
+ * Deterministic MATTERS: the colour must be the same on every peer's screen, or "the blue
+ * cursor is Ana" is true for you and false for me. Derived from the actor id, so no
+ * coordination, no allocation table, and no message on the wire to agree.
+ */
+function actorColor(actor) {
+    let hash = 0;
+    for (let i = 0; i < actor.length; i++)
+        hash = (Math.imul(hash, 31) + actor.charCodeAt(i)) | 0;
+    // Golden-angle hues spread adjacent hashes far apart, so two peers rarely collide.
+    const hue = Math.abs(hash * 137.508) % 360;
+    return `hsl(${hue.toFixed(0)}, 72%, 52%)`;
+}
+/**
+ * Black or white — whichever is actually READABLE on `background`.
+ *
+ * ---------------------------------------------------------------------------
+ * FOUND BY AXE, IN THE a11y GATE, AFTER THE UNIT TESTS WERE ALL GREEN
+ * ---------------------------------------------------------------------------
+ * The name badge was white text on the peer's colour. For a blue or purple actor that is
+ * fine. For a green or yellow one — `hsl(124, 72%, 52%)` — it is white on light green, a
+ * contrast ratio of about 2:1, and a user with low vision simply cannot read whose cursor
+ * it is. It is a coin flip decided by a hash of the actor id, which is the worst kind of
+ * accessibility bug: it works on your machine, for your account, every time you test it.
+ *
+ * The unit tests could not have caught this. They assert `aria-hidden="true"`, which is
+ * about ASSISTIVE TECH — and this is not an AT problem at all. It is a problem for someone
+ * looking straight at the screen with their eyes. Only the real axe audit over a real page
+ * with real badges on it could find it, which is the entire argument for that gate existing.
+ *
+ * (Note that `aria-hidden` does NOT excuse it, and axe is right to say so: hiding text from
+ * a screen reader does not hide it from a sighted user with poor contrast sensitivity.)
+ *
+ * THE MATH. Pick whichever of pure black and pure white contrasts better. The two curves
+ * cross at a background luminance of ~0.179, where BOTH give 4.58:1 — above the 4.5:1 WCAG
+ * AA threshold for normal text. So this choice is guaranteed to pass for EVERY hue, not
+ * merely for the ones I happened to look at.
+ */
+function contrastingTextColor(background) {
+    const rgb = parseColor(background);
+    if (!rgb)
+        return '#fff'; // unparseable custom colour: keep the old behaviour, do not throw
+    const lum = relativeLuminance(rgb);
+    const onWhite = 1.05 / (lum + 0.05); // contrast against #fff
+    const onBlack = (lum + 0.05) / 0.05; // contrast against #000
+    return onWhite >= onBlack ? '#fff' : '#000';
+}
+/** WCAG relative luminance. */
+function relativeLuminance([r, g, b]) {
+    const channel = (c) => {
+        const s = c / 255;
+        return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+    };
+    return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+}
+/** `#rgb`, `#rrggbb`, `rgb(...)` and `hsl(...)` — the forms a caller plausibly passes. */
+function parseColor(css) {
+    const s = css.trim().toLowerCase();
+    const hex = /^#([0-9a-f]{3}|[0-9a-f]{6})$/.exec(s);
+    if (hex) {
+        const h = hex[1];
+        const full = h.length === 3 ? h.split('').map((c) => c + c).join('') : h;
+        return [
+            parseInt(full.slice(0, 2), 16),
+            parseInt(full.slice(2, 4), 16),
+            parseInt(full.slice(4, 6), 16),
+        ];
+    }
+    const rgb = /^rgba?\(\s*(\d+)[\s,]+(\d+)[\s,]+(\d+)/.exec(s);
+    if (rgb)
+        return [Number(rgb[1]), Number(rgb[2]), Number(rgb[3])];
+    const hsl = /^hsla?\(\s*([\d.]+)[\s,]+([\d.]+)%[\s,]+([\d.]+)%/.exec(s);
+    if (hsl)
+        return hslToRgb(Number(hsl[1]), Number(hsl[2]) / 100, Number(hsl[3]) / 100);
+    return null;
+}
+function hslToRgb(h, s, l) {
+    const c = (1 - Math.abs(2 * l - 1)) * s;
+    const hp = (((h % 360) + 360) % 360) / 60;
+    const x = c * (1 - Math.abs((hp % 2) - 1));
+    const m = l - c / 2;
+    const [r, g, b] = hp < 1 ? [c, x, 0]
+        : hp < 2 ? [x, c, 0]
+            : hp < 3 ? [0, c, x]
+                : hp < 4 ? [0, x, c]
+                    : hp < 5 ? [x, 0, c]
+                        : [c, 0, x];
+    return [
+        Math.round((r + m) * 255),
+        Math.round((g + m) * 255),
+        Math.round((b + m) * 255),
+    ];
+}
+function actorInitials(name) {
+    const parts = name.trim().split(/\s+/).filter(Boolean);
+    if (parts.length === 0)
+        return '?';
+    if (parts.length === 1)
+        return parts[0].slice(0, 2).toUpperCase();
+    return (parts[0][0] + parts[parts.length - 1][0]).toUpperCase();
+}
+/**
+ * The presence layer.
+ *
+ * Owns one `<div>` inside the diagram root, and nothing else. It does not know about the
+ * SVGRenderer, the VNodePatcher, the RenderScheduler or the model, and it must not: the
+ * moment it can reach the render loop, someone will make it call into it.
+ */
+class PresenceOverlay {
+    constructor(options) {
+        var _a, _b, _c;
+        this.options = options;
+        this.peers = new Map();
+        this.frame = null;
+        /** A frame is pending. See `tick()` for why this is not `frame !== null`. */
+        this.scheduled = false;
+        this.disposed = false;
+        /** Interpolation frames actually run. An idle overlay must add ZERO. */
+        this.framesRun = 0;
+        this.doc = options.root.ownerDocument;
+        this.smoothing = (_a = options.smoothing) !== null && _a !== void 0 ? _a : 0.35;
+        this.requestFrameFn =
+            (_b = options.requestFrame) !== null && _b !== void 0 ? _b : ((cb) => typeof requestAnimationFrame === 'function'
+                ? requestAnimationFrame(() => cb())
+                : setTimeout(cb, 16));
+        this.cancelFrameFn =
+            (_c = options.cancelFrame) !== null && _c !== void 0 ? _c : ((h) => {
+                if (typeof cancelAnimationFrame === 'function')
+                    cancelAnimationFrame(h);
+                else
+                    clearTimeout(h);
+            });
+        this.layer = this.doc.createElement('div');
+        this.layer.className = exports.PRESENCE_LAYER_CLASS;
+        // aria-hidden: a 60Hz mouse pointer is not content. See the header.
+        this.layer.setAttribute('aria-hidden', 'true');
+        this.layer.setAttribute('style', 'position:absolute;top:0;left:0;width:100%;height:100%;overflow:hidden;pointer-events:none');
+        // The camera-transformed sub-layer. Cursors are positioned in WORLD coordinates and the
+        // browser does the projection — so a pan or a zoom moves every cursor with ONE transform
+        // write on ONE element, instead of N re-projections in JS.
+        this.world = this.doc.createElement('div');
+        this.world.setAttribute('style', `position:absolute;top:0;left:0;transform-origin:0 0;pointer-events:none;transform:${options.viewport.getHtmlLayerTransform()}`);
+        this.layer.appendChild(this.world);
+        options.root.appendChild(this.layer);
+        // The camera moved. Re-register the layer — and NOT by scheduling a diagram frame: the
+        // diagram is already repainting for its own reasons (the viewport changed, which its
+        // gate DOES see). We only have to keep our own transform in step.
+        this.unsubViewport = options.viewport.onChange(() => this.syncCamera());
+    }
+    /** For the tests and the a11y audit — the DOM this owns, and nothing more. */
+    get element() {
+        return this.layer;
+    }
+    get peerCount() {
+        return this.peers.size;
+    }
+    /**
+     * Publish the full peer set. Idempotent, and a peer that is gone is REMOVED — presence
+     * has no tombstones and no history; the current picture is the entire truth.
+     */
+    setPeers(peers) {
+        if (this.disposed)
+            return;
+        const seen = new Set();
+        for (const peer of peers) {
+            seen.add(peer.actor);
+            this.upsert(peer);
+        }
+        for (const actor of [...this.peers.keys()]) {
+            if (!seen.has(actor))
+                this.remove(actor);
+        }
+        this.tick();
+    }
+    remove(actor) {
+        const view = this.peers.get(actor);
+        if (!view)
+            return;
+        view.cursorEl.remove();
+        for (const el of view.selectionEls.values())
+            el.remove();
+        this.peers.delete(actor);
+    }
+    clear() {
+        for (const actor of [...this.peers.keys()])
+            this.remove(actor);
+        this.stopFrame();
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.clear();
+        this.unsubViewport();
+        this.layer.remove();
+    }
+    // -------------------------------------------------------------------------
+    syncCamera() {
+        if (this.disposed)
+            return;
+        this.world.style.transform = this.options.viewport.getHtmlLayerTransform();
+    }
+    upsert(peer) {
+        let view = this.peers.get(peer.actor);
+        if (!view) {
+            view = {
+                peer,
+                cursorEl: this.buildCursor(peer),
+                selectionEls: new Map(),
+                drawn: peer.cursor ? Object.assign({}, peer.cursor) : null,
+                target: peer.cursor ? Object.assign({}, peer.cursor) : null,
+            };
+            this.world.appendChild(view.cursorEl);
+            this.peers.set(peer.actor, view);
+        }
+        else {
+            view.peer = peer;
+            // A cursor that has just appeared jumps to its position; one that MOVED interpolates
+            // toward it. Interpolating from nowhere would make every new peer's cursor fly in from
+            // the origin, across the whole canvas, which reads as a glitch rather than a person.
+            view.target = peer.cursor ? Object.assign({}, peer.cursor) : null;
+            if (view.target && !view.drawn)
+                view.drawn = Object.assign({}, view.target);
+            this.paintLabel(view);
+        }
+        view.cursorEl.style.display = peer.cursor ? 'block' : 'none';
+        this.syncSelection(view);
+    }
+    buildCursor(peer) {
+        var _a, _b;
+        const color = (_a = peer.color) !== null && _a !== void 0 ? _a : actorColor(peer.actor);
+        const el = this.doc.createElement('div');
+        el.className = 'grafloria-presence-cursor';
+        el.setAttribute('data-actor', peer.actor);
+        el.setAttribute('style', 'position:absolute;left:0;top:0;will-change:transform;pointer-events:none;display:none');
+        // The arrow. Inline SVG, no external asset, no network fetch, no CSP surprise.
+        el.innerHTML =
+            `<svg width="14" height="20" viewBox="0 0 14 20" style="display:block;filter:drop-shadow(0 1px 1px rgba(0,0,0,.3))">` +
+                `<path d="M1 1 L1 15 L4.7 11.5 L7.2 17.5 L9.8 16.4 L7.3 10.6 L12.4 10.4 Z" fill="${color}" stroke="#fff" stroke-width="1"/>` +
+                `</svg>` +
+                `<span class="grafloria-presence-label" style="position:absolute;left:13px;top:16px;` +
+                `background:${color};color:${contrastingTextColor(color)};font:600 11px/1.4 system-ui,sans-serif;` +
+                `padding:1px 6px;border-radius:9px;white-space:nowrap"></span>`;
+        const label = el.querySelector('.grafloria-presence-label');
+        label.textContent = (_b = peer.name) !== null && _b !== void 0 ? _b : peer.actor;
+        return el;
+    }
+    paintLabel(view) {
+        var _a;
+        const label = view.cursorEl.querySelector('.grafloria-presence-label');
+        if (label)
+            label.textContent = (_a = view.peer.name) !== null && _a !== void 0 ? _a : view.peer.actor;
+    }
+    /**
+     * Remote SELECTION — an outline around what a peer has selected.
+     *
+     * Note what this is NOT: it does not touch `node.state.selected`. Selection is per-VIEWER,
+     * and the model's `selected` flag is a single shared register — so writing a peer's
+     * selection into the model would mean MY clicking a node deselects YOURS. It lives here,
+     * in the overlay, where it belongs. (`sync-adapter.spec.ts` asserts the same thing from
+     * the other side: selection travels as awareness, not as a document edit.)
+     */
+    syncSelection(view) {
+        var _a, _b;
+        const getBounds = this.options.getBounds;
+        const wanted = new Set(getBounds ? ((_a = view.peer.selection) !== null && _a !== void 0 ? _a : []) : []);
+        const color = (_b = view.peer.color) !== null && _b !== void 0 ? _b : actorColor(view.peer.actor);
+        for (const [id, el] of [...view.selectionEls]) {
+            if (!wanted.has(id)) {
+                el.remove();
+                view.selectionEls.delete(id);
+            }
+        }
+        for (const id of wanted) {
+            const box = getBounds === null || getBounds === void 0 ? void 0 : getBounds(id);
+            if (!box) {
+                // The entity is not here (yet, or any more). Drop a stale outline rather than draw a
+                // box around nothing.
+                const stale = view.selectionEls.get(id);
+                if (stale) {
+                    stale.remove();
+                    view.selectionEls.delete(id);
+                }
+                continue;
+            }
+            let el = view.selectionEls.get(id);
+            if (!el) {
+                el = this.doc.createElement('div');
+                el.className = 'grafloria-presence-selection';
+                el.setAttribute('data-actor', view.peer.actor);
+                el.setAttribute('data-entity', id);
+                this.world.appendChild(el);
+                view.selectionEls.set(id, el);
+            }
+            // Border width is in WORLD units under the camera scale, so it thickens as you zoom
+            // in. That is the same behaviour the SVG selection outline has, and matching it is why
+            // this looks like part of the canvas rather than pasted on top.
+            el.setAttribute('style', `position:absolute;left:${box.x}px;top:${box.y}px;width:${box.width}px;height:${box.height}px;` +
+                `border:2px solid ${color};border-radius:3px;pointer-events:none;box-sizing:border-box`);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // THE INTERPOLATION LOOP
+    //
+    // Awareness arrives at ~20Hz (throttled — see SyncAdapter). Drawn raw, a remote cursor
+    // visibly STEPS: twenty discrete jumps a second, which reads as lag even when the network
+    // is fine. Interpolating toward the target at 60fps turns the same twenty samples into
+    // smooth motion, and costs one transform write per cursor per frame.
+    //
+    // THE LOOP ONLY RUNS WHILE SOMETHING IS MOVING. `tick()` schedules a frame; the frame
+    // moves every cursor a fraction of the way to its target and schedules ANOTHER only if any
+    // cursor is still short of it. Once everyone has arrived — which, for a still mouse, is
+    // within a few frames — the loop STOPS DEAD and the overlay costs literally nothing.
+    //
+    // That is the whole reason an idle diagram with presence mounted still costs 0.0ms: not
+    // because the cursor work is cheap, but because there is NO cursor work. A perpetual rAF
+    // loop that ticks whether or not anything moved would keep the main thread awake forever,
+    // defeat every idle optimisation in the renderer, and drain a laptop battery on a diagram
+    // nobody is touching.
+    // -------------------------------------------------------------------------
+    tick() {
+        if (this.disposed || this.scheduled)
+            return;
+        // The guard is `scheduled`, NOT `frame !== null`, and that is not fussiness.
+        //
+        // `this.frame = requestFrame(cb)` assigns AFTER `cb` has been called — which is fine for
+        // a real rAF (async, always) and a trap for any synchronous one. Under a synchronous
+        // frame source the callback runs first, sets `this.frame = null`, finishes… and THEN the
+        // outer assignment writes the handle back. `frame` is left non-null with no frame
+        // pending, every later `tick()` returns early, and the cursors never move again — the
+        // exact freeze this whole layer exists to avoid, reintroduced by the guard meant to
+        // prevent double-scheduling. Found by the reachability test, which drives rAF
+        // synchronously so it does not have to race one.
+        this.scheduled = true;
+        const handle = this.requestFrameFn(() => {
+            this.scheduled = false;
+            this.frame = null;
+            if (this.disposed)
+                return;
+            this.framesRun++;
+            let moving = false;
+            for (const view of this.peers.values()) {
+                if (!view.target)
+                    continue;
+                if (!view.drawn) {
+                    view.drawn = Object.assign({}, view.target);
+                }
+                else {
+                    const dx = view.target.x - view.drawn.x;
+                    const dy = view.target.y - view.drawn.y;
+                    // Snap when close enough. Without this, exponential easing never quite arrives and
+                    // the loop runs for the rest of the session, one frame at a time, forever — an
+                    // idle overlay burning 60 frames a second to move a cursor by 0.0001px.
+                    //
+                    // `smoothing <= 0` ALSO snaps — the option is documented as "0 disables (jumps
+                    // straight there)", but the easing step below is `drawn + delta * smoothing`, so a
+                    // literal 0 multiplies the delta to nothing and FREEZES a cursor that has already
+                    // appeared (only the first-frame `!drawn` branch ever moved it). A caller that asks
+                    // for no interpolation must get an instant jump, not a stuck cursor. [wave11-fix]
+                    if (this.smoothing <= 0 || (Math.abs(dx) < 0.05 && Math.abs(dy) < 0.05)) {
+                        view.drawn = Object.assign({}, view.target);
+                    }
+                    else {
+                        view.drawn = {
+                            x: view.drawn.x + dx * this.smoothing,
+                            y: view.drawn.y + dy * this.smoothing,
+                        };
+                        moving = true;
+                    }
+                }
+                view.cursorEl.style.transform = `translate(${view.drawn.x}px, ${view.drawn.y}px)`;
+            }
+            if (moving)
+                this.tick();
+        });
+        // Only remember a handle for a frame that is genuinely still pending. If the callback
+        // already ran (synchronous rAF), `scheduled` is false again and storing the handle would
+        // leave a stale one that `stopFrame()` would later try to cancel.
+        if (this.scheduled)
+            this.frame = handle;
+    }
+    stopFrame() {
+        if (this.frame !== null) {
+            this.cancelFrameFn(this.frame);
+            this.frame = null;
+        }
+        this.scheduled = false;
+    }
+}
+exports.PresenceOverlay = PresenceOverlay;
+//# sourceMappingURL=presence-overlay.js.map

package/src/libs/renderer/src/presentation/index.d.ts

@@ -0,0 +1,3 @@
+export { InMemoryViewportChannel } from './viewport-channel';
+export type { PresenterViewport, ViewportChannel } from './viewport-channel';
+export * from './presentation';

package/src/libs/renderer/src/presentation/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryViewportChannel = void 0;
+const tslib_1 = require("tslib");
+// Wave 9 (Collaboration) — Card 7: presentation & read-only share mode.
+//
+// The read-only ENFORCEMENT is not here — it lives in the engine, at the model and
+// the CommandManager (libs/engine/src/models/readonly-lock.ts), because that is
+// where mutation actually happens. This module is the presentation layer on top:
+// locking, and the follow-presenter transport seam.
+var viewport_channel_1 = require("./viewport-channel");
+Object.defineProperty(exports, "InMemoryViewportChannel", { enumerable: true, get: function () { return viewport_channel_1.InMemoryViewportChannel; } });
+tslib_1.__exportStar(require("./presentation"), exports);
+//# sourceMappingURL=index.js.map

package/src/libs/renderer/src/presentation/presentation.d.ts

@@ -0,0 +1,94 @@
+import type { DiagramEngine, SerializedDiagram } from '@grafloria/engine';
+import { DiagramModel } from '@grafloria/engine';
+import type { ViewportController } from '../viewport/viewport-controller';
+import type { PresenterViewport, Unsubscribe, ViewportChannel } from './viewport-channel';
+/**
+ * Presentation & read-only share mode — Wave 9, Card 7.
+ *
+ * Three things, and they are independent on purpose (you can lock a document
+ * without presenting it, and present without locking — a presenter is usually the
+ * one person who still MAY edit):
+ *
+ *   1. {@link lockDocument}      — the document becomes read-only, for real.
+ *   2. {@link presentTo}         — broadcast my camera to whoever is following.
+ *   3. {@link followPresenter}   — put my camera where the presenter's is.
+ *
+ * The read-only half is NOT implemented here. It is enforced in the engine, at the
+ * model and the CommandManager (`libs/engine/src/models/readonly-lock.ts`), because
+ * that is where mutation actually happens. A "read-only mode" implemented in a
+ * presentation module would be a mode that only the presentation module respects —
+ * which is precisely the failure this wave set out to fix.
+ */
+/** The minimum a host must expose to be presented from / followed. `DiagramInstance` satisfies it. */
+export interface PresentationHost {
+    readonly viewport: ViewportController;
+    /** Queue a repaint. */
+    render(): void;
+}
+export interface PresentOptions {
+    /** Identifies this presenter on the wire; echoed back in the payload. */
+    presenterId?: string;
+    /**
+     * Coalesce broadcasts to at most one per N ms. Default 50 (≈20/s).
+     *
+     * A pan emits a viewport change on EVERY pointermove — 120/s on a high-rate
+     * trackpad. Publishing each one would flood the transport with frames the
+     * follower cannot even display. The trailing edge is always sent, so followers
+     * still land exactly where the presenter stopped rather than one frame short.
+     */
+    throttleMs?: number;
+}
+/**
+ * Broadcast this host's camera to `channel` for as long as the returned handle is
+ * alive. Returns a `stop()` that unsubscribes and cancels any pending trailing send.
+ */
+export declare function presentTo(host: PresentationHost, channel: ViewportChannel, options?: PresentOptions): {
+    stop: Unsubscribe;
+};
+export interface FollowOptions {
+    /**
+     * Ignore broadcasts carrying this presenterId — i.e. my own.
+     *
+     * Matters because a client may present AND follow on the same channel (a
+     * presenter who can be handed over to). Without it, applying my own broadcast
+     * would set my viewport, which emits a change, which re-broadcasts: an infinite
+     * feedback loop that pins the CPU. The `applying` re-entrancy guard below closes
+     * the same hole from the other side.
+     */
+    ignorePresenterId?: string;
+    /** Called whenever a presenter's viewport is applied (for a "following X" badge). */
+    onFollow?: (viewport: PresenterViewport) => void;
+}
+/**
+ * Slave this host's camera to the presenter's, for as long as the handle is alive.
+ *
+ * The follower keeps its OWN canvas size and reconstructs the camera rectangle from
+ * the presenter's centre + zoom, so a follower on a different screen size sees the
+ * same content correctly framed — and, critically, its `clientToWorld()` stays the
+ * exact inverse of what it renders. Copying the presenter's rectangle wholesale
+ * would break that (see viewport-channel.ts).
+ */
+export declare function followPresenter(host: PresentationHost, channel: ViewportChannel, options?: FollowOptions): {
+    stop: Unsubscribe;
+};
+/**
+ * Lock (or unlock) the document through the engine's own mode.
+ *
+ * Thin on purpose: it drives `DiagramMode`, which this wave finally wired to real
+ * enforcement in the model and the CommandManager. There is no second read-only
+ * flag here, because a second flag is how you end up with two read-only modes that
+ * disagree.
+ */
+export declare function lockDocument(engine: DiagramEngine, locked?: boolean): void;
+/** Is this engine's document locked against edits? */
+export declare function isDocumentLocked(engine: DiagramEngine): boolean;
+/**
+ * Build a READ-ONLY document from a snapshot — the "share a link to a frozen copy"
+ * case.
+ *
+ * The load runs as a SYSTEM write, so it works even against an engine that is
+ * already in presentation mode. Otherwise the order of two host calls would decide
+ * whether the share link renders a diagram or an empty canvas: lock-then-load would
+ * have the lock (correctly!) refuse every node the loader tried to add.
+ */
+export declare function loadReadonlySnapshot(engine: DiagramEngine, snapshot: SerializedDiagram): DiagramModel;