@grafloria/element 0.3.18 → 0.3.19

package/src/libs/renderer/src/perf/quality-governor.js

@@ -0,0 +1,154 @@
+"use strict";
+// Wave 8 (Performance & scale) — Card 7: the adaptive quality governor.
+//
+// The renderer already picks a level of detail from the ZOOM (`getLODLevel(zoom)`).
+// That is the right primary signal — a node 4px tall does not need its label — but
+// it is blind to the thing that actually hurts: the frame budget. A 10k-node scene
+// at zoom 1 is expensive; the same scene on a slow laptop is worse; and neither the
+// zoom nor the node count knows which machine it is running on.
+//
+// So the governor watches FRAME TIME and biases the tier down when the budget is
+// blown, back up when there is headroom to spare. Zoom says what the picture NEEDS;
+// the governor says what this machine can AFFORD.
+//
+// ---------------------------------------------------------------------------
+// THE ONLY HARD PART: NOT OSCILLATING
+// ---------------------------------------------------------------------------
+//
+// A naive governor ("frame was slow → drop detail; frame was fast → restore it")
+// is worse than no governor at all. Dropping detail makes the next frame fast,
+// which restores the detail, which makes the frame slow again — and the user gets a
+// diagram that visibly flickers between two levels of detail every other frame.
+// That is far more distracting than a consistently simpler picture.
+//
+// Three mechanisms, each earning its keep:
+//
+//   1. ASYMMETRIC RESPONSE. Step down FAST (the user is suffering right now) and up
+//      SLOWLY (they are not suffering; there is no hurry). Recovery requires a long
+//      run of comfortably-fast frames, not one lucky one.
+//   2. A DEAD BAND. The step-up threshold is well below the step-down threshold, so
+//      the frame time that a lower tier produces cannot by itself trigger a step
+//      back up. Without this the system is a bistable switch by construction.
+//   3. MEDIAN, NOT LAST. Decisions use the median of a rolling window, so a single
+//      GC pause cannot drop the whole scene a tier, and a single lucky frame cannot
+//      raise it.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QualityGovernor = void 0;
+const DEFAULTS = {
+    budgetMs: 16.7,
+    downFactor: 1.0,
+    upFactor: 0.55,
+    window: 12,
+    recoveryWindows: 3,
+    maxBias: 2,
+    panicFactor: 4,
+    panicWindow: 3,
+};
+class QualityGovernor {
+    constructor(options = {}) {
+        this.frames = [];
+        this.bias = 0;
+        this.recoveryStreak = 0;
+        this.lastDecision = 'steady';
+        this.lastMedian = 0;
+        this.options = Object.assign(Object.assign({}, DEFAULTS), options);
+    }
+    /** Feed the governor one frame time (ms). Returns the bias to render the NEXT frame at. */
+    record(frameMs) {
+        this.frames.push(frameMs);
+        // ESCALATION, checked before the main window. A scene rendering at 300ms/frame
+        // must not have to sit through nine more of them to be noticed — by the time a
+        // full window has elapsed the user has watched the canvas hang for two seconds.
+        // Median-of-three, so one GC pause still cannot trigger it.
+        const { panicFactor, panicWindow, budgetMs, maxBias } = this.options;
+        if (this.frames.length >= panicWindow && this.bias < maxBias) {
+            const recent = this.frames.slice(-panicWindow);
+            if (medianOf(recent) > budgetMs * panicFactor) {
+                this.lastMedian = medianOf(recent);
+                this.frames = [];
+                this.bias = (this.bias + 1);
+                this.recoveryStreak = 0;
+                this.lastDecision = 'escalated';
+                return this.bias;
+            }
+        }
+        if (this.frames.length < this.options.window) {
+            this.lastDecision = 'steady';
+            return this.bias;
+        }
+        const median = medianOf(this.frames);
+        this.lastMedian = median;
+        this.frames = [];
+        const { downFactor, upFactor, recoveryWindows } = this.options;
+        if (median > budgetMs * downFactor && this.bias < maxBias) {
+            // Suffering NOW. Drop a tier immediately, and reset any progress toward
+            // recovery — a scene that just blew the budget has not earned its detail back.
+            this.bias = (this.bias + 1);
+            this.recoveryStreak = 0;
+            this.lastDecision = 'stepped-down';
+            return this.bias;
+        }
+        if (median < budgetMs * upFactor && this.bias > 0) {
+            // Comfortably fast — but be patient. Restoring detail on the first fast window
+            // is how a governor becomes a flicker generator.
+            this.recoveryStreak++;
+            if (this.recoveryStreak >= recoveryWindows) {
+                this.bias = (this.bias - 1);
+                this.recoveryStreak = 0;
+                this.lastDecision = 'stepped-up';
+                return this.bias;
+            }
+        }
+        else {
+            // In the dead band (or already at full detail): hold, and forget any partial
+            // progress toward stepping up. Recovery must be a RUN of fast windows, not an
+            // accumulation of scattered ones.
+            this.recoveryStreak = 0;
+        }
+        this.lastDecision = 'steady';
+        return this.bias;
+    }
+    /** The bias to apply right now. */
+    getBias() {
+        return this.bias;
+    }
+    getState() {
+        return {
+            bias: this.bias,
+            medianMs: this.lastMedian,
+            samples: this.frames.length,
+            recoveryStreak: this.recoveryStreak,
+            lastDecision: this.lastDecision,
+        };
+    }
+    /**
+     * Apply the bias to a zoom-derived tier.
+     *
+     * `tiers` must be ordered richest → poorest, which is the order the LOD config
+     * declares them in. The governor can only ever make the picture SIMPLER than the
+     * zoom asked for — never richer. A governor that could upgrade detail beyond what
+     * the zoom wants would draw labels on 4px nodes to fill spare budget, which is
+     * not a feature.
+     */
+    effectiveTier(zoomTier, tiers) {
+        const index = tiers.indexOf(zoomTier);
+        if (index < 0)
+            return zoomTier; // unknown tier: never silently retier it
+        const target = Math.min(index + this.bias, tiers.length - 1);
+        return tiers[target];
+    }
+    /** Forget everything — e.g. after a diagram swap, where past frames say nothing. */
+    reset() {
+        this.frames = [];
+        this.bias = 0;
+        this.recoveryStreak = 0;
+        this.lastDecision = 'steady';
+        this.lastMedian = 0;
+    }
+}
+exports.QualityGovernor = QualityGovernor;
+function medianOf(values) {
+    const v = [...values].sort((a, b) => a - b);
+    return v.length % 2 ? v[v.length >> 1] : (v[v.length / 2 - 1] + v[v.length / 2]) / 2;
+}
+//# sourceMappingURL=quality-governor.js.map

