@oh-just-another/collab 0.57.0

package/dist/bind-awareness.js

@@ -0,0 +1,125 @@
+import { getElement, getElementWorldBounds } from "@oh-just-another/scene";
+import { PEER_CURSOR_BROADCAST_INTERVAL_MS, } from "@oh-just-another/state";
+/**
+ * Wire an `Editor` to a `CollabAwareness`:
+ *
+ *   - publishes the local user payload + cursor + selection into
+ *     awareness, throttled so a fast drag does not flood the room;
+ *   - pushes the room's other-peer cursors / selections back into the
+ *     editor so the overlay paints them.
+ *
+ * Returns an unbind function. Clearing the editor selection or cursor
+ * leaves awareness in a sane state.
+ *
+ * The editor exposes `onCursorMove` / `setPeerCursors` /
+ * `setPeerSelections` as the extension points; `@state` knows nothing
+ * about Yjs / awareness.
+ */
+export const bindAwareness = (editor, awareness, options) => {
+    const throttle = options.cursorThrottleMs ?? PEER_CURSOR_BROADCAST_INTERVAL_MS;
+    let lastBroadcastAt = 0;
+    let pendingCursor = null;
+    let flushTimer = null;
+    // Initial identity push so peers see us before our first move.
+    awareness.updateLocal({ user: options.user });
+    const broadcastNow = () => {
+        if (!pendingCursor)
+            return;
+        awareness.updateLocal({ cursor: pendingCursor });
+        lastBroadcastAt = Date.now();
+        pendingCursor = null;
+        flushTimer = null;
+    };
+    const unsubscribeCursor = editor.onCursorMove((point) => {
+        pendingCursor = point;
+        const elapsed = Date.now() - lastBroadcastAt;
+        if (elapsed >= throttle) {
+            broadcastNow();
+        }
+        else {
+            flushTimer ??= setTimeout(broadcastNow, throttle - elapsed);
+        }
+    });
+    // Local selection → awareness, with a side effect: any editor change
+    // (selection OR scene mutation) re-resolves peer selection bounds so
+    // a peer's halo follows their selected shapes as they get edited.
+    let lastSelectionKey = null;
+    const unsubscribeSelection = editor.subscribe(() => {
+        const ids = [...editor.selection].sort();
+        const key = ids.join(",");
+        if (key !== lastSelectionKey) {
+            lastSelectionKey = key;
+            awareness.updateLocal({ selection: ids });
+        }
+        // Re-resolve peer selection bounds from the current scene.
+        refreshPeerSelections();
+    });
+    // Awareness → editor. Each change recomputes both cursors and
+    // selections from the room state and pushes the materialised arrays
+    // to the editor (which paints them on the overlay).
+    let lastPeers = awareness.getPeers();
+    const applyPeers = (peers) => {
+        lastPeers = peers;
+        const cursors = [];
+        const selections = [];
+        for (const p of peers) {
+            if (p.clientId === awareness.clientId)
+                continue;
+            if (p.cursor) {
+                cursors.push({
+                    position: p.cursor,
+                    color: p.user.color,
+                    name: p.user.name,
+                });
+            }
+            if (p.selection && p.selection.length > 0) {
+                const bounds = resolveSelectionBounds(editor, p.selection);
+                if (bounds.length > 0) {
+                    selections.push({ color: p.user.color, bounds });
+                }
+            }
+        }
+        editor.setPeerCursors(cursors);
+        editor.setPeerSelections(selections);
+    };
+    // Re-resolve only the selections (cursors don't depend on scene state).
+    // Called when the editor scene changes — peer halos should track shape
+    // movement / resize made by anyone.
+    const refreshPeerSelections = () => {
+        const selections = [];
+        for (const p of lastPeers) {
+            if (p.clientId === awareness.clientId)
+                continue;
+            if (!p.selection || p.selection.length === 0)
+                continue;
+            const bounds = resolveSelectionBounds(editor, p.selection);
+            if (bounds.length > 0)
+                selections.push({ color: p.user.color, bounds });
+        }
+        editor.setPeerSelections(selections);
+    };
+    // Push current snapshot immediately so a late-binding sees existing peers.
+    applyPeers(lastPeers);
+    const unsubscribeAwareness = awareness.onPeers(applyPeers);
+    return () => {
+        unsubscribeCursor();
+        unsubscribeSelection();
+        unsubscribeAwareness();
+        if (flushTimer !== null)
+            clearTimeout(flushTimer);
+        awareness.updateLocal({ cursor: null, selection: null });
+        editor.setPeerCursors([]);
+        editor.setPeerSelections([]);
+    };
+};
+const resolveSelectionBounds = (editor, ids) => {
+    const out = [];
+    for (const id of ids) {
+        const shape = getElement(editor.scene, id);
+        if (!shape)
+            continue;
+        out.push(getElementWorldBounds(shape));
+    }
+    return out;
+};
+//# sourceMappingURL=bind-awareness.js.map

