edytor 2.0.0 → 4.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

@@ -27,14 +27,14 @@
 export { bindCrdt, type Crdt, type EngineApi, type EngineDoc, type EngineNode, type EngineTransaction, type EngineItemRef, type YNode, type YItem, type YDoc, type YUndoManager, type YTransaction } from './index.js';
 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, ChunkLimitError, type ChunkReader, CLOSE } from './providers/room.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 { 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';
 export { writeVarUint8Array, type Encoder } from 'lib0-v14/encoding';
-export { assertAdmission, assertSchema, assertUsableDoc, checkSchema, inspectAdmission, isInitialized, registryEmpty, schemaVersion, SchemaMismatchError, UndecodableUpdateError, UnsupportedDocError, type AdmissionResult, type AdmissionVerdict, type SchemaProblem } from './admission.js';
+export { assertAdmission, assertSchema, checkSchema, inspectAdmission, isInitialized, registryEmpty, schemaVersion, SchemaMismatchError, UndecodableUpdateError, type AdmissionResult, type AdmissionVerdict, type SchemaProblem } from './admission.js';
 import type { ProviderStack } from './providers/index.js';
 export declare const IndexeddbPersistence: ProviderStack['IndexeddbPersistence'];
 export declare const WebsocketProvider: ProviderStack['WebsocketProvider'];

package/dist/crdt/protocol.js

@@ -30,7 +30,7 @@ export { bindCrdt } from './index.js';
 export { SCHEMA_VERSION, META_KEY } from './edytor-doc.js';
 export { GENERATION, generationWord, frame, PROTOCOL_VERSION, GENERATION_RECORD, GenerationMismatchError, readProtocolVersion } from './protocols/envelope.js';
 // ── Message types, acknowledgements and chunks ─────────────────────────
-export { messageSync, messageAwareness, messageAuth, messageQueryAwareness, messageSaved, messageChunk, messageComments, MAX_FRAME_BYTES, chunkFrame, createChunkReader, ChunkLimitError, CLOSE } from './providers/room.js';
+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 { commentsSubscribe, commentsSnapshot, commentsChange, writeCommentsSubscribe, writeCommentsSnapshot, writeCommentsChange, readCommentsMessage } from './protocols/comments.js';
@@ -46,7 +46,7 @@ export { writeVarUint8Array } from 'lib0-v14/encoding';
 // the matrix and the refusal-preserves-data contract). The errors they
 // throw are also exported from `edytor` and `edytor/crdt/edytor`, where a
 // `loadDocument` caller catches them.
-export { assertAdmission, assertSchema, assertUsableDoc, checkSchema, inspectAdmission, isInitialized, registryEmpty, schemaVersion, SchemaMismatchError, UndecodableUpdateError, UnsupportedDocError } from './admission.js';
+export { assertAdmission, assertSchema, checkSchema, inspectAdmission, isInitialized, registryEmpty, schemaVersion, SchemaMismatchError, UndecodableUpdateError } from './admission.js';
 // ── Raw providers ──────────────────────────────────────────────────────
 //
 // The classes `createIndexeddbSync`/`createWebsocketSync` construct, bound

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

@@ -280,7 +280,7 @@ export declare const bindProviders: (Y: EngineApi) => {
             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;
         };
     };