package/src/libs/renderer/src/perf/quality-governor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quality-governor.js","sourceRoot":"","sources":["../../../../../../renderer/src/perf/quality-governor.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1 @@
+export * from './platform';

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

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./platform"), exports);
+//# sourceMappingURL=index.js.map

package/src/libs/renderer/src/platform/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../renderer/src/platform/index.ts"],"names":[],"mappings":";;;AAAA,qDAA2B"}

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

@@ -0,0 +1,34 @@
+/**
+ * Platform detection (Card 6 — SSR-safe render + hydration).
+ *
+ * `@grafloria/renderer` must be importable, and partially USABLE, in a Node/SSR
+ * process: `renderToStaticSVG()` runs the real SVGRenderer with no DOM at all.
+ * Every DOM / measurement / animation touch therefore goes through one of the
+ * guards below rather than assuming `window` exists.
+ *
+ * The rule (and the reason this module is three functions and not a framework):
+ *
+ *   - `isBrowser()`  — "may I touch `window`?" (rAF, listeners, ResizeObserver)
+ *   - `hasDocument()`— "may I touch `document`?" (element creation, `<style>`)
+ *   - `getDocument()`— the ambient document, or `undefined` — never a throw.
+ *
+ * They are deliberately evaluated PER CALL, not captured at module load: a
+ * bundler may evaluate this module during SSR and reuse the same module
+ * instance after hydration, so a cached `const isBrowser = typeof window …`
+ * would freeze the answer to `false` for the life of the page.
+ */
+/** True when a real DOM `document` is reachable (browser, jsdom, happy-dom). */
+export declare function hasDocument(): boolean;
+/** True in a browser-like environment: a `window` AND a `document`. */
+export declare function isBrowser(): boolean;
+/** The ambient `Document`, or `undefined` on the server. Never throws. */
+export declare function getDocument(): Document | undefined;
+/**
+ * `requestAnimationFrame`, or a `setTimeout(…, 16)` shim where it is missing
+ * (Node, older jsdom). Returns an opaque handle usable with {@link cancelFrame}.
+ */
+export declare function requestFrame(callback: (time: number) => void): number;
+/** Cancel a handle from {@link requestFrame}, whichever mechanism produced it. */
+export declare function cancelFrame(handle: number): void;
+/** Monotonic-ish clock that also works where `performance` is absent. */
+export declare function now(): number;