package/dist/bind-awareness.js.map

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

package/dist/bind-editor.d.ts

@@ -0,0 +1,34 @@
+import type * as Y from "yjs";
+import type { Editor } from "@oh-just-another/state";
+import { SceneDoc } from "./scene-doc.js";
+export interface BindEditorOptions {
+    /**
+     * Milliseconds to wait for a remote sync response before deciding to
+     * seed the CRDT from the local scene. Defaults to 0 (no wait — the
+     * connecting tab seeds immediately if the doc looks empty).
+     *
+     * Set this to a small value (e.g. 200 ms) in transports where peers
+     * may answer asynchronously (BroadcastChannel, WebSocket). Joiners
+     * will then adopt the room's existing state instead of clobbering it
+     * with their own.
+     */
+    readonly waitForSyncMs?: number;
+}
+/**
+ * Wire an `Editor` to a `SceneDoc` (or raw `Y.Doc`) so that local
+ * changes propagate to the CRDT and remote CRDT changes feed back into
+ * the editor.
+ *
+ * Sync handshake: when `waitForSyncMs > 0` and the CRDT looks empty
+ * at bind-time, we wait that long for the first inbound update. If it
+ * arrives, the editor adopts the room's state (`loadScene(snapshot)`).
+ * If the timeout elapses (we're the only peer), we seed the room with
+ * the editor's current scene.
+ *
+ * Self-origin transactions are tagged so the local subscriber doesn't
+ * apply its own change twice.
+ *
+ * Returns an unbind function.
+ */
+export declare const bindEditor: (editor: Editor, source: SceneDoc | Y.Doc, options?: BindEditorOptions) => (() => void);
+//# sourceMappingURL=bind-editor.d.ts.map

package/dist/bind-editor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bind-editor.d.ts","sourceRoot":"","sources":["../src/bind-editor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,CAAC,MAAM,KAAK,CAAC;AAC9B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAErD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;;OASG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,UAAU,GACrB,QAAQ,MAAM,EACd,QAAQ,QAAQ,GAAG,CAAC,CAAC,GAAG,EACxB,UAAS,iBAAsB,KAC9B,CAAC,MAAM,IAAI,CAqEb,CAAC"}

package/dist/bind-editor.js