-    watchComments: (server: string, roomName: string, listener: (message: import("../protocol.js").CommentMessage) => void) => (() => void);
+    watchComments: (server: string | null, roomName: string, listener: (message: import("../protocol.js").CommentMessage) => void) => (() => void);
     storeState: (idbPersistence: {
         db: IDBDatabase | null;
         name: string;

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

@@ -69,14 +69,15 @@ export declare const MAX_FRAME_BYTES: number;
  * receiver applies the reassembled frame only once `end` arrives.
  */
 export declare const chunkFrame: (whole: Uint8Array, maxFrameBytes?: number) => Uint8Array[];
-/** A chunk sequence announces a frame larger than its reader takes ({@link createChunkReader}). */
-export declare class ChunkLimitError extends Error {
-    readonly total: number;
-    readonly limit: number;
-    constructor(total: number, limit: number);
-}
-/** A chunk part or end with no sequence started (one lost, or never sent). */
-export declare class ChunkSequenceError extends Error {
+/**
+ * A chunk sequence its reader refuses ({@link createChunkReader}): one
+ * announcing a frame larger than the reader takes (`total` over `limit`),
+ * or a part or end with no sequence started (one lost, or never sent).
+ */
+export declare class ChunkError extends Error {
+    readonly total?: number | undefined;
+    readonly limit?: number | undefined;
+    constructor(total?: number | undefined, limit?: number | undefined);
 }
 /** A chunk reader ({@link createChunkReader}): feed it chunk bodies; `buffered` is what it holds. */
 export type ChunkReader = {
@@ -89,7 +90,7 @@ export type ChunkReader = {
  * each chunk frame's body (after the message type); it returns the whole
  * frame on `end`, `null` before. An out-of-order or oversized sequence
  * throws and resets; a sequence announcing more than `maxBytes` throws
- * {@link ChunkLimitError} at its start, before anything is buffered. A
+ * {@link ChunkError} at its start, before anything is buffered. A
  * sequence is assembled into ONE buffer of its announced size, allocated
  * at its start (`buffered`), never into parts copied at its end.
  * `admit(total)` is asked at each start, before that allocation: it may
@@ -138,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';
@@ -92,26 +93,29 @@ export const chunkFrame = (whole, maxFrameBytes = MAX_FRAME_BYTES) => {
     frames.push(frame(messageChunk, (e) => encoding.writeVarUint(e, chunkEnd)));
     return frames;
 };
-/** A chunk sequence announces a frame larger than its reader takes ({@link createChunkReader}). */
-export class ChunkLimitError extends Error {
+/**
+ * A chunk sequence its reader refuses ({@link createChunkReader}): one
+ * announcing a frame larger than the reader takes (`total` over `limit`),
+ * or a part or end with no sequence started (one lost, or never sent).
+ */
+export class ChunkError extends Error {
     total;
     limit;
     constructor(total, limit) {
-        super(`chunked frame of ${total} bytes exceeds ${limit}`);
+        super(limit === undefined
+            ? 'chunk without a start'
+            : `chunked frame of ${total} bytes exceeds ${limit}`);
         this.total = total;
         this.limit = limit;
-        this.name = 'ChunkLimitError';
+        this.name = 'ChunkError';
     }
 }
-/** A chunk part or end with no sequence started (one lost, or never sent). */
-export class ChunkSequenceError extends Error {
-}
 /**
  * The receiving half of {@link chunkFrame}, one per connection: feed it
  * each chunk frame's body (after the message type); it returns the whole
  * frame on `end`, `null` before. An out-of-order or oversized sequence
  * throws and resets; a sequence announcing more than `maxBytes` throws
- * {@link ChunkLimitError} at its start, before anything is buffered. A
+ * {@link ChunkError} at its start, before anything is buffered. A
  * sequence is assembled into ONE buffer of its announced size, allocated
  * at its start (`buffered`), never into parts copied at its end.
  * `admit(total)` is asked at each start, before that allocation: it may
@@ -136,14 +140,14 @@ export const createChunkReader = (maxBytes = Infinity, admit = () => true) => {
                 reset();
                 const announced = decoding.readVarUint(decoder);
                 if (announced > maxBytes)
-                    throw new ChunkLimitError(announced, maxBytes);
+                    throw new ChunkError(announced, maxBytes);
                 whole = admit(announced) ? new Uint8Array(announced) : null;
                 total = announced;
                 open = true;
                 return null;
             }
             if (!open)
-                throw new ChunkSequenceError(`chunk ${kind} without a start`);
+                throw new ChunkError();
             if (kind === chunkPart) {
                 const bytes = decoding.readVarUint8Array(decoder);
                 if (received + bytes.length > total)
@@ -202,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;
@@ -219,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) => {

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

@@ -228,5 +228,5 @@ export declare const bindWebsocketProvider: (Y: EngineApi) => {
             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;
         };
     };
-    watchComments: (server: string, roomName: string, listener: (message: CommentMessage) => void) => (() => void);
+    watchComments: (server: string | null, roomName: string, listener: (message: CommentMessage) => void) => (() => void);
 };