package/src/libs/renderer/src/platform/platform.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * Platform detection (Card 6 — SSR-safe render + hydration).
+ *
+ * `@grafloria/renderer` must be importable, and partially USABLE, in a Node/SSR
+ * process: `renderToStaticSVG()` runs the real SVGRenderer with no DOM at all.
+ * Every DOM / measurement / animation touch therefore goes through one of the
+ * guards below rather than assuming `window` exists.
+ *
+ * The rule (and the reason this module is three functions and not a framework):
+ *
+ *   - `isBrowser()`  — "may I touch `window`?" (rAF, listeners, ResizeObserver)
+ *   - `hasDocument()`— "may I touch `document`?" (element creation, `<style>`)
+ *   - `getDocument()`— the ambient document, or `undefined` — never a throw.
+ *
+ * They are deliberately evaluated PER CALL, not captured at module load: a
+ * bundler may evaluate this module during SSR and reuse the same module
+ * instance after hydration, so a cached `const isBrowser = typeof window …`
+ * would freeze the answer to `false` for the life of the page.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasDocument = hasDocument;
+exports.isBrowser = isBrowser;
+exports.getDocument = getDocument;
+exports.requestFrame = requestFrame;
+exports.cancelFrame = cancelFrame;
+exports.now = now;
+/** True when a real DOM `document` is reachable (browser, jsdom, happy-dom). */
+function hasDocument() {
+    return typeof document !== 'undefined' && !!document;
+}
+/** True in a browser-like environment: a `window` AND a `document`. */
+function isBrowser() {
+    return typeof window !== 'undefined' && hasDocument();
+}
+/** The ambient `Document`, or `undefined` on the server. Never throws. */
+function getDocument() {
+    return hasDocument() ? document : undefined;
+}
+/**
+ * `requestAnimationFrame`, or a `setTimeout(…, 16)` shim where it is missing
+ * (Node, older jsdom). Returns an opaque handle usable with {@link cancelFrame}.
+ */
+function requestFrame(callback) {
+    if (typeof requestAnimationFrame === 'function') {
+        return requestAnimationFrame(callback);
+    }
+    return setTimeout(() => callback(now()), 16);
+}
+/** Cancel a handle from {@link requestFrame}, whichever mechanism produced it. */
+function cancelFrame(handle) {
+    if (typeof cancelAnimationFrame === 'function') {
+        cancelAnimationFrame(handle);
+        return;
+    }
+    clearTimeout(handle);
+}
+/** Monotonic-ish clock that also works where `performance` is absent. */
+function now() {
+    return typeof performance !== 'undefined' && typeof performance.now === 'function'
+        ? performance.now()
+        : Date.now();
+}
+//# sourceMappingURL=platform.js.map