@@ -0,0 +1,87 @@
+import { SceneDoc } from "./scene-doc.js";
+/**
+ * Wire an `Editor` to a `SceneDoc` (or raw `Y.Doc`) so that local
+ * changes propagate to the CRDT and remote CRDT changes feed back into
+ * the editor.
+ *
+ * Sync handshake: when `waitForSyncMs > 0` and the CRDT looks empty
+ * at bind-time, we wait that long for the first inbound update. If it
+ * arrives, the editor adopts the room's state (`loadScene(snapshot)`).
+ * If the timeout elapses (we're the only peer), we seed the room with
+ * the editor's current scene.
+ *
+ * Self-origin transactions are tagged so the local subscriber doesn't
+ * apply its own change twice.
+ *
+ * Returns an unbind function.
+ */
+export const bindEditor = (editor, source, options = {}) => {
+    const sceneDoc = source instanceof SceneDoc ? source : new SceneDoc(source);
+    const origin = Symbol("editor-binding");
+    const waitMs = options.waitForSyncMs ?? 0;
+    let lastSyncedScene = editor.scene;
+    let disposed = false;
+    // Local change → CRDT.
+    const unsubscribeLocal = editor.subscribe(() => {
+        if (disposed)
+            return;
+        if (editor.scene === lastSyncedScene)
+            return;
+        sceneDoc.applyDelta(lastSyncedScene, editor.scene, origin);
+        lastSyncedScene = editor.scene;
+    });
+    // CRDT change → local. Filter out self-origin updates by transaction tag.
+    const onUpdate = (_update, originOfUpdate) => {
+        if (disposed || originOfUpdate === origin)
+            return;
+        const snapshot = sceneDoc.snapshot();
+        editor.loadScene(snapshot, { preserveHistory: true });
+        lastSyncedScene = editor.scene;
+    };
+    sceneDoc.doc.on("update", onUpdate);
+    // Initial seed vs adopt.
+    const isCurrentlyEmpty = () => sceneDoc.elements.size === 0 && sceneDoc.links.size === 0 && sceneDoc.layers.size === 0;
+    const seedFromEditor = () => {
+        if (disposed)
+            return;
+        sceneDoc.replace(editor.scene, origin);
+        lastSyncedScene = editor.scene;
+    };
+    const adoptFromCrdt = () => {
+        if (disposed)
+            return;
+        const snapshot = sceneDoc.snapshot();
+        editor.loadScene(snapshot);
+        lastSyncedScene = editor.scene;
+    };
+    if (!isCurrentlyEmpty()) {
+        adoptFromCrdt();
+    }
+    else if (waitMs <= 0) {
+        seedFromEditor();
+    }
+    else {
+        // Wait briefly for a peer to answer the implicit sync request that the
+        // TransportProvider sent on connect. If anything lands in the doc
+        // during that window, adopt; otherwise seed.
+        const timer = setTimeout(() => {
+            if (disposed)
+                return;
+            if (isCurrentlyEmpty())
+                seedFromEditor();
+            // Else: an update arrived → onUpdate already called loadScene.
+        }, waitMs);
+        return () => {
+            disposed = true;
+            clearTimeout(timer);
+            unsubscribeLocal();
+            sceneDoc.doc.off("update", onUpdate);
+        };
+    }
+    return () => {
+        disposed = true;
+        unsubscribeLocal();
+        sceneDoc.doc.off("update", onUpdate);
+    };
+};
+//# sourceMappingURL=bind-editor.js.map

package/dist/bind-editor.js.map

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

package/dist/branch-doc.d.ts

@@ -0,0 +1,53 @@
+import * as Y from "yjs";
+import type { Scene } from "@oh-just-another/scene";
+import { SceneDoc } from "./scene-doc.js";
+import type { BranchId, BranchMergeAPI, ConflictResolution, MergeReport } from "./merge.js";
+export declare class BranchDoc implements BranchMergeAPI {
+    readonly doc: Y.Doc;
+    private readonly branches;
+    private readonly subdocs;
+    private readonly sceneDocs;
+    constructor(doc?: Y.Doc);
+    /**
+     * Create the root branch from an initial scene. Idempotent —
+     * if `id` already exists, returns the existing metadata
+     * unchanged.
+     */
+    ensureRoot(id: string, name: string, initialScene: Scene): BranchId;
+    /**
+     * Fork a new branch from an existing one. The new subdoc starts
+     * with a copy of the parent's current scene; that scene is also
+     * remembered as the common ancestor for future merges back into
+     * any other branch.
+     */
+    createBranch(id: string, name: string, parentBranchId: string): BranchId;
+    /** SceneDoc for the named branch (throws when unknown). */
+    sceneDocFor(branchId: string): SceneDoc;
+    /** Y.Doc subdoc passthrough — required by `BranchMergeAPI`. */
+    branchToDoc(branchId: BranchId): Y.Doc;
+    /**
+     * Merge `source` into `target`. Uses the source branch's stored
+     * ancestor as the three-way merge base. Auto-applied changes
+     * land in the returned `autoMerged` scene; conflicts wait for
+     * `applyConflictResolution`.
+     */
+    mergeBranch(source: BranchId, target: BranchId): Promise<MergeReport>;
+    /**
+     * Resolve a merge report and return the final scene. Pure —
+     * does NOT push the result back into any branch's subdoc; the
+     * host commits it by calling `sceneDocFor(targetId).replace(
+     * finalScene)` when it wants to materialise the merge.
+     */
+    applyConflictResolution(report: MergeReport, resolutions: readonly ConflictResolution[]): Promise<Scene>;
+    /**
+     * Commit `scene` into `targetBranchId`'s subdoc and re-baseline
+     * the source branch's ancestor so a follow-up merge starts from
+     * the post-merge state. Call after `applyConflictResolution`
+     * when the host is happy with the result.
+     */
+    commitMerge(sourceBranchId: string, targetBranchId: string, mergedScene: Scene): void;
+    private requireBranch;
+    private requireSceneDoc;
+    private requireSubdoc;
+}
+//# sourceMappingURL=branch-doc.d.ts.map

