edytor 5.0.0 → 6.0.0

package/dist/crdt/protocols/awareness.js

@@ -94,41 +94,19 @@ export class Awareness extends IsolatedObservable {
     }
     setLocalState(state) {
         const clientID = this.clientID;
-        const currLocalMeta = this.meta.get(clientID);
-        const clock = currLocalMeta === undefined ? 0 : currLocalMeta.clock + 1;
         const prevState = this.states.get(clientID);
-        if (state === null) {
-            this.states.delete(clientID);
-        }
+        put(this, clientID, (this.meta.get(clientID)?.clock ?? -1) + 1, state, time.getUnixTime());
+        const changes = noChanges();
+        if (state === null)
+            changes.removed.push(clientID);
+        else if (prevState == null)
+            changes.added.push(clientID);
         else {
-            this.states.set(clientID, state);
-        }
-        this.meta.set(clientID, {
-            clock,
-            lastUpdated: time.getUnixTime()
-        });
-        const added = [];
-        const updated = [];
-        const filteredUpdated = [];
-        const removed = [];
-        if (state === null) {
-            removed.push(clientID);
+            changes.updated.push(clientID);
+            if (!jsonEquals(prevState, state))
+                changes.changed.push(clientID);
         }
-        else if (prevState == null) {
-            if (state != null) {
-                added.push(clientID);
-            }
-        }
-        else {
-            updated.push(clientID);
-            if (!jsonEquals(prevState, state)) {
-                filteredUpdated.push(clientID);
-            }
-        }
-        if (added.length > 0 || filteredUpdated.length > 0 || removed.length > 0) {
-            this.emit('change', [{ added, updated: filteredUpdated, removed }, 'local']);
-        }
-        this.emit('update', [{ added, updated, removed }, 'local']);
+        emitChanges(this, changes, 'local', true);
     }
     setLocalStateField(field, value) {
         const state = this.getLocalState();
@@ -143,30 +121,40 @@ export class Awareness extends IsolatedObservable {
         return this.states;
     }
 }