package/src/libs/renderer/src/platform/platform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.js","sourceRoot":"","sources":["../../../../../../renderer/src/platform/platform.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;AAGH,kCAEC;AAGD,8BAEC;AAGD,kCAEC;AAMD,oCAKC;AAGD,kCAMC;AAGD,kBAIC;AAxCD,gFAAgF;AAChF,SAAgB,WAAW;IACzB,OAAO,OAAO,QAAQ,KAAK,WAAW,IAAI,CAAC,CAAC,QAAQ,CAAC;AACvD,CAAC;AAED,uEAAuE;AACvE,SAAgB,SAAS;IACvB,OAAO,OAAO,MAAM,KAAK,WAAW,IAAI,WAAW,EAAE,CAAC;AACxD,CAAC;AAED,0EAA0E;AAC1E,SAAgB,WAAW;IACzB,OAAO,WAAW,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;AAC9C,CAAC;AAED;;;GAGG;AACH,SAAgB,YAAY,CAAC,QAAgC;IAC3D,IAAI,OAAO,qBAAqB,KAAK,UAAU,EAAE,CAAC;QAChD,OAAO,qBAAqB,CAAC,QAAQ,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,UAAU,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAsB,CAAC;AACpE,CAAC;AAED,kFAAkF;AAClF,SAAgB,WAAW,CAAC,MAAc;IACxC,IAAI,OAAO,oBAAoB,KAAK,UAAU,EAAE,CAAC;QAC/C,oBAAoB,CAAC,MAAM,CAAC,CAAC;QAC7B,OAAO;IACT,CAAC;IACD,YAAY,CAAC,MAAkD,CAAC,CAAC;AACnE,CAAC;AAED,yEAAyE;AACzE,SAAgB,GAAG;IACjB,OAAO,OAAO,WAAW,KAAK,WAAW,IAAI,OAAO,WAAW,CAAC,GAAG,KAAK,UAAU;QAChF,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE;QACnB,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;AACjB,CAAC"}

package/src/libs/renderer/src/presence/bind-presence.d.ts

@@ -0,0 +1,51 @@
+import type { DiagramInstance } from '../instance/create-diagram';
+import { PresenceOverlay } from './presence-overlay';
+/**
+ * What presence needs from a sync session — STRUCTURAL, not the concrete `SyncAdapter`.
+ *
+ * The renderer therefore gains no hard dependency on the sync layer, a host can drive
+ * presence from its own backend (a Firebase channel, a Phoenix presence, a server-sent
+ * event stream) without adopting our transport at all, and a test can hand it a fake. The
+ * real `SyncAdapter` satisfies it exactly, which is what `presence-reachability.spec.ts`
+ * proves.
+ */
+export interface PresenceSource {
+    readonly actor: string;
+    setAwareness(patch: Record<string, unknown>): void;
+    readonly awareness: {
+        getPeers(): Array<{
+            actor: string;
+            state: Record<string, unknown>;
+        }>;
+        onChange(listener: () => void): () => void;
+    };
+}
+export interface BindPresenceOptions {
+    /** Our own display name — what the OTHER peers put on our badge. */
+    name?: string;
+    /** Our own colour. Omit and one is derived deterministically from the actor id. */
+    color?: string;
+    /** Publish the local cursor. Off ⇒ we see others but they do not see us. */
+    publishCursor?: boolean;
+    /** Publish the local selection. */
+    publishSelection?: boolean;
+    /** Interpolation factor for remote cursors (0 = snap). */
+    smoothing?: number;
+    requestFrame?: (cb: () => void) => number;
+    cancelFrame?: (handle: number) => void;
+}
+export interface PresenceBinding {
+    readonly overlay: PresenceOverlay;
+    dispose(): void;
+}
+/**
+ * Mount a presence overlay on a diagram and feed it from a sync session.
+ *
+ * ```ts
+ * const diagram = createDiagram(el, { nodes, edges });
+ * const session = createSyncSession(diagram.getModel(), transport, { actor: userId });
+ * session.join();
+ * bindPresence(diagram, session, { name: 'Ana' });
+ * ```
+ */
+export declare function bindPresence(instance: DiagramInstance, source: PresenceSource, options?: BindPresenceOptions): PresenceBinding;

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