package/dist/branch-doc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-doc.d.ts","sourceRoot":"","sources":["../src/branch-doc.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAKpD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,OAAO,KAAK,EACV,QAAQ,EACR,cAAc,EACd,kBAAkB,EAElB,WAAW,EACZ,MAAM,YAAY,CAAC;AAwCpB,qBAAa,SAAU,YAAW,cAAc;IAC9C,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAwB;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IACpD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA+B;gBAE7C,GAAG,GAAE,CAAC,CAAC,GAAiB;IAKpC;;;;OAIG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,GAAG,QAAQ;IAyBnE;;;;;OAKG;IACH,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,QAAQ;IAoBxE,2DAA2D;IAC3D,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ;IAIvC,+DAA+D;IAC/D,WAAW,CAAC,QAAQ,EAAE,QAAQ,GAAG,CAAC,CAAC,GAAG;IAItC;;;;;OAKG;IACH,WAAW,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,GAAG,OAAO,CAAC,WAAW,CAAC;IA6BrE;;;;;OAKG;IACH,uBAAuB,CACrB,MAAM,EAAE,WAAW,EACnB,WAAW,EAAE,SAAS,kBAAkB,EAAE,GACzC,OAAO,CAAC,KAAK,CAAC;IAoBjB;;;;;OAKG;IACH,WAAW,CAAC,cAAc,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,GAAG,IAAI;IAUrF,OAAO,CAAC,aAAa;IAMrB,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,aAAa;CAUtB"}

package/dist/branch-doc.js