+const noChanges = () => ({ added: [], updated: [], changed: [], removed: [] });
+/** Write client `clientID`'s `state` (`null`: removed) at `clock`, heard `now`. */
+const put = (awareness, clientID, clock, state, now) => {
+    if (state === null)
+        awareness.states.delete(clientID);
+    else
+        awareness.states.set(clientID, state);
+    awareness.meta.set(clientID, { clock, lastUpdated: now });
+};
+/**
+ * Emit a change: `change` when a client was added, removed or changed its
+ * state, `update` when one was touched at all (`always`: even when none was).
+ */
+const emitChanges = (awareness, { added, updated, changed, removed }, origin, always = false) => {
+    if (added.length > 0 || changed.length > 0 || removed.length > 0)
+        awareness.emit('change', [{ added, updated: changed, removed }, origin]);
+    if (always || added.length > 0 || updated.length > 0 || removed.length > 0)
+        awareness.emit('update', [{ added, updated, removed }, origin]);
+};
 /**
  * Mark (remote) clients as inactive and remove them from the list of active
  * peers. This change is propagated to remote clients.
  */
 export const removeAwarenessStates = (awareness, clients, origin) => {
-    const removed = [];
-    for (let i = 0; i < clients.length; i++) {
-        const clientID = clients[i];
+    const changes = noChanges();
+    for (const clientID of clients) {
         if (awareness.states.has(clientID)) {
             awareness.states.delete(clientID);
-            if (clientID === awareness.clientID) {
-                const curMeta = awareness.meta.get(clientID);
-                awareness.meta.set(clientID, {
-                    clock: curMeta.clock + 1,
-                    lastUpdated: time.getUnixTime()
-                });
-            }
-            removed.push(clientID);
+            if (clientID === awareness.clientID)
+                put(awareness, clientID, awareness.meta.get(clientID).clock + 1, null, time.getUnixTime());
+            changes.removed.push(clientID);
         }
     }
-    if (removed.length > 0) {
-        awareness.emit('change', [{ added: [], updated: [], removed }, origin]);
-        awareness.emit('update', [{ added: [], updated: [], removed }, origin]);
-    }
+    emitChanges(awareness, changes, origin);
 };
 /** The update carrying `clients`' entries of `awareness` (their states in `states`). */
 export const encodeAwarenessUpdate = (awareness, clients, states = awareness.states) => writeAwarenessEntries(clients.map((clientID) => ({
@@ -202,36 +190,19 @@ export const writeAwarenessEntries = (entries) => encoding.encode((encoder) => {
  */
 export const applyAwarenessUpdate = (awareness, update, origin) => {
     const timestamp = time.getUnixTime();
-    const added = [];
-    const updated = [];
-    const filteredUpdated = [];
-    const removed = [];
-    for (const entry of readAwarenessEntries(update)) {
-        const { clientID, state } = entry;
-        let { clock } = entry;
+    const changes = noChanges();
+    const { added, updated, changed, removed } = changes;
+    for (const { clientID, clock, state } of readAwarenessEntries(update)) {
         const clientMeta = awareness.meta.get(clientID);
         const prevState = awareness.states.get(clientID);
         const currClock = clientMeta === undefined ? 0 : clientMeta.clock;
         if (currClock < clock ||
             (currClock === clock && state === null && awareness.states.has(clientID))) {
-            if (state === null) {
-                // never let a remote client remove this local state
-                if (clientID === awareness.clientID && awareness.getLocalState() != null) {
-                    // remote client removed the local state. Do not remove state. Broadcast a message
-                    // indicating that this client still exists by increasing the clock
-                    clock++;
-                }
-                else {
-                    awareness.states.delete(clientID);
-                }
-            }
-            else {
-                awareness.states.set(clientID, state);
-            }
-            awareness.meta.set(clientID, {
-                clock,
-                lastUpdated: timestamp
-            });
+            // Never let a remote client remove this local state: keep it and
+            // broadcast that this client still exists, by increasing the clock.
+            const local = awareness.getLocalState();
+            const keep = state === null && clientID === awareness.clientID && local != null;
+            put(awareness, clientID, keep ? clock + 1 : clock, keep ? local : state, timestamp);
             if (clientMeta === undefined && state !== null) {
                 added.push(clientID);
             }
@@ -239,17 +210,11 @@ export const applyAwarenessUpdate = (awareness, update, origin) => {
                 removed.push(clientID);
             }
             else if (state !== null) {
-                if (!jsonEquals(state, prevState)) {
-                    filteredUpdated.push(clientID);
-                }
+                if (!jsonEquals(state, prevState))
+                    changed.push(clientID);
                 updated.push(clientID);
             }
         }
     }
-    if (added.length > 0 || filteredUpdated.length > 0 || removed.length > 0) {
-        awareness.emit('change', [{ added, updated: filteredUpdated, removed }, origin]);
-    }
-    if (added.length > 0 || updated.length > 0 || removed.length > 0) {
-        awareness.emit('update', [{ added, updated, removed }, origin]);
-    }
+    emitChanges(awareness, changes, origin);
 };

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

@@ -147,17 +147,12 @@ export declare const bindProviders: (Y: EngineApi) => {
             loadError: unknown;
             _storeTimeout: number;
             _storeTimeoutId: ReturnType<typeof setTimeout> | null;
-            _storeUpdate: (update: Uint8Array, origin: unknown) => void;
+            _unlisten: () => void;
             awareness: Awareness;
             bcconnected: boolean;
             disableBc: boolean;
             _ownsAwareness: boolean;
             _bcSubscriber: (data: ArrayBuffer | Uint8Array, origin: unknown) => void;
-            _awarenessUpdateHandler: (updates: {
-                added: number[];
-                updated: number[];
-                removed: number[];
-            }, origin: unknown) => void;
             get synced(): boolean;
             messageHandlers: Record<number, import("./room.js").RoomMessageHandler</*elided*/ any>>;
             readMessage: (buf: Uint8Array, emitSynced: boolean) => import("lib0-v14/encoding").Encoder;
@@ -165,7 +160,7 @@ export declare const bindProviders: (Y: EngineApi) => {
             connectBc(): void;
             disconnectBc(): void;
             destroy(): Promise<void>;
-            emit<N extends "failed" | "schema-mismatch" | "message-error" | "protocol-mismatch" | "synced" | "load-error">(name: N, args: Parameters<{
+            emit<N extends "failed" | "message-error" | "schema-mismatch" | "protocol-mismatch" | "synced" | "load-error">(name: N, args: Parameters<{
                 synced: (provider: /*elided*/ any) => void;
                 'protocol-mismatch': (mismatch: import("./room.js").ProtocolMismatch, provider: /*elided*/ any) => void;
                 'load-error': (error: unknown, provider: /*elided*/ any) => void;
@@ -174,7 +169,7 @@ export declare const bindProviders: (Y: EngineApi) => {
                 failed: (error: unknown, provider: /*elided*/ any) => void;
             }[N]>): void;
             _observers: Map<string, Set<any>>;
-            on<NAME extends "failed" | "schema-mismatch" | "message-error" | "protocol-mismatch" | "synced" | "load-error">(name: NAME, f: {
+            on<NAME extends "failed" | "message-error" | "schema-mismatch" | "protocol-mismatch" | "synced" | "load-error">(name: NAME, f: {
                 synced: (provider: /*elided*/ any) => void;
                 'protocol-mismatch': (mismatch: import("./room.js").ProtocolMismatch, provider: /*elided*/ any) => void;
                 'load-error': (error: unknown, provider: /*elided*/ any) => void;
@@ -189,7 +184,7 @@ export declare const bindProviders: (Y: EngineApi) => {
                 'schema-mismatch': (detail: import("./room.js").SchemaMismatchDetail, provider: /*elided*/ any) => void;
                 failed: (error: unknown, provider: /*elided*/ any) => void;
             }[NAME];
-            once<NAME extends "failed" | "schema-mismatch" | "message-error" | "protocol-mismatch" | "synced" | "load-error">(name: NAME, f: {
+            once<NAME extends "failed" | "message-error" | "schema-mismatch" | "protocol-mismatch" | "synced" | "load-error">(name: NAME, f: {
                 synced: (provider: /*elided*/ any) => void;
                 'protocol-mismatch': (mismatch: import("./room.js").ProtocolMismatch, provider: /*elided*/ any) => void;
                 'load-error': (error: unknown, provider: /*elided*/ any) => void;
@@ -197,7 +192,7 @@ export declare const bindProviders: (Y: EngineApi) => {
                 'schema-mismatch': (detail: import("./room.js").SchemaMismatchDetail, provider: /*elided*/ any) => void;
                 failed: (error: unknown, provider: /*elided*/ any) => void;
             }[NAME]): void;
-            off<NAME extends "failed" | "schema-mismatch" | "message-error" | "protocol-mismatch" | "synced" | "load-error">(name: NAME, f: {
+            off<NAME extends "failed" | "message-error" | "schema-mismatch" | "protocol-mismatch" | "synced" | "load-error">(name: NAME, f: {
                 synced: (provider: /*elided*/ any) => void;
                 'protocol-mismatch': (mismatch: import("./room.js").ProtocolMismatch, provider: /*elided*/ any) => void;
                 'load-error': (error: unknown, provider: /*elided*/ any) => void;
@@ -258,14 +253,7 @@ export declare const bindProviders: (Y: EngineApi) => {
             _resync: ReturnType<typeof setInterval> | undefined;
             _connectTimer: ReturnType<typeof setTimeout> | undefined;
             _checkInterval: ReturnType<typeof setInterval>;
-            _updateHandler: (update: Uint8Array, origin: unknown, doc?: unknown, transaction?: {
-                local: boolean;
-            }) => void;
-            _awarenessUpdateHandler: (updates: {
-                added: number[];
-                updated: number[];
-                removed: number[];
-            }, origin: unknown) => void;
+            _unlisten: () => void;
             get url(): string;
             get unsaved(): number;
             get saved(): boolean;
@@ -275,11 +263,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" | "access" | "connection-close" | "connection-error" | "saved" | "permission-denied" | "expired" | "unreachable">(name: N, args: Parameters<WebsocketProviderEvents[N]>): void;
+            emit<N extends "refused" | "status" | "failed" | "message-error" | "schema-mismatch" | "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" | "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;
+            on<NAME extends "refused" | "status" | "failed" | "message-error" | "schema-mismatch" | "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" | "message-error" | "schema-mismatch" | "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" | "message-error" | "schema-mismatch" | "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/indexeddb.d.ts

@@ -45,17 +45,13 @@ export declare const bindIndexeddbProvider: (Y: EngineApi) => {
             loadError: unknown;
             _storeTimeout: number;
             _storeTimeoutId: ReturnType<typeof setTimeout> | null;
-            _storeUpdate: (update: Uint8Array, origin: unknown) => void;
+            /** @internal Removes the document and presence listeners (`room.listen`). */
+            _unlisten: () => void;
             awareness: Awareness;
             bcconnected: boolean;
             disableBc: boolean;
             _ownsAwareness: boolean;
             _bcSubscriber: (data: ArrayBuffer | Uint8Array, origin: unknown) => void;
-            _awarenessUpdateHandler: (updates: {
-                added: number[];
-                updated: number[];
-                removed: number[];
-            }, origin: unknown) => void;
             /** The lifetime hydration claim. */
             get synced(): boolean;
             /**
@@ -78,7 +74,7 @@ export declare const bindIndexeddbProvider: (Y: EngineApi) => {
              * close the DB. Does NOT remove stored data — `clearDocument` does.
              */
             destroy(): Promise<void>;
-            emit<N extends "failed" | "schema-mismatch" | "message-error" | "protocol-mismatch" | "synced" | "load-error">(name: N, args: Parameters<{
+            emit<N extends "failed" | "message-error" | "schema-mismatch" | "protocol-mismatch" | "synced" | "load-error">(name: N, args: Parameters<{
                 synced: (provider: /*elided*/ any) => void;
                 'protocol-mismatch': (mismatch: ProtocolMismatch, provider: /*elided*/ any) => void;
                 /** Fired when loading persisted state failed (e.g. a generation mismatch). `whenSynced` rejects. */
@@ -101,7 +97,7 @@ export declare const bindIndexeddbProvider: (Y: EngineApi) => {
                 failed: (error: unknown, provider: /*elided*/ any) => void;
             }[N]>): void;
             _observers: Map<string, Set<any>>;
-            on<NAME extends "failed" | "schema-mismatch" | "message-error" | "protocol-mismatch" | "synced" | "load-error">(name: NAME, f: {
+            on<NAME extends "failed" | "message-error" | "schema-mismatch" | "protocol-mismatch" | "synced" | "load-error">(name: NAME, f: {
                 synced: (provider: /*elided*/ any) => void;
                 'protocol-mismatch': (mismatch: ProtocolMismatch, provider: /*elided*/ any) => void;
                 /** Fired when loading persisted state failed (e.g. a generation mismatch). `whenSynced` rejects. */
@@ -144,7 +140,7 @@ export declare const bindIndexeddbProvider: (Y: EngineApi) => {
                  */
                 failed: (error: unknown, provider: /*elided*/ any) => void;
             }[NAME];
-            once<NAME extends "failed" | "schema-mismatch" | "message-error" | "protocol-mismatch" | "synced" | "load-error">(name: NAME, f: {
+            once<NAME extends "failed" | "message-error" | "schema-mismatch" | "protocol-mismatch" | "synced" | "load-error">(name: NAME, f: {
                 synced: (provider: /*elided*/ any) => void;
                 'protocol-mismatch': (mismatch: ProtocolMismatch, provider: /*elided*/ any) => void;
                 /** Fired when loading persisted state failed (e.g. a generation mismatch). `whenSynced` rejects. */
@@ -166,7 +162,7 @@ export declare const bindIndexeddbProvider: (Y: EngineApi) => {
                  */
                 failed: (error: unknown, provider: /*elided*/ any) => void;
             }[NAME]): void;
-            off<NAME extends "failed" | "schema-mismatch" | "message-error" | "protocol-mismatch" | "synced" | "load-error">(name: NAME, f: {
+            off<NAME extends "failed" | "message-error" | "schema-mismatch" | "protocol-mismatch" | "synced" | "load-error">(name: NAME, f: {
                 synced: (provider: /*elided*/ any) => void;
                 'protocol-mismatch': (mismatch: ProtocolMismatch, provider: /*elided*/ any) => void;
                 /** Fired when loading persisted state failed (e.g. a generation mismatch). `whenSynced` rejects. */

package/dist/crdt/providers/indexeddb.js

@@ -41,7 +41,7 @@ import { IsolatedObservable } from '../protocols/observable.js';
 import { bindSync } from '../protocols/sync.js';
 import { generationDbName } from '../protocols/envelope.js';
 import { CUSTOM as customStoreName, encodeRow, lastKey, openContainer, readRow, rtop, snapshotRow, storesOf, UPDATES as updatesStoreName, verifyOrStamp } from './container.js';
-import { beginDestroy, bindRoomProtocol, tabs, emitFailed, initLifecycle, markSynced, quarantined } from './room.js';
+import { beginDestroy, bindRoomProtocol, tabs, emitFailed, fault, initLifecycle, markSynced, quarantined } from './room.js';
 export const PREFERRED_TRIM_SIZE = 500;
 /**
  * Bind the IndexedDB persistence provider to the vendored v14 engine module.
@@ -175,13 +175,13 @@ export const bindIndexeddbProvider = (Y) => {
         loadError = null;
         _storeTimeout;
         _storeTimeoutId;
-        _storeUpdate;
+        /** @internal Removes the document and presence listeners (`room.listen`). */
+        _unlisten;
         awareness;
         bcconnected = false;
         disableBc;
         _ownsAwareness;
         _bcSubscriber;
-        _awarenessUpdateHandler;
         constructor(name, doc, options = {}) {
             super();
             this.doc = doc;
@@ -196,8 +196,6 @@ export const bindIndexeddbProvider = (Y) => {
             this._db = openContainer(this.dbName);
             this.destroy = this.destroy.bind(this);
             initLifecycle(this, this.destroy, () => room.depart(this));
-            this._bcSubscriber = room.bcSubscriber(this);
-            this._awarenessUpdateHandler = room.awarenessUpdateHandler(this);
             // Fail closed: no sync, no BC room join, whenSynced rejects, and
             // the terminal 'failed' fires — the provider can never reach
             // synced once loading its persisted state has failed.
@@ -216,7 +214,7 @@ export const bindIndexeddbProvider = (Y) => {
                 // A read-only doc's pre-hydration state is never persisted.
                 const beforeApplyUpdatesCallback = (updatesStore) => {
                     if (!quarantined(doc)) {
-                        rtop(updatesStore.add(encodeRow(Y.encodeStateAsUpdate(doc)))).catch((error) => this.emit('message-error', [error, this]));
+                        rtop(updatesStore.add(encodeRow(Y.encodeStateAsUpdate(doc)))).catch((error) => fault(this, error));
                     }
                 };
                 // Hydrated: join the room and claim `synced` (lifetime).
@@ -243,7 +241,7 @@ export const bindIndexeddbProvider = (Y) => {
                 .catch(onLoadError);
             this._storeTimeout = 1000;
             this._storeTimeoutId = null;
-            this._storeUpdate = (update, origin) => {
+            const storeUpdate = (update, origin) => {
                 // Outbound quarantine: a read-only doc is never persisted
                 // (`broadcastUpdate` applies the same rule to the room).
                 if (origin === this || quarantined(doc))
@@ -253,9 +251,7 @@ export const bindIndexeddbProvider = (Y) => {
                         const [updatesStore] = storesOf(this.db, [updatesStoreName]);
                         // Storage failures must surface — never an unobserved
                         // rejection (the error channel observes every failure mode).
-                        rtop(updatesStore.add(encodeRow(update))).catch((error) => {
-                            this.emit('message-error', [error, this]);
-                        });
+                        rtop(updatesStore.add(encodeRow(update))).catch((error) => fault(this, error));
                         if (++this._dbsize >= PREFERRED_TRIM_SIZE) {
                             if (this._storeTimeoutId !== null) {
                                 clearTimeout(this._storeTimeoutId);
@@ -264,7 +260,7 @@ export const bindIndexeddbProvider = (Y) => {
                                 this._storeTimeoutId = null;
                                 // The timed caller has no promise consumer — surface
                                 // compaction/storage failures on the error channel.
-                                storeState(this, false).catch((error) => this.emit('message-error', [error, this]));
+                                storeState(this, false).catch((error) => fault(this, error));
                             }, this._storeTimeout);
                         }
                     }
@@ -272,14 +268,13 @@ export const bindIndexeddbProvider = (Y) => {
                         // A synchronous transact failure (e.g. a handle closed
                         // mid-session) still lands on the error channel rather
                         // than propagating into the doc's update dispatch.
-                        this.emit('message-error', [error, this]);
+                        fault(this, error);
                     }
                 }
                 // Broadcast the update to other tabs
                 room.broadcastUpdate(this, update);
             };
-            doc.on('update', this._storeUpdate);
-            this.awareness.on('update', this._awarenessUpdateHandler);
+            this._unlisten = room.listen(this, storeUpdate);
             const onDocDestroy = () => void this.destroy();
             destroyWithDoc.set(this, onDocDestroy);
             doc.on('destroy', onDocDestroy);
@@ -324,11 +319,10 @@ export const bindIndexeddbProvider = (Y) => {
             if (this._storeTimeoutId) {
                 clearTimeout(this._storeTimeoutId);
             }
-            this.doc.off('update', this._storeUpdate);
+            this._unlisten();
             const onDocDestroy = destroyWithDoc.get(this);
             if (onDocDestroy)
                 this.doc.off('destroy', onDocDestroy);
-            this.awareness.off('update', this._awarenessUpdateHandler);
             this.disconnectBc();
             if (this._ownsAwareness) {
                 this.awareness.destroy();

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

@@ -164,6 +164,14 @@ export declare const onPageLeave: (fn: () => void, phase: PageLeavePhase) => (()
 export declare const initLifecycle: (host: LifecycleHost, destroy: () => unknown, depart?: () => void) => void;
 /** The first sync — lifetime. Returns `true` only the first time. */
 export declare const markSynced: (host: LifecycleHost) => boolean;
+/** Report `error` on `provider`'s error channel (`'message-error'`): a frame, a payload or a storage failure. */
+export declare const fault: (provider: {
+    emit?(event: "message-error", args: [unknown, unknown]): void;
+}, error: unknown) => void;
+/** A message type no handler claims inside a valid envelope: protocol skew, reported, never dropped silently. */
+export declare const unknownType: (provider: {
+    emit?(event: "message-error", args: [unknown, unknown]): void;
+}, what: string, type: number) => void;
 /**
  * Terminal `'failed'` emission (the sync-failure contract): fires at
  * most once per provider, only while it has never synced — destroy before
@@ -298,5 +306,8 @@ export declare const bindRoomProtocol: <P extends RoomProvider<P>>(syncProtocol:
     depart: (provider: P) => void;
     connectBc: (provider: P & BcMember) => void;
     disconnectBc: (provider: P & BcMember) => void;
+    listen: (provider: P & BcMember, onUpdate: (update: Uint8Array, origin: unknown, doc?: unknown, transaction?: {
+        local: boolean;
+    }) => void) => (() => void);
 };
 export {};

package/dist/crdt/providers/room.js

@@ -293,6 +293,10 @@ export const markSynced = (host) => {
     host._settleSynced[0](host);
     return true;
 };
+/** Report `error` on `provider`'s error channel (`'message-error'`): a frame, a payload or a storage failure. */
+export const fault = (provider, error) => provider.emit?.('message-error', [error, provider]);
+/** A message type no handler claims inside a valid envelope: protocol skew, reported, never dropped silently. */
+export const unknownType = (provider, what, type) => fault(provider, new Error(`Unknown ${what} message type ${type}`));
 /**
  * Terminal `'failed'` emission (the sync-failure contract): fires at
  * most once per provider, only while it has never synced — destroy before
@@ -425,13 +429,13 @@ export const bindRoomProtocol = (syncProtocol, behavior) => {
                 // (`discarded`) and reported the same way.
                 const update = decoding.readVarUint8Array(decoder);
                 const origin = emitSynced ? provider : (behavior.tabOrigin?.(provider) ?? provider);
-                const onError = (error) => provider.emit?.('message-error', [error, provider]);
+                const onError = (error) => fault(provider, error);
                 const { applied, problem, discarded } = syncProtocol.applyRemote(provider.doc, update, origin, onError);
                 const refused = problem ?? discarded;
                 if (refused) {
                     const docName = behavior.docName(provider);
                     provider.emit?.('schema-mismatch', [{ docName, problem: refused }, provider]);
-                    provider.emit?.('message-error', [new SchemaMismatchError(docName, refused), provider]);
+                    fault(provider, new SchemaMismatchError(docName, refused));
                 }
                 // Only an ACCEPTED Step2 is a held member state — a refused
                 // one never claims the handshake.
@@ -441,10 +445,7 @@ export const bindRoomProtocol = (syncProtocol, behavior) => {
                 return;
             }
             // Unknown sync subtype inside a valid envelope — observable.
-            provider.emit?.('message-error', [
-                new Error(`Unknown sync message type ${syncMessageType}`),
-                provider
-            ]);
+            unknownType(provider, 'sync', syncMessageType);
         },
         [messageQueryAwareness]: (encoder, _decoder, provider) => {
             encoding.writeVarUint(encoder, messageAwareness);
@@ -477,10 +478,7 @@ export const bindRoomProtocol = (syncProtocol, behavior) => {
         if (!messageHandler) {
             // Fail closed + observable: a VALID envelope carrying a message
             // type no handler claims is protocol skew — never silent.
-            provider.emit?.('message-error', [
-                new Error(`Unknown v14 message type ${messageType}`),
-                provider
-            ]);
+            unknownType(provider, 'v14', messageType);
             return encoder;
         }
         const followUp = messageHandler(encoder, decoder, provider, emitSynced);
@@ -503,7 +501,7 @@ export const bindRoomProtocol = (syncProtocol, behavior) => {
             catch (error) {
                 // same-tab publishes are delivered synchronously — a malformed
                 // message must not propagate into the publisher's call stack.
-                provider.emit?.('message-error', [error, provider]);
+                fault(provider, error);
             }
         };
     };
@@ -554,6 +552,21 @@ export const bindRoomProtocol = (syncProtocol, behavior) => {
     };
     /** The departure announcement — our presence, removed — on every transport the provider speaks. */
     const depart = (provider) => behavior.broadcast(provider, awarenessFrame(provider.awareness, [provider.doc.clientID], new Map()));
+    /**
+     * Wire `provider` to its room: its BroadcastChannel subscriber, `onUpdate`
+     * on its document's updates and its presence changes to the room
+     * (`awarenessUpdateHandler`). The teardown removes both listeners.
+     */
+    const listen = (provider, onUpdate) => {
+        provider._bcSubscriber = bcSubscriber(provider);
+        const onPresence = awarenessUpdateHandler(provider);
+        provider.doc.on('update', onUpdate);
+        provider.awareness.on('update', onPresence);
+        return () => {
+            provider.awareness.off('update', onPresence);
+            provider.doc.off('update', onUpdate);
+        };
+    };
     /** Leave the room: announce the presence removal, then unsubscribe the BC channel. */
     const disconnectBc = (provider) => {
         depart(provider);
@@ -572,6 +585,7 @@ export const bindRoomProtocol = (syncProtocol, behavior) => {
         hello,
         depart,
         connectBc,
-        disconnectBc
+        disconnectBc,
+        listen
     };
 };

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

@@ -185,14 +185,8 @@ export declare const bindWebsocketProvider: (Y: EngineApi) => {
             /** Closes the current dial if it has not opened in time. */
             _connectTimer: ReturnType<typeof setTimeout> | undefined;
             _checkInterval: ReturnType<typeof setInterval>;
-            _updateHandler: (update: Uint8Array, origin: unknown, doc?: unknown, transaction?: {
-                local: boolean;
-            }) => void;
-            _awarenessUpdateHandler: (updates: {
-                added: number[];
-                updated: number[];
-                removed: number[];
-            }, origin: unknown) => void;
+            /** @internal Removes the document and presence listeners (`room.listen`). */
+            _unlisten: () => void;
             /**
              * The dial URL: the room name as one encoded path segment (any id —
              * `/`, `%`, `#`, `?` included — reaches its own room; the server
@@ -223,11 +217,11 @@ export declare const bindWebsocketProvider: (Y: EngineApi) => {
             destroy(): void;
             disconnect(): void;
             connect(): 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;
+            emit<N extends "refused" | "status" | "failed" | "message-error" | "schema-mismatch" | "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" | "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;
+            on<NAME extends "refused" | "status" | "failed" | "message-error" | "schema-mismatch" | "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" | "message-error" | "schema-mismatch" | "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" | "message-error" | "schema-mismatch" | "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: CommentMessage) => void) => (() => void);