@@ -0,0 +1,144 @@
+"use strict";
+// Wave 9 — Card 5, Part B: wiring presence to a LIVE diagram.
+//
+// THE FILE THIS CODEBASE WOULD OTHERWISE NOT HAVE.
+//
+// The signature bug of this engine, found in all eight previous waves, is MACHINERY WIRED
+// TO NOTHING: a `setLayoutService()` nothing called, seventeen LOD presets that were all
+// no-ops, a worker stack whose every test forced `useWorker:false`, a quality governor
+// wired to nothing, and a `Command.serialize()` with no deserializer anywhere in the tree.
+// Green tests, zero reachability, every time.
+//
+// A `PresenceOverlay` with a `setPeers()` method and a beautiful unit test is EXACTLY that
+// shape. It renders cursors — if someone calls it. Nobody does. There is no cursor in the
+// product and every test passes.
+//
+// So this is the wire, and it is deliberately the smallest possible amount of code:
+//
+//     pointermove  → world coords → adapter.setAwareness({ cursor })
+//     selection    → ids          → adapter.setAwareness({ selection })
+//     awareness    → change       → overlay.setPeers(...)
+//
+// and `presence-reachability.spec.ts` drives a REAL `createDiagram()` with REAL pointer
+// events through a REAL SyncAdapter and asserts a cursor DOM element appears in the OTHER
+// pane. If that test is deleted, this whole card is decoration.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bindPresence = bindPresence;
+const presence_overlay_1 = require("./presence-overlay");
+const layers_1 = require("../instance/layers");
+/**
+ * Mount a presence overlay on a diagram and feed it from a sync session.
+ *
+ * ```ts
+ * const diagram = createDiagram(el, { nodes, edges });
+ * const session = createSyncSession(diagram.getModel(), transport, { actor: userId });
+ * session.join();
+ * bindPresence(diagram, session, { name: 'Ana' });
+ * ```
+ */
+function bindPresence(instance, source, options = {}) {
+    var _a;
+    const container = instance.container;
+    const root = (_a = container.querySelector(`.${layers_1.ROOT_CLASS}`)) !== null && _a !== void 0 ? _a : container;
+    const model = instance.getModel();
+    const overlay = new presence_overlay_1.PresenceOverlay({
+        root,
+        viewport: instance.viewport,
+        smoothing: options.smoothing,
+        requestFrame: options.requestFrame,
+        cancelFrame: options.cancelFrame,
+        // Where a remote selection's outline goes. Nodes and groups have a box; a LINK does not
+        // (its geometry is a routed path), so it is skipped rather than outlined with a
+        // fabricated rectangle — a box around a curve is worse than no box.
+        getBounds: (id) => {
+            var _a, _b, _c, _d;
+            const node = model.getNode(id);
+            if (node) {
+                return {
+                    x: node.position.x,
+                    y: node.position.y,
+                    width: (_b = (_a = node.size) === null || _a === void 0 ? void 0 : _a.width) !== null && _b !== void 0 ? _b : 0,
+                    height: (_d = (_c = node.size) === null || _c === void 0 ? void 0 : _c.height) !== null && _d !== void 0 ? _d : 0,
+                };
+            }
+            return null;
+        },
+    });
+    const unsubs = [];
+    // -- identity ---------------------------------------------------------------
+    // Sent once, on the first message, so peers have a name and a colour for us on the frame
+    // they learn we exist — not five seconds later when we first twitch the mouse.
+    const identity = {};
+    if (options.name !== undefined)
+        identity['name'] = options.name;
+    if (options.color !== undefined)
+        identity['color'] = options.color;
+    if (Object.keys(identity).length > 0)
+        source.setAwareness(identity);
+    // -- awareness → overlay ----------------------------------------------------
+    const repaint = () => {
+        const peers = source.awareness.getPeers().map((p) => ({
+            actor: p.actor,
+            name: p.state['name'],
+            color: p.state['color'],
+            cursor: p.state['cursor'],
+            selection: p.state['selection'],
+        }));
+        overlay.setPeers(peers);
+    };
+    unsubs.push(source.awareness.onChange(repaint));
+    repaint(); // peers who were already here before we bound
+    // -- local pointer → awareness ----------------------------------------------
+    if (options.publishCursor !== false) {
+        const onPointerMove = (event) => {
+            // WORLD coordinates, always. Screen coordinates would put my cursor wherever YOUR
+            // camera happens to be pointing — so the moment either of us pans or zooms, every
+            // remote cursor is in the wrong place, and it is wrong in a way that looks like a
+            // rendering bug rather than a coordinate bug.
+            const rect = container.getBoundingClientRect();
+            const world = instance.viewport.clientToWorld(event.clientX, event.clientY, rect);
+            source.setAwareness({ cursor: { x: Math.round(world.x), y: Math.round(world.y) } });
+        };
+        // The pointer left the canvas. `null` — not "the last place I saw it", which would leave
+        // a cursor stuck to the edge of everyone's screen while its owner reads their email.
+        const onPointerLeave = () => source.setAwareness({ cursor: null });
+        container.addEventListener('pointermove', onPointerMove);
+        container.addEventListener('pointerleave', onPointerLeave);
+        unsubs.push(() => {
+            container.removeEventListener('pointermove', onPointerMove);
+            container.removeEventListener('pointerleave', onPointerLeave);
+        });
+    }
+    // -- local selection → awareness --------------------------------------------
+    if (options.publishSelection !== false) {
+        unsubs.push(instance.on('selection:change', ({ nodes, edges }) => {
+            source.setAwareness({
+                selection: [...nodes.map((n) => n.id), ...edges.map((e) => e.id)],
+            });
+        }));
+    }
+    // -- the model changed → a remote selection outline may have moved -----------
+    // A peer selected a node, and then someone DRAGGED that node. The outline must follow it.
+    // It is cheap (one style write per outlined entity) and it is NOT a diagram frame: it
+    // repaints the overlay only, so the frame gate is not touched and an idle diagram with a
+    // remote selection on it still costs nothing.
+    const onModelChange = () => repaint();
+    unsubs.push(instance.on('nodes:change', onModelChange));
+    // `nodes:change` covers add/remove — but a DRAG is a stream of raw model
+    // `node:changed` events with no public emission until the drop commits. The
+    // outline must ride the node THROUGH the drag (live report: "when dragging
+    // the rectangle, the purple is somehow not dragged" — it sat at the start
+    // position until mouseup, in exactly the pane doing the dragging; remote
+    // panes tracked fine because each synced op fired their model events).
+    unsubs.push(model.on('node:changed', onModelChange));
+    return {
+        overlay,
+        dispose() {
+            for (const u of unsubs)
+                u();
+            unsubs.length = 0;
+            overlay.dispose();
+        },
+    };
+}
+//# sourceMappingURL=bind-presence.js.map