@@ -0,0 +1,188 @@
+import * as Y from "yjs";
+import { applyConflictResolutions, mergeScenesThreeWay, } from "@oh-just-another/scene";
+import { SceneDoc } from "./scene-doc.js";
+export class BranchDoc {
+    doc;
+    branches;
+    subdocs = new Map();
+    sceneDocs = new Map();
+    constructor(doc = new Y.Doc()) {
+        this.doc = doc;
+        this.branches = doc.getMap("branches");
+    }
+    /**
+     * Create the root branch from an initial scene. Idempotent —
+     * if `id` already exists, returns the existing metadata
+     * unchanged.
+     */
+    ensureRoot(id, name, initialScene) {
+        const existing = this.branches.get(id);
+        if (existing) {
+            return {
+                id: existing.id,
+                name: existing.name,
+                parentVersionId: existing.parentBranchId,
+            };
+        }
+        const subdoc = new Y.Doc();
+        const sceneDoc = new SceneDoc(subdoc);
+        sceneDoc.replace(initialScene, "branch-init");
+        const meta = {
+            id,
+            name,
+            parentBranchId: null,
+            subdocGuid: subdoc.guid,
+            ancestorScene: cloneScene(initialScene),
+        };
+        this.branches.set(id, meta);
+        this.subdocs.set(id, subdoc);
+        this.sceneDocs.set(id, sceneDoc);
+        return { id, name, parentVersionId: null };
+    }
+    /**
+     * Fork a new branch from an existing one. The new subdoc starts
+     * with a copy of the parent's current scene; that scene is also
+     * remembered as the common ancestor for future merges back into
+     * any other branch.
+     */
+    createBranch(id, name, parentBranchId) {
+        const parent = this.requireBranch(parentBranchId);
+        const parentDoc = this.requireSceneDoc(parentBranchId);
+        const snapshot = parentDoc.snapshot();
+        const subdoc = new Y.Doc();
+        const sceneDoc = new SceneDoc(subdoc);
+        sceneDoc.replace(snapshot, "branch-fork");
+        const meta = {
+            id,
+            name,
+            parentBranchId: parent.id,
+            subdocGuid: subdoc.guid,
+            ancestorScene: cloneScene(snapshot),
+        };
+        this.branches.set(id, meta);
+        this.subdocs.set(id, subdoc);
+        this.sceneDocs.set(id, sceneDoc);
+        return { id, name, parentVersionId: parent.id };
+    }
+    /** SceneDoc for the named branch (throws when unknown). */
+    sceneDocFor(branchId) {
+        return this.requireSceneDoc(branchId);
+    }
+    /** Y.Doc subdoc passthrough — required by `BranchMergeAPI`. */
+    branchToDoc(branchId) {
+        return this.requireSubdoc(branchId.id);
+    }
+    /**
+     * Merge `source` into `target`. Uses the source branch's stored
+     * ancestor as the three-way merge base. Auto-applied changes
+     * land in the returned `autoMerged` scene; conflicts wait for
+     * `applyConflictResolution`.
+     */
+    mergeBranch(source, target) {
+        const sMeta = this.requireBranch(source.id);
+        const sourceScene = this.requireSceneDoc(source.id).snapshot();
+        const targetScene = this.requireSceneDoc(target.id).snapshot();
+        // Yjs snapshot allocates fresh shape objects every call — reference
+        // equality (the algorithm's default) can't tell "unchanged" from
+        // "edited" across two snapshots. JSON.stringify is good enough for
+        // plain-object shapes, which is what the kernel ships.
+        const report = mergeScenesThreeWay(sMeta.ancestorScene, sourceScene, targetScene, {
+            compareElements: (a, b) => JSON.stringify(a) === JSON.stringify(b),
+        });
+        const applied = [];
+        for (const [id, shape] of report.autoMerged.elements) {
+            const prev = targetScene.elements.get(id);
+            if (prev !== shape)
+                applied.push(id);
+        }
+        const conflicts = report.conflicts.map((c) => ({
+            elementId: c.elementId,
+            base: c.base,
+            source: c.source,
+            target: c.target,
+        }));
+        return Promise.resolve({
+            applied,
+            conflicts,
+            autoMerged: report.autoMerged,
+        });
+    }
+    /**
+     * Resolve a merge report and return the final scene. Pure —
+     * does NOT push the result back into any branch's subdoc; the
+     * host commits it by calling `sceneDocFor(targetId).replace(
+     * finalScene)` when it wants to materialise the merge.
+     */
+    applyConflictResolution(report, resolutions) {
+        return Promise.resolve(applyConflictResolutions({
+            autoMerged: report.autoMerged,
+            conflicts: report.conflicts.map((c) => ({
+                elementId: c.elementId,
+                base: c.base,
+                source: c.source,
+                target: c.target,
+            })),
+        }, resolutions.map((r) => ({
+            elementId: r.elementId,
+            choice: r.choice === "ours" ? "ours" : r.choice === "theirs" ? "theirs" : "both",
+        }))));
+    }
+    /**
+     * Commit `scene` into `targetBranchId`'s subdoc and re-baseline
+     * the source branch's ancestor so a follow-up merge starts from
+     * the post-merge state. Call after `applyConflictResolution`
+     * when the host is happy with the result.
+     */
+    commitMerge(sourceBranchId, targetBranchId, mergedScene) {
+        const targetDoc = this.requireSceneDoc(targetBranchId);
+        targetDoc.replace(mergedScene, "branch-merge");
+        const sMeta = this.requireBranch(sourceBranchId);
+        this.branches.set(sourceBranchId, {
+            ...sMeta,
+            ancestorScene: cloneScene(mergedScene),
+        });
+    }
+    requireBranch(id) {
+        const m = this.branches.get(id);
+        if (!m)
+            throw new Error(`BranchDoc: unknown branch "${id}"`);
+        return m;
+    }
+    requireSceneDoc(id) {
+        const cached = this.sceneDocs.get(id);
+        if (cached)
+            return cached;
+        // Subdoc was created in a different session — rehydrate.
+        const subdoc = this.requireSubdoc(id);
+        const sceneDoc = new SceneDoc(subdoc);
+        this.sceneDocs.set(id, sceneDoc);
+        return sceneDoc;
+    }
+    requireSubdoc(id) {
+        const cached = this.subdocs.get(id);
+        if (cached)
+            return cached;
+        const meta = this.requireBranch(id);
+        // Create the subdoc shell with the recorded guid so peers
+        // converge on the same doc id across sessions.
+        const subdoc = new Y.Doc({ guid: meta.subdocGuid });
+        this.subdocs.set(id, subdoc);
+        return subdoc;
+    }
+}
+/**
+ * Deep clone a scene. The Yjs subdoc owns its own copies of
+ * shapes / edges / layers, so the ancestor snapshot has to be a
+ * detached deep clone — otherwise editor mutations would silently
+ * mutate the ancestor and the three-way merge would always see
+ * "no changes" on the source side.
+ */
+const cloneScene = (scene) => ({
+    elements: new Map([...scene.elements].map(([id, shape]) => [id, structuredClone(shape)])),
+    links: new Map([...scene.links].map(([id, edge]) => [id, structuredClone(edge)])),
+    layers: new Map([...scene.layers].map(([id, layer]) => [id, structuredClone(layer)])),
+    annotations: new Map([...scene.annotations].map(([id, ann]) => [id, structuredClone(ann)])),
+    files: new Map([...scene.files].map(([id, file]) => [id, structuredClone(file)])),
+    viewport: structuredClone(scene.viewport),
+});
+//# sourceMappingURL=branch-doc.js.map

