edytor 3.0.0 → 5.0.0

package/dist/crdt/placement/slots.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Slots and move records — where a block or an array item stands (fork
+ * patch YP22).
+ *
+ * Every data owner keeps ONE order sequence, its node's list part (a block's
+ * node, an atom's node, the registry root for the top-level blocks, the
+ * `docdata` root for the document's data). The sequence holds one countable
+ * unit per thing it orders:
+ *
+ * - a block's **home slot** `{ b: id }`, written once at the block's creation
+ *   in its parent's sequence, right after its left sibling's unit (YATA's
+ *   origin rule: later inserts there stay together, `order.insert.run`);
+ * - an array item's **slot** `{ p: path, i: id }` (`crdt/data.ts`): the
+ *   item exists while its slot does;
+ * - a **move record** (the engine's `ContentMove`): one unit at the
+ *   destination naming the units it moves, in order. Each named unit shows
+ *   at the record that wins its movers — the greatest `(priority, client,
+ *   clock)` — and reads as deleted at home, so a sequence walk sees it gone
+ *   from there. Deleting a record (an undo) hands its units to the next
+ *   record, else home.
+ *
+ * A reader of a sequence (`entriesOf`) walks its live items: a slot at home,
+ * or a record expanded to the units it shows. A writer places a new slot or a
+ * record after a displayed entry (`placeAfter`): when that entry is a unit in
+ * the middle of a record's display, the new record also carries the record's
+ * later units, so the new thing shows between them.
+ *
+ * The engine is read through `engine.js` (structural types, `engine-api.ts`).
+ */
+import type { EngineDoc, EngineNode } from '../engine-api.js';
+import { type StoreStruct } from '../structs.js';
+export type BlockId = string;
+/**
+ * A block's home slot in its parent's sequence; `s`, when the block was made
+ * by a split (Enter, a paste of lines): the id (`client, clock`) of the
+ * split's boundary item in the text, the engine's sort key among the slots
+ * of one origin (the boundaries' order in the text, so two peers' splits of
+ * one block keep its text's order, `order.split.text`).
+ */
+export type BlockSlot = {
+    b: BlockId;
+    s?: [client: number, clock: number];
+};
+/** An array item's slot: the array's path (`crdt/data.ts`) and the item's id. */
+export type DataSlot = {
+    p: string;
+    i: string;
+};
+/** One unit of a sequence: its engine id. */
+export type Unit = {
+    c: number;
+    k: number;
+};
+export declare const isBlockSlot: (v: unknown) => v is BlockSlot;
+export declare const isDataSlot: (v: unknown) => v is DataSlot;
+/** A sequence item as the slot reads walk it. */
+export type SeqItem = StoreStruct & {
+    left: SeqItem | null;
+    right: SeqItem | null;
+    content: {
+        arr?: unknown[];
+        priority?: number;
+        side?: number;
+        part?: number;
+        at?: unknown;
+        ids?: number[];
+    };
+    /** The record that shows this unit (fork patch YP22), `null` at home. */
+    mover?: SeqItem | null;
+    movers?: SeqItem[] | null;
+    /** Removed or held: shown nowhere. */
+    gone?: boolean;
+};
+/** Whether `it` is a move record. */
+export declare const isRecord: (it: SeqItem) => boolean;
+/** A record's stamp, the order its wins follow: `(priority, client, clock)`. */
+export type Stamp = readonly [priority: number, client: number, clock: number];
+export declare const stampOf: (r: SeqItem) => Stamp;
+export declare const cmpStamp: (a: Stamp, b: Stamp) => number;
+/** One displayed entry of a sequence: its value, its unit, and the record it shows through (`null`: at home; `at`: its place among the units read with it). */
+export type Entry = {
+    value: unknown;
+    unit: Unit;
+    via: SeqItem | null;
+    at: number;
+};
+/** Whether `a` and `b` are one unit. */
+export declare const sameUnit: (a: Unit, b: Unit) => boolean;
+/** The item holding unit `u`, or `null` when `doc` lacks it (no value read: the fold's hot path). */
+export declare const itemAt: (doc: EngineDoc, u: Unit) => SeqItem | null;
+/** The item holding unit `u` and the value at it, or `null` when `doc` lacks it (a GC struct, not arrived). */
+export declare const unitOf: (doc: EngineDoc, u: Unit) => {
+    item: SeqItem;
+    value: unknown;
+} | null;
+/**
+ * The units item `it` can show, in order, those `keep` takes: a live
+ * record's named units (present, not gone; `via` the record), a slot item's
+ * units, moved away or not (none when it is gone; `via` `null`). THE walk
+ * every reader of a sequence's units takes: the engine's (`shownBy`), the
+ * index's places (`placement/resolve.ts`) and the writers' view of them
+ * (`placement/model.ts`).
+ */
+export declare const unitsOf: (doc: EngineDoc, it: SeqItem, keep: (item: SeqItem, value: unknown, unit: Unit) => boolean) => Entry[];
+/** The units the engine shows at item `it`, in order: a live record's, those it wins; a live slot item's, all. */
+export declare const shownBy: (doc: EngineDoc, it: SeqItem) => Entry[];
+/** The displayed entries of `node`'s sequence, in order. */
+export declare const entriesOf: (doc: EngineDoc, node: EngineNode) => Entry[];
+/**
+ * The entry unit `home` displays as: at home when no live record wins it,
+ * else at its mover (`via`, `at`); `null` when it shows nowhere (gone).
+ */
+export declare const anchorOf: (doc: EngineDoc, home: Unit) => Entry | null;
+/** The sequence node that holds `e`'s displaying item (its record's, or its slot's). */
+export declare const nodeOf: (doc: EngineDoc, e: Entry) => EngineNode;
+/** `units` as `client, clock, len` triples (one unit each). */
+export declare const triples: (units: readonly Unit[]) => number[];
+/**
+ * Write new slots (`payloads`) and/or a move of `moved` (unit triples) into
+ * `node`'s sequence right after the displayed entry `left` (at the start when
+ * `null`; `right` the entry that follows, if any). When `left` is a unit in
+ * the middle of a record's display, the record written here carries that
+ * record's later units too, so the new entries show between them. `side` is
+ * the record's class among the items of its origin (`0` after, `1` before);
+ * `chain` the units the record stands at for the engine's sort of two
+ * records at one origin, given its first unit — the home slots from the root
+ * sequence down to the unit it stands at (`null`: the first unit alone) — and
+ * `part` its order among the records standing there. `shown` reads the units
+ * a record shows, as the reader sees them (the index's: a unit a cycle sent
+ * back elsewhere is not carried).
+ */
+export declare const placeAfter: (doc: EngineDoc, node: EngineNode, left: Entry | null, right: Entry | null, payloads: readonly unknown[] | null, moved?: readonly number[] | null, side?: number, part?: number, chain?: ((first: Unit) => readonly Unit[]) | null, shown?: (r: SeqItem) => Entry[]) => void;
+/** Remove unit `u` from its sequence (the engine's delete: it shows nowhere any more). */
+export declare const removeUnit: (doc: EngineDoc, u: Unit) => void;

package/dist/crdt/placement/slots.js

@@ -0,0 +1,152 @@
+import { Y } from '../engine.js';
+import { asYDoc, clientsOf, engineOps, firstItem, storeOf, structAt } from '../structs.js';
+export const isBlockSlot = (v) => v != null && typeof v === 'object' && typeof v.b === 'string';
+export const isDataSlot = (v) => v != null &&
+    typeof v === 'object' &&
+    typeof v.p === 'string' &&
+    typeof v.i === 'string';
+/** Whether `it` is a move record. */
+export const isRecord = (it) => it.content.priority !== undefined && it.content.ids !== undefined;
+export const stampOf = (r) => [r.content.priority, r.id.client, r.id.clock];
+export const cmpStamp = (a, b) => a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+/** Whether `a` and `b` are one unit. */
+export const sameUnit = (a, b) => a.c === b.c && a.k === b.k;
+const ops = engineOps(Y);
+/** The item holding unit `u`, or `null` when `doc` lacks it (no value read: the fold's hot path). */
+export const itemAt = (doc, u) => {
+    const structs = clientsOf(doc).get(u.c);
+    if (structs === undefined || u.k >= storeOf(doc).getClock(u.c))
+        return null;
+    const item = structAt(Y, structs, u.k);
+    return item === null || !ops.isItem(item) ? null : item;
+};
+/** The item holding unit `u` and the value at it, or `null` when `doc` lacks it (a GC struct, not arrived). */
+export const unitOf = (doc, u) => {
+    const item = itemAt(doc, u);
+    return item === null ? null : { item, value: item.content.arr?.[u.k - item.id.clock] };
+};
+/**
+ * The units item `it` can show, in order, those `keep` takes: a live
+ * record's named units (present, not gone; `via` the record), a slot item's
+ * units, moved away or not (none when it is gone; `via` `null`). THE walk
+ * every reader of a sequence's units takes: the engine's (`shownBy`), the
+ * index's places (`placement/resolve.ts`) and the writers' view of them
+ * (`placement/model.ts`).
+ */
+export const unitsOf = (doc, it, keep) => {
+    const out = [];
+    const add = (item, value, unit, via) => {
+        if (item.gone !== true && keep(item, value, unit))
+            out.push({ value, unit, via, at: out.length });
+    };
+    if (!isRecord(it))
+        it.content.arr?.forEach((value, j) => add(it, value, { c: it.id.client, k: it.id.clock + j }, null));
+    else if (!it.deleted) {
+        const ids = it.content.ids;
+        for (let i = 0; i < ids.length; i += 3)
+            for (let k = 0; k < ids[i + 2]; k++) {
+                const unit = { c: ids[i], k: ids[i + 1] + k };
+                const u = unitOf(doc, unit);
+                if (u !== null)
+                    add(u.item, u.value, unit, it);
+            }
+    }
+    return out;
+};
+/** The units the engine shows at item `it`, in order: a live record's, those it wins; a live slot item's, all. */
+export const shownBy = (doc, it) => {
+    const via = isRecord(it) ? it : null;
+    return it.deleted ? [] : unitsOf(doc, it, (item) => item.mover === via);
+};
+/** The displayed entries of `node`'s sequence, in order. */
+export const entriesOf = (doc, node) => {
+    const out = [];
+    for (let it = firstItem(node); it !== null; it = it.right)
+        for (const e of shownBy(doc, it))
+            out.push(e);
+    return out;
+};
+/**
+ * The entry unit `home` displays as: at home when no live record wins it,
+ * else at its mover (`via`, `at`); `null` when it shows nowhere (gone).
+ */
+export const anchorOf = (doc, home) => {
+    const u = unitOf(doc, home);
+    if (u === null || u.item.gone === true)
+        return null;
+    const r = u.item.mover ?? null;
+    if (r === null || r.deleted)
+        return { value: u.value, unit: home, via: null, at: 0 };
+    return shownBy(doc, r).find((e) => sameUnit(e.unit, home)) ?? null;
+};
+/** The sequence node that holds `e`'s displaying item (its record's, or its slot's). */
+export const nodeOf = (doc, e) => (e.via !== null ? e.via.parent : unitOf(doc, e.unit).item.parent);
+/** The live index of the item that displays `e` (its record, or its slot unit). */
+const liveIndexOf = (doc, e) => {
+    const id = e.via === null ? Y.createID(e.unit.c, e.unit.k) : Y.createID(e.via.id.client, e.via.id.clock);
+    return Y.indexOfId(asYDoc(doc), id).index;
+};
+/** `units` as `client, clock, len` triples (one unit each). */
+export const triples = (units) => units.flatMap((u) => [u.c, u.k, 1]);
+/**
+ * Write new slots (`payloads`) and/or a move of `moved` (unit triples) into
+ * `node`'s sequence right after the displayed entry `left` (at the start when
+ * `null`; `right` the entry that follows, if any). When `left` is a unit in
+ * the middle of a record's display, the record written here carries that
+ * record's later units too, so the new entries show between them. `side` is
+ * the record's class among the items of its origin (`0` after, `1` before);
+ * `chain` the units the record stands at for the engine's sort of two
+ * records at one origin, given its first unit — the home slots from the root
+ * sequence down to the unit it stands at (`null`: the first unit alone) — and
+ * `part` its order among the records standing there. `shown` reads the units
+ * a record shows, as the reader sees them (the index's: a unit a cycle sent
+ * back elsewhere is not carried).
+ */
+export const placeAfter = (doc, node, left, right, payloads, moved = null, side = 0, part = 0, chain = null, shown = (r) => shownBy(doc, r)) => {
+    let index;
+    let carry = [];
+    if (left === null)
+        index = right === null ? node.length : liveIndexOf(doc, right);
+    else {
+        if (left.via !== null)
+            carry = shown(left.via)
+                .slice(left.at + 1)
+                .map((e) => e.unit);
+        // A unit shown at home though its item moved away (a cycle sent it back)
+        // is no live unit: the gap after it starts at its live index.
+        const live = left.via !== null || unitOf(doc, left.unit)?.item.deleted !== true;
+        index = liveIndexOf(doc, left) + (live ? 1 : 0);
+    }
+    const units = moved === null ? [] : [...moved];
+    if (payloads !== null && payloads.length > 0) {
+        // The new slots' first unit is this writer's next clock.
+        if (carry.length > 0)
+            units.push(doc.clientID, storeOf(doc).getClock(doc.clientID), payloads.length);
+        node.insert(index, payloads);
+    }
+    // A carried unit that moves here anyway is named once.
+    const named = new Set();
+    for (let i = 0; i < units.length; i += 3)
+        for (let k = 0; k < units[i + 2]; k++)
+            named.add(`${units[i]}:${units[i + 1] + k}`);
+    for (const u of carry)
+        if (!named.has(`${u.c}:${u.k}`))
+            units.push(u.c, u.k, 1);
+    if (units.length > 0 && (moved !== null || carry.length > 0)) {
+        const first = { c: units[0], k: units[1] };
+        const at = chain === null ? null : chain(first);
+        // A chain of the first unit alone is the engine's default: not written.
+        const own = at !== null && at.length === 1 && sameUnit(at[0], first);
+        node.move(index, units, side, part, at === null || own ? null : at.map((u) => Y.createID(u.c, u.k)));
+    }
+};
+/** Remove unit `u` from its sequence (the engine's delete: it shows nowhere any more). */
+export const removeUnit = (doc, u) => {
+    Y.transact(asYDoc(doc), (tr) => {
+        const it = Y.getItemCleanStart(tr, Y.createID(u.c, u.k));
+        if (it.length > 1)
+            Y.getItemCleanStart(tr, Y.createID(u.c, u.k + 1));
+        if (!it.removed)
+            ops.remove(tr, it);
+    });
+};

package/dist/crdt/protocol.d.ts

@@ -29,7 +29,7 @@ export { SCHEMA_VERSION, META_KEY } from './edytor-doc.js';
 export { GENERATION, generationWord, frame, PROTOCOL_VERSION, GENERATION_RECORD, GenerationMismatchError, readProtocolVersion, type GenerationRecord } from './protocols/envelope.js';
 export { messageSync, messageAwareness, messageAuth, messageQueryAwareness, messageSaved, messageChunk, messageComments, MAX_FRAME_BYTES, chunkFrame, createChunkReader, ChunkError, type ChunkReader, CLOSE } from './providers/room.js';
 export { messageYjsSyncStep1, messageYjsSyncStep2, messageYjsUpdate, type SyncProtocol } from './protocols/sync.js';
-export { messagePermissionDenied, messageReadOnly, writePermissionDenied, writeReadOnly } from './protocols/auth.js';
+export { messageAccess, messagePermissionDenied, messageReadOnly, writeAccess, writePermissionDenied, writeReadOnly } from './protocols/auth.js';
 export { commentsSubscribe, commentsSnapshot, commentsChange, writeCommentsSubscribe, writeCommentsSnapshot, writeCommentsChange, readCommentsMessage, type CommentChange, type CommentMessage, type CommentSnapshot, type CommentThread, type ThreadComment } from './protocols/comments.js';
 export { applyAwarenessUpdate, encodeAwarenessUpdate, readAwarenessEntries, writeAwarenessEntries, type AwarenessEntry } from './protocols/awareness.js';
 export { createDecoder, readVarUint, readVarUint8Array, type Decoder } from 'lib0-v14/decoding';

package/dist/crdt/protocol.js

@@ -32,7 +32,7 @@ export { GENERATION, generationWord, frame, PROTOCOL_VERSION, GENERATION_RECORD,
 // ── Message types, acknowledgements and chunks ─────────────────────────
 export { messageSync, messageAwareness, messageAuth, messageQueryAwareness, messageSaved, messageChunk, messageComments, MAX_FRAME_BYTES, chunkFrame, createChunkReader, ChunkError, CLOSE } from './providers/room.js';
 export { messageYjsSyncStep1, messageYjsSyncStep2, messageYjsUpdate } from './protocols/sync.js';
-export { messagePermissionDenied, messageReadOnly, writePermissionDenied, writeReadOnly } from './protocols/auth.js';
+export { messageAccess, messagePermissionDenied, messageReadOnly, writeAccess, writePermissionDenied, writeReadOnly } from './protocols/auth.js';
 export { commentsSubscribe, commentsSnapshot, commentsChange, writeCommentsSubscribe, writeCommentsSnapshot, writeCommentsChange, readCommentsMessage } from './protocols/comments.js';
 export { applyAwarenessUpdate, encodeAwarenessUpdate, readAwarenessEntries, writeAwarenessEntries } from './protocols/awareness.js';
 // Minimal wire codec for frame bodies (lib0 — the codec the frames are

package/dist/crdt/protocols/auth.d.ts

@@ -14,10 +14,20 @@ import * as decoding from 'lib0-v14/decoding';
 export declare const messagePermissionDenied = 0;
 /** The denial of a read-only socket's write: that socket still syncs (not a terminal refusal). */
 export declare const READ_ONLY_DENIAL = "read-only";
+/** The denial of what a suggest-only socket wrote that is no suggestion's: it still syncs. */
+export declare const SUGGEST_ONLY_DENIAL = "suggest-only";
 export declare const writePermissionDenied: (encoder: encoding.Encoder, reason: string) => void;
 /** The socket may read but not write: sent when it joins, before any write is refused. */
 export declare const messageReadOnly = 1;
 export declare const writeReadOnly: (encoder: encoding.Encoder) => void;
+/**
+ * The socket's access (the string that follows: `write`, `suggest` or
+ * `comment`), sent when it joins, before anything else it reads; a
+ * `comment` one's after its read-only notice (a `read` one has only the
+ * notice).
+ */
+export declare const messageAccess = 2;
+export declare const writeAccess: (encoder: encoding.Encoder, access: string) => void;
 export type PermissionDeniedHandler = (ydoc: unknown, reason: string) => void;
 /**
  * Decode one auth payload. Returns the auth message subtype so the caller
@@ -25,4 +35,4 @@ export type PermissionDeniedHandler = (ydoc: unknown, reason: string) => void;
  * do not speak is protocol skew, and this stack's contract is that skew is
  * reported, not silently dropped (same rule as unknown sync subtypes).
  */
-export declare const readAuthMessage: (decoder: decoding.Decoder, y: unknown, permissionDeniedHandler: PermissionDeniedHandler, readOnlyHandler?: (ydoc: unknown) => void) => number;
+export declare const readAuthMessage: (decoder: decoding.Decoder, y: unknown, permissionDeniedHandler: PermissionDeniedHandler, readOnlyHandler?: (ydoc: unknown) => void, accessHandler?: (access: string) => void) => number;

package/dist/crdt/protocols/auth.js

@@ -14,6 +14,8 @@ import * as decoding from 'lib0-v14/decoding';
 export const messagePermissionDenied = 0;
 /** The denial of a read-only socket's write: that socket still syncs (not a terminal refusal). */
 export const READ_ONLY_DENIAL = 'read-only';
+/** The denial of what a suggest-only socket wrote that is no suggestion's: it still syncs. */
+export const SUGGEST_ONLY_DENIAL = 'suggest-only';
 export const writePermissionDenied = (encoder, reason) => {
     encoding.writeVarUint(encoder, messagePermissionDenied);
     encoding.writeVarString(encoder, reason);
@@ -23,13 +25,24 @@ export const messageReadOnly = 1;
 export const writeReadOnly = (encoder) => {
     encoding.writeVarUint(encoder, messageReadOnly);
 };
+/**
+ * The socket's access (the string that follows: `write`, `suggest` or
+ * `comment`), sent when it joins, before anything else it reads; a
+ * `comment` one's after its read-only notice (a `read` one has only the
+ * notice).
+ */
+export const messageAccess = 2;
+export const writeAccess = (encoder, access) => {
+    encoding.writeVarUint(encoder, messageAccess);
+    encoding.writeVarString(encoder, access);
+};
 /**
  * Decode one auth payload. Returns the auth message subtype so the caller
  * can surface unknown subtypes — a valid envelope carrying an auth type we
  * do not speak is protocol skew, and this stack's contract is that skew is
  * reported, not silently dropped (same rule as unknown sync subtypes).
  */
-export const readAuthMessage = (decoder, y, permissionDeniedHandler, readOnlyHandler) => {
+export const readAuthMessage = (decoder, y, permissionDeniedHandler, readOnlyHandler, accessHandler) => {
     const authMessageType = decoding.readVarUint(decoder);
     switch (authMessageType) {
         case messagePermissionDenied:
@@ -38,6 +51,9 @@ export const readAuthMessage = (decoder, y, permissionDeniedHandler, readOnlyHan
         case messageReadOnly:
             // Unclaimed, it is returned like any subtype the caller does not speak.
             readOnlyHandler?.(y);
+            break;
+        case messageAccess:
+            accessHandler?.(decoding.readVarString(decoder));
     }
     return authMessageType;
 };

package/dist/crdt/protocols/comments.d.ts

@@ -67,6 +67,16 @@ export type CommentRequest = {
     block?: string | null;
     /** The first comment's id (default: one the store makes). */
     comment?: string;
+    /**
+     * The text it is made on, as anchors (`DocAnchor`s, each span's
+     * ends): the room writes its anchor mark over them for a user who
+     * may only comment (`room.access.comment`); a writer's view writes
+     * it itself.
+     */
+    anchors?: {
+        start: unknown;
+        end: unknown;
+    }[];
 } | {
     op: 'reply';
     thread: string;
@@ -85,11 +95,16 @@ export type CommentRequest = {
     thread: string;
     comment?: string;
 };
-/** Who asks: a verified user, read-only or not; a moderator may delete anyone's comment. */
+/**
+ * Who asks: a verified user, read-only or not; a moderator may delete
+ * anyone's comment; `anchors`: the store writes a new thread's anchor (a
+ * user who may only comment).
+ */
 export type CommentActor = {
     user: string;
     readOnly?: boolean;
     moderator?: boolean;
+    anchors?: boolean;
 };
 /** What one request changed (the room broadcasts it, `onComment` receives it). */
 export type CommentChange = {

package/dist/crdt/protocols/comments.js

@@ -62,13 +62,21 @@ export const parseCommentRequest = (value) => {
                 return null;
             if (v.block !== undefined && v.block !== null && typeof v.block !== 'string')
                 return null;
+            if (v.anchors !== undefined &&
+                (!Array.isArray(v.anchors) ||
+                    v.anchors.length > 64 ||
+                    v.anchors.some((a) => typeof a?.start !== 'object' || typeof a?.end !== 'object')))
+                return null;
             return {
                 op: 'add',
                 thread: v.thread,
                 body: v.body,
                 ...(v.quote === undefined ? {} : { quote: v.quote }),
                 ...(v.block === undefined ? {} : { block: v.block }),
-                ...(v.comment === undefined ? {} : { comment: v.comment })
+                ...(v.comment === undefined ? {} : { comment: v.comment }),
+                ...(v.anchors === undefined
+                    ? {}
+                    : { anchors: v.anchors })
             };
         case 'reply':
             if (typeof v.body !== 'string')

package/dist/crdt/providers/index.d.ts

@@ -47,6 +47,8 @@ export type EdytorSyncPayload = {
      * websocket sync's local store. `document.attachSync` passes it.
      */
     attach?: (sync: EdytorSync) => EdytorSyncCleanup | void;
+    /** What the room says the document's user may do (`EdytorDocument.access`). */
+    access?: (access: 'write' | 'suggest' | 'comment' | 'read') => void;
 };
 export type EdytorSyncCleanup = () => void | Promise<void>;
 export type EdytorSync = ((payload: EdytorSyncPayload) => void | EdytorSyncCleanup) & {
@@ -273,11 +275,11 @@ export declare const bindProviders: (Y: EngineApi) => {
             destroy(): void;
             disconnect(): void;
             connect(): void;
-            emit<N extends "refused" | "status" | "failed" | "schema-mismatch" | "message-error" | "protocol-mismatch" | "synced" | "connection-close" | "connection-error" | "saved" | "permission-denied" | "expired" | "unreachable">(name: N, args: Parameters<WebsocketProviderEvents[N]>): void;
+            emit<N extends "refused" | "status" | "failed" | "schema-mismatch" | "message-error" | "protocol-mismatch" | "synced" | "access" | "connection-close" | "connection-error" | "saved" | "permission-denied" | "expired" | "unreachable">(name: N, args: Parameters<WebsocketProviderEvents[N]>): void;
             _observers: Map<string, Set<any>>;
-            on<NAME extends "refused" | "status" | "failed" | "schema-mismatch" | "message-error" | "protocol-mismatch" | "synced" | "connection-close" | "connection-error" | "saved" | "permission-denied" | "expired" | "unreachable">(name: NAME, f: WebsocketProviderEvents[NAME]): WebsocketProviderEvents[NAME];
-            once<NAME extends "refused" | "status" | "failed" | "schema-mismatch" | "message-error" | "protocol-mismatch" | "synced" | "connection-close" | "connection-error" | "saved" | "permission-denied" | "expired" | "unreachable">(name: NAME, f: WebsocketProviderEvents[NAME]): void;
-            off<NAME extends "refused" | "status" | "failed" | "schema-mismatch" | "message-error" | "protocol-mismatch" | "synced" | "connection-close" | "connection-error" | "saved" | "permission-denied" | "expired" | "unreachable">(name: NAME, f: WebsocketProviderEvents[NAME]): void;
+            on<NAME extends "refused" | "status" | "failed" | "schema-mismatch" | "message-error" | "protocol-mismatch" | "synced" | "access" | "connection-close" | "connection-error" | "saved" | "permission-denied" | "expired" | "unreachable">(name: NAME, f: WebsocketProviderEvents[NAME]): WebsocketProviderEvents[NAME];
+            once<NAME extends "refused" | "status" | "failed" | "schema-mismatch" | "message-error" | "protocol-mismatch" | "synced" | "access" | "connection-close" | "connection-error" | "saved" | "permission-denied" | "expired" | "unreachable">(name: NAME, f: WebsocketProviderEvents[NAME]): void;
+            off<NAME extends "refused" | "status" | "failed" | "schema-mismatch" | "message-error" | "protocol-mismatch" | "synced" | "access" | "connection-close" | "connection-error" | "saved" | "permission-denied" | "expired" | "unreachable">(name: NAME, f: WebsocketProviderEvents[NAME]): void;
         };
     };
     watchComments: (server: string | null, roomName: string, listener: (message: import("../protocol.js").CommentMessage) => void) => (() => void);

package/dist/crdt/providers/index.js

@@ -38,7 +38,7 @@ export const bindProviders = (Y) => {
         const room = `${serverUrl}/${roomName}`;
         const persistName = options.persist === false ? undefined : (options.persistName ?? `edytor:${room}`);
         const sync = (payload) => {
-            const { doc, awareness, synced, failed, attach, armBound, holdBound } = payload;
+            const { doc, awareness, synced, failed, attach, armBound, holdBound, access } = payload;
             const { params, WebSocketPolyfill, maxBackoffTime, connectTimeout, disableBc, onExpired, maxFrameBytes } = options;
             const local = persistName !== undefined && typeof indexedDB !== 'undefined'
                 ? localSync(persistName, { disableBc })
@@ -54,6 +54,8 @@ export const bindProviders = (Y) => {
             });
             if (onExpired)
                 provider.on('expired', (state) => onExpired(state));
+            if (access)
+                provider.on('access', access);
             provider.on('synced', (isSynced) => {
                 if (isSynced)
                     synced(provider);

package/dist/crdt/providers/room.d.ts

@@ -139,13 +139,27 @@ export type LifecycleHost = {
     _leave: () => void;
     emit?(event: 'failed', args: [unknown, unknown]): void;
 };
+/** When a subscriber of {@link onPageLeave} runs: a session's last writes, then the transports. */
+export type PageLeavePhase = 'write' | 'transport';
+/**
+ * Be told when the page leaves for good: a `pagehide` of a page the
+ * back/forward cache keeps nothing of (a kept page may come back as it was),
+ * or, in Node, the process's `exit`. One listener for the page; its
+ * subscribers run in two phases whatever order they subscribed in — a
+ * session's last writes (`write`: a history's release, `hist.release.end`)
+ * before the transports' teardown (`transport`: each provider), so those
+ * writes go out while the sockets and stores are still open (listener order
+ * on the window is registration order in Chromium, capturing or not).
+ * Returns the unsubscribe.
+ */
+export declare const onPageLeave: (fn: () => void, phase: PageLeavePhase) => (() => void);
 /**
  * Install the lifecycle on a provider: `hasSynced`, `whenSynced`, and the
  * departure announcement. `beforeunload` only announces it (`depart`): an
  * app's unsaved-changes prompt fires it and the user may stay, so the
  * provider keeps running and its presence returns at the next renewal.
- * Leaving the page (`pagehide` of a page not kept in the back/forward
- * cache; Node: `exit`) destroys the provider, whose teardown announces it.
+ * Leaving the page for good ({@link onPageLeave}'s `transport` phase)
+ * destroys the provider, whose teardown announces it.
  */
 export declare const initLifecycle: (host: LifecycleHost, destroy: () => unknown, depart?: () => void) => void;
 /** The first sync — lifetime. Returns `true` only the first time. */

package/dist/crdt/providers/room.js

@@ -45,6 +45,7 @@ import * as encoding from 'lib0-v14/encoding';
 import * as decoding from 'lib0-v14/decoding';
 import * as promise from 'lib0-v14/promise';
 import { applyAwarenessUpdate, encodeAwarenessUpdate } from '../protocols/awareness.js';
+import { callEach } from '../protocols/observable.js';
 import { BARE_REPLY_LENGTH, frame, GENERATION, writeProtocolVersion } from '../protocols/envelope.js';
 import { checkSchema, SchemaMismatchError } from '../admission.js';
 import { asEngineDoc } from '../structs.js';
@@ -205,13 +206,68 @@ export const tabs = {
 };
 /** The outbound quarantine: a read-only document does not spread. */
 export const quarantined = (doc) => checkSchema(asEngineDoc(doc)) !== null;
+/**
+ * The departures installed, by the page's `addEventListener` (one per realm
+ * in a browser; a harness simulating several pages in one realm gives each
+ * its own) or, in Node, by the process.
+ */
+const departures = new WeakMap();
+/** The page (Node: the process) leaves for good: the writes first, then the transports, each isolated. */
+const leave = (departure) => {
+    for (const phase of ['write', 'transport'])
+        callEach(`[edytor] page leave (${phase})`, [...departure.leaving[phase]]);
+};
+/**
+ * Be told when the page leaves for good: a `pagehide` of a page the
+ * back/forward cache keeps nothing of (a kept page may come back as it was),
+ * or, in Node, the process's `exit`. One listener for the page; its
+ * subscribers run in two phases whatever order they subscribed in — a
+ * session's last writes (`write`: a history's release, `hist.release.end`)
+ * before the transports' teardown (`transport`: each provider), so those
+ * writes go out while the sockets and stores are still open (listener order
+ * on the window is registration order in Chromium, capturing or not).
+ * Returns the unsubscribe.
+ */
+export const onPageLeave = (fn, phase) => {
+    const page = globalThis;
+    const proc = globalThis.process ?? {};
+    const key = page.addEventListener ?? proc;
+    let departure = departures.get(key);
+    if (departure === undefined) {
+        const created = {
+            leaving: { write: new Set(), transport: new Set() },
+            uninstall: () => { }
+        };
+        if (page.addEventListener) {
+            const hide = (event) => void (event.persisted || leave(created));
+            const remove = page.removeEventListener;
+            page.addEventListener('pagehide', hide);
+            created.uninstall = () => remove?.call(page, 'pagehide', hide);
+        }
+        else {
+            const exit = () => leave(created);
+            proc.on?.('exit', exit);
+            created.uninstall = () => proc.off?.('exit', exit);
+        }
+        departures.set(key, (departure = created));
+    }
+    const own = departure;
+    own.leaving[phase].add(fn);
+    return () => {
+        own.leaving[phase].delete(fn);
+        if (own.leaving.write.size + own.leaving.transport.size === 0 && departures.get(key) === own) {
+            own.uninstall();
+            departures.delete(key);
+        }
+    };
+};
 /**
  * Install the lifecycle on a provider: `hasSynced`, `whenSynced`, and the
  * departure announcement. `beforeunload` only announces it (`depart`): an
  * app's unsaved-changes prompt fires it and the user may stay, so the
  * provider keeps running and its presence returns at the next renewal.
- * Leaving the page (`pagehide` of a page not kept in the back/forward
- * cache; Node: `exit`) destroys the provider, whose teardown announces it.
+ * Leaving the page for good ({@link onPageLeave}'s `transport` phase)
+ * destroys the provider, whose teardown announces it.
  */
 export const initLifecycle = (host, destroy, depart = () => { }) => {
     host.hasSynced = false;
@@ -222,21 +278,12 @@ export const initLifecycle = (host, destroy, depart = () => { }) => {
     // A consumer that never attaches a catch must not crash the process.
     host.whenSynced.catch(() => { });
     const page = globalThis;
-    if (page.addEventListener) {
-        const leave = (event) => void (event.persisted || destroy());
-        page.addEventListener('beforeunload', depart);
-        page.addEventListener('pagehide', leave);
-        host._leave = () => {
-            page.removeEventListener?.('beforeunload', depart);
-            page.removeEventListener?.('pagehide', leave);
-        };
-    }
-    else {
-        const leave = () => void destroy();
-        const proc = globalThis.process ?? {};
-        proc.on?.('exit', leave);
-        host._leave = () => proc.off?.('exit', leave);
-    }
+    page.addEventListener?.('beforeunload', depart);
+    const off = onPageLeave(() => void destroy(), 'transport');
+    host._leave = () => {
+        page.removeEventListener?.('beforeunload', depart);
+        off();
+    };
 };
 /** The first sync — lifetime. Returns `true` only the first time. */
 export const markSynced = (host) => {