edytor 1.0.0-rc.2 → 1.0.0

package/dist/crdt/protocols/sync.js

@@ -7,38 +7,28 @@
  * (`applyRemote`) and are stamped with a non-null `remoteApplyOrigin` so
  * echo suppression + undo exclusion keep working.
  *
- * Wire format (y-protocols' layout; SyncStep2 in the v2 encoding since
- * schema generation 5):
+ * Wire format (y-protocols' layout; every update in the engine's one
+ * encoding, the columnar one upstream calls v2, since schema generation 6):
  *
  * ```
  *   varuint messageType | payload
  *   messageType 0 (SyncStep1):   varuint8array stateVector
- *   messageType 1 (SyncStep2):   varuint8array update (v2, columnar)
- *   messageType 2 (Update):      varuint8array update (v1)
+ *   messageType 1 (SyncStep2):   varuint8array update
+ *   messageType 2 (Update):      varuint8array update
  * ```
  *
- * A SyncStep2 carries a state — a document's or what a peer lacks — and
- * the v2 encoding is smaller on any such batch (a 1,000-block document:
- * 280,557 → 220,444 bytes, gzip 55,016 → 28,476). An Update carries one
- * transaction, and v1 is smaller for most of those (a one-character
- * delete 13 vs 24 bytes, a block move 62 vs 84, a block delete 43 vs 65),
- * so updates stay v1: what the engine emits on `doc.on('update')` is
- * relayed as it is. A receiver converts a SyncStep2 to v1
- * ({@link step2Update}) and applies it through the one inbound path. That does NOT mean v13 and v14 peers are interchangeable — the
- * provider layer (`providers/*`) wraps every message in the protocol-version
- * envelope (`protocols/envelope.ts`) so engines that do not speak v14 never
- * reach `readSyncMessage`.
+ * What the engine emits on `doc.on('update')` is relayed as it is, and a
+ * SyncStep2 is applied through the same inbound path as an Update. That
+ * does NOT mean v13 and v14 peers are interchangeable — the provider layer
+ * (`providers/*`) wraps every message in the protocol-version envelope
+ * (`protocols/envelope.ts`) so engines that do not speak v14 never reach
+ * {@link applyRemote}.
  *
- * API boundary — two tiers:
- *
- * - RAW readers (`readSyncStep1`, `readSyncStep2`, `readUpdate`,
- *   `readSyncMessage`) apply through the inbound refusal but report
- *   nothing, and `readSyncMessage` THROWS on an unknown message type. They
- *   exist for harnesses/custom transports; the shipped providers do not
- *   route room traffic through them.
- * - The path the providers use lives in `providers/room.ts`:
- *   `applyRemote` + per-type dispatch, so a refused payload never mutates
- *   the live doc and an unknown type is a reported drop, not a throw.
+ * One inbound path: every payload a client or a server receives applies
+ * through `applyRemote`, which refuses a forged schema stamp before
+ * anything integrates; the providers dispatch by message type in
+ * `providers/room.ts` (an unknown type is a reported drop), the room in
+ * `cloudflare/room/admission.ts`.
  *
  * Engine functions are injected (`bindSync(Y)`): `src/lib` never
  * runtime-imports the vendored `.js` (see `engine-api.ts`), so the caller
@@ -55,7 +45,7 @@ import { asEngineDoc, attrItems } from '../structs.js';
  * is optional). Remote integration MUST always arrive under a non-null,
  * non-tracked origin:
  *