package/src/libs/renderer/src/presence/bind-presence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bind-presence.js","sourceRoot":"","sources":["../../../../../../renderer/src/presence/bind-presence.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,4 @@
+export { PresenceOverlay, PRESENCE_LAYER_CLASS, actorColor, actorInitials, contrastingTextColor, } from './presence-overlay';
+export type { PresencePeer, PresenceOverlayOptions, BoundsLookup } from './presence-overlay';
+export { bindPresence } from './bind-presence';
+export type { PresenceSource, PresenceBinding, BindPresenceOptions } from './bind-presence';

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

@@ -0,0 +1,18 @@
+"use strict";
+// Wave 9 (Collaboration) — Card 5, Part B: LIVE PRESENCE.
+//
+// Remote cursors, remote selections and name badges, as a SEPARATE DOM LAYER that never
+// enters the VNode tree — so a cursor at 60fps cannot dirty a 10,000-node diagram's frame,
+// and an idle canvas with presence mounted still costs 0.0ms. See `presence-overlay.ts` for
+// why `invalidateFrame()` is the obvious fix and the wrong one.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bindPresence = exports.contrastingTextColor = exports.actorInitials = exports.actorColor = exports.PRESENCE_LAYER_CLASS = exports.PresenceOverlay = void 0;
+var presence_overlay_1 = require("./presence-overlay");
+Object.defineProperty(exports, "PresenceOverlay", { enumerable: true, get: function () { return presence_overlay_1.PresenceOverlay; } });
+Object.defineProperty(exports, "PRESENCE_LAYER_CLASS", { enumerable: true, get: function () { return presence_overlay_1.PRESENCE_LAYER_CLASS; } });
+Object.defineProperty(exports, "actorColor", { enumerable: true, get: function () { return presence_overlay_1.actorColor; } });
+Object.defineProperty(exports, "actorInitials", { enumerable: true, get: function () { return presence_overlay_1.actorInitials; } });
+Object.defineProperty(exports, "contrastingTextColor", { enumerable: true, get: function () { return presence_overlay_1.contrastingTextColor; } });
+var bind_presence_1 = require("./bind-presence");
+Object.defineProperty(exports, "bindPresence", { enumerable: true, get: function () { return bind_presence_1.bindPresence; } });
+//# sourceMappingURL=index.js.map