package/dist/branch-doc.js.map

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

package/dist/constants.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Tunable thresholds for the collab package.
+ */
+/**
+ * Length of the public room identifier in bytes (hex string =
+ * 2× chars). 10 bytes = 80 bits = ~1 in 2^80 collision odds at
+ * realistic concurrency; matches standard's 20-hex format.
+ */
+export declare const ROOM_ID_BYTES = 10;
+/**
+ * AES key length in bits. AES-128 is the modern default for
+ * symmetric session keys — fast on every platform and
+ * cryptographically equivalent to AES-256 against any practical
+ * attacker (the 256-bit version's marginal extra security
+ * matters only for offline attacks against a long-lived key,
+ * not for ephemeral session keys).
+ */
+export declare const ENCRYPTION_KEY_BITS = 128;
+/**
+ * Initialisation-vector length for AES-GCM. NIST SP 800-38D
+ * recommends 96 bits (12 bytes) — the construction is most
+ * efficient at that length, longer IVs go through an extra
+ * hashing step.
+ */
+export declare const ENCRYPTION_IV_BYTES = 12;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;GAIG;AACH,eAAO,MAAM,aAAa,KAAK,CAAC;AAEhC;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,KAAK,CAAC"}

package/dist/constants.js

@@ -0,0 +1,26 @@
+/**
+ * Tunable thresholds for the collab package.
+ */
+/**
+ * Length of the public room identifier in bytes (hex string =
+ * 2× chars). 10 bytes = 80 bits = ~1 in 2^80 collision odds at
+ * realistic concurrency; matches standard's 20-hex format.
+ */
+export const ROOM_ID_BYTES = 10;
+/**
+ * AES key length in bits. AES-128 is the modern default for
+ * symmetric session keys — fast on every platform and
+ * cryptographically equivalent to AES-256 against any practical
+ * attacker (the 256-bit version's marginal extra security
+ * matters only for offline attacks against a long-lived key,
+ * not for ephemeral session keys).
+ */
+export const ENCRYPTION_KEY_BITS = 128;
+/**
+ * Initialisation-vector length for AES-GCM. NIST SP 800-38D
+ * recommends 96 bits (12 bytes) — the construction is most
+ * efficient at that length, longer IVs go through an extra
+ * hashing step.
+ */
+export const ENCRYPTION_IV_BYTES = 12;
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,EAAE,CAAC;AAEhC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,CAAC"}