- * - history capture (`document.history` / `Y.UndoManager`) keeps
+ * - history capture (`document.history`, edytor's undo manager) keeps
  *   untracked, non-local transactions out of the local undo stack — a
  *   `null` origin is ambiguous (it is also the untyped-local marker), so
  *   an explicit marker documents intent for `doc.on('update')`
@@ -73,6 +63,12 @@ const defaultRemoteApplyOrigin = () => Symbol('edytor-remote-apply');
 export const messageYjsSyncStep1 = 0;
 export const messageYjsSyncStep2 = 1;
 export const messageYjsUpdate = 2;
+/** An inbound update that could not be read or applied: its handler hears it, the console shows it. */
+const reportUpdateError = (error, errorHandler) => {
+    if (errorHandler != null)
+        errorHandler(error);
+    console.error('Caught error while handling a Yjs update', error);
+};
 /**
  * Bind the sync protocol to a concrete engine module (the vendored v14 `Y`).
  */
@@ -85,29 +81,7 @@ export const bindSync = (Y) => {
     };
     const writeSyncStep2 = (encoder, doc, encodedStateVector) => {
         encoding.writeVarUint(encoder, messageYjsSyncStep2);
-        encoding.writeVarUint8Array(encoder, Y.encodeStateAsUpdateV2(doc, encodedStateVector));
-    };
-    /** A SyncStep2 payload (v2) as the v1 update every inbound path applies. */
-    const step2Update = (payload) => Y.convertUpdateFormatV2ToV1(payload);
-    /** Read SyncStep1 message and reply with SyncStep2. */
-    const readSyncStep1 = (decoder, encoder, doc) => writeSyncStep2(encoder, doc, decoding.readVarUint8Array(decoder));
-    /**
-     * Read and apply structs + delete set to a doc — through the same
-     * inbound refusal as the providers ({@link applyRemote}), which report
-     * a refused stamp; this raw reader reports only decode/apply errors.
-     */
-    const readSyncStep2 = (decoder, doc, transactionOrigin, errorHandler) => {
-        let update;
-        try {
-            update = step2Update(decoding.readVarUint8Array(decoder));
-        }
-        catch (error) {
-            if (errorHandler != null)
-                errorHandler(error);
-            console.error('Caught error while handling a Yjs update', error);
-            return;
-        }
-        applyRemote(doc, update, transactionOrigin, errorHandler);
+        encoding.writeVarUint8Array(encoder, Y.encodeStateAsUpdate(doc, encodedStateVector));
     };
     /**
      * The state-vector coverage test of the join rule: does the encoded
@@ -125,10 +99,6 @@ export const bindSync = (Y) => {
         encoding.writeVarUint(encoder, messageYjsUpdate);
         encoding.writeVarUint8Array(encoder, update);
     };
-    /** Read and apply an Update (v1) through the inbound refusal. */
-    const readUpdate = (decoder, doc, transactionOrigin, errorHandler) => {
-        applyRemote(doc, decoding.readVarUint8Array(decoder), transactionOrigin, errorHandler);
-    };
     /**
      * Inbound refusal: the schema problem `parts` (decoded updates,
      * judged together) would write, or `null`. The frame already proved its
@@ -193,7 +163,7 @@ export const bindSync = (Y) => {
     /** What the engine holds pending on `doc` (structs and deletes waiting for a dependency). */
     const held = (doc) => {
         const pending = [doc.store.pendingStructs?.update, doc.store.pendingDs];
-        return pending.flatMap((bytes) => (bytes ? [Y.decodeUpdateV2(bytes)] : []));
+        return pending.flatMap((bytes) => (bytes ? [Y.decodeUpdate(bytes)] : []));
     };
     /**
      * Apply one inbound update (SyncStep2 / Update payload) to the live doc
@@ -230,9 +200,7 @@ export const bindSync = (Y) => {
                 : { applied: true, problem: null, discarded };
         }
         catch (error) {
-            if (errorHandler != null)
-                errorHandler(error);
-            console.error('Caught error while handling a Yjs update', error);
+            reportUpdateError(error, errorHandler);
             return { applied: false, problem: null };
         }
     };
@@ -248,12 +216,12 @@ export const bindSync = (Y) => {
      * vector alone ignores the second field; a body without it acknowledges
      * no deletes.
      */
-    const writeSaved = (encoder, doc, deletes, unstored = doc.store.pendingDs && Y.decodeUpdateV2(doc.store.pendingDs).ds) => {
+    const writeSaved = (encoder, doc, deletes, unstored = doc.store.pendingDs && Y.decodeUpdate(doc.store.pendingDs).ds) => {
         encoding.writeVarUint8Array(encoder, Y.encodeStateVector(doc));
         const held = deletes && unstored ? Y.diffIdSet(deletes, unstored) : deletes;
         if (!held || held.isEmpty())
             return;
-        const body = new Y.UpdateEncoderV1();
+        const body = new Y.UpdateEncoder();
         encoding.writeVarUint(body.restEncoder, 0); // no structs
         Y.writeIdSet(body, held);
         encoding.writeVarUint8Array(encoder, body.toUint8Array());
@@ -265,31 +233,6 @@ export const bindSync = (Y) => {
             ? Y.decodeUpdate(decoding.readVarUint8Array(decoder)).ds
             : null
     });
-    /**
-     * Read a sync message from `decoder`; writes any reply (SyncStep2) into
-     * `encoder`. Returns the decoded message type. Callers MUST gate the
-     * protocol-version envelope before invoking this (see `envelope.ts`).
-     * RAW: payloads apply through the inbound refusal (unreported) and an
-     * unknown message type THROWS — the shipped providers dispatch through
-     * `providers/room.ts` (`applyRemote` + reported drops) instead.
-     */
-    const readSyncMessage = (decoder, encoder, doc, transactionOrigin, errorHandler) => {
-        const messageType = decoding.readVarUint(decoder);
-        switch (messageType) {
-            case messageYjsSyncStep1:
-                readSyncStep1(decoder, encoder, doc);
-                break;
-            case messageYjsSyncStep2:
-                readSyncStep2(decoder, doc, transactionOrigin, errorHandler);
-                break;
-            case messageYjsUpdate:
-                readUpdate(decoder, doc, transactionOrigin, errorHandler);
-                break;
-            default:
-                throw new Error('Unknown message type');
-        }
-        return messageType;
-    };
     return {
         messageYjsSyncStep1,
         messageYjsSyncStep2,
@@ -297,12 +240,7 @@ export const bindSync = (Y) => {
         remoteApplyOrigin,
         writeSyncStep1,
         writeSyncStep2,
-        step2Update,
-        readSyncStep1,
-        readSyncStep2,
         writeUpdate,
-        readUpdate,
-        readSyncMessage,
         applyRemote,
         lacks,
         writeSaved,

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

@@ -1,2 +1,4 @@
-import { type ProviderStack } from './index.js';
+import { type PrefetchOptions, type ProviderStack } from './index.js';
 export declare const providers: ProviderStack;
+/** {@link prefetchWith} over the one stack. */
+export declare const prefetch: (options: PrefetchOptions) => Promise<import("./index.js").PrefetchResult>;

package/dist/crdt/providers/bound.js

@@ -5,5 +5,7 @@
  * `instanceof` holds whichever entry point a consumer imported it from.
  */
 import { Y } from '../engine.js';
-import { bindProviders } from './index.js';
+import { bindProviders, prefetchWith } from './index.js';
 export const providers = bindProviders(Y);
+/** {@link prefetchWith} over the one stack. */
+export const prefetch = (options) => prefetchWith(Y, providers, options);

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

@@ -1,25 +1,19 @@
 export declare const UPDATES = "updates";
 export declare const CUSTOM = "custom";
-/** Open (creating when absent) a container with its two stores. */
+/** A request's result, as a promise (its failure as an `Error`). */
+export declare const rtop: <T>(request: IDBRequest<T>) => Promise<T>;
+/** The stores `names` of one read-write transaction on `db`. */
+export declare const storesOf: (db: IDBDatabase, names: string[]) => IDBObjectStore[];
+/** The greatest key of `store` (`null` when it is empty). */
+export declare const lastKey: (store: IDBObjectStore) => Promise<IDBValidKey | null>;
+/** Open (creating when absent) a container with its two stores; it closes when another version opens. */
 export declare const openContainer: (dbName: string) => Promise<IDBDatabase>;
 /** A row is the update's bytes in a buffer of their own. */
 export declare const encodeRow: (update: Uint8Array) => ArrayBuffer;
-export declare const decodeRow: (row: unknown) => Uint8Array;
-/**
- * A snapshot row (storage `'v2'`): the document in the v2 encoding,
- * gzip-compressed where the platform has `CompressionStream` (and that
- * makes it smaller). Update rows stay v1 `ArrayBuffer`s. A build from
- * before the v2 snapshots reads such a row as no update at all (`decodeRow` throws),
- * so it fails to load the store instead of misreading it.
- */
-export type SnapshotRow = {
-    v2: ArrayBuffer;
-};
-export declare const snapshotRow: (updateV2: Uint8Array) => Promise<SnapshotRow>;
-/** A stored row as the update to apply: `{ v2 }` for a snapshot row (inflated). */
-export declare const readRow: (row: unknown) => Promise<Uint8Array | {
-    v2: Uint8Array;
-}>;
+/** A snapshot row: the document's state, gzip-compressed where that makes it smaller. */
+export declare const snapshotRow: (update: Uint8Array) => Promise<ArrayBuffer>;
+/** A stored row as the update to apply (a compressed snapshot inflated). */
+export declare const readRow: (row: unknown) => Promise<Uint8Array>;
 /**
  * The one verify-or-stamp rule: a container carrying this generation's
  * record passes; an EMPTY container without a record is stamped; anything

package/dist/crdt/providers/container.js

@@ -1,38 +1,50 @@
 /**
  * The v14 IndexedDB container — one owner for the store names, the row
- * codec (v1 update rows, v2 snapshot rows: `room.store.v2`), the open, the non-creating probe and the ONE verify-or-stamp rule,
- * shared by the provider and the migrator. Rows are append-only for every
+ * codec (every row an update in the engine's one encoding, a snapshot
+ * gzip-compressed where that makes it smaller), the open, the non-creating
+ * probe and the ONE verify-or-stamp rule. Rows are append-only for every
  * writer (a provider's compaction appends its snapshot before deleting the
  * rows it subsumes).
  */
-import * as idb from 'lib0-v14/indexeddb';
-import { GENERATION_KEY, GenerationMismatchError, isGenerationRecord, STORED_GENERATION_RECORD } from '../protocols/envelope.js';
+import { GENERATION_KEY, GenerationMismatchError, GENERATION_RECORD, isGenerationRecord } from '../protocols/envelope.js';
 import { gunzip, packed } from '../storage.js';
 export const UPDATES = 'updates';
 export const CUSTOM = 'custom';
-/** Open (creating when absent) a container with its two stores. */
-export const openContainer = (dbName) => idb.openDB(dbName, (db) => idb.createStores(db, [[UPDATES, { autoIncrement: true }], [CUSTOM]]));
-/** A row is the update's bytes in a buffer of their own. */
-export const encodeRow = (update) => update.slice().buffer;
-export const decodeRow = (row) => {
-    if (row instanceof ArrayBuffer)
-        return new Uint8Array(row);
-    if (row instanceof Uint8Array)
-        return row;
-    throw new TypeError('Stored Yjs update is not binary data');
+/** A request's result, as a promise (its failure as an `Error`). */
+export const rtop = (request) => new Promise((resolve, reject) => {
+    request.onerror = () => reject(new Error(String(request.error)));
+    request.onsuccess = () => resolve(request.result);
+});
+/** The stores `names` of one read-write transaction on `db`. */
+export const storesOf = (db, names) => {
+    const transaction = db.transaction(names, 'readwrite');
+    return names.map((name) => transaction.objectStore(name));
 };
-export const snapshotRow = async (updateV2) => ({
-    v2: (await packed(updateV2)).slice().buffer
+/** The greatest key of `store` (`null` when it is empty). */
+export const lastKey = (store) => rtop(store.openKeyCursor(null, 'prev')).then((cursor) => cursor?.key ?? null);
+/** Open (creating when absent) a container with its two stores; it closes when another version opens. */
+export const openContainer = (dbName) => new Promise((resolve, reject) => {
+    const request = indexedDB.open(dbName);
+    request.onupgradeneeded = () => {
+        request.result.createObjectStore(UPDATES, { autoIncrement: true });
+        request.result.createObjectStore(CUSTOM);
+    };
+    request.onerror = () => reject(request.error);
+    request.onsuccess = () => {
+        const db = request.result;
+        db.onversionchange = () => db.close();
+        resolve(db);
+    };
 });
-/** A stored row as the update to apply: `{ v2 }` for a snapshot row (inflated). */
+/** A row is the update's bytes in a buffer of their own. */
+export const encodeRow = (update) => update.slice().buffer;
+/** A snapshot row: the document's state, gzip-compressed where that makes it smaller. */
+export const snapshotRow = async (update) => encodeRow(await packed(update));
+/** A stored row as the update to apply (a compressed snapshot inflated). */
 export const readRow = async (row) => {
-    if (typeof row === 'object' && row !== null && 'v2' in row) {
-        const bytes = row.v2;
-        if (!(bytes instanceof ArrayBuffer))
-            throw new TypeError('Stored snapshot is not binary data');
-        return { v2: await gunzip(new Uint8Array(bytes)) };
-    }
-    return decodeRow(row);
+    if (!(row instanceof ArrayBuffer))
+        throw new TypeError('Stored Yjs update is not binary data');
+    return gunzip(new Uint8Array(row));
 };
 /**
  * The one verify-or-stamp rule: a container carrying this generation's
@@ -41,9 +53,9 @@ export const readRow = async (row) => {
  * {@link GenerationMismatchError} — nothing inside a row is inspected.
  */
 export const verifyOrStamp = async (name, updates, custom) => {
-    const found = await idb.get(custom, GENERATION_KEY);
-    if (found === undefined && (await idb.count(updates)) === 0) {
-        await idb.rtop(custom.put({ ...STORED_GENERATION_RECORD }, GENERATION_KEY));
+    const found = await rtop(custom.get(GENERATION_KEY));
+    if (found === undefined && (await rtop(updates.count())) === 0) {
+        await rtop(custom.put({ ...GENERATION_RECORD }, GENERATION_KEY));
     }
     else if (!isGenerationRecord(found)) {
         throw new GenerationMismatchError(name, found);

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

@@ -127,9 +127,6 @@ export type LastUpdatedOptions = WebsocketTarget & {
 };
 export type ProviderStack = ReturnType<typeof bindProviders>;
 export declare const bindProviders: (Y: EngineApi) => {
-    prefetch: (options: PrefetchOptions) => Promise<PrefetchResult>;
-    lastUpdated: (options: LastUpdatedOptions) => Promise<number | null>;
-    documentSnapshot: (options: LastUpdatedOptions) => Promise<JSONDoc | null>;
     IndexeddbPersistence: {
         new (name: string, doc: YDoc, options?: import("./indexeddb.js").IndexeddbPersistenceOptions): {
             doc: YDoc;
@@ -153,7 +150,7 @@ export declare const bindProviders: (Y: EngineApi) => {
             bcconnected: boolean;
             disableBc: boolean;
             _ownsAwareness: boolean;
-            _bcSubscriber: (data: ArrayBuffer, origin: unknown) => void;
+            _bcSubscriber: (data: ArrayBuffer | Uint8Array, origin: unknown) => void;
             _awarenessUpdateHandler: (updates: {
                 added: number[];
                 updated: number[];
@@ -225,7 +222,7 @@ export declare const bindProviders: (Y: EngineApi) => {
             bcChannel: string;
             bcconnected: boolean;
             disableBc: boolean;
-            _bcSubscriber: (data: ArrayBuffer, origin: unknown) => void;
+            _bcSubscriber: (data: ArrayBuffer | Uint8Array, origin: unknown) => void;
             _fromTab: {};
             wsUnsuccessfulReconnects: number;
             wsLastMessageReceived: number;
@@ -292,9 +289,40 @@ export declare const bindProviders: (Y: EngineApi) => {
         _dbsize: number;
         _destroyed: boolean;
     }, forceStore?: boolean) => Promise<undefined>;
-    clearDocument: (name: string) => Promise<any>;
+    clearDocument: (name: string) => Promise<void>;
     PREFERRED_TRIM_SIZE: number;
     createIndexeddbSync: (name: string) => EdytorSync;
     createWebsocketSync: (options: WebsocketSyncOptions) => WebsocketSync;
 };
 export type { IndexeddbProvider };
+/**
+ * `[serverUrl (no trailing slash), room]` of a target, the room id checked.
+ * The target is `{ server, room }`; the names before them are refused, in
+ * a message that names the `caller` it was passed to.
+ */
+export declare const targetOf: (caller: string, options: WebsocketTarget) => [string, string];
+/**
+ * Keep a document fresh without opening it: load its local store
+ * (the one `createWebsocketSync` keeps, `edytor:<server>/<room>` unless
+ * `persistName` names another), dial the room once, take what it lacks
+ * and hand it what the store holds that the room lacks, wait until the
+ * room stored it, then close. Resolves with whether the room sent
+ * anything new; rejects with the room's refusal (`SyncRefusedError`),
+ * after `timeout`, or where there is no IndexedDB. Over the provider
+ * classes of `stack` (bound to `Y`).
+ */
+export declare const prefetchWith: (Y: EngineApi, stack: ProviderStack, options: PrefetchOptions) => Promise<PrefetchResult>;
+/**
+ * When the room last stored a change (ms since the epoch), or `null`:
+ * `?lastUpdated`, answered without opening the document. Compare it with
+ * when a document was last fetched to decide whether to `prefetch` it.
+ * Throws on an HTTP error (`403` refused, `401` expired).
+ */
+export declare const lastUpdated: (options: LastUpdatedOptions) => Promise<number | null>;
+/**
+ * The room's document as JSON, or `null` when it stores nothing yet:
+ * `?snapshot`, answered from the room's live document. Show it while a
+ * view's own copy hydrates: `<Edytor snapshot>`. Throws on an HTTP error
+ * (`403` refused, `401` expired).
+ */
+export declare const documentSnapshot: (options: LastUpdatedOptions) => Promise<JSONDoc | null>;

package/dist/crdt/providers/index.js

@@ -13,8 +13,8 @@ export const bindProviders = (Y) => {
             provider.on('failed', failed);
         return () => provider.destroy();
     }, { bound: Infinity, target: `indexeddb:${name}` });
-    /** A document stored only here: a generation-4 store of `name` converts into it (the cutover). */
-    const createIndexeddbSync = (name) => localSync(name, { convertPrevious: true });
+    /** A document stored only here. */
+    const createIndexeddbSync = (name) => localSync(name);
     /**
      * The socket, and by default a local store beside it. The store is its
      * own provider on the document (`attach`), so the document's readiness
@@ -107,116 +107,7 @@ export const bindProviders = (Y) => {
         };
         return Object.assign(sync, { bound: Infinity, target: `websocket:${room}`, persistName });
     };
-    /**
-     * `[serverUrl (no trailing slash), room]` of a target, the room id checked.
-     * The target is `{ server, room }`; the names before them are refused, in
-     * a message that names the `caller` it was passed to.
-     */
-    const targetOf = (caller, options) => {
-        const { server, room } = options;
-        if (typeof server !== 'string' || typeof room !== 'string')
-            throw new TypeError(`${caller}: the target is \`server\` and \`room\` (\`serverUrl\` and \`roomName\` are gone)`);
-        assertRoomId(room);
-        return [server.replace(/\/+$/, ''), room];
-    };
-    /**
-     * Keep a document fresh without opening it: load its local store
-     * (the one `createWebsocketSync` keeps, `edytor:<server>/<room>` unless
-     * `persistName` names another), dial the room once, take what it lacks
-     * and hand it what the store holds that the room lacks, wait until the
-     * room stored it, then close. Resolves with whether the room sent
-     * anything new; rejects with the room's refusal (`SyncRefusedError`),
-     * after `timeout`, or where there is no IndexedDB.
-     */
-    const prefetch = (options) => {
-        const [serverUrl, room] = targetOf('prefetch', options);
-        if (typeof indexedDB === 'undefined') {
-            return Promise.reject(new TypeError('prefetch needs IndexedDB to keep the document'));
-        }
-        const doc = keepingReplaced(new Y.Doc());
-        const local = new idb.IndexeddbPersistence(options.persistName ?? `edytor:${serverUrl}/${room}`, doc, { disableBc: true });
-        let socket = null;
-        /** Prefetch's one timer: its deadline (`timeout`), cleared when it closes. */
-        let deadline;
-        const close = async () => {
-            clearTimeout(deadline);
-            socket?.destroy();
-            await local.destroy();
-            doc.destroy();
-        };
-        return new Promise((resolve, reject) => {
-            const fail = (error) => void close().then(() => reject(error));
-            deadline = setTimeout(() => fail(new Error(`prefetch of ${room} timed out`)), options.timeout ?? 30_000);
-            local.whenSynced.then(() => {
-                const before = Y.encodeStateVector(doc);
-                const provider = (socket = new ws.WebsocketProvider(serverUrl, room, doc, {
-                    params: options.params,
-                    WebSocketPolyfill: options.WebSocketPolyfill,
-                    maxBackoffTime: options.maxBackoffTime,
-                    connectTimeout: options.connectTimeout,
-                    maxFrameBytes: options.maxFrameBytes,
-                    disableBc: true
-                }));
-                // A prefetch is nobody's presence.
-                provider.awareness.setLocalState(null);
-                const done = () => {
-                    if (!provider.synced || !provider.saved)
-                        return;
-                    const after = Y.encodeStateVector(doc);
-                    const updated = after.length !== before.length || after.some((b, i) => b !== before[i]);
-                    void close().then(() => resolve({ updated }));
-                };
-                provider.on('synced', done);
-                provider.on('saved', done);
-                provider.on('refused', (refusal) => fail(refusal));
-                done();
-            }, fail);
-        });
-    };
-    /**
-     * When the room last stored a change (ms since the epoch), or `null`:
-     * one authorized HTTP `GET <server>/<room>?lastUpdated`, which
-     * `routeDocumentSocket` answers without opening the document. Compare
-     * it with when a document was last fetched to decide whether to
-     * `prefetch` it. Throws on an HTTP error (`403` refused, `401` expired).
-     */
-    const lastUpdated = async (options) => {
-        const [serverUrl, room] = targetOf('lastUpdated', options);
-        const url = new URL(`${serverUrl.replace(/^ws/, 'http')}/${encodeURIComponent(room)}`);
-        for (const [key, value] of Object.entries(options.params ?? {}))
-            url.searchParams.set(key, value);
-        url.searchParams.set('lastUpdated', '1');
-        const response = await (options.fetch ?? fetch)(url.toString());
-        if (!response.ok) {
-            throw new Error(`lastUpdated of ${room}: ${response.status} ${await response.text()}`);
-        }
-        const { lastUpdated: at } = (await response.json());
-        return typeof at === 'number' ? at : null;
-    };
-    /**
-     * The room's document as JSON, or `null` when it stores nothing yet:
-     * one authorized HTTP `GET <server>/<room>?snapshot`, which
-     * `routeDocumentSocket` answers from the room's live document. Show it
-     * while a view's own copy hydrates: `<Edytor snapshot>`. Throws on an
-     * HTTP error (`403` refused, `401` expired).
-     */
-    const documentSnapshot = async (options) => {
-        const [serverUrl, room] = targetOf('documentSnapshot', options);
-        const url = new URL(`${serverUrl.replace(/^ws/, 'http')}/${encodeURIComponent(room)}`);
-        for (const [key, value] of Object.entries(options.params ?? {}))
-            url.searchParams.set(key, value);
-        url.searchParams.set('snapshot', '1');
-        const response = await (options.fetch ?? fetch)(url.toString());
-        if (!response.ok) {
-            throw new Error(`snapshot of ${room}: ${response.status} ${await response.text()}`);
-        }
-        const { lastUpdated: at, document } = (await response.json());
-        return typeof at === 'number' ? document : null;
-    };
     return {
-        prefetch,
-        lastUpdated,
-        documentSnapshot,
         IndexeddbPersistence: idb.IndexeddbPersistence,
         WebsocketProvider: ws.WebsocketProvider,
         watchComments: ws.watchComments,
@@ -227,3 +118,107 @@ export const bindProviders = (Y) => {
         createWebsocketSync
     };
 };
+/**
+ * `[serverUrl (no trailing slash), room]` of a target, the room id checked.
+ * The target is `{ server, room }`; the names before them are refused, in
+ * a message that names the `caller` it was passed to.
+ */
+export const targetOf = (caller, options) => {
+    const { server, room } = options;
+    if (typeof server !== 'string' || typeof room !== 'string')
+        throw new TypeError(`${caller}: the target is \`server\` and \`room\``);
+    assertRoomId(room);
+    return [server.replace(/\/+$/, ''), room];
+};
+/**
+ * Keep a document fresh without opening it: load its local store
+ * (the one `createWebsocketSync` keeps, `edytor:<server>/<room>` unless
+ * `persistName` names another), dial the room once, take what it lacks
+ * and hand it what the store holds that the room lacks, wait until the
+ * room stored it, then close. Resolves with whether the room sent
+ * anything new; rejects with the room's refusal (`SyncRefusedError`),
+ * after `timeout`, or where there is no IndexedDB. Over the provider
+ * classes of `stack` (bound to `Y`).
+ */
+export const prefetchWith = (Y, stack, options) => {
+    const [serverUrl, room] = targetOf('prefetch', options);
+    if (typeof indexedDB === 'undefined') {
+        return Promise.reject(new TypeError('prefetch needs IndexedDB to keep the document'));
+    }
+    const doc = keepingReplaced(new Y.Doc());
+    const local = new stack.IndexeddbPersistence(options.persistName ?? `edytor:${serverUrl}/${room}`, doc, { disableBc: true });
+    let socket = null;
+    /** Prefetch's one timer: its deadline (`timeout`), cleared when it closes. */
+    let deadline;
+    const close = async () => {
+        clearTimeout(deadline);
+        socket?.destroy();
+        await local.destroy();
+        doc.destroy();
+    };
+    return new Promise((resolve, reject) => {
+        const fail = (error) => void close().then(() => reject(error));
+        deadline = setTimeout(() => fail(new Error(`prefetch of ${room} timed out`)), options.timeout ?? 30_000);
+        local.whenSynced.then(() => {
+            const before = Y.encodeStateVector(doc);
+            const provider = (socket = new stack.WebsocketProvider(serverUrl, room, doc, {
+                params: options.params,
+                WebSocketPolyfill: options.WebSocketPolyfill,
+                maxBackoffTime: options.maxBackoffTime,
+                connectTimeout: options.connectTimeout,
+                maxFrameBytes: options.maxFrameBytes,
+                disableBc: true
+            }));
+            // A prefetch is nobody's presence.
+            provider.awareness.setLocalState(null);
+            const done = () => {
+                if (!provider.synced || !provider.saved)
+                    return;
+                const after = Y.encodeStateVector(doc);
+                const updated = after.length !== before.length || after.some((b, i) => b !== before[i]);
+                void close().then(() => resolve({ updated }));
+            };
+            provider.on('synced', done);
+            provider.on('saved', done);
+            provider.on('refused', (refusal) => fail(refusal));
+            done();
+        }, fail);
+    });
+};
+/**
+ * One authorized HTTP `GET <server>/<room>?<key>` (`lastUpdated`,
+ * `snapshot`), which `routeDocumentSocket` answers without a socket: its
+ * JSON. Throws on an HTTP error (`403` refused, `401` expired).
+ */
+const query = async (caller, key, options) => {
+    const [serverUrl, room] = targetOf(caller, options);
+    const url = new URL(`${serverUrl.replace(/^ws/, 'http')}/${encodeURIComponent(room)}`);
+    for (const [name, value] of Object.entries(options.params ?? {}))
+        url.searchParams.set(name, value);
+    url.searchParams.set(key, '1');
+    const response = await (options.fetch ?? fetch)(url.toString());
+    if (!response.ok) {
+        throw new Error(`${key} of ${room}: ${response.status} ${await response.text()}`);
+    }
+    return (await response.json());
+};
+/**
+ * When the room last stored a change (ms since the epoch), or `null`:
+ * `?lastUpdated`, answered without opening the document. Compare it with
+ * when a document was last fetched to decide whether to `prefetch` it.
+ * Throws on an HTTP error (`403` refused, `401` expired).
+ */
+export const lastUpdated = async (options) => {
+    const { lastUpdated: at } = await query('lastUpdated', 'lastUpdated', options);
+    return typeof at === 'number' ? at : null;
+};
+/**
+ * The room's document as JSON, or `null` when it stores nothing yet:
+ * `?snapshot`, answered from the room's live document. Show it while a
+ * view's own copy hydrates: `<Edytor snapshot>`. Throws on an HTTP error
+ * (`403` refused, `401` expired).
+ */
+export const documentSnapshot = async (options) => {
+    const { lastUpdated: at, document } = await query('documentSnapshot', 'snapshot', options);
+    return typeof at === 'number' ? document : null;
+};