package/src/libs/renderer/src/presence/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../renderer/src/presence/index.ts"],"names":[],"mappings":";AAAA,0DAA0D;AAC1D,EAAE;AACF,wFAAwF;AACxF,2FAA2F;AAC3F,4FAA4F;AAC5F,gEAAgE;;;AAEhE,uDAM4B;AAL1B,mHAAA,eAAe,OAAA;AACf,wHAAA,oBAAoB,OAAA;AACpB,8GAAA,UAAU,OAAA;AACV,iHAAA,aAAa,OAAA;AACb,wHAAA,oBAAoB,OAAA;AAItB,iDAA+C;AAAtC,6GAAA,YAAY,OAAA"}

package/src/libs/renderer/src/presence/presence-overlay.d.ts

@@ -0,0 +1,121 @@
+import type { ViewportController } from '../viewport/viewport-controller';
+/** One peer, as far as the overlay is concerned. Ephemeral by construction. */
+export interface PresencePeer {
+    actor: string;
+    name?: string;
+    color?: string;
+    /** WORLD coordinates — never screen: peers have different cameras. */
+    cursor?: {
+        x: number;
+        y: number;
+    } | null;
+    /** Entity ids this peer has selected. */
+    selection?: string[];
+}
+/** World-space box of an entity, so the overlay can outline a remote selection. */
+export type BoundsLookup = (entityId: string) => {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | null;
+export interface PresenceOverlayOptions {
+    /** The mounted diagram's root — `.grafloria-diagram-root`. */
+    root: HTMLElement;
+    viewport: ViewportController;
+    /** Where a selected entity is, in world space. Usually `model.getNode(id)`. */
+    getBounds?: BoundsLookup;
+    /** Interpolate remote cursors toward their target. 0 disables (jumps straight there). */
+    smoothing?: number;
+    /** Injectable rAF, so the interpolation tests are deterministic. */
+    requestFrame?: (cb: () => void) => number;
+    cancelFrame?: (handle: number) => void;
+}
+export declare const 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.
+ */
+export declare function actorColor(actor: string): string;
+/**
+ * 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.
+ */
+export declare function contrastingTextColor(background: string): string;
+export declare function actorInitials(name: string): string;
+/**
+ * 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.
+ */
+export declare class PresenceOverlay {
+    private readonly options;
+    private readonly layer;
+    private readonly world;
+    private readonly peers;
+    private readonly doc;
+    private frame;
+    /** A frame is pending. See `tick()` for why this is not `frame !== null`. */
+    private scheduled;
+    private disposed;
+    private readonly unsubViewport;
+    private readonly smoothing;
+    private readonly requestFrameFn;
+    private readonly cancelFrameFn;
+    /** Interpolation frames actually run. An idle overlay must add ZERO. */
+    framesRun: number;
+    constructor(options: PresenceOverlayOptions);
+    /** For the tests and the a11y audit — the DOM this owns, and nothing more. */
+    get element(): HTMLElement;
+    get peerCount(): number;
+    /**
+     * 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: readonly PresencePeer[]): void;
+    remove(actor: string): void;
+    clear(): void;
+    dispose(): void;
+    private syncCamera;
+    private upsert;
+    private buildCursor;
+    private paintLabel;
+    /**
+     * 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.)
+     */
+    private syncSelection;
+    private tick;
+    private stopFrame;
+}