package/dist/encryption.d.ts

@@ -0,0 +1,74 @@
+import type { Transport } from "@oh-just-another/network";
+/**
+ * Client-side AES-GCM encryption for collab transports. Mirrors
+ * standard's "URL fragment carries the key" model: the secret
+ * never reaches the relay, so a blind fan-out server can route
+ * payloads without ever decrypting them.
+ *
+ * URL convention (set by the host app, parsed in `apps/diagram/src/collab.ts`):
+ *
+ *   /#room=<roomId>,<keyBase64>
+ *
+ * `roomId` goes in the WebSocket pathname (`/<roomId>`) so the
+ * relay can route by room. `keyBase64` stays in the URL fragment
+ * which the browser does not transmit on any request — including
+ * the WebSocket upgrade — so the server never sees it.
+ *
+ * Wire format per frame:
+ *
+ *   [ 12-byte IV ][ AES-GCM ciphertext + 16-byte auth tag ]
+ *
+ * IV is random per frame (WebCrypto / NIST guidance — never reuse
+ * an IV with the same key). The auth tag is part of the ciphertext
+ * tail produced by AES-GCM; tampered frames throw on decrypt.
+ */
+/** Strongly-typed result of {@link generateRoomKey}. */
+export interface RoomCredentials {
+    /** Public room identifier — appears in the WS pathname, visible to relay. */
+    readonly roomId: string;
+    /**
+     * Base64url-encoded raw AES key. Goes into the URL fragment; share
+     * the full URL to invite peers. Never log this value.
+     */
+    readonly keyBase64: string;
+    /** The imported `CryptoKey` ready for AES-GCM operations. */
+    readonly key: CryptoKey;
+}
+/**
+ * Mint a fresh credentials pair for a new collab session. Uses
+ * `crypto.getRandomValues` for the roomId and `crypto.subtle` for
+ * the AES key.
+ */
+export declare const generateRoomKey: () => Promise<RoomCredentials>;
+/**
+ * Re-import a key the second peer parsed out of the URL fragment.
+ * Throws on malformed base64 / wrong length so the caller can
+ * surface "broken invite link" cleanly.
+ */
+export declare const importRoomKey: (keyBase64: string) => Promise<CryptoKey>;
+/**
+ * Wrap any {@link Transport} so every outgoing payload is AES-GCM
+ * encrypted and every incoming payload is decrypted before reaching
+ * subscribers. The relay sees nothing but binary blobs.
+ *
+ * Decryption errors are silently dropped — a tampered or
+ * wrong-key frame should not surface as a noisy console error
+ * (that would let a malicious peer flood the log). Callers can opt
+ * into observability by passing `onDecryptError`.
+ */
+export declare class EncryptedTransport implements Transport {
+    private readonly inner;
+    private readonly key;
+    private readonly options;
+    private readonly handlers;
+    private unsubscribe;
+    constructor(inner: Transport, key: CryptoKey, options?: {
+        readonly onDecryptError?: (err: unknown) => void;
+    });
+    send(payload: Uint8Array): void;
+    onMessage(handler: (payload: Uint8Array) => void): () => void;
+    close(): void;
+    private encryptAndSend;
+    private decryptAndDispatch;
+}
+//# sourceMappingURL=encryption.d.ts.map